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 `gMultiuserInstance`:
    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 `setNetMessageHandler()`.
| 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 `mouseUp` event. Once the callback is declared in Lingo it will be triggered each time a message arrives from the network. A callback handler should be written to perform tasks based on the contents of the incoming message that triggers it.
| For example, this statement declares that the handler `defaultMessageHandler` in the script cast member Connection Script is the handler to run when any incoming message is received from the server:
    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 `setNetMessageHandler()` is a symbol for the handler you are declaring. You make it a symbol by adding a pound sign (`#`) to the beginning of the handler name. The second parameter is the name of the script object that contains the handler. This could be a script cast member or the name of a variable containing a behavior instance, a parent script, or a simple Lingo value to be passed to global scripts.
| You can specify individual handlers to be run based on a particular message subject, a sender, or both by adding optional parameters to `SetNetMessageHandler()`. These individual handlers are run instead of the default message handler when the specified type of message arrives.
| You can also add an optional integer parameter to the end of the `setNetMessageHandler()` command to tell Lingo to pass the message contents to the message handler as an argument. This prevents the handler from needing Lingo specifically to get the message out of the incoming message queue, as in the previous example. When you specify a value of `TRUE (1)`, the message contents are passed to the handler as an argument. If you omit this parameter, it defaults to `FALSE (0)` and the message contents are not passed as an argument.
| 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 `connectToNetServer`.
| 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 `defaultMessageHandler` you declared earlier.

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