Description

RealityServer Web Services state system. RealityServer Web Services state is used to setup the initial environment before server requests are processed. State processing occurs for both HTTP and RTMP requests and performs essentially the same function in both. However due to the differences in the capabilities of the two protocols separate state implementations are provided for each.

In addition to setting up the server environment state handlers provide an additional level of access control. A handler can return false to deny a request or true to allow it.

HTTP State

HTTP state processing is the next step after a url has been authorized. A state module is primarily used to setup the initial environment for command processing. To achieve this it has access to all the HTTP request information.

A typical state module will check the HTTP request for state information. This information may be encoded within the url (EG: by embedding an ID within the url), encoded as a cookie or provided as arguments. From this the module can:

• Specify the initial scope in which commands are executed.

• Specify the user state name. This name is used to access a user scope in which information related to the state can be stored. This scope is not used by the RealityServer Web Services core but is provided for use by user commands and events.

• Install event handlers.

• Attach objects which will be provided to all other components executed while processing this request.

• Perform URL remapping. By default the incoming URL path is mapped directly into the content root directory. A state handler can rewrite this path to an alternate directory in content root. Any relative paths passed into the path mapper will be resolved relative to the new URL path. Additionally, static content requests will be performed on the rewritten path.

As the state module has full access to the HTTP request it is able to modify it as required. These modifications will be passed on to the next levels of processing. Any component used to specify state should typically be removed from the request so it does not interfere with later components. For example if state information was encoded in the url path then this must be stripped from the url.

Multiple state handlers can be registered with RealityServer Web Services and handlers can be configured on a per URL basis.

After state processing the url is checked to see if it is a documentation or static content request and then proceeds to protocol processing.

RTMP State

RTMP state processing only occurs for RPC command requests. As the RTMP specification provides no standard way to provide state information with RPC; RealityServer Web Services defines it's own method of doing so by passing optional state information in addition to command arguments.

A typical RTMP service command call is made by providing the command name to execute, any response methods and and an object containing the named command arguments.

‎var connection:NetConnection = ...

connection.call("element_set_attribute",new Responder(elementSet,commandError),
    {
        "element_name":"gold_shader",
        "attribute_name":"refl_color",
        "attribute_value": { "r":0.3,"g":0.6,"b":0.8 }
    }
);

State information is specified by adding two optional arguments. The first is a String containing the URL path to execute the request at. The second is an Object containing String/Value pairs representing additional state information. Both of these are passed directly into the RTMP state handler and either can be null.

‎var connection:NetConnection = ...

connection.call("element_set_attribute",new Responder(elementSet,commandError),
    {
        "element_name":"gold_shader",
        "attribute_name":"refl_color",
        "attribute_value": { "r":0.3,"g":0.6,"b":0.8 }
    },
    "/applications/rtmp_demo/",        // URL path
    {
        "scope_name":"user_scope_1"    // state information
    }
);

RTMP state handlers can setup and modify the same information as HTTP handlers including URL remapping. The supplied URL path is used to select the state handler to execute, if it is not supplied then the URL path used when creating the initial connection is used.

State handlers are implemented in RealityServer Web Services plugins using the mi::rswservices::IState interface. These are registered with RealityServer Web Services via mi::rswservices::IExtension_context.