Multiuser Lingo Dictionary > Multiuser Lingo Dictionary > setNetMessageHandler |  |

setNetMessageHandler

Syntax

    gMultiuserInstance.setNetMessageHandler(#handlerSymbol, handlerObject, {subject, {sender}} {, integerPassMessage})

Description

Multiuser Server Lingo command; sets the callback handler that is invoked when messages arrive. This should be set before connecting with `connectToNetServer()` in order to capture the response message.

You can set as many callbacks as you need. It is much more efficient to have multiple callbacks that react to specific types of incoming messages than to have one callback that filters messages and then calls another handler.

This ability is key for creating flexible and effective experiences. You might have a scenario that uses avatar objects to represent other users, and set a callback to each specific object. In that way, any message related to that user is routed automatically when dealing with the object. The avatar object itself may even have multiple callbacks for messages with different subjects.

#handlerSymbol is a symbol that represents the handler.

handlerObject represents the object where the handler is located. This may be a behavior instance, a parent script, or any Lingo value. If it is a script or behavior instance, the handler associated with it is called. If it is a Lingo value, the handler must be in a global script and the Lingo value is passed as the first parameter to that script.

subject and sender are optional parameters that route messages with particular subjects, senders, or both to a handler. This lets avatar scripts receive all the messages from a sender. To route all messages from one sender to a handler, set the subject to 0 and specify the sender's ID.

IntegerPassMessage is an optional parameter that indicates whether Lingo should pass the contents of the incoming message directly to the specified handler as an argument. This allows your message handlers to be simpler because they can omit Lingo that serves the purpose of getting the message out of the message queue.

To disable message notification for a given type of message, call `setNetMessageHandler()` again and set the handler information to 0.

Examples

This statement sets the handler `on MyNetMessageHandler` located in the script cast member CallBackScript as the generic message callback handler (no specific subject or sender is specified):

    errCode = gMultiuserInstance.setNetMessageHandler(#MyNetMessageHandler, script "CallBackScript")

The message handler might look like this:

    on myNetMessageHandler
    	global gMultiuserInstance
    	newMessage = gMultiuserInstance.getNetMessage()
    	member("messageOutput").text = newMessage
    	if newMessage.errorCode <> 0 then
    		alert "Incoming message contained an error."
    	end if
    end

The following statement sets the handler `on BobHandler` in the script cast member Callbacks as the message callback handler for messages with any subject received from user Bob. The last parameter of 1 tells Lingo to pass the messages to the handler as arguments.

    errCode = gMultiuserInstance.setNetMessageHandler(#BobHandler, script "Callbacks", "", "Bob", 1)

The simplified message handler without Lingo for getting the messages out of the message queue might look like the following. Note the `message` argument that appears after the handler name.

    on BobHandler me, message
    	member("messageOutput").text = message
    	if message.errorCode <> 0 then
    		alert "Incoming message contained an error."
    	end if
    end

This statement sets the handler `on RedCarMsgHandler` in the script object `me` as the message callback handler for messages with a subject of setCarPosMsg and a sender of Fred:

    errCode = gMultiuserInstance.setNetMessageHandler(#RedCarMsgHandler, me, "setCarPosMsg", "Fred")

This statement disables the handler declared above by specifying 0 in place of the handler symbol:

    errCode = gMultiuserInstance.setNetMessageHandler(0, me, "setCarPosMsg", "Fred")

See also

`connectToNetServer()`