User manual MACROMEDIA FLASH COMMUNICATION SERVER MX - SERVER-SIDE COMMUNICATION ACTIONSCRIPT DICTIONARY

Server-Side Communication ActionScript Dictionary Macromedia Flash Communication Server MX TM TM 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, Fontographer, FreeHand, FreeHand Graphics Studio, Generator, Generator Developer's Studio, Generator Dynamic Graphics Server, Knowledge Objects, Knowledge Stream, Knowledge Track, Lingo, Live Effects, Macromedia, Macromedia M Logo & Design, Macromedia Flash, Macromedia Xres, Macromind, Macromind Action, MAGIC, Mediamaker, Object Authoring, Power Applets, Priority Access, Roundtrip HTML, Scriptlets, SoundEdit, ShockRave, Shockmachine, Shockwave, Shockwave Remote, Shockwave Internet Studio, Showcase, Tools to Power Your Ideas, Universal Media, Virtuoso, Web Design 101, Whirlwind and Xtra are trademarks of Macromedia, Inc. and may be registered in the United States or in other jurisdictions including internationally. Other product names, logos, designs, titles, words or phrases mentioned within this publication may be trademarks, servicemarks, or tradenames of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally. Third-Party Information Speech compression and decompression technology licensed from Nellymoser, Inc. (www.nellymoser.com). SorensonTM SparkTM video compression and decompression technology licensed from Sorenson Media, Inc. This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia endorses or accepts any responsibility for the content on those third-party sites. Copyright © 2002 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced, translated, or converted to any electronic or machine-readable form in whole or in part without prior written approval of Macromedia, Inc. Acknowledgments Director: Erick Vera Producer: JuLee Burdekin Writing: Jay Armstrong, Jody Bleyle, JuLee Burdekin, Barbara Herbert, and Barbara Nelson Editing: Anne Szabla Multimedia Design and Production: Aaron Begley, Benjamin Salles Print Design, Production, and Illustrations: Chris Basmajian First Edition: May 2002 Macromedia, Inc. 600 Townsend St. San Francisco, CA 94103 CONTENTS Server-Side Communication ActionScript ............................ 5 Using server-side ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Using naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Contents of the dictionary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Application (object). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Application.acceptConnection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Application.clearSharedObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Application.clearStreams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Application.clients. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Application.disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Application.name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Application.onAppStart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Application.onAppStop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Application.onConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Application.onDisconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Application.onStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Application.registerClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Application.registerProxy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Application.rejectConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Application.server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 clearInterval. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Client (object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Client.agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Client.call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Client."commandName". . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Client.getBandwidthLimit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Client.ip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Client.readAccess. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Client.referrer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Client.__resolve. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Client.setBandwidthLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Client.writeAccess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 NetConnection (object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 NetConnection.addHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 NetConnection.call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 NetConnection.close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 NetConnection.connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 3 NetConnection.isConnected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 NetConnection.onStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 NetConnection.uri . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 setInterval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 SharedObject (object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 SharedObject.clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 SharedObject.close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 SharedObject.flush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 SharedObject.get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 SharedObject.getProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 SharedObject.getPropertyNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 SharedObject.handlerName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 SharedObject.lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 SharedObject.name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 SharedObject.onStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 SharedObject.onSync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 SharedObject.purge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 SharedObject.resyncDepth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 SharedObject.send. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 SharedObject.setProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 SharedObject.size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 SharedObject.unlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 SharedObject.version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Stream (object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Stream.bufferTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Stream.clear. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Stream.get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Stream.length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Stream.name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Stream.onStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Stream.play . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Stream.record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Stream.send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Stream.setBufferTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 APPENDIX Server-Side Information Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4 Contents 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. You can also use server-side scripting to allow and disallow users access to various server-side application resources and to allow users to update and share information. Server-side ActionScript is based on the ECMA-262 specification (ECMAScript 1.5) derived from JavaScript and lets you access the core JavaScript server object model. (For more information, see the Netscape DevEdge website at http://developer.netscape.com/docs/manuals/ index.html?content=ssjs.html.) Server-side ActionScript provides global methods and objects and exposes a rich object model for developing communication applications. You can also create your own objects, properties, and methods. This dictionary provides detailed information about the objects and their properties, methods, and events. Client-Side Communication ActionScript is based on the ECMA-262 specification, but there are some differences in its implementation. Server-side ActionScript, however, does not deviate from the ECMA-262 specification. To learn how client-side ActionScript and server-side ActionScript differ, see "Differences between ActionScript and JavaScript" in Using Flash Help. For information about the relationship between server-side ActionScript and client-side ActionScript, see Developing Communication Applications. Using server-side ActionScript To use server-side ActionScript with a Flash Communication Server application, you write the code, copy the script into the appropriate server directory, and run the SWF file that connects to the server. To understand Flash Communication Server applications, see Developing Communication Applications. Create the server-side ActionScript file and name it main.asc. All ActionScript code that is embedded in the script file and not inside a function body executes once when the application is loaded but before the application.onAppStart event handler is called. Note: Any double-byte characters (including characters of all Asian languages) in the server-side ActionScript file must be UTF-8-encoded. For more information, see "Writing double-byte language applications" in the "Application Development Tips and Tricks" chapter in Developing Communication Applications. Server-Side Communication ActionScript 5 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. For convenience during development, client-side application files (SWFs and HTMLs) are stored in the same directory with your server-side application files (ASCs, FLVs, FLAs). When you deploy applications, you'll need to separate client files from your server-side source files. While your SWF and HTML files should be accessible through a web server, your serverside ASC files, your audio/video FLV files, and your ActionScript FLA source files should not be accessible to a user browsing your Web site. You can either install the server again on your production machine and choose Production Install, or you can change the configuration settings in the administration XML files as described in the Managing Flash Communication Server manual. If you choose Production Install, you can specify both the location of your client-side application files (SWFs and HTMLs) and the location of your server-side application files (ASCs, FLVs, and FLAs). The server will look for your client-side files under \flashcom\applications in the Web server's root directory and will look for your server-side application files under \applications under the directory you specify.If you did not accept the default installation settings and you aren't sure where the application directory is located, the location is specified in the tag of the Vhost.xml file, which is located at \Flash Communication Server MX\conf\_defaultRoot_\_defaultVhost_\. For information about configuring a different application directory, see Managing Flash Communication Server. 2 Create a subdirectory in the server-side application directory called appName, where appName is a name you choose as the filename of your Flash Communication Server application. You must pass this name as a parameter to the NetConnection.connect method in the client-side ActionScript. Place the main.asc file in the appName directory or in a subdirectory called scripts in the appName directory. Open the Flash application (the SWF) in a browser or in the stand-alone Flash Player. The SWF must contain ActionScript code that passes appName to the connect method of the NetConnection object, as shown in the following example: nc = new NetConnection(); nc.connect("rtmp://flashcomsvr.mydomain.com/myFlashComAppName"); Note: You can use the Communication App inspector or the Administration Console to check if the application loaded successfully. 3 4 Using naming conventions When you write server-side ActionScript code, there are certain naming conventions that you must use to name your applications, methods, properties, and variables. These rules let you logically identify objects so your code executes properly. 6 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. Specifying instances By specifying a unique application instance name after an application name, you can run multiple instances of a single application. For example, rtmp:/support/session215 specifies a customer support application named "support" and refers to a specific session of that application named "session215". All users who connect to the same instance name can communicate with each other by referencing the same streams or shared objects. Using JavaScript syntax You must follow all syntax rules of JavaScript. For example, JavaScript is case-sensitive and does not allow punctuation other than underscores (_) and dollar signs ($) in names. You can use numbers in names, but names cannot begin with a number. Avoiding reserved commands Flash Communication Server has reserved commands that you cannot use in a script. These commands are either that methods belong to the client-side NetConnection object or methods that belong to the server-side Client object. This means that if you have a NetConnection object on the client (player), you cannot make the following call: nc.call( "reservedCmd", ... ); In this call, "reservedCmd" is any of the following commands: closeStream, connect, createStream, deleteStream, onStatus, pause, play, publish, receiveAudio, receiveVideo, or seek. It also cannot be any of the server-side Client object methods: getBandwidthLimit, setBandwidthLimit, getStats, and ping. Contents of the dictionary All dictionary entries are listed alphabetically. However, methods, properties, and event handlers that are associated with an object are listed along with the object's name--for example, the name property of the Application object is listed as Application.name. The following table helps you locate these elements. ActionScript element acceptConnection addHeader agent application bufferTime call clear See entry Application.acceptConnection NetConnection.addHeader Client.agent Application (object) Stream.bufferTime Client.call, NetConnection.call SharedObject.clear, Stream.clear Server-Side Communication ActionScript 7 clearInterval clearSharedObject clearStreams Client clients close "commandName" connect disconnect flush get getBandwidthLimit getProperty getPropertyNames handlerName ip isConnected length clearInterval Application.clearSharedObjects Application.clearStreams Client (object) Application.clients NetConnection.close, SharedObject.close Client."commandName" NetConnection.connect Application.disconnect SharedObject.flush SharedObject.get, Stream.get Client.getBandwidthLimit SharedObject.getProperty SharedObject.getPropertyNames SharedObject.handlerName Client.ip NetConnection.isConnected Stream.length load SharedObject.lock Application.name, SharedObject.name, Stream.name NetConnection (object) Application.onAppStart Application.onAppStop Application.onConnect Application.onDisconnect Application.onStatus, NetConnection.onStatus, SharedObject.onStatus, Stream.onStatus SharedObject.onSync Stream.play SharedObject.purge Client.readAccess Stream.record Client.referrer Application.registerClass Application.registerProxy Application.rejectConnection load lock name NetConnection onAppStart onAppStop onConnect onDisconnect onStatus onSync play purge readAccess record referrer registerClass registerProxy rejectConnection 8 __resolve resyncDepth send setBandwidthLimit setBufferTime setInterval setProperty SharedObject size server Stream trace unlock uri version writeAccess Client.__resolve SharedObject.resyncDepth SharedObject.send, Stream.send Client.setBandwidthLimit Stream.setBufferTime setInterval SharedObject.setProperty SharedObject (object) SharedObject.size Application.server Stream (object) trace SharedObject.unlock NetConnection.uri SharedObject.version Client.writeAccess Application (object) The Application object contains information about a Flash Communication Server application instance that lasts until the application instance is unloaded. A Flash Communication Server application is a collection of stream objects, shared objects, and clients (connected users). Each application has a unique name, and you can use the naming scheme described in "Using naming conventions" on page 6 to create multiple instances of an application. The Application object lets you accept and reject client connection attempts, register and unregister classes and proxies, and create functions that are invoked when an application starts or stops or when a client connects or disconnects. Besides the built-in properties of the Application object, you can create other properties of any legal ActionScript type, including references to other ActionScript objects. For example, the following lines of code create a new property of type array and a new property of type number: application.myarray = new Array(); application.num_requests = 1; Server-Side Communication ActionScript 9 Method summary for the Application object Method Application.acceptConnection Description Accepts a connection to an application from a client. Application.clearSharedObjects Clears all shared objects associated with the current instance. Application.clearStreams Application.disconnect Application.registerClass Application.registerProxy Application.rejectConnection Clears all stream objects associated with the current instance. Disconnects a client from the server. Registers or unregisters a constructor that is called during object deserialization. Registers a NetConnection or Client object to fulfill a method request. Rejects a connection to an application. Property summary for the Application object Property (read-only) Application.clients Application.name Application.server Description An object containing a list of all clients currently connected to the application. The name of an application instance. The platform and version of the server. Event handler summary for the Application object Event handler Application.onAppStart Application.onAppStop Application.onConnect Application.onDisconnect Application.onStatus Description Invoked when the application is loaded by the server. Invoked when the application is unloaded by the server. Invoked when a client connects to the application. Invoked when a client disconnects from the application. Invoked when a script generates an error. Application.acceptConnection Availability Flash Communication Server MX. Usage application.acceptConnection(clientObj) Parameters clientObj Returns A client to accept. Nothing. 10 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.onConnect event handler to accept a client connection that had been placed in a pending state (for example, to verify a user name and password). Example The following example uses the application.acceptConnection method to accept the connection from client1: application.onConnect = function (client1){ // insert code here application.acceptConnection(client1); client1.call("welcome"); }; See also Application.onConnect, Application.rejectConnection Application.clearSharedObjects Availability Flash Communication Server MX. Usage application.clearSharedObjects(soPath); Parameters soPath Returns A string that indicates the URI of a shared object. Nothing. Description Method; removes persistent shared objects specified by the soPath parameter and clears all properties from active shared objects (both persistent and nonpersistent). You can use the SharedObject object to create shared objects in a Flash Communication Server application instance. The Flash Communication Server stores persistent shared objects for each application. You can use application.clearSharedObjects to handle one shared object at a time, so you must specify the name of the shared object. You can also use application.clearStreams to remove all the recorded streams based on a stream path. The soPath parameter specifies the name of a shared object, which can include a slash (/) as a delimiter between directories in the path. The last element in the path can contain wildcard patterns (for example, a question mark [?] and an asterisk [*]) or a shared object name. The application.clearSharedObjects method traverses the shared object hierarchy along the specified path and clears all the shared objects. Specifying the a slash clears all the shared objects associated with an application instance. Server-Side Communication ActionScript 11 The following are possible values for the soPath parameter: · · · · / clears all local and persistent shared objects associated with the instance. clears the shared object /foo/bar; if bar is a directory name, no shared objects are /foo/bar deleted. /foo/bar/* 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. clears all shared objects that begin with XX, followed by any two characters. If a directory name matches this specification, all the shared objects within this directory are cleared. /foo/bar/XX?? If you call the clearSharedObjects method and the specified path matches a shared object that is currently active, all its properties are deleted, and a "clear" event is sent to all subscribers of the shared object. If it is a persistent shared object, the persistent store is also cleared. Example The following example clears all the shared objects for an instance: function onApplicationStop(clientObj){ application.clearSharedObjects("/"); } Application.clearStreams Availability Flash Communication Server MX. Usage application.clearStreams(streamPath); Parameters streamPath Returns A string that indicates the URI of a stream. Nothing. Description Method; clears recorded streams from the hard disk. You can use the Stream object to create recorded streams in a Flash Communication Server application instance. The server stores recorded files for each application instance. You can use application.clearStreams to handle one stream at a time, so you must specify the name of the steam. You can also use application.clearStreams to remove all the recorded streams based on a stream path. The streamPath parameter specifies the name of a stream, which can include a slash (/) as a delimiter between directories in the path. The last element in the path can contain wildcard patterns (for example, a question mark [?] and an asterisk [*]) or a stream name. The application.clearStreams method traverses the stream hierarchy along the specified path and clears all the recorded streams that match the given wildcard pattern. Specifying a slash clears all the streams associated with an application instance. 12 The following are possible values for the streamPath parameter: · · · · / clears all recorded streams associated with the instance. clears recorded streams /foo/bar; if bar is a directory name, no streams are deleted. /foo/bar /foo/bar/* 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. clears all streams that begin with XX, followed by any two characters. If there are directories within the given directory listing, the directories are cleared of any streams that match XX??. /foo/bar/XX?? If an application.clearStreams method is invoked on a stream that is currently recording, the recorded file is set to length 0 (cleared), and the internal cached data is also cleared. Note: You can also use the Administration API removeApp method to delete all the resources for a single instance. Examples The following example clears all recorded streams: function onApplicationStop(clientObj){ application.clearStreams("/"); } Application.clients Availability Flash Communication Server MX. Usage application.clients Description Property (read-only); an object containing all the Flash clients or other Flash Communication Servers currently connected to the application. The object is a custom object like an array, but with only one property, length. Each element in the object is a reference to a Client object instance, and you can use the length property to determine the number of users connected to the application. You can use the array access operator ([]) with the application.clients property to access elements in the object. The object used for the clients property is not an array, but it acts the same except for one difference: you can't use the following syntax to iterate through the object: for(var i in application.clients) { // insert code here } Instead, use the following code to loop through each element in a clients object: for (var i = 0; i < application.clients.length; i++) { // insert code here } Server-Side Communication ActionScript 13 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. Returns The object must be a Client object from the A Boolean value of true if the disconnect was successful; otherwise, false. Description Method; causes the server to terminate a client connection to the application. When this method is called, NetConnection.onStatus is invoked on the client side with a status message of NetConnection.Connection.Closed. The application.onDisconnect method is also invoked. Example This example calls the application.disconnect method to disconnect all users of an application instance: function disconnectAll(){ for (i=0; i < application.clients.length; i++){ application.disconnect(application.clients[i]); } } Application.name Availability Flash Communication Server MX. Usage application.name Description Property (read-only); contains the name of the Flash Communication Server application instance. 14 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. You can use application.onAppStop and application.onAppStop to initialize and clean up global variables in an application because each of these events is invoked only once during the lifetime of an application instance. Example The following example defines an anonymous function for the application.onAppStart event handler that sends a trace message: application.onAppStart = function () { trace ("onAppStart called"); }; Application.onAppStop Availability Flash Communication Server MX. Usage application.onAppStop = function (info){ // insert code here }; Parameters info An information object that explains why the application stopped running. See the Appendix, "Server-Side Information Objects," on page 67. Returns The value returned by the function you define, if any, or null. To refuse to unload the application, return false. To unload the application, return true or any non-false value. Server-Side Communication ActionScript 15 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. The Flash Communication Server application passes an information object to the event. You can use server-side ActionScript to look at this information object to decide what to do in the function you define. You could also define the application.onAppStop event to notify users before shutdown. application.onAppStop If you use the Administration Console or the Administration API to unload a Flash Communication Server application, application.onAppStop is not invoked. Therefore you cannot use the application.onAppStop event, for example, to tell users that the application is exiting. Example This example defines a function to perform the shutdown operations on the application. The function is then assigned to the event handler so that it executes when the handler is invoked. function onMyApplicationEnd(info){ // Do all the application-specific shutdown logic... // insert code here } application.onAppStop = onMyApplicationEnd; Application.onConnect Availability Flash Communication Server MX. Usage application.onConnect = function (clientObj [, p1, ..., pN]){ // insert code here to call methods that do authentication // returning null puts client in a pending state return null; }; (usage 2) application.onConnect = function (clientObj [, p1, ..., pN]){ // insert code here to call methods that do authentication // accepts the connection application.acceptConnection(clientObj); } (usage 3) application.onConnect = function (clientObj [, p1, ..., pN]) { // insert code here to call methods that do authentication // accepts the connection by returning true return true; } Parameters clientObj The client connecting to the application. 16 p1 ..., pN 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. 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. If the client is put in a pending state, you must call application.acceptConnection or application.rejectConnection at a later time to accept or reject the connection. For example, you can perform external authentication by making a NetConnection call in your application.onConnect event handler to an application server, and having the reply handler call application.acceptConnection or application.rejectConnection, depending on the information received by the reply handler. You can also call application.acceptConnection or application.rejectConnection inside the application.onConnect event handler. If you do, any value returned by the function is ignored. Note: Returning 1 or 0 is not the same as returning true or false. The values 1 and 0 are treated the same as any other integers and do not accept or reject a connection. Accepted client Client-side ActionScript true, acceptConnection NetConnection.connect acceptConnection Server-side ActionScript New Client object (not accepted or rejected yet) Application.onConnect none, null Pending client false, rejectConnection rejectConnection Rejected client How to use application.onConnect to accept, reject, or put a client in a pending state Server-Side Communication ActionScript 17 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. All the information required for authentication should be sent to the server by the client as parameters (p1 ..., pN) that you define. In addition to authentication, the script can set the access rights to all server-side objects that this client can modify by setting the Client.readAccess and Client.writeAccess properties. If there are several simultaneous connection requests for an application, the server serializes the requests so there is only one application.onConnect handler executing at a time. It is a good idea to write code for the application.onConnect function that executes quickly to prevent a long connect time for clients. Example This example verifies that the user has sent the password "XXXX". If the password is sent, the user's access rights are modified and the user can complete the connection. In this case, the user can create or write to streams and shared objects in the user's own directory and can read or view any shared object or stream in this application instance. // This code should be placed in the global scope application.onConnect = function (newClient, userName, password){ // Do all the application-specific connect logic if (password == "XXXX"){ newClient.writeAccess = "/" + userName; this.acceptConnection(newClient); } var err = new Object(); err.message = "Invalid password"; this.rejectConnection(newClient, err); }; If the password is incorrect, the user is rejected and an information object with a message property set to "Invalid password" is returned to the client side. The object is assigned to infoObject.application. To access the message property, use the following code on the client side: ClientCom.onStatus = function (info){ trace(info.application.message); // it will print "Invalid password" // in the Output window on the client side }; See also Application.acceptConnection, Application.rejectConnection Application.onDisconnect Availability Flash Communication Server MX. 18 Usage application.onDisconnect = function (clientObj){ // insert code here }; Parameters clientObj Returns A client disconnecting from the application. 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.onDisconnect event handler: // This code should be placed in the global scope. application.onDisconnect = function (client){ // Do all the client-specific disconnect logic... // insert code here trace("user disconnected"); }; Application.onStatus Availability Flash Communication Server MX. Usage application.onStatus = function (infoObject){ // insert code here }; Parameters infoObject An object that contains the error level, code, and sometimes a description. See the Appendix, "Server-Side Information Objects," on page 67. Returns Any value that the callback function returns. Description Event handler; invoked when the server encounters an error while processing a message that was targeted at this application instance. The application.onStatus event handler is the root for any Stream.onStatus or NetConnection.onStatus messages that don't find handlers. Also, there are a few status calls that come only to application.onStatus. This event handler can be used for debugging messages that generate errors. Server-Side Communication ActionScript 19 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. When a typed object is sent from the client to the server, this class is called to create the server-side object. After the application stops, the registerClass method is called again and passes the value null to unregister the class. function Color(){ this.red = 255; this.green = 0; this.blue = 0; } Color.prototype.getRed = function(){ return this.red; } Color.prototype.getGreen = function(){ return this.green; } Color.prototype.getBlue = function(){ return this.blue; } Color.prototype.setRed = function(){ this.red = value; } Color.prototype.setGreen = function(){ this.green = value; } Color.prototype.setBlue = function(){ this.blue = value; } application.onAppStart = function(){ application.registerClass("Color", Color); }; application.onAppStop = function(){ application.registerClass("Color", null); }; The following example shows how to use the application.registerClass method with the prototype property: function A(){} function B(){} B.prototype = new A(); B.prototype.constructor = B; // set constructor back to that of B // insert code here application.registerClass("B", B); Application.registerProxy Availability Flash Communication Server MX. Usage application.registerProxy(methodName, proxyConnection [, proxyMethodName]) Server-Side Communication ActionScript 21