Multiuser Lingo Dictionary > Multiuser Lingo Dictionary > connectToNetServer() |  |

connectToNetServer()

Syntax

    gMultiuserInstance.connectToNetServer(userNameString, passwordString, serverIDString, portNumber, movieIDString {, #mode} {, encryptionKey})

    gMultiuserInstance.connectToNetServer(serverIDString, portNumber, [#userID: userNameString, #password: passwordString, #movieID: movieIDString] {, #mode} {, encryptionKey})

    gMultiuserInstance.connectToNetServer([#logonInfo: [#userID: userNameString, #password: passwordString, #movieID: movieIDString], #remoteAddress: serverIDString {, #remoteTCPPort: serverPortNumber} {, #localAddress: clientIPAddress} {, #encryptionKey: encryptionKeyString}])

Description

Multiuser Server Lingo command; starts a connection to the server and returns an error code indicating whether the connection was initiated.

This command has three formats, shown above. The second format requires version 2.1 or later of the Shockwave Multiuser Server and makes use of additional security features. When this format is used, the Multiuser Xtra passes the Internet location of the movie to the server in addition to the standard login information. This location takes the form http://www.company.com/directory/movieName.dcr. If the server's Multiuser.cfg file has been configured to verify the location of the movie with the `moviePathName` tag, this feature can be used to prevent movies from connecting to the server from locations other than where the author intended.

userNameString and passwordString provide account information for logging on to the host system. User names must not contain any control characters or the characters @ or `#`.

serverIDString represents the Internet address of the server, such as gameServer.macromedia.com or 123.45.67.1.

portNumber is an integer specifying the connection port to be used. (By default, the Shockwave Multiuser Server uses port 1626.) This must be the same port specified in the server configuration file.

movieIDString represents the multiuser application name for this connection, such as GameChat or PingPong.

mode is an optional parameter. With the first format of `connectToNetServer()`, this parameter must be an integer; the default value is 0. If set to 1, it opens the connection as a text-based connection for communicating with IRC and SMTP servers. With the second format, this parameter must be a symbol. The default is `#smus`, which indicates a normal Shockwave Multiuser Server connection. If set to `#text`, the connection opens as a text-based connection.

A movie running in a browser or in Shockmachine that attempts make a text server connection invokes a security dialog box unless the text server resides in the same domain name as the Web server the movie is served from. Projectors running with `the safePlayer` set to `TRUE` also display a security dialog box when making text connections, unless the movie being played is a remote DCR file on the same server as the text server. If this command is used to connect to POP, SMTP, or IRC chat servers, none of the Multiuser Server command functionality is available. The command supports only simple text messaging.

encryptionKey is another optional parameter. This string is used to encrypt log-on information sent to the server and must match the encryption key specified in the Multiuser.cfg file for the server.

The third format of `connectToNetServer()` takes a property list and allows you to specify a particular local IP address to be used for messaging on clients that have multiple IP addresses. This third format also compares the client movie's location with the address string in the `moviePathName` tag in the server's Multiuser.cfg file.

The #logonInfo property list contains the user name, password and movie ID.

#remoteAddress indicates the address of the Multiuser Server you are connecting to.

#remoteTCPPort indicates the server port number to use for TCP messages. The default is 1626.

#localAddress indicates the IP address of the client machine. You can use the `getNetAddressCookie()` function to determine the IP address and to select a specific IP address if there is more than one address on the client machine.

Note that the third format of `connectToNetServer()` should be used only for connecting to the Shockwave Multiuser Server and does not contain the `#mode` parameter.

Use this command to connect to multiuser servers. Finding and connecting to the server can take some time. This function first returns an error message immediately from the Xtra. If the function's parameters are valid, the returned error code is 0. The server sends a subsequent message and calls the message handler when the connection is actually made.

Before using the `connectToNetServer` command, you should first set up a handler to receive the message that `connectToNetServer` returns. To set up the connection, create an instance of the Xtra, define the message handler using a `setNetMessageHandler` statement, and then connect with `connectToNetServer()`.

The message returned from the `getNetMessage` function is a property list with the following information:

`#errorCode` | Resulting error code: 0 if there is no error
`#senderID` | System
`#subject` | ConnectToNetServer
`#content` | Empty string
`#timeStamp` | Time in milliseconds on the server

You disconnect from the server by setting the variable containing the Multiuser Xtra instance to 0.

Example

This statement is a typical call that initiates a connection that is not encrypted:

    errCode = gMultiuserInstance.connectToNetServer( "Fred", "secret", "serverName.company.com", 1626, "ExcitingGame")

See also

`waitForNetConnection()`, `setNetMessageHandler`, `getNetAddressCookie()`