What's New in Director 8.5 > Using the Shockwave Multiuser Server and Xtra > Creating multiuser movies > Connecting to the server |
![]() ![]() ![]() |
Connecting to the server
To connect to the Shockwave Multiuser Server, you may write Lingo scripts that execute each step of setting up the Multiuser Xtra and establishing the Xtra's communication with the server. For detailed explanations of each Multiuser Xtra Lingo command, see Multiuser Lingo Dictionary overview. You may also use the multiuser behaviors included in Director's Behavior Library to connect to the server without writing Lingo of your own.
To set up a server connection for sending messages:
1 |
Make sure you have a working server running on a computer on your network and that you know its network address. |
2 |
Create an instance of the Multiuser Xtra. |
For example, these statements place the Xtra instance into the global variable |
|
global gMultiuserInstance gMultiuserInstance = new(xtra "Multiuser") |
|
A single Xtra instance always corresponds to a single server connection. To make more than one connection at a time, use multiple Xtra instances. When you are ready to disconnect from the server, set the variable containing your Xtra instance to 0. |
|
3 |
Set up one or more callbacks for handling incoming messages using |
When your movie initially connects to the server, the server responds with a message confirming the connection. In order to handle this and subsequent messages, you must create callbacks. These are Lingo handlers that are run when messages arrive at a movie from the server or from peer-to-peer users. You must create at least one callback before your movie connects to the server. The arrival of a message is treated as a Lingo event in the same way that a mouse click is treated as a |
|
For example, this statement declares that the handler |
|
errCode = gMultiuserInstance.setNetMessageHandler( \ #defaultMessageHandler, script "Connection Script") |
|
The message handler would look like this: |
|
on defaultMessageHandler global gMultiuserInstance newMessage = gMultiuserInstance.getNetMessage() member("messageOutput").text = string(newMessage) if newMessage.errorCode <> 0 then alert "Incoming message contained an error." end if end |
|
The first parameter you specify with |
|
You can specify individual handlers to be run based on a particular message subject, a sender, or both by adding optional parameters to |
|
You can also add an optional integer parameter to the end of the |
|
This statement declares a handler that runs when a message containing the subject Chat Text arrives from sender Guest Speaker, and tells Lingo to pass those messages to the handler as arguments: |
|
errCode = gMultiuserInstance.setNetMessageHandler( \ #guestMessageHandler, script "Connection Script", "Chat Text",\ "Guest Speaker", True) |
|
The simplified message handler would look like this: |
|
on guestMessageHandler me, message member("messageOutput").text = string(message) if message.errorCode <> 0 then alert "Incoming message from Guest Speaker contained \ an error." end if end |
|
If you want to include the integer parameter without specifying a subject or a sender, use empty strings for the subject and sender. |
|
errCode = gMultiuserInstance.setNetMessageHandler( \ #guestMessageHandler, script "Connection Script", "", "", 1) |
|
For information about message subjects, senders, and contents, see Sending messages. |
|
4 |
Establish the server connection with |
When the message handlers have been declared, you are ready to make your server connection. The Xtra connects to the server with a user name and password, along with other parameters you supply. You must know the server's address and port number as well as the name you want your movie to use to identify itself. |
|
Note: If you expect that your multiuser Shockwave movies will be run primarily on double-byte systems, such as Japanese and Korean, and your movies allow user names and other data to be entered in double-byte text, you should run your server on a double-byte system as well. On roman systems, user names and other properties are not case-sensitive. However, passwords are case sensitive. On Japanese and Korean systems, the server uses double-byte string comparisons. Server passwords can be as long as 250 characters on roman (single-byte) systems and 125 characters on double-byte systems. |
|
The following Lingo connects the movie Tech Chat to a Shockwave Multiuser Server with a user ID of Bob and a password of MySecret. The example server name is chatserver.mycompany.com and the communications port number, 1626, is the default. |
|
errCode = gMultiuserInstance.connectToNetServer( \ "chatserver.mycompany.com", 1626, [#userID: "Bob", #password: \ "MySecret", #movieID: "Tech Chat"]) |
|
The server uses the name you provide for the movie to associate other instances of the same movie with each other. By default, all messages sent by the movie Tech Chat will be sent only to other users of the same movie on the network. |
|
When the server accepts the connection, it will respond with a message whose subject is ConnectToNetServer, which will trigger the |
|
![]() |
The entire Lingo script for connecting to the server looks like this:
on makeAServerConnection -- declare a global variable to hold the Xtra instance global gMultiuserInstance -- create the Xtra instance gMultiuserInstance = new(xtra "Multiuser") -- declare message handler callback(s) to handle incoming -- messages, including the server's initial connection response errCode = gMultiuserInstance.setNetMessageHandler( \ #defaultMessageHandler, script "Connection Script", True) if errCode <> 0 then alert "Problem with setNetMessageHandler" end if -- connect to the server errCode = gMultiuserInstance.connectToNetServer( \ "chatserver.mycompany.com", 1626, [#userID: "Bob", #password: \ "MySecret", #movieID: "Tech Chat"]) if errCode <> 0 then alert "Problem with connectToNetServer" end if end -- message handler for incoming messages on defaultMessageHandler newMessage member("messageOutput").text = string(newMessage) if newMessage.errorCode <> 0 then alert "Incoming message contained an error." end if end
The connectToNetServer()
command can also accept its parameters in another format that allows the server to check the Internet location of the movie that is connecting. This provides additional security when distributing movies over the Web.
The second format takes the server name and port, followed by a property list with the user name, password, and movie name, and then optional connection mode and encryption key parameters. The connection mode can be either #smus
or #text
. The symbol #smus
indicates a normal Shockwave Multiuser Server connection, and #text
indicates a text-mode connection. See Creating text connections.
When #smus
is specified with the second format, the Multiuser Xtra will include the Internet address of the movie with the user name and password information it sends to the server when logging on. The Internet address that is passed to the server takes the form http://server.company.com/directory/movieName.dcr. This way the server can verify that the movie is connecting from the Internet location that the author intended. For information about configuring the server to make use of the movie location information, see Using the Multiuser.cfg file.
The following Lingo connects the movie Tech Chat to a Shockwave Multiuser Server with a user ID of Bob and a password of MySecret. The example server name is chatserver.mycompany.com and the communications port number, 1626, is the default. The connection mode is Shockwave Multiuser Server. No encryption key is specified.
errorCode = myConnection.connectToNetServer( \ "chatserver.mycompany.com", 1626, [#userID:"Bob", \ #password:"MySecret", #movieID:"Tech Chat"], #smus)
The following code uses the second format for connectToNetServer()
and declares two message callback handlers. One will handle generic messages and one will handle messages with a #subject
property of Chat Text. The setNetMessageHandler()
calls use the optional TRUE/FALSE
parameter so the message contents are passed directly to the message handlers.
on makeAServerConnection -- declare a global variable to hold the Xtra instance global gMultiuserInstance -- create the Xtra instance gMultiuserInstance = new(xtra "Multiuser") -- declare message callback handler to handle incoming messages -- that don't meet the specific criteria of the second message -- callback handler declared below errCode = gMultiuserInstance.setNetMessageHandler( \ #defaultMessageHandler, script "Connection Script", "", "", \ True) if errCode <> 0 then alert "Problem with setNetMessageHandler" end if -- this is the second message callback declaration -- declare a specific message callback handler for messages -- with #subject Chat Text errCode = gMultiuserInstance.setNetMessageHandler( \ #chatMessageHandler, script "Connection Script", "Chat Text",\ "", True) if errCode <> 0 then alert "Problem with setNetMessageHandler" end if -- connect to the server errCode = gMultiuserInstance.connectToNetServer( \ "chatserver.mycompany.com", 1626, [#userID: "Bob", #password:\ "MySecret", #movieID: "Tech Chat"], #smus) if errCode <> 0 then alert "Problem with connectToNetServer" end if end -- message handler for generic incoming messages on defaultMessageHandler me, message member("messageOutput").text = string(message) if message.errorCode <> 0 then alert "Incoming message contained an error." end if end -- message handler for incoming messages with #subject Chat Text on chatMessageHandler me, message put message.content after member "chatField" if message.errorCode <> 0 then alert "Incoming message contained an error." end if end
![]() ![]() ![]() |