Client class

The Client class lets you handle each user, or client, connection to a Flash Media Server application instance. The server automatically creates a Client object when a user connects to an application; the object is destroyed when the user disconnects from the application. Users have unique Client objects for each application to which they are connected. Thousands of Client objects can be active at the same time.

You can use the properties of the Client class to determine the version, platform, and IP address of each client. You can also set individual read and write permissions to various application resources such as Stream objects and shared objects. Use the methods of the Client class to set bandwidth limits and to call methods in client-side scripts.

When you call NetConnection.call() from a client-side ActionScript script, the method that is executed in the server-side script must be a method of the Client class. In your server-side script, you must define any method that you want to call from the client-side script. You can also call any methods that you define in the server-side script directly from the Client class instance in the server-side script.

If all instances of the Client class (each client in an application) require the same methods or properties, you can add those methods and properties to the class itself instead of adding them to each instance of a class. This process is called extending a class. To extend a class, instead of defining methods in the constructor function of the class or assigning them to individual instances of the class, you assign methods to the prototype property of the constructor function of the class. When you assign methods and properties to the prototype property, the methods are automatically available to all instances of the class.

The following code shows how to assign methods and properties to an instance of a class. In the application.onConnect() handler, the client instance clientObj is passed to the server-side script as a parameter. You can then assign a property and method to the client instance.

application.onConnect = function(clientObj){ 
    clientObj.birthday = myBDay;  
    clientObj.calculateDaysUntilBirthday = function(){ 
        // Insert code here. 
    } 
};

The previous example works, but must be executed every time a client connects. If you want the same methods and properties to be available to all clients in the application.clients array without defining them every time, assign them to the prototype property of the Client class.

There are two steps to extending a built-in class by using the prototype property. You can write the steps in any order in your script. The following example extends the built-in Client class, so the first step is to write the function that you will assign to the prototype property:

// First step: write the functions. 
 
function Client_getWritePermission(){ 
// The writeAccess property is already built in to the Client class. 
    return this.writeAccess; 
} 
 
function Client_createUniqueID(){ 
    var ipStr = this.ip; 
// The ip property is already built in to the Client class. 
    var uniqueID = "re123mn" 
// You would need to write code in the above line 
// that creates a unique ID for each client instance. 
    return uniqueID; 
} 
 
// Second step: assign prototype methods to the functions. 
 
Client.prototype.getWritePermission = Client_getWritePermission; 
Client.prototype.createUniqueID = Client_createUniqueID; 
 
// A good naming convention is to start all class method  
// names with the name of the class followed by an underscore.

You can also add properties to prototype, as shown in the following example:

Client.prototype.company = "Adobe";

The methods are available to any instance, so within application.onConnect(), which is passed a clientObj parameter, you can write the following code:

application.onConnect = function(clientObj){ 
    var clientID = clientObj.createUniqueID(); 
    var clientWritePerm = clientObj.getWritePermission(); 
};

Availability

Flash Communication Server 1

Property summary

Property	Description
`Client.agent`	Read-only; the version and platform of the client.
`Client.audioSampleAccess`	Enables Flash Player to access raw, uncompressed audio data from streams in the specified folders.
`Client.farAddress`	Read-only; the derived address from which the server sees the client connection originate.
`Client.farID`	Read-only; a String identifying the RTMFP identity of the server.
`Client.farNonce`	Read-only; a String unique to this client.
`Client.id`	Read-only; a String that uniquely identifies the client.
`Client.ip`	Read-only; a string containing the IP address of the client.
`Client.nearAddress`	Read-only; the public address of the server that the client connected to.
`Client.nearID`	Read-only; a String indicating the RTMFP identity of the server.
`Client.nearNonce`	Read-only.; a String unique to this client.
`Client.pageUrl`	Read-only; a string containing the URL of the web page in which the client SWF file is embedded.
`Client.potentialNearAddresses`	Read-only; the list of all public addresses of the server.
`Client.protocol`	Read-only; a string indicating the protocol used by the client to connect to the server.
`Client.protocolVersion`	Read-only; a string indicating the version of the protocol used by the client to connect to the server.
`Client.readAccess`	A string of directories containing application resources (shared objects and streams) to which the client has read access.
`Client.referrer`	Read-only; a string containing the URL of the SWF file or the server in which this connection originated.
`Client.reportedAddresses`	Read-only; an Array of addresses as Strings of all local addresses at which it can receive RTMFP traffic.
`Client.secure`	Read-only; a boolean value that indicates whether this is an SSL connection (`true`) or not (`false`).
`Client.uri`	Read-only; the URI specified by the client to connect to this application instance.
`Client.videoSampleAccess`	Enables Flash Player to access raw, uncompressed video data from streams in the specified folders.
`Client.virtualKey`	A virtual mapping for clients connecting to the server.
`Client.writeAccess`	Provides write access to directories that contain application resources (such as shared objects and streams) for this client.

