Methods and Properties of ElectroServerAS

And now, without further ado, here is the list of all events and functions that the ElectroServerAS object can perform.

Please note that all of the methods included here are intended to be used with Flash Player 6; the version that supports and correctly interprets them is Flash Player 6.

ElectroServer works with Flash 5 and with Flash MX. However, the ElectroServerAS object works only with Flash MX, because of the function scoping changes that are new to Flash MX.

ElectroServerAS.addToHistory

Usage: ElectroServerAS.addToHistory(message)

Parameters:

message

This parameter is the string to add to the chat history.

Returns: Nothing.

Description: Method; appends a string to the history property, ElectroServerAS.history.

Example: The following line adds a chat message to the history property:

 ElectroServerAS.addToHistory("Anyone for a game of golf?")  

ElectroServerAS.ban

Usage: ElectroServerAS.ban(who, why)

Parameters:	who	This is the user name of the person whom you wish to ban.
	why	This parameter shows the reason why you wish to ban this user.

Returns: Nothing.

Description: Method; disconnects a user from the ElectroServer socket server and bans him or her from connecting from that IP address again. This method is only available to users with administrator-level access. See also ElectroServerAS.login.

Example: The following line bans a user:

 ElectroServerAS.ban("meanie", "Offensive language")  

ElectroServerAS.cancelChallenge

Usage: ElectroServerAS.cancelChallenge()

Parameters: None.

Returns: Nothing.

Description: Method; cancels the challenge request you sent out. The ElectroServerAS.challengeCancelled event is fired on the challengee's side.

ElectroServerAS.challenge

Usage: ElectroServerAS.challenge(who, game)

Parameters:	who	This is the user name of the person whom you wish to challenge.
	game	This parameter is a string that is the name of the game to which you are challenging a user.

Returns: Nothing.

Description: Method; challenges a user to a game. The ElectroServerAS .challengeReceived event is triggered on the challengee's computer. The property ElectroServerAS.challenging is set to true.

Example: The following line is an example of how to challenge a user:

 ElectroServerAS.challenge("jobem","Mini Golf")  

ElectroServerAS.challengeAnswered

Usage: ElectroServerAS.challengeAnswered(which)

Parameters:

which

This is a string value indicating the response from the person challenged ("accepted", "declined", or "autodeclined").

Returns: Nothing.

Description: Method; a callback function invoked by the ElectroServerAS object when a person you have challenged responds to that challenge. If the user accepts your challenge, which is "accepted". If the user declines your challenge, which is "declined". If for any number of reasons the user's Flash client declines your challenge automatically, which is "autodeclined".

Example: The following lines create a function to be called when a challenge request is answered:

 function challengeAnswered(which) {    if (which == "accepted") {       _root.gotoAndStop("game");    } else if (which == "declined") {       trace("declined");    } else if (which == "autodeclined") {       trace("auto declined");    } } ElectroServerAS.challengeAnswered = this.challengeAnswered; 

ElectroServerAS.challengeCancelled

Usage: ElectroServerAS.challengeCancelled

Parameters: None.

Returns: Nothing.

Description: Method; a callback function invoked by the ElectroServerAS object when a challenge request that has been sent to you is cancelled.

ElectroServerAS.challengeReceived

Usage: ElectroServerAS.challengeReceived(who, game)

Parameters:	who	This is the user name of the person who challenged you.
	game	This is the game you were challenged to.

Returns: Nothing.

Description: Method; a callback function invoked by the ElectroServerAS object when a challenge is received. You can be challenged to a game by other users. The who parameter contains the user name of the person who challenged you, and the game parameter contains the name of the game.

ElectroServerAS.challenging

Usage: ElectroServerAS.challenging

Description: Property; this is a Boolean value. If true, then a challenge has been sent and no response has yet been received. If, while this is true, you are challenged, then an automated decline message is sent back to the challenger. If challenging is not true, then you can receive challenges. This property is used internally by the ElectroServerAS object.

ElectroServerAS.chatReceiver

Usage: ElectroServerAS.chatReceiver(info)

Parameters:

info

An object containing the properties from, type, and body.

Returns: Nothing.

Description: Method; a callback function invoked by the ElectroServerAS object when a chat message is received. When this method is called, an object is passed in. The properties of this object are from, type, and body. The from property is the user name of the person who sent the message. The type property is the type of message that arrived. If type is "public", then it is a message to the room; if type is "private", then it is a private message to you. The body property is a string value that contains the chat message.

