Server-Side Communication ActionScript > Client (object)

Client (object)

The Client object lets you handle each user, or client, connection to a Flash Communication 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 object 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 object to set bandwidth limits and call methods in client-side scripts.

When you call NetConnection.call from a client-side ActionScript script, the method that executes in the server-side script must be a method of the Client object. 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 you define in the server-side script directly from the Client object instance in the server-side script.

If all instances of the Client object (each client in an application) require the same methods or properties, you can add those methods and properties to the class itself instead of adding them to each instance of a class. This process is called extending a class. You can extend any server-side or client-side ActionScript class. To extend a class, instead of defining methods inside 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.

Extending a class lets you define the methods of a class separately, which makes them easier to read in a script. And more importantly, it is more efficient to add methods to prototype, otherwise the methods are reinterpreted each time an instance is created.

The following code shows how to assign methods and properties to an instance of a class. During application.onConnect, a 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 above 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, you must assign them to the prototype property of the Client object There are two steps to extending a built-in class using the prototype method. You can write the steps in any order in your script. The following example extends the built-in Client object, 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(){
// "writeAccess" property is already built-in to the client class
return this.writeAccess;
}

function Client_createUniqueID(){
	var ipStr = this.ip;    
// "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 = "Macromedia";

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

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

 
Method summary for the Client object

Method	Description
Client.call	Executes a method on the Flash client asynchronously and returns the value from the Flash client to the server.
Client.getBandwidthLimit	Returns the maximum bandwidth the client or the server can attempt to use for this connection.
Client.getStats	Returns statistics for the client.
Client.ping	Sends a "ping" message to the client. If the client responds, the method returns true; otherwise it returns false.
Client.__resolve	Provides values for undefined properties.
Client.setBandwidthLimit	Sets the maximum bandwidth for the connection.

 
Property summary for the Client object

Property	Description
Client.agent	The version and platform of the Flash client.
Client.ip	The IP address of the Flash client.
Client.protocol	The protocol used by the client to connect to the server.
Client.readAccess	A list of access levels to which the client has read access.
Client.referrer	The URL of the SWF file or server where this connection originated.
Client.writeAccess	A list of access levels to which the client has write access.

 
Event handler summary for the Client object

Event handler	Description
Client."commandName"	Invoked when NetConnection.call(commandName) is called in a client-side script.