SloodleLSLRequest

Contents 1 Declaration 2 Summary 3 Compatibility 4 Data 4.1 Status Data 4.1.1 var $request_data_processed 4.1.2 var $auth_status 4.2 Request Data 4.2.1 var $password 4.2.2 var $login_zone_pos 4.2.3 var $course_id 4.2.4 var $module_id 4.2.5 var $avatar_uuid 4.2.6 var $avatar_name 4.2.7 var $login_security_token 4.3 Utility Objects 4.3.1 var $response 4.3.2 var $user 5 Functions 5.1 Passive Accessors 5.1.1 is_request_data_processed() 5.1.2 get_auth_status() 5.1.3 is_authenticated() 5.1.4 is_auth_failed() 5.1.5 set_response($response) 5.1.6 set_user($user) 5.2 Active Accessors 5.2.1 get_password() 5.2.2 get_course_id() 5.2.3 get_module_id() 5.2.4 get_avatar_uuid() 5.2.5 get_avatar_name() 5.2.6 get_login_security_token() 5.2.7 get_response() 5.2.8 get_user() 5.3 Construction 5.3.1 SloodleLSLRequest(&$response, &$user) 5.4 Other Functions 5.4.1 process_request_data($force = FALSE) 5.4.2 authenticate_request($require = TRUE) 5.4.3 get_course_record($require = TRUE) 5.4.4 get_course_module_instance($type = '', $require = TRUE) 5.4.5 required_param($parname, $type=PARAM_RAW)

Declaration

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

Summary

This PHP class is created to simplify and automated much of the handling of HTTP requests from LSL scripts. With a single function call, it will fetch and store all of the standard Sloodle parameters, and perform basic functionality. It will also manipulate a SloodleUser object and a SloodleLSLResponse object to reflect the input data (both of these objects can be provided in the constructor, which is handled automatically by the SloodleLSLHandler class).

Additional functions allow further processing on the input data, as well as the ability to fetch custom parameters. It is also capable of terminating the script and automatically outputting an error message if an error occurs.

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 appropriate accessor functions.

Data

All data should be considered private.

Status Data

These data members represent general status information about the request.

var $request_data_processed

This member will always be a boolean, initially FALSE, indicating whether or not the request data has been processed yet. Use the "process_request_data(..)" function to process the data.

var $auth_status

This member indicates the status of authentication of the request (i.e. the success or failure of the password). It will take on one of the following values: SLOODLE_AUTH_UNKNOWN (default), SLOODLE_AUTH_OK, or SLOODLE_AUTH_FAILED. These represent "authentication not attempted, "authentication succeeded", and "authentication failed" respectively.

You can check authentication by calling the "authenticate_request()" member function.

Request Data

These data members represent data which has been passed-in via HTTP parameter. If a value is NULL (default) and the request data has been processed, then that value was not specified in the request.

var $password

The security password provided by an object in the "sloodlepwd" parameter. This can either be the site-wide Prim Password, or an object-specific session key (if using Object Authorization).

var $login_zone_pos

Contains an array vector {x,y,z} giving the position of a LoginZone, as reported in HTTP parameter "sloodleloginzonepos".

var $course_id

Integer identifying a Moodle course, as specified in HTTP parameter "sloodlecourseid".

var $module_id

Integer identifying a Moodle course module instance, as specified in HTTP parameter "sloodlemoduleid".

var $avatar_uuid

A string containing the UUID of an SL avatar, as specified in HTTP parameter "sloodleuuid". When processing takes place, this value is automatically passed-on to the $response object.

var $avatar_name

A string containing the name of an SL avatar, as specified in HTTP parameter "sloodleavname". Note that this is the full name separated by a space -- i.e. "firstname lastname".

var $login_security_token

A string containing the login security token for the user registration attempt, as given in HTTP parameter "sloodlelst".

Utility Objects

These members are references to other objects which are used/manipulated by this object. They may be passed-in from outside, either via the constructor or via accessor. However, if none are passed-in, then the class creates them itself. (Note: the SloodleLSLHandler class automatically provides its own objects for this purpose).

var $response

Reference to a SloodleLSLResponse object, to which appropriate response data is automatically written during request processing. Additionally, this object is used for output purposes if an error occurs.

var $user

References to a SloodleUser object, to which appropriate user data is automatically written during request processing. If an avatar is identified in the request data, then their Sloodle user data is fetched (if it exists). Additionally, if it is linked to a Moodle account, then that data is fetched as well.

Functions

Passive Accessors

These functions are used to get/set data which is otherwise private. No other processing is done in these functions.

is_request_data_processed()

Returns the value of member $request_data_processed, indicating whether or not basic request processing has already been done.

get_auth_status()

Returns the value of member $auth_status, indicating if request authentication has been attempted, and whether or not it was successful.

is_authenticated()

Returns TRUE if the request has been authenticated, or FALSE if it has not been attempted, or if authentication failed.

is_auth_failed()

Returns TRUE if request authentication has failed, or FALSE if it succeeded or has not yet been attampted.

set_response($response)

