Server-Side Communication ActionScript Dictionary Macromedia Flash Communication Server MX ™ ™ macromedia ®
Trademarks Afterburner, AppletAce, Attain, Attain Enterprise Learning System, Attain Essentials, Attain Objects for Dreamweaver, Authorware, Authorware Attain, Authorware Interactive Studio, Authorware Star, Authorware Synergy, Backstage, Backstage Designer, Backstage Desktop Studio, Backstage Enterprise Studio, Backstage Internet Studio, Design in Motion, Director, Director Multimedia Studio, Doc Around the Clock, Dreamweaver, Dreamweaver Attain, Drumbeat, Drumbeat 2000, Extreme 3D, Fireworks, Flash, Fonto
CONTENTS Server-Side Communication ActionScript ............................ 5 Using server-side ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Using naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Contents of the dictionary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Application (object). . . . . . . . . . . . . . . . . . . . .
NetConnection.isConnected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 NetConnection.onStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 NetConnection.uri . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 setInterval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server-Side Communication ActionScript Server-Side Communication ActionScript is a scripting language on the server that lets you develop efficient and flexible client-server Macromedia Flash Communication Server MX applications. For example, you can use server-side ActionScript to control login procedures, control events in connected Flash movies, determine what users see in their Flash movies, and communicate with other servers.
To install and test the server-side ActionScript file, do the following: 1 Locate the flashcom application directory. During installation, you can choose either a Developer Install or a Production Install of the product. If you choose Developer Install, you can run the samples and test your applications from the \flashcom\applications directory under the directory you specify.
Naming applications Flash Communication Server application names must follow the Uniform Resource Identifier (URI) RFC 2396 convention (see http://www.w3.org/Addressing/). This convention supports a hierarchical naming system where a forward slash (/) separates the elements in the hierarchy. The first element specifies the application name. The element following the application name specifies the application instance name. Each instance of the application has its own script environment.
clearInterval 8 clearInterval clearSharedObject Application.clearSharedObjects clearStreams Application.clearStreams Client Client (object) clients Application.clients close NetConnection.close, SharedObject.close "commandName" Client."commandName" connect NetConnection.connect disconnect Application.disconnect flush SharedObject.flush get SharedObject.get, Stream.get getBandwidthLimit Client.getBandwidthLimit getProperty SharedObject.getProperty getPropertyNames SharedObject.
__resolve Client.__resolve resyncDepth SharedObject.resyncDepth send SharedObject.send, Stream.send setBandwidthLimit Client.setBandwidthLimit setBufferTime Stream.setBufferTime setInterval setInterval setProperty SharedObject.setProperty SharedObject SharedObject (object) size SharedObject.size server Application.server Stream Stream (object) trace trace unlock SharedObject.unlock uri NetConnection.uri version SharedObject.version writeAccess Client.
Method summary for the Application object Method Description Application.acceptConnection Accepts a connection to an application from a client. Application.clearSharedObjects Clears all shared objects associated with the current instance. Application.clearStreams Clears all stream objects associated with the current instance. Application.disconnect Disconnects a client from the server. Application.registerClass Registers or unregisters a constructor that is called during object deserialization.
Description Method; accepts the connection call from a client to the server. The application.onConnect event handler is invoked on the server side to notify a script when NetConnection.connect is called from the client side. You can use the application.acceptConnection method inside an application.onConnect event handler to accept a connection from a client. You can use the application.acceptConnection method outside an application.
The following are possible values for the soPath parameter: • • / clears all local and persistent shared objects associated with the instance. /foo/bar clears the shared object /foo/bar; if bar is a directory name, no shared objects are deleted. • /foo/bar/* • /foo/bar/XX?? clears all shared objects stored under the instance directory /foo/bar. The bar directory is also deleted if no persistent shared objects are in use within this name space.
The following are possible values for the streamPath parameter: • • • / • /foo/bar/XX?? clears all recorded streams associated with the instance. /foo/bar clears recorded streams /foo/bar; if bar is a directory name, no streams are deleted. clears all streams stored in the instance directory /foo/bar. The bar directory is also deleted if no streams are in use within this name space. /foo/bar/* clears all streams that begin with XX, followed by any two characters.
Example This example uses a for loop to iterate through each member of the application.clients array and calls the method serverUpdate on each client: for (i = 0; i < application.clients.length; i++){ application.clients[i].call("serverUpdate"); } Application.disconnect Availability Flash Communication Server MX. Usage application.disconnect(clientObj) Parameters clientObj The client to disconnect. application.clients array.
Example The following example checks the name property against a specific string before it executes some code: if (application.name == "videomail/work"){ // insert code here } Application.onAppStart Availability Flash Communication Server MX. Usage application.onAppStart = function (info){ // insert code here }; Parameters None. Returns Nothing. Description Event handler; invoked when the server first loads the application instance. You use this handler to initialize an application state.
Description Event handler; invoked when the application is about to be unloaded by the server. You can define a function that executes when the event handler is invoked. If the function returns true, the application unloads. If the function returns false, the application doesn’t unload. If you don’t define a function for this event handler, or if the return value is not a Boolean value, the application is unloaded when the event is invoked.
Optional parameters passed to the application.onConnect method. These parameters are passed from the client-side NetConnection.connect method when a client connects to the application. p1 ..., pN Returns The value you provide. If you return a Boolean value of true, the server accepts the connection; if the value is false, the server rejects the connection. If you return null or no return value, the server puts the client in a pending state and the client can’t receive or send messages.
Description Event handler; invoked on the server side when NetConnection.connect is called from the client side and a client attempts to connect to an application instance. You can define a function for the application.onConnect event handler. If you don’t define a function, connections are accepted by default. If the server accepts the new connection, the application.clients object is updated. You can use the application.onConnect event in server-side scripts to perform authentication.
Usage application.onDisconnect = function (clientObj){ // insert code here }; Parameters clientObj A client disconnecting from the application. Returns The server ignores any return value. Description Event handler; invoked when a client disconnects from the application. You can use this event handler to flush any client state information or to notify other users of this event. This event handler is optional. Example This example uses an anonymous function and assigns it to the application.
Example The following example defines a function that sends a trace statement whenever the application.
If you register a class that has its prototype set to another class, you must set the prototype constructor back to the original class after setting the prototype. The second example below illustrates this point. Example This example defines a Color constructor function with properties and methods. After the application connects, the registerClass method is called to register a class for the objects of type Color.
Parameters The name of a method. All requests to execute methodName for this application instance are forwarded to the proxyConnection object. methodName A Client or NetConnection object. All requests to execute the remote method specified by methodName are sent to the Client or NetConnection object that is specified in the proxyConnection parameter. Any result that is returned is sent back to the originator of the call. To unregister, or remove, the proxy, provide a value of null for this parameter.
Returns Nothing. Description Method; rejects the connection call from a client to the server. The application.onConnect event handler notifies a script when a new client is connecting. In the function assigned to application.onConnect, you can either accept or reject the connection. You can also define a function for application.onConnect that calls an application server for authentication. In that case, an application could call application.
clearInterval Availability Flash Communication Server MX. Usage clearInterval(intervalID) Parameters intervalID A unique ID returned by a previous call to the setInterval method. Returns Nothing. Description Method (global); cancels a time-out that was set with a call to the setInterval method. Example The following example creates a function named callback and passes it to the setInterval method, which is called every 1000 milliseconds and sends the message “interval called” to the Output window.
If all instances of the Client object (each client in an application) require the same methods or properties, you can add those methods and properties to the class itself instead of adding them to each instance of a class. This process is called extending a class. You can extend any server-side or client-side ActionScript class.
The methods are available to any instance, so within application.onConnect, which is passed a clientObj argument, you can write the following code: application.onConnect(clientObj){ var clientID = clientObj.createUniqueID(); var clientWritePerm = clientObj.getWritePermission(); }; Method summary for the Client object Method Description Client.call Executes a method on the Flash client asynchronously and returns the value from the Flash client to the server. Client.
Example The following example checks the agent property against the string "WIN" and executes different code depending on whether they match. This code is written inside an onConnect function. function onConnect(newClient, name){ if (newClient.agent.indexOf("WIN") > -1){ trace ("Window user"); } else { trace ("non Window user.agent is" + newClient.agent); } } Client.call Availability Flash Communication Server MX. Usage Client.call(methodName, [resultObj, [p1, ...
The following server-side script uses the Client.call method inside the application.onConnect handler to call the random method that was defined on the client side. The server-side script also defines a function called randHander, which is used in the Client.call method as the resultObj parameter. application.onConnect = function(clientObj){ trace("we are connected"); application.acceptConnection(clientObj); clientObj.call("random", new randHandler()); }; randHandler = function(){ this.
The sum method can then be called from NetConnection.call on the Flash client side, as shown in the following example: nc = new NetConnection(); nc.connect("rtmp://myServer/myApp"); nc.call("sum", new result.sum(), 20, 50); function result.sum(){ this.onResult = function (retVal){ output += "sum is " + retVal; }; this.onStatus = function(errorVal){ output += errorVal.code + " error occurred"; }; } The sum method can also be called on the server side, as shown here: newClient.
Returns An integer indicating bytes per second. Description Method; returns the maximum bandwidth that the client or the server can use for this connection. Use the iDirection parameter to get the value for each direction of the connection. The value returned indicates bytes per second and can be changed with Client.setBandwidthLimit. The default value for a connection is set for each application in the Application.xml file. Example The following example uses Client.
By default, all clients have full read access, and the readAccess property is set to slash (/). To give a client read access, specify a list of access levels (in URI format), delimited by semicolons. Any files or directories within a specified URI are also considered accessible. For example, if myMedia is specified as an access level, then any files or directories in the myMedia directory are also accessible (for example, myMedia/mp3s).
Parameters propName The name of an undefined property. Returns The value of the undefined property, which is specified by the propName parameter. Description Method; provides values for undefined properties. When an undefined property of a Client object is referenced by server-side ActionScript code, that object is checked for a __resolve method. If the object has a __resolve method, the __resolve method is invoked and passed the name of the undefined property.
Client.writeAccess Availability Flash Communication Server MX. Usage Client.writeAccess Description Property; provides write-access rights to application resources (shared objects, streams, and so on) for this client. To give a client write access to directories containing application resources, list directories in a string delimited by semicolons. By default, all clients have full write access, and the writeAccess property is set to slash (/).
Note: For security reasons, your server-side applications directory, which contains ASC files, audio/video FLV files, and ActionScript FLA source files, should not be accessible to a user browsing your Web site. Example The following example loads the myLoadedFile.as file: load("myLoadedFile.
Method summary for the NetConnection object Method Description NetConnection.addHeader Adds a context header. NetConnection.call Invokes a method or operation on a remote server. NetConnection.close Closes a server connection. NetConnection.connect Establishes connection to a server. Property summary for the NetConnection object Property Description NetConnection.isConnected A Boolean value indicating whether a connection has been made. NetConnection.
Parameters name A string that identifies the header and the ActionScript object data associated with it. A Boolean value; true indicates that the server must understand and process this header before it handles any of the following headers or messages. mustUnderstand object Any ActionScript object. Returns Nothing. Description Method; adds a context header to the AMF packet structure. This header is sent with every future AMF packet. If you call NetConnection.
Description Method; invokes a command or method on a Flash Communication Server or an application server to which the application instance is connected. The NetConnection.call method on the server works the same way as the NetConnection.call method on the client: it invokes a command on a remote server. Note: If you want to call a method on a client from a server, use the Client.call method.
Example The following code closes the NetConnection instance myNetConn: myNetConn.close(); NetConnection.connect Availability Flash Communication Server MX. Usage myNetConnection.connect(URI, [p1, ..., pN]) Parameters URI A URI to connect to. p1, ..., pN Optional parameters that can be of any ActionScript type, including references to other ActionScript objects. These parameters are sent as connection parameters to the application.onConnect event handler for RTMP connections.
Usage myNetConnection.isConnected Description Property (read-only); a Boolean value that indicates whether a connection has been made. It is set to true if there is a connection to the server. It’s a good idea to check this property value in the onStatus callback function. This property is always true for AMF connections to application servers. Example This example uses NetConnection.isConnected inside an onStatus definition to check if a connection has been made: nc = new NetConnection(); nc.
Example This example defines a function for the onStatus handler that outputs messages to indicate whether the NetConnection was successful: nc = new NetConnection(); nc.onStatus = function(info){ if (info.code == "NetConnection.Connect.Success") { _root.gotoAndStop(2); } else { if (! nc.isConnected){ _root.gotoAndStop(1); } } }; NetConnection.uri Availability Flash Communication Server MX. Usage myNetConnection.
Description Method (global); continually calls a function or method at a specified time interval until the clearInterval method is called. This method allows a server-side script to run a generic routine. The setInterval method returns a unique ID that you can pass to the clearInterval method to stop the routine. Note: Standard JavaScript supports an additional usage for the setInterval method, setInterval(stringToEvaluate, timeInterval), which is not supported by Server-Side Communication ActionScript.
Every shared object is identified by a unique name and contains a list of name-value pairs, called properties, just like any other ActionScript object. A name must be a unique string and a value can be any ActionScript data type. (For more information about data types, see Using Flash MX.) All shared objects have a data property. Any property of the data property can be shared and is called a slot.
Method summary for the SharedObject object Method Description SharedObject.clear Deletes all properties of a persistent shared object. SharedObject.close Unsubscribes from a shared object. SharedObject.flush Causes the server to save the current state of a shared object. SharedObject.get Returns a reference to a shared object. SharedObject.getProperty Gets the value of a shared object property. SharedObject.
Parameters None. Returns Returns true if successful; false otherwise. Description Method; deletes all properties and sends a “clear” event to all clients that subscribe to a persistent shared object. The persistent data object is also removed from persistent shared object. You can use SharedObject.clear to detach from a shared object immediately after SharedObject.get is invoked. You can use SharedObject.
SharedObject.flush Availability Flash Communication Server MX. Usage SharedObject.flush() Parameters None. Returns A Boolean value of true if successful, false otherwise. Description Method; causes the server to save the current state of the shared object instance. The shared object must have been created with the persistence option. Example The following example places a reference to the shared object foo in the variable myShared.
Description Static method; returns a reference to a shared object instance. To perform any operation on a shared object, the server-side script must get a reference to the named shared object using the SharedObject.get method. If the object requested is not found, a new instance is created. There are two types of shared objects, persistent and nonpersistent, and they are in separate name spaces.
Example This example creates a shared object named foo inside the function onProcessCmd. The function is passed a parameter, cmd, that is assigned to a property in the shared object. function onProcessCmd(cmd){ // insert code here var shObj = SharedObject.get("foo", true); propName = cmd.name; shObj.getProperty (propName, cmd.newAddress); } The following example uses a proxied shared object.
SharedObject.getPropertyNames Availability Flash Communication Server MX. Usage mySharedObject.getPropertyNames() Parameters None. Returns An array containing all the property names of a shared object. Description Method; enumerates all the property names for a given shared object. This method returns an array of strings that refer to the current properties. Example This example calls getPropertyNames on the sharedInfo shared object and places the names into the names variable.
The this keyword used in the body of the function is set to the shared object instance returned by SharedObject.get. If you don’t want the server to receive a particular broadcast message, do not define this handler. Example The following example defines a handler function called broadcastMsg: var mySO = SharedObject.get("userList", false); mySO.broadcastMsg = function(msg1, msg2){ trace(msg1 + " : " + msg2); } SharedObject.lock Availability Flash Communication Server MX. Usage SharedObject.
Example This example outputs foo to the NetConnection Debugger: mySO = SharedObject.get("foo"); trace(mySO.name); SharedObject.onStatus Availability Flash Communication Server MX. Usage SharedObject.onStatus = function(info) { // insert code here }; Parameters info An information object. For more information, see the Appendix, “Client-Side Information Objects,” in the Client-Side Communication ActionScript Dictionary. Returns Nothing.
Local shared objects Code Meaning change A property was changed by a subscriber. delete A property was deleted by a subscriber. name The name of a property that has changed or been deleted. oldValue The old value of a property. This is true for both change and delete messages; on the client, oldValue is not set for delete. Note: Changing or deleting a property on the server side using the SharedObject.setProperty method always succeeds, so there is no notification of these changes.
Example The following example creates a function that is invoked whenever a property of the shared object so changes: // create a new NetConnection object nc = new NetConnection(); nc.connect("rtmp://server1.xyx.com/myApp"); // create the shared object so = SharedObject.get("MasterUserList", true, nc); // the list parameter is an array of objects containing information // about successfully of unsuccessfully changed properties // from the last time onSync() was called so.
SharedObject.resyncDepth Availability Flash Communication Server MX. Usage SharedObject.resyncDepth Description Property; an integer that indicates when the deleted properties of a shared object should be permanently deleted. You can use this property in a server-side script to resynchronize shared objects and to control when shared objects are deleted. The default value is infinity.
Returns A Boolean value of true if the message was sent to the client; false otherwise. Description Method; executes a method in a client-side script. You can use SharedObject.send to asynchronously execute a method on all the Flash clients subscribing to a shared object. The server does not receive any notification from the client on the success, failure, or return value in response to this message. Example This example calls the SharedObject.
If you call SharedObject.setProperty on the server side, it invokes a change message in the SharedObject.onSync method on the client side for any Flash Player client that is using the shared object. The name parameter on the server side is the same as an attribute of the data property on the client side. For example, the following two lines of code are equivalent: the first line is server-side ActionScript, and the second is client-side ActionScript: sharedInfo.setProperty(nameVal, "foo"); clientSO.
Usage mySharedObject.unlock() Parameters None. Returns An integer indicating the lock count: 0 or greater if successful, -1 otherwise. For proxied shared objects, this method always returns -1. Description Method; unlocks a shared object instance. This causes the script to relinquish exclusive access to the shared object and lets other clients update the instance. This method also causes the server to commit all changes made after the SharedObject.
You can create other Stream properties of any legal ActionScript type, including references to other ActionScript objects, for a particular instance of the Stream object. The properties are available until the stream is removed from the application. For more information about streams, see the NetStream (object) entry in the Client-Side Communication ActionScript Dictionary. Property summary for the Stream object Property (read-only) Description Stream.
Stream.clear Availability Flash Communication Server MX. Usage Stream.clear() Parameters None. Returns A Boolean value of true if the call succeeds, false otherwise. Description Method; deletes a stream that uses previously recorded by the server. Example This example deletes a recorded stream called foo. Before the stream is deleted, the example defines an onStatus handler that uses two information object error codes, NetStream.Clear.Success and NetStream.Clear.
Example This example gets the stream foo and assigns it to the variable playStream. It then calls the Stream.play method from playStream. function onProcessCmd(cmd){ var playStream = Stream.get("foo"); playStream.play("file1", 0, -1); } Stream.length Availability Flash Communication Server MX. Usage Stream.length(name) Parameters name Name of a recorded stream. Returns The length of a recorded stream in seconds. Description Method (static); returns the length of a recorded stream in seconds.
Usage myStream.onStatus = function([infoObject]) { // Insert code here }; Parameters infoObject An optional parameter defined according to the status message. For details about this parameter, see the Appendix, “Server-Side Information Objects,” on page 67. Returns Nothing. Description Event handler; invoked every time the status of a Stream object changes. For example, if you play a file in a stream, Stream.onStatus is invoked. Use Stream.
A Boolean value that flushes the playing stream. If reset is false, the server maintains a playlist, and each call to Stream.play is appended to the end of the playlist so that the next play does not start until the previous play finishes. You can use this technique to create a dynamic playlist. If reset is true, any playing stream stops, and the playlist is reset. By default, the value is true. This is an optional parameter.
Example This example illustrates how streams can be chained between servers: application.myRemoteConn = new NetConnection(); application.myRemoteConn.onStatus = function(info){ trace("Connection to remote server status " + info.code + "\n"); // tell all the clients for (var i = 0; i < application.clients.length; i++){ application.clients[i].call("onServerStatus", null, info.code, info.description); } }; // Use the NetConnection object to connect to a remote server application.myRemoteConn.
Parameters This parameter can have the value record, append, or false. If the value is record, the data file is overwritten if it exists. If the value is append, the incoming data is appended to the end of the existing file. If the value is false, any previous recording stops. By default, the value is record. flag Returns A Boolean value of true if the recording succeeds, false otherwise. Description Method; records all the data going through a Stream object.
Description Method; calls a method on all the clients subscribing to a stream. When you call Stream.send on the server side, any client publishing to that stream is stopped from publishing. Therefore, the best practice is to create a new stream before calling Stream.send. There should be one stream for every communication call in a Flash Communication Server application. Example This example calls the method Test on the client-side Stream object and sends it the string "hello world": application.
trace Availability Flash Communication Server MX. Usage trace("Hello world"); trace("Value of i = " + i); Returns Nothing. Description Method (global); displays the value of an expression in the Output window. The trace message is also published to the logs/application appname stream, which is available in the Administration Console or in the Communication App inspector. The values in the trace expression are converted to strings if possible before they are sent to the Output window.
APPENDIX Server-Side Information Objects The Application, NetConnection, and Stream objects provide an onStatus event handler that uses an information object for providing information, status, or error messages. To respond to this event handler, you must create a function to process the information object, and you must know the format and contents of the information object returned. You can define the following global function at the top of your main.
Code Level Application.Resource.LowMemory Warning Meaning The ActionScript engine is low on runtime memory. This provides an opportunity for the application instance to free some resources or take suitable action. If the application instance runs out of memory, it is unloaded and all users are disconnected. In this state, the server will not invoke the Application.onDisconnect event handler or the Application.onAppStop event handler. Application.
Code Level NetStream.Failed Error An attempt to use a Stream method failed.* NetStream.Unpublish.Success Status An attempt to unpublish was successful. NetStream.Record.Start Status Recording was started. NetStream.Record.NoAccess Error An attempt was made to record a read-only stream. NetStream.Record.Stop Status Recording was stopped. NetStream.Record.Failed Error An attempt to record a stream failed. NetStream.Play.Start Status Play was started.** NetStream.Play.
