Communicating between server and client
From SLIS Second Life Wiki
This specification was implemented fully for Sloodle version 0.2. You can find more information about using it in the Developer Documentation.
Contents |
[edit] Requesting information from the Moodle server
To request information from the Moodle server, send an HTTP request to the relevant Sloodle linker script.
The best way to construct your response on the server is to use the Sloodle PHP API (particularly look at the SloodleLSLHandler and it's member instance of SloodleLSLResponse).
If you just need a list of a single piece of data that doesn't contain pipe characters or new-lines, and you're not doing any error handling, you can just do this:
1 first thing second thing third thing
...but make sure your LSL script wouldn't break if it received something like:
1|OK|322,422|AVATAR_LIST|1191894643|1191894681|1234343-dfdfjdksfjdk-2323232|12345|3|2 first thing second thing third thing
If you're doing more than that, read on...
The script should respond with an HTTP response with the following characteristics:
- The first line is the "status line" for information about the request. (See below)
- Fields should be separated by pipe characters (|). If you need to use a pipe characters i your content, it should be escaped with a backslash, eg. \|.
- Items should be separated by UNIX-style new-line characters (\n). If you need to use a UNIX-style new-line characters in your content, it should be escaped with a backslash (\\n).
- Backslashes (\) should be escaped with a backslash (\\)
- The response should contain no more than 2048 characters. If you need to send more than 2048 characters to the client, your data should be separated into pages, which will be indicated in the status line. See Separating data into pages for details.
[edit] The status line
The status line should contain the following information, in order, separated by pipe characters (|):
- (Required) Result: 1 for success, a negative number for failure. [NB Up until now I was using "OK" or "ERROR".] These will be clustered by type, eg. -100 to -200 for authentication issues, -200 to -300 for system failures, etc. These codes should be documented on the Sloodle status codes page.
- (Optional) Description: A generalized status description understandable by both humans and scripts. In the case of an authentication error, this field would read "AUTH". These should also be documented on the Sloodle status codes page.
- (Optional) Side-effect status codes: A comma-delimited list of events that occurred in addition to the main function of the script. For example, a user may try to take a quiz, but be automatically registered and enrolled on the course in the process. In this case, we would return the course data as normal, but add success codes for registration and enrollment in this field. (eg. "322,422")
- (Optional) Request descriptor: This is a piece of text that should be set in the request, allowing the script to tell what kind of request it's getting back. For example, if it's making a request for a list of avatars for the course, the request might contain "AVATAR_LIST" and the response the same.
- (Optional) Request timestamp: A unix timestamp passed by the requesting script showing the time at which the request was made. This should be passed as is back to the requester.
- (Optional) Response timestamp: The time the response header was generated
- (Optional) User Key: The key of the user concerned, if there is one.
- (Optional) Tracking Code: A tracking code for the response. [TODO: Figure out exactly how we'll use these...]
- (Recommended) Page total: The number of pages across which the data we are trying to transmit has been split. Usually we won't need to do fancy things like this, so it'll be 1.
- (Recommended) Page number: The page number of the current page, starting at 1. Usually we won't need to do fancy things like this, so it'll be 1.
To allow for meta-data we realize we need in the future, LSL scripts should ignore any additional fields tacked onto the end of the meta-data line that we hadn't created when we wrote the script.
[edit] The data lines
In case of success, the data lines should contain whatever you want to put in them. You should document what you're putting in them in comments in the PHP linker script. In the case of an error, they should contain descriptive human-readable error messages.
[edit] Example: Success (Simple example)
1 Buddy Sprocket Edmund Earp
[edit] Example: Success (More complicated example)
1|QUIZZES|322,422|1234343-dfdfjdksfjdk-2323232|12345|3|2 1234|What's the difference between a duck?|One of it's legs is both the same. 1235|What do you call a chicken with a pipe character and a new-line?|\|\\n
[edit] Example: Failure
-102|AUTH||1234343-dfdfjdksfjdk-2323232|12346|1|1 The authentication code supplied, asdf123asdf987, was not valid.
| This page is part of the Sloodle documentation | |||
|---|---|---|---|
| SloodleDocs Home | User Documentation | Administrator Documentation | Developer Documentation | Sloodle Wiki Home | |||