Method summary

Method	Description
`Client.call()`	Executes a method on a client or on another server.
`Client.checkBandwidth()`	Call this method from a client-side script to detect bandwidth.
`Client.getBandwidthLimit()`	Returns the maximum bandwidth that the client or the server can use for this connection.
`Client.getStats()`	Returns statistics for the client.
`Client.introducePeer()`	Passes the address for an initiating peer and the tag for its introduction request targeting this client, causing the client to open its end of a P2P connection back to the initiating peer.
`Client.ping()`	Sends a ”ping“ message to the client and waits for a response.
`Client.remoteMethod()`	Invoked when a client or another server calls the NetConnection.call() method.
`Client.__resolve()`	Provides values for undefined properties.
`Client.setBandwidthLimit()`	Sets the maximum bandwidth for this client from client to server, server to client, or both.

Event summary

Method	Description
`Client.onFarAddressChange()`	Invoked when a client's far address has changed.
`Client.onGroupLeave`	Invoked when a client leaves a NetGroup.
`Client.onGroupJoin`	Invoked with a client joins a NetGroup.
`Client.onReportedAddressChange()`	Invoked when a client reports new addresses.

Client.agent

clientObject.agent

Read-only; the version and platform of the client.

When a client connects to the server, the format of Client.agent is as follows:

Operating_System Flash_Player_Version

For example, if Flash Player version 9.0.45.0 is running on Windows®, the value of Client.agent is:

"WIN 9,0,45,0".

When a connection is made to another Flash Media Server, the format of Client.agent is as follows:

Server_Name/Server_Version Operating_System/Operating_System_Build

For example, if the server version is 3.0.0 and it’s running on Windows Server® 2003, the value of Client.agent is:

"FlashCom/3.0.0 WIN/5.1.2600".

Availability

Flash Communication Server 1

Example

The following example checks the agent property against the string "WIN" and executes different code depending on whether they match. This code is written in an onConnect() function:

function onConnect(newClient, name){ 
    if (newClient.agent.indexOf("WIN") > -1){ 
        trace ("Window user"); 
    }    else { 
        trace ("non Window user.agent is" + newClient.agent); 
    } 
}

Client.audioSampleAccess

clientObject.audioSampleAccess

Enables Flash Player to access raw, uncompressed audio data from streams in the specified folders.

Call the SoundMixer.computeSpectrum() method in client-side ActionScript 3.0 to read the raw sound data for a waveform that is currently playing. For more information, see the SoundMixer.computeSpectrum() entry in the ActionScript 3.0 Language and Components Reference and “Accessing raw sound data” in Programming ActionScript 3.0.

Availability

Flash Media Server 3

Example

The following server-side code sets the audioSampleAccess directory to publicdomain:

application.onConnect = function(client) { 
 
        // Anyone can play free content, which is all streams placed under the  
        // samples/, publicdomain/ and contrib/ folders. 
    client.readAccess = "samples;publicdomain;contrib"; 
 
        // Paying customers get to watch more streams. 
        if ( isPayingCustomer(client)) 
        client.readAccess += "nonfree;premium"; 
 
        // Content can be saved (user recorded streams) to contrib/ folder. 
    client.writeAccess = "contrib"; 
 
        // Anyone can gain access to an audio snapshot of the publicdomain/ folder. 
    client.audioSampleAccess = "publicdomain"; 
 
        // Paying customers can also get a video snapshot of the publicdomain/ folder. 
    if (isPayingCustomer(client)) 
        client.videoSampleAccess = "publicdomain"; 
}

Client.call()

clientObject.call(methodName, [resultObj, [p1, ..., pN]])

Executes a method in client-side code or on another server. The remote method can return data to the resultObj parameter, if provided. Whether the remote agent is a client or another server, the method is called on the remote agent’s NetConnection object.

In ActionScript 2.0, define the method on the NetConnection object. In ActionScript 3.0, assign the NetConnection.client property to an object on which callback methods are invoked. Define the method on that object.

Availability

Flash Communication Server 1

Parameters

methodName: A string indicating a remote method. The string uses the form "[objectPath/]method". For example, the string "someObj/doSomething" tells the client to invoke the NetConnection.someObj.doSomething() method on the client or remote server. The string "doAction" calls the doAction() method on the client or remote server.
resultObj: An Object. This is an optional parameter that is required when the sender expects a return value from the client. If parameters are passed but no return value is desired, pass the value null. The result object can be any object that you define. To be useful, it should have two methods that are invoked when the result arrives: onResult() and onStatus(). The resultObj.onResult() event is triggered if the invocation of the remote method is successful; otherwise, the resultObj.onStatus() event is triggered.
p1, ..., pN: Optional parameters that can be of any ActionScript type, including a reference to another ActionScript object. These parameters are passed to the methodName parameter when the method is executed on the Flash client. If you use these optional parameters, you must pass in some value for resultObj; if you do not want a return value, pass null.