Provides a reference to a SloodleLSLResponse object which is to be stored in the $response member.

• Note: if you are providing a custom response object, it is advisable to provide it in the constructor, or immediately thereafter.

set_user($user)

Provides a reference to a SloodleUser object which is to be stored in the $user member.

• Note: if you are providing a custom user object, it is advisable to provide it in the constructor, or immediately thereafter.

Active Accessors

These functions provide access to the request data, but will first make sure the request data has been processed. (Note: if the request data has already been processed, then it is not done again). Remember that each function may return NULL if the appropriate parameter was not specified in the request.

get_password()

Returns the password string stored in member $password.

get_course_id()

Returns the course ID integer stored in member $course_id.

get_module_id()

Returns the module ID integer stored in member $module_id.

get_avatar_uuid()

Returns the avatar UUID string stored in member $avatar_uuid.

get_avatar_name()

Returns the avatar name string stored in member $avatar_name.

get_login_security_token()

Returns the login security token string stored in member $login_security_token.

get_response()

Returns the reference to a SloodleLSLResponse object stored in member $response.

get_user()

Returns the reference to a SloodleUser object stored in member $user.

Construction

SloodleLSLRequest(&$response, &$user)

This constructor can be used to provide references to SloodleLSLResponse and SloodleUser objects (parameters $response and $user respectively). If they are not NULL, then they are stored in members $response and $user respectively. However, if the parameters are NULL, then the constructor creates its own objects for this.

• Note: you can provide one object, and make the other NULL.

Other Functions

Like the "Active Accessors" above, these functions will make sure the request data has been processed before they execute.

process_request_data($force = FALSE)

This is the most important function in the class. It will check for all of the standard Sloodle parameters in the incoming HTTP request (using the Moodle "optional_param" function), and store any values it finds. Most other member functions in this class will call this function if necessary before they start, so you rarely actually need to call this function directly. However, it is strongly advisable to do so anyway, to avoid problems.

It also performs certain processing, such as converting the Login Zone position string to an array of vector information. Most importantly, if an avatar is identified by name and/or UUID, then it will lookup that user in the database and, if found, store their details in the SloodleUser $user member. Additionally, if the avatar is linked to a Moodle account, then it will automatically lookup and store the details for that Moodle account in the $user member as well. Another useful feature is that, if only the avatar name or UUID was specified in the request, but the other item was found in the database, then it will replace the missing request data so that your processing scripts can continue without problem.

Furthermore, this processing function will write certain items of data to the SloodleLSLResponse $response member, including avatar UUID, and the request descriptor (which does not get stored in the request class).

• NOTE: when processing is done, the $request_data_processed member is set to TRUE. If processing has already been done when this function is called, then it is not done again... unless the optional $force parameter is explicitly set to TRUE (the default is FALSE). This can be used if you know the request data has changed, for whatever reason... although that is a very unlikely circumstance!

authenticate_request($require = TRUE)

This function is used to check the authentication information provided in the request parameters (i.e. the $password member) against the authentication data in the database. If the authentication data is correct, then it will set the $auth_status member to SLOODLE_AUTH_OK, and return TRUE.

If authentication fails, then behaviour the $auth_status member is set to SLOODLE_AUTH_FAILED, although the subsequent behaviour depends upon the $require parameter. If $require is TRUE (default), then the script will terminate with an error message. Otherwise, it will simply return FALSE.

• In most cases, you can omit the $require parameter, as it will default to TRUE, and you want to make sure unauthorised requests are not permitted.
• See Prim Password and Object Authorization for more information on object authentication methods.

get_course_record($require = TRUE)

Searches the database for the course identified in member $course_id (HTTP parameter "sloodlecourseid"). If the parameter was specified, and the course is found, it returns a database record object representing the course.

Note that if the course ID was not specified, the course does not exist, or if it is not visible, the function will fail. If parameter $require is TRUE (default) then failure means the script will terminate with an error message. Otherwise, it will return FALSE.

get_course_module_instance($type = '', $require = TRUE)

Searches the database for the course module instance identified in member $module_id (HTTP parameter "sloodlemoduleid"). If the instance is found, is visible, and is of the correct type (according to the name in parameter $type) then a database record object is returned. (Note: type-checking is based on module names such as "forum" or "sloodle". It is optional, and is skipped if the name is empty).

Note that if the module ID was not specified, the module does not exist, it is not visible, or if it is of the wrong type, then the function fails. If parameter $require is TRUE (default) then failure means the script will terminate with an error message. Otherwise, it will return FALSE.

required_param($parname, $type=PARAM_RAW)

This function is a Sloodle-friendly version of the Moodle "required_param" function. However, instead of rendering an HTML error message on failure, this will render an LSL-friendly error message.

It is used to get a particular HTTP request parameter, with name $parname, and type according to parameter $type (the standard Moodle types work here, such as PARAM_RAW for a string, PARAM_INT for an integer).

• See also the global Sloodle function: sloodle_required_param.

(The advantage to using the member version is that it will still output other response status data that may have been accumulated).

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