SloodleLSLResponse

Contents 1 Declaration 2 Summary 3 Compatibility 4 Data 4.1 var $status code 4.2 var $status_descriptor 4.3 var $side_effects 4.4 var $request_descriptor 4.5 var $request_timestamp 4.6 var $response_timestamp 4.7 var $user_key 4.8 var $tracking_code 4.9 var $page_total 4.10 var $page_number 4.11 var $data 5 Functions 5.1 Accessors 5.1.1 set_status_code($par) 5.1.2 set_status_descriptor($par) 5.1.3 set_side_effects($par) 5.1.4 add_side_effects($par) 5.1.5 add_side_effect($par) 5.1.6 =set_request_descriptor($par) 5.1.7 set_request_timestamp($par) 5.1.8 set_response_timestamp($par) 5.1.9 set_user_key($par) 5.1.10 set_tracking_code($par) 5.1.11 set_page_total($par) 5.1.12 set_page_number($par) 5.1.13 set_data($par) 5.1.14 add_data_line($par) 5.1.15 clear_data() 5.2 Other Functions 5.2.1 SloodleLSLResponse($status_code=NULL, $status_descriptor=NULL, $data=NULL) 5.2.2 render_to_string(&$str) 5.2.3 render_to_output() 5.2.4 quick_output($status_code, $status_descriptor=NULL, $data=NULL, $static=TRUE) 5.2.5 _internal_validation_error($msg)

Declaration

class SloodleLSLResponse
Defined in: lib/sl_iolib.php
Contained by: SloodleLSLHandler, SloodleLSLRequest

Summary

This PHP class will help to structure and render appropriate response data for HTTP requests coming from in Second Life. See Sloodle communications specification for more information on the format.

The functions in the class are mostly accessor functions, which can be used to set items of data. They will do basic error-checking, store the data appropriately. The data rendering function will then perform additional error-checking, and then structure the data accordingly. It can be returned as a string, or renderer directly to the HTTP response.

Compatibility

This class conforms to PHP4 syntax, and so scope visibility qualifiers (public, private, protected) are not available. All of the data should be considered private, with access via appropraite accessor functions.

Data

Each data member represents some data to be output. If the value is NULL (which is default), then it is ignored (unless the value is required, in which case an error is generated). All data in this class should be considered private:

var $status code

Required. An integer representing the status code of the request. A positive value means success, while a negative value means error.

var $status_descriptor

Optional, but recommended. A string giving the general category of the status code. You can see this information alongside the status codes on the Sloodle status codes page.

var $side_effects

Optional. Status codes of any side-effects caused while handling the request (such as auto-registration/enrolment of the user). Can be either a single integer, or an array of integers.

var $request_descriptor

Optional. A brief string describing the request. This value should not usually be specified within a PHP script. Rather, it should be taken from an HTTP parameter in a request (parameter name 'sloodlerequestdesc'). If using the SloodleLSLHandler class correctly, this value will be automatically parsed by the SloodleLSLRequest object, and written into the SloodleLSLResponse object. This can be used by LSL scripts to distinguish one response from another.

var $request_timestamp

Optional. An integer giving the timestamp when the request was first made from within Second Life. Note that currently this value is not automatically parsed and handled by the SloodleLSLRequest class, so it will need to be handled manually if desired.

var $response_timestamp