Returns

A boolean value of true if a call to methodName was successful on the client; otherwise, false.

Example

The following ActionScript 2.0 example shows a client-side script that defines a function called getNumber() that generates a random number:

nc = new NetConnection(); 
nc.getNumber = function(){ 
    return (Math.random()); 
}; 
nc.connect("rtmp:/clientCall");

The following is the same code in ActionScript 3.0:

var nc:NetConnection = new NetConnection() 
var ncClient = new Object(); 
nc.client = ncClient; 
ncClient.getNumber = nc_getNumber; 
function nc_getNumber():void{ 
    return (Math.random()); 
}

The following server-side script calls Client.call() in the application.onConnect() handler to call the getNumber() method that was defined on the client. The server-side script also defines a function called randHander(), which is used in the Client.call() method as the resultObj parameter.

randHandler = function(){ 
    this.onResult = function(res){ 
        trace("Random number: " + res); 
    } 
    this.onStatus = function(info){ 
        trace("Failed with code:" + info.code); 
    } 
}; 
application.onConnect = function(clientObj){ 
    trace("Connected"); 
    application.acceptConnection(clientObj); 
    clientObj.call("getNumber", new randHandler()); 
};

Note: This example does not work with version 2 components. For an example of calling Client.call() when using version 2 components, see application.onConnectAccept().

Client.checkBandwidth()

clientObject.checkBandwidth()

Note: This method is not supported over RTMFP connections.

Call this method from a client-side script to detect client bandwidth. If the client is connected directly to the origin server, bandwidth detection occurs on the origin. If the client is connected to the origin server through an edge server, bandwidth detection happens at the first edge to which the client connected.

To use this method to detect client bandwidth, define onBWDone() and onBWCheck() methods in a client-side script. For more information, see the Adobe Flash Media Server Developer Guide.

Note: If you define the checkBandwidth() function in a server-side script, the client call runs your definition instead of the definition in the core server code.

Availability

Flash Media Server 3

Client.farAddress

clientObject.farAddress

Read-only. The address from which the server sees the client connection originate. This value is different than Client.ip because the value of Client.farAddress contains both the IP address and port number for the connection. This property is called the far address because from the perspective of the server, the address is on the far side of the NAT or firewall.

Availability

Flash Media Server 4.5

Client.farID

clientObject.farId

Read-only. A String identifying the RTMFP identity of the client. This property has the same value as the ActionScript 3.0 NetConnection.nearID property. This property is meaningful only for RTMFP connections.

Availability

Flash Media Server 4

Client.farNonce

clientObject.farNonce

Read-only. A String unique to this client. This value is defined for RTMFP, RTMPE, and RTMPTE connections.

Availability

Flash Media Server 4

Client.getBandwidthLimit()

clientObject.getBandwidthLimit(iDirection)

Note: This method is not supported over RTMFP connections.

Returns the maximum bandwidth that the client or the server can use for this connection. Use the iDirection parameter to get the value for each direction of the connection. The value returned indicates bytes per second and can be changed with the Client.setBandwidthLimit() method. Set the default value for a connection in the Application.xml file of each application.

You can call this method from a client-side script. Call the NetConnection.call() method and pass it the name of the method, a result object, and any arguments, as in the following:

var re:Responder = new Responder(res); 
function res(info) {     
     trace(info); 
     for (var i:String in info) { trace(i + " - " + info[i]); } 
} 
nc.call("getBandwidthLimit", re, 0);

Availability

Flash Communication Server 1

Parameters

iDirection: A number specifying the connection direction. The value 0 indicates a client-to-server direction; 1 indicates a server-to-client direction.

Returns

A number.

Example

The following example uses Client.getBandwidthLimit() to set the variables clientToServer and serverToClient:

application.onConnect = function(newClient){ 
    var clientToServer= newClient.getBandwidthLimit(0);var serverToClient= newClient.getBandwidthLimit(1);  
};

Client.getStats()

clientObject.getStats()

Returns statistics for the client.

You can call this method from a client-side script. Call the NetConnection.call() method and pass it the name of the method, a result object, and any arguments, as in the following:

var re:Responder = new Responder(res); 
function res(info) {     
     trace(info); 
     for (var i:String in info) { trace(i + " - " + info[i]); } 
} 
nc.call("getStats", re);

Availability

Flash Communication Server 1

Returns

An Object with various properties for each statistic returned. The following table describes the properties of the returned object:

