Macromedia SERVER-SIDE COMMUNICATION ACTIONSCRIPT DICTIONARY User Manual

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, 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).

Sorenson™ Spark™ 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

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

Contents4

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

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

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.

application.onAppStart event handler is called.

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

<AppsDir> 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.

3 Place the main.asc file in the appName directory or in a subdirectory called scripts in the

appName directory.

4 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.

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.

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 property of the Application object is listed as locate these elements.

ActionScript element See entry

acceptConnection Application.acceptConnection

addHeader NetConnection.addHeader

agent Client.agent

application Application (object)

bufferTime Stream.bufferTime

call Client.call, NetConnection.call

clear SharedObject.clear, Stream.clear

Application.name. The following table helps you

Server-Side Communication ActionScript 7

name

clearInterval 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.getPropertyNames

handlerName SharedObject.handlerName

ip Client.ip

isConnected NetConnection.isConnected

length Stream.length

load

lock SharedObject.lock

name Application.name, SharedObject.name, Stream.name

NetConnection NetConnection (object)

onAppStart Application.onAppStart

onAppStop Application.onAppStop

onConnect Application.onConnect

onDisconnect Application.onDisconnect

onStatus Application.onStatus, NetConnection.onStatus,

onSync SharedObject.onSync

play Stream.play

purge SharedObject.purge

readAccess Client.readAccess

record Stream.record

referrer Client.referrer

registerClass Application.registerClass

registerProxy Application.registerProxy

rejectConnection Application.rejectConnection

load

SharedObject.onStatus, Stream.onStatus

__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.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

application.myarray = new Array(); application.num_requests = 1;

array and a new property of type number:

Server-Side Communication ActionScript 9

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

Application.registerProxy Registers a NetConnection or Client object to fulfill a method request.

Application.rejectConnection Rejects a connection to an application.

deserialization.

Property summary for the Application object

Property (read-only) Description

Application.clients An object containing a list of all clients currently connected to the application.

Application.name The name of an application instance.

Application.server The platform and version of the server.

Event handler summary for the Application object

Event handler Description

Application.onAppStart Invoked when the application is loaded by the server.

Application.onAppStop Invoked when the application is unloaded by the server.

Application.onConnect Invoked when a client connects to the application.

Application.onDisconnect Invoked when a client disconnects from the application.

Application.onStatus Invoked when a script generates an error.

Application.acceptConnection

Availability

Flash Communication Server MX.

Usage

application.acceptConnection(clientObj)

Parameters

clientObj A client to accept.

Returns

Nothing.

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

application.onConnect = function (client1){

// insert code here application.acceptConnection(client1); client1.call("welcome");

};

See also

Application.onConnect, Application.rejectConnection

client1:

Application.clearSharedObjects

Availability

Flash Communication Server MX.

Usage

application.clearSharedObjects(soPath);

Parameters

soPath A string that indicates the URI of a shared object.

Returns

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 must specify the name of the shared object. You can also use

application.clearSharedObjects to handle one shared object at a time, so you

application.clearStreams to

remove all the recorded streams based on a stream path.

soPath parameter specifies the name of a shared object, which can include a slash (/) as a

The 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.

• /foo/bar clears the shared object /foo/bar; if bar is a directory name, no shared objects are

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.

• /foo/bar/XX?? 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.

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 A string that indicates the URI of a stream.

Returns

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.

streamPath parameter specifies the name of a stream, which can include a slash (/) as a

The 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.

The following are possible values for the streamPath parameter:

• / 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.

• /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.

• /foo/bar/XX?? 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

XX??.

match

application.clearStreams method is invoked on a stream that is currently recording, the

If an 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, instance, and you can use the application. You can use the array access operator ( to access elements in the object.

The object used for the 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

}

length. Each element in the object is a reference to a Client object

length property to determine the number of users connected to the

[]) with the application.clients property

clients property is not an array, but it acts the same except for one

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

for (i = 0; i < application.clients.length; i++){

application.clients[i].call("serverUpdate");

}

serverUpdate on each client:

Application.disconnect

Availability

Flash Communication Server MX.

Usage

application.disconnect(clientObj)

Parameters

clientObj The client to disconnect. The object must be a Client object from the

application.clients array.

Returns

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.

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 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.

application.onAppStop and

Example

The following example defines an anonymous function for the application.onAppStart event handler that sends a

application.onAppStart = function () {

trace ("onAppStart called");

};

trace message:

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 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

application.onAppStop 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.

If you use the Administration Console or the Administration API to unload a Flash Communication Server application, cannot use the

application.onAppStop event, for example, to tell users that the application is

application.onAppStop is not invoked. Therefore you

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

true,

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.

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.rejectConnection at a later time to accept or reject the connection. For example,

application.acceptConnection or

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 the

application.onConnect event handler. If you do, any value returned by the function is

application.acceptConnection or application.rejectConnection inside

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

NetConnection.connect

true, acceptConnection

acceptConnection

Server-side ActionScript

New Client object

(not accepted or rejected yet)

none, null

false, rejectConnection

Rejected

client

Pending clientApplication.onConnect

rejectConnection

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

application.onConnect event handler. If you don’t define a function, connections are

for the 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 ( rights to all server-side objects that this client can modify by setting the

Client.writeAccess properties.

p1 ..., pN) that you define. In addition to authentication, the script can set the access

Client.readAccess and

If there are several simultaneous connection requests for an application, the server serializes the requests so there is only one idea to write code for the

application.onConnect handler executing at a time. It is a good

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

};