Application class

Availability

Flash Communication Server 1

Parameters

clientObj

A Client object; a client to accept.

Details

When NetConnection.connect() is called from the client side, it passes a Client object to application.onConnect() on the server. Call application.acceptConnection() in an application.onConnect() event handler to accept a connection from a client. When this method is called, NetConnection.onStatus() is invoked on the client with the info.code property set to "NetConnection.Connect.Success".

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

When you call this method, NetConnection.onStatus() is invoked on the client with the info.code property set to "NetConnection.Connect.Success". For more information, see the NetStatusEvent.info property in the ActionScript 3.0 Language and Components Reference or the NetConnection.onStatus() entry in the Adobe Flash Media Server ActionScript 2.0 Language Reference.

Example

The following server-side code accepts a client connection and traces the client ID:

application.onConnect = function(client){ 
    // Accept the connection. 
        application.acceptConnection(client); 
    trace("connect: " + client.id); 
};

Availability

Flash Media Server 2

Availability

Flash Media Server 2

Parameters

cmd

A string; the name of the a handler on the client-side NetConnection object.

p1,..., pN

A string; messages to broadcast.

Example

The following server-side code sends a message to the client:

application.broadcastMsg("serverMessage", "Hello Client");

The following client-side ActionScript 2.0 code handles the message and outputs “Hello Client”:

nc = new NetConnection(); 
nc.serverMessage = function(msg){ 
    trace(msg);  
};

The following client-side ActionScript 3.0 code handles the message and outputs “Hello Client”:

var nc:NetConnection = new NetConnection() 
var ncClient = new Object(); 
nc.client = ncClient; 
ncClient.serverMessage = nc_serverMessage; 
function nc_serverMessage(msg:String):void{ 
    trace(msg); 
}

Availability

Flash Communication Server 1

Parameters

soPath

A string indicating the Uniform Resource Identifier (URI) of a shared object.

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 a slash (/) clears all the shared objects that are associated with an application instance.

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

The following values are possible 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. If no persistent shared objects are in use within this namespace, the bar directory is also deleted.

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

Returns

A boolean value of true if the shared object at the specified path was deleted; otherwise, false. If wildcard characters are used to delete multiple files, the method returns true only if all the shared objects that match the wildcard pattern were successfully deleted; otherwise, it returns false.

Example

The following example clears all the shared objects for an instance:

function onApplicationStop(){ 
    application.clearSharedObjects("/"); 
}

Availability

Flash Communication Server 1

Parameters

streamPath

A string indicating the Uniform Resource Identifier (URI) of a stream.

The streamPath parameter specifies the location and name of a stream relative to the directory of the application instance. You 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 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 that are associated with an application instance.

To clear FLV, F4V, or MP3 files, precede the stream path with flv:, mp4:, or mp3:. When you specify flv: or mp3: you don’t have to specify a file extension; .flv and .mp3 are implied. However, when you call application.clearStreams("mp4:foo"), the server deletes any file with the name “foo” in an MPEG-4 container; for example, foo.mp4, foo.mov, and foo.f4v. To delete a specific file, pass the file extension in the call; for example, application.clearStreams("mp4:foo.f4v").

Note: If you don't precede the stream path with a file type, only FLV files are deleted.

The following examples show some possible values for the streamPath parameter:

• flv:/ clears all FLV streams associated with the application instance.

• mp3:/ clears all MP3 files associated with the application instance.

• mp4:/ clears all F4V streams associated with the application instance (for example, foo.mp4, foo.f4v, and so on).

• mp4:foo.mp4 clears the foo.mp4 file.

• mp4:foo.mov clears the foo.mov file.

• mp3:/mozart/requiem clears the MP3 file named requiem.mp3 from the application instance’s /mozart subdirectory.