Property	Description
`bytes_in`	Total number of bytes received by this application instance.
`bytes_out`	Total number of bytes sent from this application instance.
`msg_in`	Total number of RTMP messages received.
`msg_out`	Total number of RTMP messages sent.
`msg_dropped`	Total number of dropped RTMP messages.
`ping_rtt`	Length of time the client takes to respond to a ping message.
`audio_queue_msgs`	Current number of audio messages in the queue waiting to be delivered to the client.
`video_queue_msgs`	Current number of video messages in the queue waiting to be delivered to the client.
`so_queue_msgs`	Current number of shared object messages in the queue waiting to be delivered to the client.
`data_queue_msgs`	Current number of data messages in the queue waiting to be delivered to the client.
`dropped_audio_msgs`	Number of audio messages that were dropped.
`dropped_video_msgs`	Number of video messages that were dropped.
`audio_queue_bytes`	Total size of all audio messages (in bytes) in the queue waiting to be delivered to the client.
`video_queue_bytes`	Total size of all video messages (in bytes) in the queue waiting to be delivered to the client.
`so_queue_bytes`	Total size of all shared object messages (in bytes) in the queue waiting to be delivered to the client.
`data_queue_bytes`	Total size of all data messages (in bytes) in the queue waiting to be delivered to the client.
`dropped_audio_bytes`	Total size of all audio messages (in bytes) that were dropped.
`dropped_video_bytes`	Total size of all video messages (in bytes) that were dropped.
`bw_out`	Current downstream bandwidth (outbound from the server).
`bw_in`	Current upstream bandwidth (inbound to the server) .
`client_id`	A unique ID issued by the server for this client.

Example

The following example outputs a client’s statistics:

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

Client.id

clientObject.id

Read-only; a string that uniquely identifies the client.

Availability

Flash Media Server 3

Example

The following onConnect() function traces the ID of the connecting client:

application.onConnect(newClient) { 
    trace(newClient.id); 
}

Client.introducePeer()

clientObject.introducePeer(initiatorAddress:String, tag:ByteArray)

Opens a peer-to-peer connection with a peer that requested a connection. The peer that requests the connection is called the initiating peer. The initiating peer requests a connection with a target peer. To open the connection, the target peer calls this method and passes the address for the initiating peer and the tag for the introduction request.

Call this method to Distribute peer introductions across multiple servers.

Availability

Flash Media Server 4.5

Parameters

initiator: String. The address that the lookup request of the initiating peer came from.
tag: ByteArray. The tag identifying the specific lookup request issued by the initiating peer. This value must be handed back in order for the initiating peer to properly correlate and associate the connection attempt from this client to it.

Returns

Nothing.

Client.ip

clientObject.ip

Read-only; A string containing the IP address of the client.

Availability

Flash Communication Server 1

Example

The following example uses the Client.ip property to verify whether a new client has a specific IP address. The result determines which block of code runs.

application.onConnect = function(newClient, name){ 
    if (newClient.ip == "127.0.0.1"){ 
        // Insert code here. 
    } else { 
        // Insert code here. 
    } 
};

Client.nearAddress

clientObject.nearAddress

Read-only. The public address the client connected to on the server. This address is public, it is not a behind NAT or firewall. This is essential information to generate peer redirects when distributing introductions across multiple servers. The redirect address set must contain known addresses for the target peer as well as the public server address the target peer is connected to. It is called the near address because from the perspective of the server it is on the near side of the NAT or firewall.

See Distribute peer introductions across multiple servers.

Availability

Flash Media Server 4.5

Client.nearID

nc.nearId

Read-only. A String indicating the RTMFP identity of the server to which the client is connected. This property has the same value as the ActionScript 3.0 NetConnection.farID property. This property is meaningful only for RTMFP connections.

Availability

Flash Media Server 4

Client.nearNonce

nc.nearNonce

Read-only. A String unique to this client. This value appears to another server as its Client.farNonce value. This value is defined for RTMFP, RTMPE, and RTMPTE connections.

Availability

Flash Media Server 4

Client.onFarAddressChange()

client.onFarAddressChange = function(){}

Invoked when the farAddress of a client has changed. For example, a far address changes when a client transitions from a LAN to a wireless connection. RTMFP supports connection mobility so the farAddress for a client can change without the connection having to disconnect and reconnect.

Use this event to store a list of client far addresses in a global registry or shared datastore to support distributed peer lookups. See Distribute peer introductions across multiple servers.

Availability

Flash Media Server 4.5

Client.onGroupLeave

client.onGroupLeave = function(groupspecDigest:String){}

Invoked when a client with an open server channel leaves a group or disconnects.

Availability

Flash Media Server 4.5

Parameters

groupspecDigest: A String. The groupspec digest for the group the client is leaving.