Example: The following lines create a function that is to be called when a message is received:

 function messageArrived(info) {       var from = info.from;     var type = info.type;    var body = info.body;    if (type == "public") {       var msg = from+": "+body+newline;    } else if (type == "private") {       var msg = from+"(private): "+body+newline;    }    chat.window.text = ES.addToHistory(msg);    chat.bar.setScrollPosition(chat.window.maxscroll); } ElectroServerAS.chatReceiver = this.messageArrived; 

ElectroServerAS.connectToServer

Usage: ElectroServerAS.connectToServer()

Parameters: None.

Returns: Nothing.

Description: Method; this method uses the ElectroServerAS.port and ElectroServerAS.IP properties, and initializes a socket connection with the ElectroServer socket server. See ElectroServerAS.port and ElectroServerAS.IP for more information.

Example: The following line makes a connection with the ElectroServer socket server:

 ElectroServerAS.connectToServer()  

ElectroServerAS.createVariable

Usage: ElectroServerAS.createVariable(name, value, deleteOnExit, lock)

Parameters:	name	The name of the server variable you wish to create in your current room.
	value	The string value of the variable.
	deleteOnExit	Either true (or "True") or false (or "False"). If true, then the variable is deleted when you exit the room. If false, then the variable is not deleted when you exit the room.
	lock	Either true (or "True") or false (or "False"). If true, then the variable cannot be updated. If false, then the variable can be updated. The variable can be deleted using ElectroServerAS.deleteVariable() no matter what value lock has.

Returns: Nothing.

Description: Method; creates or updates a variable in your current room on the socket server. Whenever a variable is created, updated, or deleted, all users in that room are informed via the ElectroServerAS.roomVariablesChanged event. All room variables are stored in an object on the ElectroServerAS object called roomVars.

Example: The following line creates a room variable:

 ElectroServerAS.createVariable("secret_door","door3",true,false)  

ElectroServerAS.deleteVariable

Usage: ElectroServerAS.deleteVariable(name)

Parameters:

name

The name of the room variable you wish to delete.

Returns: Nothing.

Description: Method; deletes a room variable of the name you specify. The variable is deleted even if it is locked (see ElectroServerAS.createVariable()). Once it's deleted, all users in that room are informed.

Example: The following line deletes a room variable:

 ElectroServerAS.deleteVariable("secret_door")  

ElectroServerAS.disconnectFromServer

Usage: ElectroServerAS.disconnectFromServer()

Parameters: None.

Returns: Nothing.

Description: Method; closes the connection between Flash and the ElectroServer socket server.

Example: The following line disconnects the Flash client from the ElectroServer socket server:

 ElectroServerAS.disconnectFromServer()  

ElectroServerAS.getHistory

Usage: ElectroServerAS.getHistory()

Parameters: None.

Returns: The string ElectroServerAS.history.

Description: Method; returns the chat history. The chat history is stored as a string in ElectroServerAS.history and gets added to using the ElectroServerAS.addToHistory() function.

Example: The following line sets a variable from the chat history:

 myHistory = ElectroServerAS.getHistory()  

ElectroServerAS.getRoomList

Usage: ElectroServerAS.getRoomList()

Parameters: None.

Returns: An array of objects.

Description: Method; returns an array. Each element of the array is an object that describes a room and has two properties: name and total. The property name is the name of the room; the property total is the number of people in that room.

Example: The following ActionScript loops through the room list and shows the names and number of people in each room in the output window:

 var theRooms = ElectroServerAS.getRoomList();  for (i in theRooms) {    trace(theRooms[i].name);    trace(theRooms[i].total); } 

ElectroServerAS.getUserList

Usage: ElectroServerAS.getUserList()

Parameters: None.

Returns: An array of objects.

Description: Method; returns an array. Each element of the array is an object that describes a user and has only one property: name. The property name is the user name of one person in your room.

Example: The following ActionScript loops through the room list and shows the names and number of people in each room in the output window:

 var theUsers = ElectroServerAS.getUserList();  for (i in theUsers) {    trace(theUsers[i].name); } 

ElectroServerAS.history

Usage: ElectroServerAS.history

Description: Property; this is a string value that stores the chat history. Currently this method just returns the history property. However, in future revisions of the ElectroServerAS object, the history may be stored in a different manner, in which case the getHistory() method will be more useful. So it would be a good idea to get into the practice of using the ElectroServerAS.getHistory() method.

Example: The following line is an example usage of this property:

 myHistory = ElectroServerAS.history  

