Multiuser Lingo Dictionary > Multiuser Lingo Dictionary > sendNetMessage() |  |

sendNetMessage()

Syntax

    gMultiuserInstance.sendNetMessage(string/ListRecipient, stringSubject, string/ListMessage)

    gMultiuserInstance.sendNetMessage(propertyListMessage)

Description

Multiuser Server Lingo command; sends a message to one or more recipients in the current movie or a specified movie on the same server. The recipient may be a specific user, such as Sarah, a group, such as @TicTacToePlayers, or a list of strings containing individual user names or groups. To send a message to all users connected to the same movie, set the recipient to the default group @AllUsers. To send a message to a user in a different movie on the server, add the movie name, preceded by the @ symbol, to the end of the user name: for example, Jane@TechChat.

The message recipient can be a single string or a list of strings, in the case of multiple recipients. The subject must be a valid string. The contents may be a single Lingo value, such as a string, integer, floating-point number, point, rect, property, list, property list, color, date, 3D vector, 3D transform, or data such as the `media of member` property or the `picture of member` property.

If you are sending large data, such as a picture or the media of a cast member, make sure the buffer limits are large enough for both the client and the server. See `setNetBufferLimits` and Configuring the server.

The second possible syntax accepts a property list containing all the information for the message. The property list contains values for the symbols `#errorCode`, `#recipient`,`#subject`, and `#content`. (The `#errorCode` and `#content` values are optional.) This format is similar to the format for messages received by `getNetMessage()`.

If you send a message to a group of which you are a member, you receive the message as well. If the server has problems sending the message to any recipients in a group or list, no error message is returned.

To send requests to the server, you must use a special syntax for the recipient, containing `System`, an object name, and the server command name. If the operation is successful, the server responds with a message that has the same subject, with an error code of 0.

To execute script handlers on the server, address the message to `system.script` and include the name of the handler to be executed as the subject of the message. The server-side script must have an `on incomingMessage` handler that parses the subject and then calls the handler named in the subject of the message.

If the connection is opened as a text connection, the recipient and subject are ignored. The message contents should all be simple Lingo values that will be converted to strings. Any carriage-return-line-feed (CRLF) combinations, such as those required by a POP server, must be explicitly added to the text sent by the Director movie.

Examples

These statements are some possible variations that can be used to send messages:

    errCode = gMultiuserInstance.sendNetMessage("@AllUsers", "ChatMsg", gChatText)
    errCode = gMultiuserInstance.sendNetMessage("BlackBeard", "MoveShipTo", point(shipX, shipY))
    errCode = gMultiuserInstance.sendNetMessage("@groupRedTeam", "Help", "I am lost")
    errCode = gMultiuserInstance.sendNetMessage(["Bill", "Joe", "Sue"] "JoinMe", "")

This statement provides its parameters in the form of a property list:

    errCode = gMultiuserInstance.sendNetMessage([#recipients: "Bob", #subject: "Hello", #content: "How are you?"])

This statement sends a message to user Jane in a separate movie called TechChat:

    errCode = gMultiuserInstance.sendNetMessage("Jane@TechChat", "ChatMsg", "What are you talking about?")

This statement sends the command `getUsers` to the server:

    errCode = gMultiuserInstance.sendNetMessage("system.group.getUsers", "anySubject", "@RedTeam")

This statement sends the command `getGroupCount` to the server as a request for information about a separate movie on the server called AdventureGame:

    errCode = gMultiuserInstance.sendNetMessage ("system.movie.getGroupCount@AdventureGame", "anySubject")

This statement sends a message to the `on incomingMessage` handler in the movie's server-side script, which will parse the subject and call the `on updatePlayers` handler in the server-side script:

    errCode = gMultiuserInstance.sendNetMessage ("system.script", "updatePlayers")

The following statement sends a message to the `on incomingMessage` handler in the server's Dispatcher script and causes it to immediately send the same message back to the client. The `case` section of the Dispatcher's `on incomingMessage` handler must be uncommented for the `ping` command to work.

    errCode = gMultiuserInstance.sendNetMessage ("system.script", "System.Script.Admin.Ping")

This statement sends the RETR command to a text-based mail server to retrieve one piece of mail:

    errCode = gMultiuserInstance.sendNetMessage("system", "anySubject", "RETR 1")