Client.onGroupJoin

client.onGroupJoin = function(groupcontrol:GroupControl){}

Invoked when a client with an open server channel joins a group.

Availability

Flash Media Server 4.5

Parameters

groupcontrol: A GroupControl object. The control object representing this Client's membership within a group..

Example

var groups = {}; 
 
Client.prototype.onGroupJoin = function(groupControl) 
{ 
    groupControl["client"] = this; // Remember the associated Client. 
    var groupControlArray = groups[groupControl.groupspecDigest]; 
    if (groupControlArray) 
    { 
        trace("Register Client in existing Group (by groupspec digest): " + 
              groupControl.groupspecDigest + 
              ", current Group size is: " + 
              groupControlArray.length); 
 
        // find a random member to bootstrap with 
        r = Math.random(); 
        index = Math.floor(r * groupControlArray.length); 
 
        var peerGroupControl = groupControlArray[index]; 
        groupControl.addNeighbor(peerGroupControl["client"].farID); 
        groupControlArray.push(groupControl); 
    } 
    else 
    { 
        trace("Track client joining new Group (by groupspec digest): " + groupControl.groupspecDigest); 
 
        groupControlArray = []; 
        groupControlArray.push(groupControl); 
        groups[groupControl.groupspecDigest] = groupControlArray; 
    } 
}

Client.onReportedAddressChange()

client.onReportedAddressChange = function(){}

Invoked when a client reports new addresses.

Use this event to store a list of client addresses in a global registry or shared datastore to support distributed peer lookups. See Distribute peer introductions across multiple servers.

Availability

Flash Media Server 4.5

Example

client.onReportedAddressesChange = function() { 
    var newReportedAddresses = this.reportedAddresses; 
    // Now store these in a global registry or shared datastore to support distributed scripted peer lookups. 
    // ... 
}

Client.pageUrl

clientObject.pageUrl

Read-only; A string containing the URL of the web page in which the client SWF file is embedded. If the SWF file isn’t embedded in a web page, the value is the location of the SWF file. The following code shows the two examples:

// trace.swf file is embedded in trace.html. 
client.pageUrl: http://www.example.com/trace.html 
 
// trace.swf is not embedded in an html file. 
client.pageUrl: http://www.example.com/trace.swf

The value cannot be a local file address.

Availability

Flash Media Server 2

Example

The following example uses the Client.pageUrl property to verify whether a new client is located at a particular URL. The result determines which block of code runs.

application.onConnect = function(newClient){ 
    if (newClient.pageUrl == "http://www.example.com/index.html"){ 
        return true; 
    } else { 
        return false; 
    } 
};

Client.ping()

clientObject.ping()

Sends a “ping” message to the client and waits for a response. If the client responds, the method returns true; otherwise, false. Use this method to determine whether the client connection is still active.

Availability

Flash Communication Server 1

Example

The following onConnect() function pings the connecting client and traces the results of the method:

application.onConnect(newClient) { 
    if (newClient.ping()){ 
        trace("ping successful"); 
    } 
    else { 
        trace("ping failed"); 
    } 
}

Client.potentialNearAddresses

clientObject.potentialNearAddress

Read-only; the list of all public addresses of the server. The nearAddress is the public address of the interface to which the client is connected. However the potentialNearAdresses is the list of all the public interfaces that may be used to communicate with the server this client is connected to.

Use this property to distribute peer introductions across multiple servers. See Distribute peer introductions across multiple servers.

Availability

Flash Media Server 4.5

Example

The following example outputs all the potential near addresses of the server the client has connected to:

function logAllPotentialNearAddresses(client) { 
    var n = client.potentialNearAddresses.length; 
    trace("Client has " + n + " potential near addresses (at the server-end of its connection)."); 
    for (var i = 0; i < n; ++i) 
        trace("  " + i + " : " + client.potentialNearAddresses[i] + "\n "); 
}

Client.protocol

clientObject.protocol

Read-only; A string indicating the protocol used by the client to connect to the server. This string can have one of the following values:

Protocol	Description
`rtmp`	RTMP over a persistent socket connection.
`rtmpt`	RTMP tunneled over HTTP.
`rtmps`	RTMP over an SSL (Secure Socket Layer) connection.
`rtmpe`	An encrypted RTMP connection.
`rtmpte`	An encrypted RTMP connection tunneled over HTTP.
rtmfp	Real-Time Media Flow Protocol.

Availability

Flash Communication Server 1

Example

The following example checks the connection protocol used by a client upon connection to the application:

application.onConnect(clientObj){ 
    if(clientObj.protocol == "rtmp") { 
        trace("Client connected over RTMP"); 
    } else if(clientOjb.protocol == "rtmpt") { 
        trace("Client connected over RTMP tunneled over HTTP"); 
    } 
}

