Multiuser Lingo Dictionary > Multiuser Lingo Dictionary > waitForNetConnection()

 

waitForNetConnection()

Syntax

gMultiuserInstance.waitForNetConnection(userIDString, localTCPPortNumber {, maxNumberOfConnections, {encryptionKeyString}})

gMultiuserInstance.waitForNetConnection([#userID: userIDString {, #maxConnections; maxNumberOfConnections {, #localAddress: localIPAddress} {, #localTCPPort: TCPPortNumber} {, #encryptionKey: encryptionKeyString}]

Description

Multiuser Server Lingo function; listens for incoming peer-to-peer connections from other computers.

This function takes arguments in two formats. The first format contains the following parameters:

userIDString represents the log-on name of the user acting as the host and waiting for connections.

portNumber represents the Internet port the connecting system will contact. Multiuser servers should use port 1626 by default. Generic inbound TCP connection requests are not supported.

maxNumberOfConnections represents an optional parameter for the maximum number of possible connections to the host. Up to 16 peer connections are allowed.

encryptionKeyString is an optional parameter that supplies a key string to decode log-on information from other systems. If this parameter is used, the other systems must use an identical encryption key string when they connect using connectToNetServer.

The second format includes a property list containing the following optional parameters in addition to those listed above:

#localAddress indicates the local IP address of the host computer. Use this parameter on machines with multiple local IP addresses. You can obtain the IP address of the machine with the getNetAddressCookie() function.

The connecting computer uses connectToNetServer and appears to be connecting to a normal multiuser server, but it is actually connecting to a peer computer that has issued the waitForNetConnection function. In connections of this type, no server commands are available. The computer that calls waitForNetConnection must do so before a peer calls connectToNetServer.

Because waiting for an incoming connection can take a long time, this function returns an error code immediately. An error code of 0 indicates that the Xtra has begun listening successfully. A message is sent back from the Xtra (and the message handler called) when the incoming connection is actually established. For this to work, you must set a handler with setNetMessageHandler before calling waitForNetConnection. The message handler called should return TRUE if the host movie wants to accept the connection, or FALSE if it is to be rejected. The returned message is a list that contains the following items:

#errorCode

Resulting error code: 0 if there is no error

#senderID

System

#subject

WaitForNetConnection

#content

Remote user information in a property list containing #userID, #password, and #movieID


Up to 16 peer-to-peer connections can be established with each Xtra instance using waitForNetConnection. Multiple calls to waitForNetConnection cannot be made using the same port number, because the Xtra instances cannot all wait on the same port number.

After the function is called, you cannot turn off the wait for additional connections, except by deleting the Xtra instance. You can specify a limit to the number of connections when calling waitForNetConnection, or use the incoming message handler to return TRUE or FALSE to allow or reject the incoming connection attempts.

Do not make outgoing server connections using an Xtra instance that has called waitForNetConnection.

Examples

These statements show a range of typical calls to set the movie to receive connections:

errCode = gMultiuserInstance.waitForNetConnection("Fred", 1626)
errCode = gMultiuserInstance.waitForNetConnection("Mark", 1626, 16, "Queen3ToRook2")
errCode = gMultiuserInstance.waitForNetConnection("Joe", 1626, 2, "RogerWilco")

See also

setNetMessageHandler, getNetAddressCookie(), connectToNetServer()