ElectroServerAS.inGame

Usage: ElectroServerAS.inGame

Description: Property; this is a Boolean value (true or false). If it's true, then you are currently in a game. If it's false, then you are not currently in a game. If you receive a challenge and ElectroServerAS.inGame has a value of true, then a decline message is sent automatically. This property is used internally by the ElectroServerAS object.

ElectroServerAS.ip

Usage: ElectroServerAS.ip

Description: Property; stores the IP address of the server you wish to connect to. It (as well as ElectroServerAS.port) must be set before the ElectroServerAS.connectToServer() method will perform properly. This can be the numeric IP address of a server or the domain name (such as "23.244.81.5" or "macromedia.com").

Example:

 ElectroServer = new ElectroServerAS();  ElectroServerAS.ip = "localhost"; ElectroServerAS.port = 8080; ElectroServerAS.connectToServer(); 

ElectroServerAS.isResponding

Usage: ElectroServerAS.isResponding

Description: Property; this is a Boolean value (true or false) used internally by the ElectroServerAS object. If you receive a challenge, this property is set to true. If while it's true you receive another challenge, a decline message is automatically sent. Once you respond to this challenge by either accepting it or declining it, isResponding is set to false.

ElectroServerAS.joinRoom

Usage: ElectroServerAS.joinRoom(name)

Parameters:

name

The name of the room you want to join.

Returns: Nothing.

Description: Method; changes the room you are in to the room specified in the name parameter. If the room does not yet exist, then it is created. The name of the room you have chosen to join is stored in the property ElectroServerAS.myRoom.

Example: The following line changes the room you are in to "Lobby":

 ElectroServerAS.joinRoom("Lobby")  

ElectroServerAS.kick

Usage: ElectroServerAS.kick(who, why)

Parameters:	who	The user name of the person you wish to kick.
	why	The reason why you are kicking this person.

Returns: Nothing.

Description: Method; disconnects a user from the ElectroServer socket server. You must have administrator-level access to the server in order to initiate this method.

Example: The following line kicks a user from the server:

 ElectroServerAS.kick("meanie")  

ElectroServerAS.leaveAlone

Usage: ElectroServerAS.leaveAlone

Description: Method; this is a Boolean value (true or false); the default is false. If true, then all incoming challenge requests will automatically be declined.

ElectroServerAS.login

Usage: ElectroServerAS.challenge(name, password)

Parameters:	name	This is the user name you wish to have.
	password	This is an optional parameter containing a password.

Returns: Nothing.

Description: Method; logs in a user to the server. If a password is used, the log-in information is compared with the user name and passwords listed for administrator-level users. If no password is used, the user is just logged in. An administrator is created using tools provided with the ElectroServer socket server.

Example: The following line logs in the user:

 ElectroServerAS.login("jobem")  

The following line logs in the user as an administrator:

 ElectroServerAS.login("important_person","his_password")  

ElectroServerAS.loginResponse

Usage: ElectroServerAS.loginResponse(success, reason)

Parameters:	success	This is a Boolean value (true or false). If true, then the log-in was successful; if false, then it was not.
	reason	This is a string value saying why the log-in was not accepted.

Returns: Nothing.

Description: Method; a callback function invoked by the ElectroServerAS object when a response has been received from the server after a log-in has been attempted. The first parameter, success, is true if the log-in was a success and false if it was not. If the log-in failed (success false) then the reason parameter (a string value that contains the reason why the log-in attempt failed) is passed in.

Example: The following lines create a function that is to be called when a response to the log-in attempt is received:

 function loginResponse(success, reason) {    if (success) {       ElectroServerAS.joinRoom("Lobby");       chat.gotoAndStop("chat");    } else {       trace("reason="+reason);    } } ElectroServerAS.loginResponse = this.loginResponse; 

ElectroServerAS.moveReceived

Usage: ElectroServerAS.moveReceived(object)

Parameters:

object

A custom object that an opponent created.

Returns: Nothing.

Description: Method; a callback function invoked by the ElectroServerAS object when an opponent sends you a move in a game. This custom object can contain any data type, including arrays, XML objects, and variables.

Example: The following lines create a function and set that function to be called when a move is received. The function simply traces the names and values of all properties of the custom object passed in.

 function moveReceived(ob) {    for (i in ob) {       trace(i+"="+ob[i]);    } } ElectroServerAS.moveReceived = this.moveReceived; 

ElectroServerAS.myRoom

Usage: ElectroServerAS.myRoom

