Pyogp will be implementing and testing many of the Legacy and OGP protocols. This is a listing of those protocols as well as the details on how to go about implementing and testing them.

Note that for the exception fields for the calls in each step, you can generally get all the standard exceptions for HTTP, sockets, or URLs. However, the ones listed are the ones that are typical signs that something may be off.

Legacy Login

We will detail what needs to be done to login with the legacy protocols.

OGP Login

OGP Draft Login flowchart - flowchart for current OGP login protocols

Login is the process of establishing the three way communication between viewer, agent and region. There are two phases, viewer to agent login, and then placement of agent in a particular region. Over the course of a viewer session, the agent may move around from region to region, and so constitutes a repetition of the agent to region login phase.

The OGP uses HTTP methods for logging in, such as POST and GET.

Flow Outline

Login to auth.cgi on a login server with credentials
Get other capabilities, such as place_avatar
Post to place_avatar with desired region_url

Details

The first thing that needs to be done is to pass our credentials to a login server that is running the OGP protocols (agent domain implemented). Currently, Linden Lab has a server that is running an agent domain that is still a work-in-progress. The login server is https://login1.aditi.lindenlab.com/cgi-bin/auth.cgi.

Step 1 - Login to login server running OGP protocols (has agent domain implemented) to get agent host seed capability

Verb	POST
URL	login url for the agent domain https://login1.aditi.lindenlab.com/cgi-bin/auth.cgi
Headers	{"Content-type" : "application/llsd+xml"}
Request	{"password": password, "lastname": lastname, "firstname": firstname}
Response - Success	agent-host-seed-capability url Note: in the current LL implementation of the agent domain, there is redirect that needs to take place. When posting to the login url, there will be a HTTP 302 error that will have the capability url set in the 'location' field of the error headers (headers['location']). You will have to properly handle the exception thrown in order to get the location of the redirect.
Response - Failure	HTTP 404 - Not Found - your credentials were probably typed in incorrectly, your agent isn't registered, or something else.
Exceptions	HTTP 500 - Internal Server Error - the login server is down. Someone must internally fix it.

Step 2 - Getting Capabilities (at least place_avatar)

Step 1 got us the agent-host-seed-capability. With the seed capability we can invoke it and get other capabilities for anything that we might need to do. At the very least, we should be getting the place_avatar capability because we need this to get placed onto a region (or simulator). We may also want the event_queue capability, among others.

Verb	POST
URL	agent-host-seed-capability from Step 1
Headers	{"Content-type" : "application/llsd+xml"}
Request	{ "caps": [ name1, name2, … ] }
Response - Success	{ "caps": { name1: url1, name2: url2, … } }
Response - Failure
Exceptions

Step 3 - invoking place_avatar

Step 2 got us the url for the place_avatar capability. Now we have to invoke it with the region url of where we want to be placed. This invocation causes us to be placed in the region (or on a simulator). The response also gives us the capability to the region/sim (called "seed_capability" in the response), along with the ip, port, and everything else we need to connect to the sim. With the seed capability for the sim, we can start communicating with it.

Verb	POST
URL	place_avatar capability from Step 2
Headers	{"Content-type" : "application/llsd+xml"}
Request	{"region_url": <url string> "position": [<f32>x, <f32>y, <f32>z]} Note: position is optional
Response - Success	{ "seed_capability": <uri string> "look_at" : [<f32>x, <f32>y, <f32>z] "sim_ip": <ip string> "sim_port": <int> "region_x": <int> "region_y": <int> "region_id" : <uuid> "sim_access" : <string> "PG"\|"Mature" "connect": <bool> "position": [<f32>x, <f32>y, <f32>z] // Extra stuff "connect": <bool> // The above are the same as response to rez_avatar // The following are only returned on login, not over teleport "session_id":<uuid> "secure_session_id":<uuid> "circuit_code":<int> }
Response - Failure	HTTP 400 - Bad Requeset - Seems we get a 400 when we try to log in too soon after logging out.
Exceptions	Sometimes the circuit_code, session_id, or secure_session_id aren't returned. This is probably when the region or sim believes we are already logged in (didn't log out the last time we exited)

Step 4 - LOGIN COMPLETE

Now we can start communicating with the sim using the information we received as a response from Step 3. From here, we go into different protocols to follow. We have to establish presence, set up the event_queue, and start getting and sending updates to the sim.

Pyogp/Protocols

Contents