8.2 Tutorials: Simple Extension
The source FLA of
this example is found under the Examples/AS2/pro_SimpleExtension folder. |
» Introduction
In this tutorial we will write a very simple extension that will show
you all the basics of the server side extensions programming with SmartFoxServer PRO.
The extensions will take an array of numbers and it will return the same array
with the values multiplied by 2.
Before we dive into the code it's good to take a look at how the extension is
loaded. First of all the Actionscript file is saved in the sfsExtensions/ folder,
which is the root of all extensions in SmartFoxServer PRO.
If you take a look at the settings in the config.xml file you
will find that the extensions is loaded at Zone Level in the
Zone called "dbTest".
This means that our extension can be called from any room within that Zone. It is also assigned a name ("simpleExt" in this case) that is going to be used in order to invoke methods on that extension.
» The client side
Now it's time to open the source .FLA file and have a look at the very simple
code inside it. If you quickly inspect the code in the "connect" and
"chat" labels it should look familiar as it is very similar to what we have
done in all the previous tutorials.
You can now position the playhead in the "chat" label and look at the code that
handles the button click:
function sendValues()
{
var obj:Object = {}
obj.values = [100, 200, 300, 400, 500]
smartfox.sendXtMessage(extensionName, "double", obj, "xml")
output_txt.text += "Sent: " + obj.values + newline
}
In the first two lines an array containing five numbers is created: these are
the values that we will send to the server side extension and we expect to receive
an array with those five numbers multiplied by 2.
The next line is very important because it shows how we can call our custom
code on the server. The sendXtMessage() is used to call
our extensions and the following list shows the parameters needed:
extName |
|
The name of the extension to call. It must be the same as declared in
the config.xml |
cmd |
|
The name of the command that should be executed by the server side extension |
params |
|
An object containing data to pass to the server code. (It can contain
strings, numbers, booleans, arrays, objects) |
type |
|
It can be "xml" or "str". It represents the type of protocol being used
to send the request. By default "xml" is used and your request is sent
in XML format.
If you use "str" you will send the request in a raw, string-based format
that can save a lot of bandwidth. You can learn more about how to use this
format by following the tutorial in chapter 8.6 |
Back to our code, at line 10, we defined a global variable called "extensionName":
var extensionName:String = "simpleExt"
this is the name of the extension that we will call. The second argument passed
to sendXtMessage() is "double", which is the name
of the command that will multiply the values by 2. Then we passed the object
containing the numbers array and finally we chose to use the XML format for this
request.
Since XML is used by default we could have omitted the last paramater.
PLEASE NOTE: SmartFoxServer uses XML format for all its messages.
Even if XML can lead to larger messages when compared to pure string-based format,
it allows easy debugging of the server messages and complex data serialization.
Also the XML code has been optimized to reduce overhead.
The string-based format can be great for real-time action games and in all those
cases where continuous and fast client updates are required. String-based (raw)
format does not allow to serialize complex objects and you will be able to send
simple data such as numbers, strings etc...
More in general when sending non time-critical messages such as room updates,
user updates etc... or when dealing with turn-based games XML is preferrable
as it allows more flexibility. On the other hand when fast updates are needed
you can use the raw format. Both approaches can be mixed transparently. You will
learn more about this topic in the next tutorials.
» The server side
Now that we've sent the request from the client, it's time to see how it is handled
in our server code:
function init()
{
// Using trace will send data to the server console
trace("Hello from the Simple Extension Example!")
}
function destroy()
{
trace("Bye bye!")
}
function handleRequest(cmd, params, user, fromRoom)
{
if (cmd == "double")
{
var response = {}
response._cmd = "double"
response.values = []
for (var i = 0; i < params.values.length; i++)
{
var n = params.values[i]
response.values[i] = n * 2
}
_server.sendResponse(response, -1, null, [user])
}
}
function handleInternalEvent(evt)
{
// Simply print the name of the event that was received
trace("Event received: " + evt.name)
}
You can see that both the init() and destroy() method
just trace a message to the console. The trace() command,
like in the Flash IDE, prints your text and variables to the server console and
also to the Administrator Tool trace window.
If you keep your AdminTool connected to SmartFoxServer while testing your extensions,
you will receive all the trace output and you will be able to remotely debug
your server code.
The important code is contained in the handleRequest() function: first we check
if the command name is the one we expected, then we prepare an object
called "response" with an empty array for ther server reply.
Also we add a property called "_cmd" with the name of the command. This is a
convention that we will use through all the examples in this section. (Even if
it's not mandatory to call that variable "_cmd", you will anyway need to pass
a property with the command name or you will not be able to detect which command
is replying on the client side.)
In the next lines we cycle through the array sent from the client (params.values)
and fill the response array with the doubled values.
Finally we send the result back to the client by using the _server.sendResponse()method which takes 5 parameters:
response |
|
an object with the _cmd property specifying the name of the response
command |
fromRoom |
|
the id of the room where the response comes from (-1 if not needed) |
sender |
|
the User object of the client sending the response (null if not needed) |
recipients |
|
a list of User objects that should receive the reponse |
type |
|
can be "xml" or "str". It represent the message format.
By default "xml" is used |
» Back to the client
Now it's time to get back to the client side of the application and see how the
server response is received.
We will use the onExtensionsResponse event handler:
smartfox.onExtensionResponse = function(resObj:Object, type:String)
{
trace("cmd: " + resObj._cmd)
trace("type: " + type)
// We expect the response to be xml formatted
if (type == "xml")
{
// Let's check if it's a "getData" message
if (resObj._cmd == "double")
{
trace("res: " + resObj.values)
output_txt.text += "Received: " + resObj.values + newline
}
}
}
The resObj object contains the data sent by the server and "type"
tells us what protocol was used for the current message. In this case we expected
an "xml" formatted message and we also expected a response from the "double"
command.
If these conditions are satisfied we can finally output the result in the text
area.
» Summing up
We've seen that writing server side extensions is very simple and it takes basically three steps:
» send the request object from the client
» handle the request on the server side and reply to the client
» handle the server response back to the client
In the next chapters we will see how to add database connections, handle server events, create custom login procedures, use optimized protocols and more...