Description: Property; stores as a string the name of the room you are currently in.

ElectroServerAS.onConnection

Usage: ElectroServerAS.onConnection(success)

Parameters:

success

This is a Boolean (true or false). If true, then the connection was successfully established; if false, then it was not.

Returns: Nothing.

Description: Method; a callback function invoked by the ElectroServerAS object when a connection to the ElectroServer socket server has been established and verified. A value of true is passed into the callback function if the connection was a success; a value of false is passed in if it was not. The server must successfully send a message verifying that the connection is valid before this event is fired. In other words, making the connection to the server is not enough to fire this event you need confirmation of the connection.

Example: The following lines create a function that is to be called when a connection to ElectroServer is established and verified:

 function connectionResponse(success) {    if (success) {       chat.gotoAndStop("login");    } else {       trace("connection failed");    } } ElectroServerAS.onConnection = this.connectionResponse; 

ElectroServerAS.onPlayersInRoomChange

Usage: ElectroServerAS.onPlayersInRoomChange(num)

Parameters:

num

A number representing the total number of people in your room.

Returns: Nothing.

Description: Method; a callback function invoked by the ElectroServerAS object when the number of people in your room changes. This happens whenever a person joins or leaves your room.

Example: The following lines create a function and set it to be called when the number of people in your room changes. The function checks to see if there are two people in your room. If there are, then it is time to initialize the game (assuming it is a two-player game).

 function numPlayers(num) {    if (num == 2) {       startGame();    } } ElectroServerAS.onPlayersInRoomChange = this.numPlayers; 

ElectroServerAS.onRoomVarChange

Usage: ElectroServerAS.onRoomVarChange(roomVars, type, name)

Parameters:	roomVars	An object containing variables.
	type	A string specifying the type of room-variable change that has occurred ("list", "update", or "delete")
	name	The string name of the changed variable.

Returns: Nothing.

Description: Method; a callback function invoked by the ElectroServerAS object when the list of variables associated with your current room (stored on the socket server) changes or when you first enter a room. When you first enter a room, this event occurs and you are sent a list of all of the variables in that room. The type parameter is "list" when this happens. When a variable in your room is created or modified, then the type parameter is "update" and the name parameter contains a string name of the variable that changed (or was created). When a variable in your room is deleted, then the type parameter is "delete", and the name parameter contains a string name of the variable that has been deleted.

ElectroServerAS.opponent

Usage: ElectroServerAS.opponent

Description: Property; stores the name of your opponent. This property is created when you and another person have agreed to play a game.

ElectroServerAS.player

Usage: ElectroServerAS.player

Description: Property; stores your "player number" within a game. If you are in a game with only two players, then this property has a value of 1 for one person and a value of 2 for the other.

Example: The following is an example of a snippet of code you might find at the beginning of a chess game:

 if (ElectroServerAS.player == 1) {    myChessPieceColor = "white"; } else if (ElectroServerAS.player == 2) {    myChessPieceColor = "black"; } 

ElectroServerAS.port

Usage: ElectroServerAS.port

Description: Property; stores the IP address of the server you wish to connect to. It must be set (as well as ElectroServerAS.ip) before the ElectroServerAS.connect() method will perform properly. This can be the numeric IP address of a server or the domain name (for example, "23.244.81.5" or "macromedia.com").

Example:

 ElectroServer = new ElectroServerAS();  ElectroServerAS.ip="localhost"; ElectroServerAS.port=8080; ElectroServerAS.connect(); 

ElectroServerAS.roomListChanged

Usage: ElectroServerAS.roomListChanged(rooms)

Parameters:

rooms

This is an array of objects.

Returns: Nothing.

Description: Method; a callback function invoked by the ElectroServerAS object when the list of visible rooms changes. When it's called, an array is passed in. Each element in the array is an object representing a room with the properties name and total. The name property is the name of the room, and total is the number of people in that room.

Example: The following lines create a function and set it to be called when the room list changes. The function populates a text field with room names that take the format Lobby(32).

 function roomListChanged(roomList) {    roomList.text = "";    for (var i = 0; i<roomList.length; ++i) {       chat.roomList.text += roomList[i].name+"       ("+roomList[i].total+")"+newline;    } } ElectroServerAS.roomListChanged = this.roomListChanged; 

ElectroServerAS.rooms

Usage: ElectroServerAS.rooms