Optional. An integer giving the timestamp when the response was generated on the Moodle side. This can be used by objects in-world to test turnaround times, and also to check when responses might be invalidated. Note that currently this is not generated automatically, so it will need to be set manually if you want to use it. (The return value from PHP's standard "time()" function would suffice).

var $user_key

Optional. A string containing the UUID key of an SL agent (or avatar). It should generally refer to the avatar who initiated the request in the first place, but this is optional.

• Note: when using the SloodleLSLHandler object correctly, the user key will be automatically taken from the "sloodleuuid" request parameter when the request is first processed. Thereafter, you can change it if you wish.

var $tracking_code

Not used yet. Can be any type which can be directly cast to a string.

var $page_total

Not used yet. An integer specifying the total number of pages which the full response requires. If $page_total is set but $page_number is not (or vice versa) then the response rendering function will fail.

var $page_number

Not used yet. An integer specifying the response page currently being returned. If $page_total is set but $page_number is not (or vice versa) then the response rendering function will fail.

var $data

Optional. This member will contain the line or lines of data which should follow the status line in the response. It can be a single scalar value (e.g. int or string), or an array. If it is an array, then each element becomes one line. Each line can also be a single scalar, or an array of scalars. Wherever the line is an array, each element is printed on the same line, with a field separator between them.

• NOTE: it is imperative that you avoid data which conflicts with the line and field separators (SLOODLE_LINE_SEPARATOR and SLOODLE_FIELD_SEPARATOR). Currently these are the newline "\n" and pipe "|" characters respectively.

Functions

Accessors

Each accessor function is used to set a particular value in the response. They will perform any basic error checking, and will immediately terminate the script with an error message on failure. You can set a value to NULL to remove it from the response (unless it is a required value). There are no equivalent "get" accessors.

set_status_code($par)

Sets the value of member $status_code. Fails if $par is not an integer, or if is 0 (because 0 is an invalid status code).

set_status_descriptor($par)

Sets the value of member $status_descriptor. Fails if $par is not a string or NULL.

set_side_effects($par)

Sets the value of member $side_effects. Fails if $par is not an integer, an array or integers, or NULL.

• Note: this function should not normally be used, unless you want to set the side effects codes to NULL in order to remove them from the response. Normally you should use "add_side_effect(..)" or "add_side_effects(..)".

add_side_effects($par)

Adds one or more side effect codes to the $side_effects member. Parameter $par can be either an integer or an array of integers. Otherwise, the function fails.

add_side_effect($par)

Adds a single side effect to the $side_effects member. Parameter $par must be a single integer, otherwise the function will fail.

=set_request_descriptor($par)

Sets the value of member $request_descriptor. Fails if $par is not a string or NULL.

set_request_timestamp($par)

Sets the value of member $request_timestamp. Fails if $par is not an integer or NULL.

set_response_timestamp($par)

Sets the value of member $response_timestamp. Fails if $par is not an integer or NULL.

set_user_key($par)

Sets the value of member $user_key. Fails if $par is not a string or NULL.

set_tracking_code($par)

Sets the value of member $tracking_code. No error checking.

set_page_total($par)

Sets the value of member $page_total. Fails if $par is not a positive or zero integer, or NULL.

set_page_number($par)

Sets the value of member $page_number. Fails if $par is not a positive or zero integer, or NULL.

set_data($par)

Sets the value of member $data. Parameter $par can be NULL, a single scalar, or an array containing scalars and/or arrays of scalars. Otherwise, the function fails.

• NOTE: You are advised not to use this function in most circumstances. It is generally preferable to use the "add_data_line(..)" member function instead (see below).

add_data_line($par)

Adds a single line of data to the $data member. Parameter $par can be a single scalar, or an array of scalars. Otherwise, the function fails.

clear_data()

Clears all data from the response by setting the $data member to NULL.

Other Functions

SloodleLSLResponse($status_code=NULL, $status_descriptor=NULL, $data=NULL)

Constructor. All parameters for this constructor are optional. If specified, they will be automatically stored in the object. Otherwise, the function does nothing.

render_to_string(&$str)

This function takes an object reference, forces it to an empty string, and renders all of the response data to it. If any errors occur (such as invalid data), the script will terminate with an error message.

render_to_output()

This function will create a string, use the "render_to_string(..)" function (see above) to render the output, and then echo it to the HTTP response.

quick_output($status_code, $status_descriptor=NULL, $data=NULL, $static=TRUE)

This function is designed for quick output, avoiding several accessor-calls. It call be used in two ways: statically (default), or non-statically. (This is affected by the $static parameter, not by calling method convention). If in static mode, then it creates a new response object, writes all of the specified parameters (status code etc.) to it, and immediately outputs it to the HTTP response.

Non-static mode will use the object as-is, write your parameters to its members, and render it to output. This is useful if you are using a SloodleLSLResponse object in a SloodleLSLHandler class, in which case certain items of data may already have been written to it by the SloodleLSLRequest class.

_internal_validation_error($msg)

This function is used internally when a validation error has occured within the SloodleLSLResponse class. It will output properly structured data containing the error message from parameter $msg. It does not use any class functions or data, so it can safely be called statically on the class (rather than on an instance).

This page is part of the SLOODLE documentation
Docs: Users | Administrators | Developers
Wiki Frontpage Sloodle.org