Revision as of 09:43, 26 June 2014

Introduction

Within the LLUDP protocol, there is a message type called GenericMessage. This has the following structure (taken from a viewer's app_settings/message_template.msg file).

 GenericMessage  Low 261 NotTrusted Zerocoded
 {
   AgentData     Single
   {   AgentID     LLUUID    }    
   { SessionID LLUUID    }    
   { TransactionID LLUUID  }
 }
 {
   MethodData  Single
   { Method    Variable 1 }
   { Invoice   LLUUID  }
 }
 {
   ParamList   Variable
   { Parameter Variable 1 }
 }

Linden Lab uses this message for some miscellaneous functionality. However, because we can switch messages on the Method parameter, we can also use GenericMessage as a carrier of arbitrary UDP data between the client/viewer and the simulator, as GenericMessages can flow both ways.

Example

Typically, we would create an OpenSimulator region module to subscribe to the GenericMessages with certain Method names. There is an example GenericMessagingModule at https://github.com/justincc/GenericMessagingModule which does exactly this. We will extract the important parts here.

First thing to do is to have the region module subscribe to incoming GenericMessages from viewers with a particular method name. The module looks for a method named "Test", but in a real application you would want to pick a name which is very unlikely to be used by Linden Lab in the future or any other OpenSimulator extension. Here's the code snippet.

public void AddRegion(Scene scene)
{
    scene.EventManager.OnNewClient += HandleNewClient;
}
 
private void HandleNewClient(IClientAPI client)
{
    client.AddGenericPacketHandler("test", HandleGenericMessage);
}
 
private void HandleGenericMessage(object sender, string method, List<string> args)
{
    IClientAPI client = (IClientAPI)sender;
 
    m_log.DebugFormat(
        "[GENERIC MESSAGE]: Received message with method {0}, args {1} from {2} in {3}",
        method, string.Join("|", args.ToArray()), client.Name, client.Scene.Name);
}