Description: Property; an array that stores information about each room. Every element in the array is an object with the properties of name and total. The name property contains the name of the room; total is the number of people in that room. It is recommended to use the ElectroServerAS.getRoomList() method; currently ElectroServerAS.getRoomList() just returns the rooms property, but in future revisions of the ElectroServerAS object, the room list may be stored in a different way.

ElectroServerAS.roomVars

Usage: ElectroServerAS.roomVars

Description: Property; an object that stores the room variables. Every time a variable is created, updated, or deleted from the server, it is also reflected in this object. If you define an event handler using ElectroServerAS.onRoomVarChange, you will be informed when this happens.

Example: The following example shows the names of all the server variables in the output window, along with their values:

 ob = ElectroServerAS.roomVars;  for (i in ob) {    trace(i+"="+ob[i]); } 

ElectroServerAS.sendData

Usage: ElectroServerAS.send Data(msg)

Parameters:

msg

The data you would like to send to the server.

Returns: Nothing.

Description: Method; sends the information found in the msg parameter to the server. This method is used internally by the ElectroServerAS object, and it is unlikely to be needed for anything other than extending the ElectroServerAS object.

ElectroServerAS.sendMessage

Usage: ElectroServerAS.sendMessage(msg, who)

Parameters:	msg	The chat message you would like to send.
	who	A string value stating to whom you would like this message to go. If the string is "All", then the message will be sent to everyone in your current room. If the string specifies a user name (in any room), then the message will be sent to that user as a private message.

Returns: Nothing.

Description: Method; sends a chat message to the room or to a user. This is the method used for regular chatting and private messaging.

Example: The following line sends a message to the room:

 ElectroServerAS.sendMessage("Good morning Raleigh!","All")  

The following line sends a message to "jobem":

 ElectroServerAS.sendMessage("Hey man, where've you  been?","jobem") 

ElectroServerAS.sendMove

Usage: ElectroServerAS.sendMove(who, what)

Parameters:	who	The player to whom you want to send the move.
	what	The object you would like to send.

Returns: Nothing.

Description: Method; sends an object to the specified user. The object is of type object and can contain any other data objects, such as arrays, date objects, or XML objects. This method is how moves are made in a game.

Example: The following sends a move to "jobem":

 myObject=new Object();  myObject.ball_x=32; myObject.ball_y=413; ElectroServerAS.sendMove("jobem",myObject); 

ElectroServerAS.sendSystemMessage

Usage: ElectroServerAS.sendSystemMessage(msg)

Parameters:

msg

A string value of the message you wish to send.

Returns: Nothing.

Description: Method; sends a message to every user in every room on the server. This is only available to users with administrator-level access to the server.

Example: The following line of ActionScript sends a message to everyone connected to the server:

 ElectroServerAS.sendSystemMessage("The server is about to be  rebooted. Please refresh in 1 minute.") 

ElectroServerAS.userListChanged

Usage: ElectroServerAS.userListChanged(users)

Parameters:

users

An array of objects.

Returns: Nothing.

Description: Method; a callback function invoked by the ElectroServerAS object when the list of users in your room changes. When you first enter a room, this event occurs, and you are sent a list of all the users in the room. The users parameter is an array of objects. Each object represents one user and has one property, name, which stores the user name of the user whom it represents.

Example: These lines of ActionScript create a function and set it to be called whenever the list of users in the room changes. The function uses the Flash ListBox component to display the list of users.

 function userListChanged(userList) {    var path = chat.userList;    path.removeAll();    for (var i = 0; i<userList.length; ++i) {       path.addItem(userList[i].name);    } } ElectroServerAS.userListChanged = this.userListChanged; 

ElectroServerAS.username

Usage: ElectroServerAS.username

Description: Property; the name with which you are logged in.

ElectroServerAS.users

Usage: ElectroServerAS.users

Description: Property; an array of objects. Each object represents a user in your room with one property, name, that stores the user name of that person. It is recommended that you use ElectroServerAS.getUserList() to retrieve the user list. In future revisions of this object, the user list may be stored differently.

ElectroServerAS.usersInMyRoom

Usage: ElectroServerAS.usersInMyRoom

Description: Property; an integer that specifies the total number of people in your room.

new ElectroServerAS()

Usage: new ElectroServerAS()

Parameters: None.

Returns: Nothing.

Description: Constructor; creates a new ElectroServerAS object. You must use the constructor method to create an instance of the ElectroServerAS object before calling any of the ElectroServerAS object methods.

Example: The following line creates an instance of the ElectroServerAS object with a reference of ES:

 ES = new ElectroServerAS();