Client.protocolVersion

clientObject.protocolVersion

Read-only; A string indicating the version of the protocol used by the client to connect to the server. This value matches the value in the c-proto-ver field in the Access log.

See Fields in access logs.

Availability

Flash Media Server 4

Client.readAccess

clientObject.readAccess

Gives clients read access to directories containing shared objects and streams. You cannot specify file names, you can specify only a directory or a path to a directory (for example, "directory" or "directory/subdir/subdir2"). The directory you specify grants read access to that directory and to all its subdirectories. To give a client read access to multiple directories, list the directories in a string delimited by semicolons.

The default value is "/". This value grants read access to the directories in which the server is configured to look for streams and shared objects.

Note: Adobe recommends that you store either streams or shared objects in a directory, but not both.

A directory you specify is relative to the directory in which the server is configured to store streams or shared objects for that application instance. If you use a virtual directory or a storage directory, the readAccess value is relative to that location.

By default, the server stores persistent shared objects in the rootinstalldir\applications\appname\sharedobjects\_definst_ directory.

By default, the server looks for streams for the default application instance in the directory rootinstalldir\applications\appname\streams\_definst_. For example, a client that connects to "rtmp://somefmssever.com/test" looks for streams in the rootinstalldir\applications\test\streams\_definst_ directory. A client that connects to "rtmp://somefmsserver.com/test/room1" looks for streams in the rootinstalldir\applications\test\streams\room1 directory.

Suppose there is a stream called "sample.f4v" in the applications\test\streams\_definst_ directory. In the server-side script, if you give client.readAccess any value other than "/", the stream does not play.

Note: If you specify "\", the script does not run.

Suppose you copy the file sample2.f4v into the directory test/streams/_definst_/protected. In the server-side script, set client.readAccess="protected". In the client-side script, call netstream.play("mp4:protected/sample2.f4v"). The file plays because it’s located in a directory that has read access.

Now call netstream.play("mp4:sample.f4v"). The file does not play because the test/streams/_definst_ directory does not have read access.

Availability

Flash Communication Server 1

Details

To give a client read access, specify a list of directories (in URI format), delimited by semicolons. Any files or directories within a specified URI are also considered accessible. For example, if you specify "myMedia", any files or directories in the myMedia directory are also accessible (for example, myMedia/mp3s). Any files or directories in the myMedia/mp3s directory are also accessible, and so on.

Clients with read access to a directory that contains streams can play the streams. Clients with read access to a directory that contains shared objects can subscribe to the shared objects and receive notification of changes in the shared objects.

For streams, readAccess controls the streams that the connection can play.
For shared objects, readAccess controls whether the connection can listen to shared object changes.

To control access for a particular file, create a separate directory for the file and set readAccess to that directory.

Note: You cannot set this property in the application.onPublish() event.

Example

The following code is for an application called “fmsapp”. It gives clients read access to all files in the folders mymedia/mp3s and mydata/notes. The clients also have read access to any files in subfolders of those folders.

application.onConnect = function(newClient, name){ 
    newClient.readAccess = "mymedia/mp3s;mydata/notes"; 
};

Clients that connect to an instance of the application “fmsapp” can play streams in the folder rootinstall/applications/fmsapp/streams/instancename/mymedia/mp3s and all its subfolders. Those clients can listen for changes to shared objects in the folder rootinstall/applications/fmsapp/sharedobjects/instancename/mydata/notes and all its subfolders.

Client.referrer

clientObject.referrer

Read-only; A string containing the URL of the SWF file or the server in which this connection originated. The property is set when a SWF hosted on a web server or connects to an application on Flash Media Server. The property is also set when one Flash Media Server connects to another.

This property is not set when a SWF from a local file system running in stand-alone Flash Player version 10 or above connects to Flash Media Server. If a SWF file is running in standalone Flash Player version 8 or 9, the property is set as file:///....

Availability

Flash Communication Server 1

Example

application.onConnect = function(newClient, name){ 
    trace("New user connected to server from" + newClient.referrer);  
};

Client.remoteMethod()

myClient.remoteMethod = function([p1, ..., pN]){}

You can define methods on the Client object and call the methods from client-side code. To call methods from client-side code, call the NetConnection.call() method and pass it the name of the method you defined. The server searches the Client object instance for the method. If the method is found, it is invoked and the return value is sent back to the result object specified in the call to NetConnection.call().

Availability

Flash Communication Server 1

Parameters

p1, ..., pN: Optional parameters passed to the NetConnection.call() method.

Example

The following example creates a method called sum() as a property of the Client object newClient on the server side:

Client.prototype.sum = function(op1, op2){ 
    return op1 + op2; 
};

