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()`