EventQueueGet

From Second Life Wiki
Jump to navigation Jump to search

The EventQueueGet cap is actually a service. The CAP provides access to the service. Currently if the client cannot get an EventQueueGet cap, it will refuse to show neighbor regions and you will not be able to teleport to another region. You're essentially trapped where you are.

It's also very easy for the client to stop polling the EventQueueGet CAP

The Client essentially sends an application/xml Map with two keys. ack and done. Ack is an integer of the last Event ID and done is.. well, we don't know what done is yet besides it's a boolean. At this moment, it's always false.

The simulator will hold on to this request until it has some events to send to the client or the simulator times out the connection with a very specific response. The simulator will usually do this in around 20 to 30 seconds from the request start. To understand this, think in terms of requesting a web page that does a lot of background processing before sending you back a response. If you were to be able to post to the EventQueueGet Cap in a browser, it would look like a white page loading for about 20 or 30 seconds, and then it would give you back a 502 error. Don't fret! the 502 error is normal! When the EventQueueGet service doesn't have any events to send to the client, it typically sends a 'HTTP/1.0 502 Upstream error:' response with 'Upstream error: ' as the body. It's really important to note that the client will *only* accept a response like stated above. If you send it as a HTTP/1.1 response, the client will stop polling!

After the client closes the connection to the simulator (with a DisableSimulator packet), further attempts to poll the EventQueueGet cap will result in a 404 response. This tells the client to stop polling the cap. On the Debug Console, you'll see a nice message paraphrased: EventPollResponder: {1} https://CAPADDRESS/ stop 404

The client will keep polling the EventQueueGet cap until you give it a 404 even after you've left the region!


The client posts to the EventQueueGet cap provided in the region seed cap with an application/xml content type. (this will eventually be application/llsd+xml)

Client Request ->
{
  ack  : integer,
  done : boolean
}

; Successful response (no events) <-
HTTP/1.0 502 Upstream error:
Content-Type: text/plain
Connection: close

Upstream error: 

; Successful Response (event) <-
{
  events : [ event ],
  id     : integer
}

There are a few events that OpenSimulator has implemented over the EventQueueGet cap. So far they're;

  • EnableSimulator
  • CrossedRegion
  • TeleportFinish


EnableSimulator

EnableSimulator is the event that tells the client to connect to a new simulator. We use it to inform clients that there is a neighbor region to the one that the avatar is currently in. This causes the client to attempt to connect to the region described in the EnableSimulator event.

{
  body    : {
              SimulatorInfo : [
                                {
                                  Handle : binary
                                  IP     : binary
                                  Port   : integer
                                }
                              ]
            },
  message : 'EnableSimulator'
}

Remember, Handle is the regionhandle of the new simulator in BIG Endian format, base64 encoded. IP is the IP Address of the new simulator as a byte array, base64 encoded. Port is the UDP port of the new simulator UDP service.

Note:
The IP address (24.151.1.250) contains 4 bytes:
24
151
1
250

The regionhandle is a 64 bit representation of the X and Y cordinate of the 0,0 point of the new simulator
Where x is the uint X coordinate, and y is the uint Y coordinate, the formula for creating a regionhandle is: 
ulong regionhandle = ((ulong)x << 32) | (ulong)y;


CrossedRegion

The simulator uses CrossedRegion to inform your client that it has crossed into a new region. Typically this is sent out when an avatar crosses a border between two simulators.

{
  body    : {
              CrossedRegion : [
                                {
                                  AgentData  : [
                                                 {
                                                   AgentID   : UUID,
                                                   SessionID : UUID
                                                 }
                                               ],
                                  RegionData : [
                                                 {
                                                   RegionHandle   : binary,
                                                   SeedCapability : string,
                                                   SimIP          : binary,
                                                   SimPort        : integer
                                                 }
                                               ],
                                  Info       : [
                                                 {
                                                   LookAt   : [ real, real, real ],
                                                   Position : [ real, real, real ]
                                                 }
                                               ]
                                }
                              ]
            },
  message : 'EnableSimulator'
}

TeleportFinish

This tells the client that the serverside processing for teleport is complete and that the client should begin the client side portion of the teleport.

{
  body    : {
              Info : [
                       {
                         AgentID : UUID,
                         LocationID : integer,
                         RegionHandle : binary,
                         SeedCapability : string,
                         SimAccess : integer,
                         SimIP : binary,
                         SimPort : integer,
                         TeleportFlags : binary
                       }
                     ]
             },
  message : 'TeleportFinish'
}


You can find additional information on : a page from libsecondlife.org.