You can call the server-side sum() method from a client-side call to the NetConnection.call() method:

nc = new NetConnection(); 
nc.connect("rtmp://myServer/myApp"); 
nc.call("sum", new result(), 20, 50); 
function result(){ 
    this.onResult = function (retVal){ 
        output += "sum is " + retVal; 
    }; 
    this.onStatus = function(errorVal){ 
        output += errorVal.code + " error occurred"; 
    }; 
}

You can also call the sum() method in server-side code:

newClient.sum();

The following example creates two functions that you can call from either a client-side or server-side script:

application.onConnect = function(clientObj) { 
    // The function foo returns 8.  
    clientObj.foo = function() {return 8;}; 
    // The function bar is defined outside the onConnect call.  
    clientObj.bar = application.barFunction;  
};  
// The bar function adds the two values it is given.  
application.barFunction = function(v1,v2) { 
    return (v1 + v2);  
};

You can call either of the two functions that were defined in the previous example (foo and bar) by using the following code in a client-side script:

c = new NetConnection();  
c.call("foo");  
c.call("bar", null, 1, 1);

You can call either of the two functions that were defined in the previous example (foo and bar) by using the following code in a server-side script:

c = new NetConnection();  
c.onStatus = function(info) { 
    if(info.code == "NetConnection.Connect.Success") { 
        c.call("foo");  
        c.call("bar", null, 2, 2);  
    }  
};

Client.reportedAddresses

clientObject.reportedAddresses

Read-only; an Array of Strings containing all the addresses at which a client can receive RTMFP traffic. The client can update this value multiple times over the lifetime of its RTMFP connection to the server.

There is a small time lag between when the client is connected and when it reports its IP addresses. The time lag is usually a few hundred milliseconds. When the server receives the reported addresses from the client, it gets an Client.onReportedAddressChange() event. The reported addresses are valid only after the first onReportedAddressChange() event.

Use this property to distribute peer introductions across multiple servers. See Distribute peer introductions across multiple servers.

Availability

Flash Media Server 4.5

Example

The following function outputs a list of all the reported addresses for a client:

function logReportedAddresses(client) { 
    var n = client.reportedAddresses.length; 
    trace("Client has reported " + n + " addresses."); 
    for (var i = 0; i < n; ++i) 
        trace("  " + i + ": " + client.reportedAddresses[i]); 
}

Client.__resolve()

Client.__resolve = function(propName){}

Provides values for undefined properties. When an undefined property of a Client object is referenced by Server-Side ActionScript code, the Client object is checked for a _resolve() method. If the object has a _resolve() method, it is invoked and passed the name of the undefined property. The return value of the _resolve() method is the value of the undefined property. In this way, _resolve() can supply the values for undefined properties and make it appear as if they are defined.

Availability

Flash Communication Server 1

Parameters

propName: A string indicating the name of an undefined property.

Returns

The value of the property specified by the propName parameter.

Example

The following example defines a function that is called whenever an undefined property is referenced:

Client.prototype.__resolve = function (name) { 
    return "Hello, world!"; 
}; 
function onConnect(newClient){ 
// Prints "Hello World". 
    trace (newClient.property1);  
}

Client.secure

clientObject.secure

Read-only; A boolean value that indicates whether this is an SSL connection (true) or not (false).

Availability

Flash Media Server 2

Client.setBandwidthLimit()

clientObject.setBandwidthLimit(iServerToClient, iClientToServer)

Note: This method is not supported over RTMFP connections.

Sets the maximum bandwidth for this client from client to server, server to client, or both. The default value for a connection is set for each application in the Client section of the Application.xml file. The value specified cannot exceed the bandwidth cap value specified in the Application.xml file. For more information, see BandwidthCap in the Adobe Flash Media Server Configuration and Administration Guide.

You can call this method from a client-side script. Call the NetConnection.call() method and pass it the name of the method, a result object, and any arguments, as in the following:

var re:Responder = new Responder(res); 
function res(info) {     
     trace(info); 
     for (var i:String in info) { trace(i + " - " + info[i]); } 
} 
nc.call("setBandwidthLimit", re, 125000, 125000);

Availability

Flash Communication Server 1

Parameters

iServerToClient: A number; the bandwidth from server to client, in bytes per second. Use 0 if you don’t want to change the current setting.
iClientToServer: A number; the bandwidth from client to server, in bytes per second. Use 0 if you don’t want to change the current setting.

Example

The following example sets the bandwidth limits for each direction, based on values passed to the onConnect() function:

application.onConnect = function(newClient, serverToClient, clientToServer){ 
    newClient.setBandwidthLimit(serverToClient, clientToServer); 
    application.acceptConnection(newClient); 
}

Client.uri

clientObject.uri

Read-only; the URI specified by the client to connect to this application instance.