• mp3:/mozart/* clears all MP3 files from the application instance’s /mozart subdirectory.

• /report clears the report.flv stream file from the application instance directory.

• /presentations/intro clears the recorded intro.flv stream file from the application instance’s /presentations subdirectory; if intro is a directory name, no streams are deleted.

• /presentations/* clears all FLV files from the application instance’s /presentations subdirectory. The /presentation subdirectory is also deleted if no streams are used in this namespace.

• /presentations/report?? clears all FLV files that begin with “report,” followed by any two characters. If there are directories within the given directory listing, the directories are cleared of any streams that match report??.

Returns

A boolean value of true if the stream at the specified path was deleted; otherwise, false. If wildcard characters are used to clear multiple stream files, the method returns true only if all the streams that match the wildcard pattern were successfully deleted; otherwise, it returns false.

Example

The following example clears all recorded streams:

function onApplicationStop(){ 
    application.clearStreams("/"); 
}

The following example clears all MP3 files from the application instance’s /disco subdirectory:

function onApplicationStop(){ 
    application.clearStreams("mp3:/disco/*"); 
}

Availability

Flash Communication Server 1

Example

The following example uses a for loop to iterate through each element in the application.clients array and calls the serverUpdate() method on each client:

for (i = 0; i < application.clients.length; i++){ 
    application.clients[i].call("serverUpdate"); 
}

Availability

Flash Media Server 2

Example

Use this sample section from an Application.xml file for this example:

<Application> 
    <JSEngine> 
            <ApplicationObject> 
                <config> 
                <user_name>jdoe</user_name> 
                <dept_name>engineering</dept_name>  
            </config> 
            </ApplicationObject> 
    </JSEngine> 
</Application>

The following lines of code access the user_name and dept_name properties:

trace("I am " + application.config.user_name + " and I work in the " + application.config.dept_name + " department."); 
 
trace("I am " + application.config["user_name"] + " and I work in the " + application.config["dept_name"] + " department.");

The following code is sent to the application log file and the Administration Console:

I am jdoe and I work in the engineering department.

Availability

Flash Communication Server 1

Parameters

clientObj

A Client object indicating the client to disconnect. The object must be a Client object from the application.clients array.

Returns

A boolean value of true if the disconnection was successful; otherwise, false.

Example

The following example calls application.disconnect() to disconnect all users from an application instance:

function disconnectAll(){ 
    for (i=0; i < application.clients.length; i++){ 
        application.disconnect(application.clients[i]); 
    } 
}

Availability

Flash Media Server 2

Availability

Flash Communication Server 1

Returns

An Object whose properties contain statistics about the application instance. The following table describes the properties:

Example

The following example outputs application statistics to the Live Log panel in the Administration Console:

function testStats(){ 
    var stats = application.getStats(); 
    for(var prop in stats){ 
         trace("stats." + prop + " = " + stats[prop]); 
    } 
} 
 
application.onConnect = function(client){ 
    this.acceptConnection(client);  
    testStats();     
};

Availability

Flash Communication Server 1.5

Availability

Flash Communication Server 1

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

Availability

Flash Communication Server 1

Example

application.onAppStart = function (){ 
    trace ("*** sample_guestbook application start"); 
 
    // Create a reference to a persistent shared object. 
    application.entries_so = SharedObject.get("entries_so", true); 
     
    // Prevent clients from updating the shared object. 
    application.entries_so.lock(); 
     
    // Get the number of entries saved in the shared object 
    // and save it in application.lastEntry.         
    var maxprop = 0; 
    var soProperties = application.entries_so.getPropertyNames(); 
    trace("soProperties:" + soProperties); 
    if (soProperties == null) { 
        application.lastEntry = 0; 
    } else { 
        for (var prop in soProperties) { 
            maxprop = Math.max (parseInt(prop), maxprop); 
            trace("maxprop " + maxprop); 
        } 
        application.lastEntry = maxprop+1; 
    } 
    // Allow clients to update the shared object. 
    application.entries_so.unlock(); 
    trace("*** onAppStart called."); 
};

Availability

Flash Communication Server 1

Parameters

info

An Object, called an information object, with properties that explain why the application is about to stop running. The information object has a code property and a level property.

Code property	Level property	Description
Application.Shutdown	status	The application instance is about to shut down.
Application.GC	status	The application instance is about to be destroyed by the server.

Returns

The value returned by the function you define, if any, or null. To unload the application, return true or any non-false value. To refuse to unload the application, return false.

Example

The following example flushes the entries_so shared object when the application stops:

application.onAppStop = function (info){ 
    trace("*** onAppStop called."); 
    if (info=="Application.Shutdown"){ 
        application.entries_so.flush(); 
    } 
}

Availability

Flash Communication Server 1

Parameters

clientObj

A Client object. This object contains information about the client that is connecting to the application.

p1 ..., pN

Optional parameters passed to the application.onConnect() handler from the client-side NetConnection.connect() method when a client connects to the application.

Returns

A boolean value; true causes the server to accept the connection; false causes the server to reject the connection.

When true is returned, NetConnection.onStatus() is invoked on the client with info.code set to "NetConnection.Connect.Success". When false is returned, NetConnection.onStatus() is invoked on the client with info.code set to "NetConnection.Connect.Rejected".

If null or no value is returned, 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() in the application.onConnect() event handler. If you do, any value returned by the function is ignored.

View full size graphic

A.

Client-side ActionScript

B.

Server-Side ActionScript

Example

The following examples show three ways to accept or reject a connection in the onConnect() handler:

(Usage 1) 
application.onConnect = function (clientObj [, p1, ..., pN]){ 
    // Insert code here to call methods that do authentication. 
    // Returning null puts the client in a pending state. 
    return null;  
}; 
(Usage 2) 
application.onConnect = function (clientObj [, p1, ..., pN]){ 
    // Insert code here to call methods that do authentication. 
    // The following code accepts the connection: 
    application.acceptConnection(clientObj); 
}; 
(Usage 3) 
application.onConnect = function (clientObj [, p1, ..., pN]) 
{ 
    // Insert code here to call methods that do authentication. 
    // The following code accepts the connection by returning true: 
    return true; 
};

The following 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); 
    } else { 
        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.application.message){ 
    trace(info.application.message); 
    // Prints "Invalid password" 
    // in the Output panel on the client side. 
};

Availability

Flash Media Server (with version 2 media components only).

Parameters

clientObj

A Client object; the client connecting to the application.

p1, ..., pN

Optional parameters passed to the application.onConnectAccept() method. These parameters are passed from the client-side NetConnection.connect() method when a client connects to the application; they can be any ActionScript data type.

Example

The following example is client-side code:

nc = new NetConnection(); 
nc.connect("rtmp:/test","jlopes"); 
 
nc.onStatus = function(info) { 
    trace(info.code); 
}; 
 
nc.doSomething = function(){ 
    trace("doSomething called!"); 
}

The following example is server-side code:

// When using components, always load components.asc. 
load("components.asc"); 
 
application.onConnect = function(client, username){ 
    trace("onConnect called"); 
        gFrameworkFC.getClientGlobals(client).username = username; 
    if (username == "hacker") { 
        application.rejectConnection(client); 
    }  
    else { 
        application.acceptConnection(client); 
    } 
} 
 
// Code is in onConnectAccept and onConnectReject statements 
// because components are used. 
application.onConnectAccept = function(client, username){ 
    trace("Connection accepted for "+username); 
    client.call("doSomething",null); 
} 
 
application.onConnectReject = function(client, username){ 
    trace("Connection rejected for "+username); 
}

Availability

Flash Media Server (with version 2 components only)

Parameters

clientObj

A Client object; the client connecting to the application.

p1, ..., pN

Optional parameters passed to the application.onConnectReject() handler. These parameters are passed from the client-side NetConnection.connect() method when a client connects to the application.

Example

The following example is client-side code that you can use for an application:

nc = new NetConnection(); 
nc.connect("rtmp:/test","jlopes"); 
 
nc.onStatus = function(info) { 
    trace(info.code); 
}; 
 
nc.doSomething = function(){ 
    trace("doSomething called!"); 
}

The following example is server-side code that you can include in the main.asc file:

// When using components, always load components.asc. 
load( "components.asc" ); 
 
application.onConnect = function(client, username){ 
    trace("onConnect called"); 
        gFrameworkFC.getClientGlobals(client).username = username; 
    if (username == "hacker") { 
        application.rejectConnection(client); 
    }  
    else { 
        application.acceptConnection(client); 
    } 
} 
 
application.onConnectAccept = function(client, username){ 
    trace("Connection accepted for "+username); 
    client.call("doSomething",null); 
} 
 
application.onConnectReject = function(client, username){ 
    trace("Connection rejected for "+username); 
}

Availability

Flash Communication Server 1

Parameters

clientObj

A Client object; a client disconnecting from the application.

Returns

Server ignores any return value.

Example

This example notifies all connected clients when a client disconnects from an application. The client-side FLA file contains an input text field called nameText, a dynamic text field called statusText, and a button called connectButton. The user enters their name in the input text field. The client-side code passes the name to the server in the NetConnection.connect() call, as follows:

nc = new NetConnection(); 
nc.userDisconnects = function(name) { 
    statusText.text = name + ": disconnected"; 
} 
nc.onStatus = function(info){ 
    statusText.text = info.code; 
} 
connectButton.onPress = function() { 
    nc.connect("rtmp://localhost/testapp", nameText.text); 
};

The server-side onConnect() handler receives the user name from the client-side code and assigns it to a property of the Client object. The server passes the Client object to the onDisconnect() handler when a client disconnects from the application. The Client.call() method inside the onDisconnect() handler calls the userDisconnects method on the client and passes it the name of the disconnecting client. The client displays the name of the disconnected user.

application.onConnect = function(client, name){ 
    client.name = name; 
    trace(client.name + ": onConnect"); 
    return true; 
} 
application.onDisconnect = function(client){ 
    for (var i = 0; i < application.clients.length; i++){ 
        application.clients[i].call("userDisconnects", null, client.name); 
    } 
    trace(client.name + ": onDisconnect"); 
}

Availability

Flash Media Interactive Server 3 and Flash Media Development Server 3

Parameters

clientObj

A Client object; the client publishing the stream to the application.

streamObj

A Stream object; the stream being published to the application.

Returns

Server ignores any return value.

Availability

Flash Communication Server 1

Parameters

infoObject

An Object with code and level properties that contain information about the status of an application. Some information objects also have details and description properties.The following table describes the information object property values:

Code property	Level property	Description
Application.Script.Error	error	The ActionScript engine has encountered a runtime error. This information object also has the following properties: filename: name of the offending ASC file. lineno: line number where the error occurred. linebuf: source code of the offending line.
Application.Script.Warning	warning	The ActionScript engine has encountered a runtime warning. This information object also has the following properties: filename: name of the offending ASC file. lineno: line number where the error occurred. linebuf: source code of the offending line.
Application.Resource.LowMemory	warning	The ActionScript engine is low on runtime memory. This provides an opportunity for the application instance to free some resources or to take suitable action. If the application instance runs out of memory, it is unloaded and all users are disconnected. In this state, the server does not invoke the application.onDisconnect() event handler or the application.onAppStop() event handler.

Returns

Any value that the callback function returns.

Example

application.onStatus = function(info){ 
    trace("code: " + info.code + " level: " + info.level); 
    trace(info.code + " details: " + info.details); 
}; 
// Application.Script.Warning level: warning

Availability

Flash Media Interactive Server 3 and Flash Media Development Server 3

Parameters

clientObj

A Client object; the client publishing the stream to the application.

streamObj

A Stream object; the stream being published to the application.

Returns

Server ignores any return value.

Availability

Flash Media Interactive Server 3 and Flash Media Development Server 3

Parameters

clientObj

A Client object specifying a client to reject.

url

A string specifying the new connection URL.

Note: If you omit this parameter, rejectConnection() is called instead.

description

A string that lets you provide more information when a connection is redirected.

errorObj

An object of any type that is sent to the client, explaining the reason for rejection. The errorObj object is available in client-side scripts as the application property of the information object that is passed to the NetConnection.onStatus() call when the connection is rejected.

Example

The following example is server-side code:

application.onConnect = function(clientObj, count){ 
    var err = new Object(); 
    err.message = "This is being rejected"; 
    err.message2 = "This is the second message. with number description"; 
    if (count == 1){ 
        redirectURI = "rtmp://www.example.com/redirected/fromScript"; 
        redirectDescription = "this is being rejected via Server Side Script."; 
    } 
    else if (count == 2){ 
        redirectURI = "rtmp://www.example2.com/redirected/fromScript"; 
        redirectDescription = "this is being rejected via Server Side Script.";     
    } 
    application.redirectConnection(clientObj, redirectURI, redirectDescription, err);     
}

The following example is client-side ActionScript 3.0 code:

var theConnection:NetConnection; 
var theConnection2:NetConnection; 
var client:Object = new Object(); 
 
function init():void{ 
    connect_button.label = "Connect"; 
    disconnect_button.label = "Disconnect"; 
     
    connect_button.addEventListener(MouseEvent.CLICK, buttonHandler); 
    disconnect_button.addEventListener(MouseEvent.CLICK, buttonHandler); 
} 
 
function buttonHandler(event:MouseEvent){ 
    switch (event.target){ 
        case connect_button : 
            doConnect(); 
            break; 
        case disconnect_button : 
            disConnect(); 
            break; 
    } 
} 
function doConnect(){ 
    makeConnection(theURI.text); 
} 
 
 
function disConnect(){ 
    theConnection.close(); 
}to 
 
function makeConnection(uri:String){ 
    if (theConnection){ 
        theConnection.close(); 
    } 
    theConnection = new NetConnection(); 
    theConnection.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler); 
    theConnection.client = client; 
    theConnection.connect(uri); 
} 
 
function makeConnection2(uri:String){ 
    if (theConnection2){ 
        theConnection2.close(); 
    } 
    theConnection2 = new NetConnection(); 
    theConnection2.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler); 
    theConnection2.client = client; 
    theConnection2.connect(uri); 
} 
 
function netStatusHandler(event:NetStatusEvent):void{ 
//Check the Redirect code and make connection to redirect URI if appropriate. 
    try{ 
        if (event.info.ex.code == 302){ 
            var redirectURI:String; 
            redirectURI = event.info.ex.redirect; 
            if (redirectURI.charCodeAt(redirectURI.length-1) == 13){ 
                redirectURI = redirectURI.slice(0,(redirectURI.length-1)); 
            } 
            makeConnection2(redirectURI); 
        } 
    } 
} 
 
init();

Availability

Flash Communication Server 1

Parameters

className

A string indicating the name of an ActionScript class.

constructor

A constructor function used to create an object of a specific class type during object deserialization. The name of the constructor function must be the same as className. During object serialization, the name of the constructor function is serialized as the object’s type. To unregister the class, pass the value null as the constructor parameter. Serialization is the process of turning an object into something that you can send to another computer over the network.

Example

The following 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(value){ 
    this.red = value; 
} 
Color.prototype.setGreen = function(value){ 
    this.green = value; 
} 
Color.prototype.setBlue = function(value){ 
    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(); 
// Set constructor back to that of B. 
B.prototype.constructor = B; 
// Insert code here. 
application.registerClass("B", B); 

Availability

Flash Communication Server 1

Parameters

methodName

A string indicating the name of a method. All requests to execute methodName for this application instance are forwarded to the proxyConnection object.

proxyConnection

A Client or NetConnection object. All requests to execute the remote method specified by methodName are sent to the Client or NetConnection object specified in the proxyConnection parameter. Any result returned is sent back to the originator of the call. To unregister or remove the proxy, provide a value of null for this parameter.

proxyMethodName

A string indicating the name of a method for the server to call on the object specified by the proxyConnection parameter if proxyMethodName is different from the method specified by the methodName parameter. This is an optional parameter.

Returns

A value that is sent back to the client that made the call.

Example

In the following example, the application.registerProxy() method is called in a function in the application.onAppStart() event handler and is executed when the application starts. In the function block, a new NetConnection object called myProxy is created and connected. The application.registerProxy() method is then called to assign the method getXyz() to the myProxy object.

application.onAppStart = function(){ 
    var myProxy = new NetConnection(); 
    myProxy.connect("rtmp://xyz.com/myApp"); 
    application.registerProxy("getXyz", myProxy); 
}; 

Availability

Flash Communication Server 1

Parameters

clientObj

A Client object specifying a client to reject.

description

A string that allows you to provide more information when a connection is redirected.

errObj

An object of any type that is sent to the client, explaining the reason for rejection. The errObj object is available in client-side scripts as the application property of the information object that is passed to the NetConnection.onStatus() call when the connection is rejected.

Example

In the following example, the client is rejected and sent an error message. This is the server-side code:

application.onConnect = function(client){ 
    // Insert code here. 
    var error = new Object();error.message = "Too many connections"; 
    application.rejectConnection(client, error); 
};

This is the client-side code:

clientConn.onStatus = function (info){ 
    if (info.code == "NetConnection.Connect.Rejected"){ 
        trace(info.application.message); 
        // Sends the message  
        // "Too many connections" to the Output panel 
        // on the client side. 
    } 
};

Availability

Flash Communication Server 1

Example

The following example checks the server property against a string before executing the code in the if statement:

if (application.server == "Flash Media Server-Windows/1.0"){ 
    // Insert code here. 
}

Availability

Flash Media Server 2

Returns

A boolean value indicating success (true) or failure (false).