Availability

Flash Media Server 2

Example

The following example defines an onConnect() callback function that sends a message indicating the URI that the new client used to connect to the application:

application.onConnect = function(newClient, name){ 
    trace("New user requested to connect to " + newClient.uri);  
};

Client.videoSampleAccess

clientObject.videoSampleAccess

Enables Flash Player to access raw, uncompressed video data from streams in the specified folders.

Call the BitmapData.draw() method in client-side ActionScript 3.0 to read the raw data for a stream that is currently playing. For more information, see the BitmapData.draw() entry in ActionScript 3.0 Language and Components Reference.

Availability

Flash Media Server 3

Example

The following server-side code sets the videoSampleAccess directory to publicdomain for paying customers:

application.onConnect = function(client) { 
 
        // Anyone can play free content, which is all streams placed under the  
        // samples/, publicdomain/, and contrib/ folders. 
    client.readAccess = "samples;publicdomain;contrib"; 
 
        // Paying customers get to watch more streams. 
        if ( isPayingCustomer(client)) 
        client.readAccess += "nonfree;premium"; 
 
        // Content can be saved (user recorded streams) to the contrib/ folder. 
    client.writeAccess = "contrib"; 
 
        // Anyone can gain access to an audio snapshot of the publicdomain/ folder. 
    client.audioSampleAccess = "publicdomain"; 
 
        // Paying customers can also get a video snapshot of the publicdomain/ folder. 
    if (isPayingCustomer(client)) 
        client.videoSampleAccess = "publicdomain"; 
}

Client.virtualKey

clientObject.virtualKey

Use this property in conjunction with the Stream.setVirtualPath() method to map stream URLs to physical locations on the server. This allows you to serve different content to different versions of Flash Player.

When a client connects, it receives a virtual key that corresponds to ranges that you set in the Vhost.xml file. You can use Client.virtualKey to change that value in a server-side script. The following is the code in the Vhost.xml file that you must configure:

<VirtualKeys> 
    <!-- Create your own ranges and key values.    --> 
    <!-- You can create as many Key elements as you need.    --> 
    <Key from="WIN 7,0,19,0" to="WIN 9,0,0,0">A</Key> 
</VirtualKeys>

Using the previous Vhost.xml file, if a Flash Player 8 client connected to the server, its Client.virtualKey value would be A.

Note: A legal key cannot contain the characters “*” and “:”.

Availability

Flash Media Server 2

Client.writeAccess

clientObject.writeAccess

Provides write access to directories that contain application resources (such as shared objects and streams) for this client. To give a client write access to directories that contain application resources, list directories in a string delimited by semicolons. By default, all clients have full write access, and the writeAccess property is set to slash (/). For example, if myMedia is specified as an access level, then any files or directories in the myMedia directory are also accessible (for example, myMedia/myStreams). Similarly, any files or subdirectories in the myMedia/myStreams directory are also accessible, and so on.

For shared objects, writeAccess provides control over who can create and update the shared objects.
For streams, writeAccess provides control over who can publish and record a stream.

You cannot use this property to control access to a single file. To control access to a single file, create a separate directory for the file.

Don’t precede the stream path with a leading slash (/) on the client side.

Note: You cannot set this property in the application.onPublish() event.

Availability

Flash Communication Server 1

Example

The following example provides write access to the /myMedia/myStreams and myData/notes directories:

application.onConnect = function(newClient, name){ 
    newClient.writeAccess = "/myMedia/myStreams;myData/notes"; 
    application.acceptConnection(); 
};

The following example completely disables write access:

application.onConnect = function(clientObj){ 
    clientObj.writeAccess = ""; 
    return true; 
};

Client class

Availability

Property summary

Method summary

Event summary

Client.agent

Availability

Example

Client.audioSampleAccess

Availability

Example

See also

Client.call()

Availability

Parameters

Returns

Example

Client.checkBandwidth()

Availability

Client.farAddress

Availability

Client.farID

Availability

Client.farNonce

Availability

Client.getBandwidthLimit()

Availability

Parameters

Returns

Example

Client.getStats()

Availability

Returns

Example

Client.id

Availability

Example

Client.introducePeer()

Availability

Parameters

Returns

Client.ip

Availability

Example

Client.nearAddress

Availability

Client.nearID

Availability

Client.nearNonce

Availability

Client.onFarAddressChange()

Availability

Client.onGroupLeave

Availability

Parameters

Client.onGroupJoin

Availability

Parameters

Example

Client.onReportedAddressChange()

Availability

Example

Client.pageUrl

Availability

Example

Client.ping()

Availability

Example

See also

Client.potentialNearAddresses

Availability

Example

Client.protocol

Availability

Example

Client.protocolVersion

Availability

Client.readAccess

Availability

Details