RealityServer Web Services API Programmer's Manual

mi::rswservices::IExtension_context Class Reference

[Extensions]

Description

Context which can be used to register user implemented functionality. This context is supplied to RealityServer Web Services plugins to enable them to register their functionality.

Public Member Functions

virtual const IConfigurationget_configuration() const =0
Returns the RealityServer Web Services configuration. More...
virtual nservices::IEvent_contextget_event_context() const =0
Returns the RealityServer Web Services event context. More...
virtual nservices::IFactoryget_factory() const =0
Returns a factory, may be used to create user type definitions. More...
virtual http::IServerget_http_server() const =0
Returns the HTTP server. More...
virtual base::ILoggerget_logger() const =0
Returns a logger that can be used by extensions. More...
virtual neuraylib::IPlugin_apiget_plugin_api() const =0
Returns the neuray library plugin api.
virtual Sint32 install_authorizer( IAuthorizer* authorizer) =0
Install an authorizer into RealityServer Web Services. More...
virtual Sint32 install_command( nservices::IService_command* command, const char* url = NULL) =0
Install a command into RealityServer Web Services. More...
virtual Sint32 install_event_handler( nservices::IEvent_handler* handler) =0
Install an event handler into RealityServer Web Services. More...
virtual Sint32 install_log_handler( ILog_handler* log_handler) =0
Install a log handler into RealityServer Web Services. More...
virtual Sint32 install_protocol( IProtocol* protocol) =0
Install a protocol into RealityServer Web Services. More...
virtual Sint32 install_render_handler( IRtmp_render_handler_factory* render_handler_factory) =0
Install a RTMP render handler factory into RealityServer Web Services. More...
virtual Sint32 install_state( IState* state) =0
Install a state processor into RealityServer Web Services. More...
virtual Sint32 install_user_type( nservices::IUser_type_definition* definition) =0
Install a user type into RealityServer Web Services. More...
virtual Sint32 install_websocket_handler( IWebsocket_handler* websocket_handler) =0
Install a websocket handler into RealityServer Web Services. More...
virtual Sint32 remove_authorizer( IAuthorizer* authorizer) =0
Removes an authorizer from RealityServer Web Services. More...
virtual Sint32 remove_command( nservices::IService_command* command, const char* url = NULL) =0
Removes a command from RealityServer Web Services. More...
virtual Sint32 remove_event_handler( nservices::IEvent_handler* handler) =0
Removes an event handler from RealityServer Web Services. More...
virtual Sint32 remove_log_handler( ILog_handler* log_handler) =0
Removes a log handler from RealityServer Web Services. More...
virtual Sint32 remove_protocol( IProtocol* protocol) =0
Removes a protocol from RealityServer Web Services. More...
virtual Sint32 remove_render_handler( IRtmp_render_handler_factory* render_handler_factory) =0
Removes a render handler from RealityServer Web Services. More...
virtual Sint32 remove_state( IState* state) =0
Removes a state processor from RealityServer Web Services. More...
virtual Sint32 remove_user_type( nservices::IUser_type_definition* definition) =0
Removes a user-type from RealityServer Web Services. More...
virtual Sint32 remove_websocket_handler( IWebsocket_handler* websocket_handler) =0
Removes a websocket handler from RealityServer Web Services. More...

Member Functions

virtual const IConfiguration* mi::​rswservices::​IExtension_context::get_configuration() const [pure virtual]

Returns the RealityServer Web Services configuration.

Returns

the configuration

virtual nservices::IEvent_context* mi::​rswservices::​IExtension_context::get_event_context() const [pure virtual]

Returns the RealityServer Web Services event context. UAC events must be registered on this event context. Note that events registered with this context will not receives state or execution transactions.

virtual nservices::IFactory* mi::​rswservices::​IExtension_context::get_factory() const [pure virtual]

Returns a factory, may be used to create user type definitions.

Returns

a factory

virtual http::IServer* mi::​rswservices::​IExtension_context::get_http_server() const [pure virtual]

Returns the HTTP server. The user may install their own request handlers which will be called if the standard RealityServer Web Services handlers fail to process the request. Note that CGI request handlers will be executed before any other processing, including Authorization occurs. User response handlers will be called before any internal handlers.

Returns

the http server

virtual base::ILogger* mi::​rswservices::​IExtension_context::get_logger() const [pure virtual]

Returns a logger that can be used by extensions. Log messages from extensions should use the category "PLUGIN".

virtual neuraylib::IPlugin_api* mi::​rswservices::​IExtension_context::get_plugin_api() const [pure virtual]

Returns the neuray library plugin api.

virtual Sint32 mi::​rswservices::​IExtension_context::install_authorizer( IAuthorizer* authorizer) [pure virtual]

Install an authorizer into RealityServer Web Services. Note that RealityServer Web Services will not use the installed authorizer unless configured to do so.

Parameters

authorizer
the authorizer to install

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : authorizer is NULL or name not given.
  • mi::nservices::NRS_ERROR_INVALID_OPERATION : an authorizer already exists with the same name.
  • mi::nservices::NRS_ERROR_FAILED : general failure.

virtual Sint32 mi::​rswservices::​IExtension_context::install_command( nservices::IService_command* command, const char* url = NULL) [pure virtual]

Install a command into RealityServer Web Services. If a url is supplied then the command will only be made available to HTTP requests whose URL paths match url. If url is NULL or the empty string then the access path is derived from the location of the plugin DSO on the filesystem. If the DSO is beneath the RealityServer Web Services content root directory then the URL path is the path to the plugin relative to the content root. If it is outside content root then the command is accessible to all URLs.

If two commands with the same name and namespace are installed to the same url then the existing command will be removed and this commands implementation used instead. The RealityServer Web Services core commands plugin always installs its commands first. Other plugins are initialized in the order that their 'plugin_directory' directives appear in the configuration file. Within a given directory plugins are installed in alphabetical order by plugin filename. Naming plugin files along the lines of NNN_custom_commands-PLATFORM.so (where N represents a digit) can be used to control the order in which plugins are loaded and hence the order in which commands are installed.

Parameters

command
the command to install.
url
the url used to access the command.

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : command is NULL.
  • mi::nservices::NRS_ERROR_FAILED : general failure.

virtual Sint32 mi::​rswservices::​IExtension_context::install_event_handler( nservices::IEvent_handler* handler) [pure virtual]

Install an event handler into RealityServer Web Services. Note that this does not register the event handler to run at any time but simply makes it available to the framework. To register events use IEvent_context::register_handler

Parameters

handler
the handler to install

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : handler is NULL.
  • mi::nservices::NRS_ERROR_EVENT_HANDLER_NAME_INVALID : a handler with this name is already installed
  • mi::nservices::NRS_ERROR_FAILED : general failure.

virtual Sint32 mi::​rswservices::​IExtension_context::install_log_handler( ILog_handler* log_handler) [pure virtual]

Install a log handler into RealityServer Web Services.

Parameters

log_handler
the log handler to install

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : log_handler is NULL or name not given.
  • mi::nservices::NRS_ERROR_FAILED : general failure.

virtual Sint32 mi::​rswservices::​IExtension_context::install_protocol( IProtocol* protocol) [pure virtual]

Install a protocol into RealityServer Web Services.

Parameters

protocol
the protocol to install

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : protocol is NULL or name not given.
  • mi::nservices::NRS_ERROR_INVALID_OPERATION : a protocol already exists with the same name.
  • mi::nservices::NRS_ERROR_FAILED : general failure.

virtual Sint32 mi::​rswservices::​IExtension_context::install_render_handler( IRtmp_render_handler_factory* render_handler_factory) [pure virtual]

Install a RTMP render handler factory into RealityServer Web Services.

Parameters

render_handler_factory
the factory to install

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : render_handler_factory is NULL or name not given.
  • mi::nservices::NRS_ERROR_FAILED : general failure.

virtual Sint32 mi::​rswservices::​IExtension_context::install_state( IState* state) [pure virtual]

Install a state processor into RealityServer Web Services. Note that RealityServer Web Services will not use the installed state unless configured to do so.

Parameters

state
the state processor to install

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : state is NULL or name not given.
  • mi::nservices::NRS_ERROR_INVALID_OPERATION : a state processor already exists with the same name.
  • mi::nservices::NRS_ERROR_FAILED : general failure.

virtual Sint32 mi::​rswservices::​IExtension_context::install_user_type( nservices::IUser_type_definition* definition) [pure virtual]

Install a user type into RealityServer Web Services. If a user type is already registered under the given user type name then an error is returned unless the element names and types match exactly.

Parameters

definition
the definition created from a factory.

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : user_type_definition is NULL or name is NULL or an empty string.
  • mi::nservices::NRS_ERROR_INVALID_OPERATION : the user type name contains an invalid character or starts with '_' or the user type defines an infinite cycle of nested structures..
  • mi::nservices::NRS_ERROR_NOT_FOUND : a user type already exists with the same name but different elements.
  • mi::nservices:NRS_ERROR_NEURAY : a type with this name is already registered with the neuray library. Most likely a Structure is already registered under the same name.
  • mi::nservices::NRS_ERROR_FAILED : general failure.

virtual Sint32 mi::​rswservices::​IExtension_context::install_websocket_handler( IWebsocket_handler* websocket_handler) [pure virtual]

Install a websocket handler into RealityServer Web Services.

Parameters

websocket_handler
the websocket handler to install

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : websocket_handler is NULL or name not given.
  • mi::nservices::NRS_ERROR_FAILED : general failure.

virtual Sint32 mi::​rswservices::​IExtension_context::remove_authorizer( IAuthorizer* authorizer) [pure virtual]

Removes an authorizer from RealityServer Web Services. This method will only remove the authorizer if authorizer contains the same authorizer instance as that passed to install_authorizer.

Parameters

authorizer
The instance of the authorizer passed to install_authorizer.

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : name is NULL.
  • mi::nservices::NRS_ERROR_NOT_FOUND : an authorizer with this name is not registered.
  • mi::nservices::NRS_ERROR_FAILED : general failure.

virtual Sint32 mi::​rswservices::​IExtension_context::remove_command( nservices::IService_command* command, const char* url = NULL) [pure virtual]

Removes a command from RealityServer Web Services. This method will only remove the command if the command parameter contains the same instance of the services command passed to install_command.

Parameters

command
The instance of the service command that was passed to install_command.
url
the url that the command was registered under.

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : name is NULL
  • mi::nservices::NRS_ERROR_INVALID_OPERATION : no commands registered at url
  • mi::nservices::NRS_ERROR_NOT_FOUND : no command exists with the same name and namespace at url.
  • mi::nservices::NRS_ERROR_FAILED: framework not initialized.

virtual Sint32 mi::​rswservices::​IExtension_context::remove_event_handler( nservices::IEvent_handler* handler) [pure virtual]

Removes an event handler from RealityServer Web Services. This method will only remove the event handler if handler contains the same event handler instance as that passed to install_event_handler.

Parameters

handler
The instance of the event handler passed to install_event_handler.

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : name is NULL.
  • mi::nservices::NRS_ERROR_NOT_FOUND : an event handler with this name is not registered.
  • mi::nservices::NRS_ERROR_FAILED : general failure.

virtual Sint32 mi::​rswservices::​IExtension_context::remove_log_handler( ILog_handler* log_handler) [pure virtual]

Removes a log handler from RealityServer Web Services. This method will only remove the log handler if log_handler contains the same log handler instance as that passed to install_log_handler.

Parameters

log_handler
The instance of the log handler passed to install_log_handler.

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : name is NULL.
  • mi::nservices::NRS_ERROR_NOT_FOUND : a render handler with this name is not registered.
  • mi::nservices::NRS_ERROR_FAILED : general failure.

virtual Sint32 mi::​rswservices::​IExtension_context::remove_protocol( IProtocol* protocol) [pure virtual]

Removes a protocol from RealityServer Web Services. This method will only remove the protocol if protocol contains the same protocol instance as that passed to install_protocol.

Parameters

protocol
The instance of the protocol passed to install_protocol.

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : name is NULL.
  • mi::nservices::NRS_ERROR_NOT_FOUND : a protocol with this name is not registered.
  • mi::nservices::NRS_ERROR_FAILED : general failure.

virtual Sint32 mi::​rswservices::​IExtension_context::remove_render_handler( IRtmp_render_handler_factory* render_handler_factory) [pure virtual]

Removes a render handler from RealityServer Web Services. This method will only remove the render handler factory if render_handler_factory contains the same render handler factory instance as that passed to install_render_handler.

Parameters

render_handler_factory
The instance of the render handler factory passed to install_render_handler.

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : name is NULL.
  • mi::nservices::NRS_ERROR_NOT_FOUND : a render handler with this name is not registered.
  • mi::nservices::NRS_ERROR_FAILED : general failure.

virtual Sint32 mi::​rswservices::​IExtension_context::remove_state( IState* state) [pure virtual]

Removes a state processor from RealityServer Web Services. This method will only remove the state if state contains the same state instance as that passed to install_state.

Parameters

state
The instance of the state passed to install_state.

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : name is NULL.
  • mi::nservices::NRS_ERROR_NOT_FOUND : a state processor with this name is not registered.
  • mi::nservices::NRS_ERROR_FAILED : general failure.

virtual Sint32 mi::​rswservices::​IExtension_context::remove_user_type( nservices::IUser_type_definition* definition) [pure virtual]

Removes a user-type from RealityServer Web Services. This method will only remove the user type if definition contains the same user type definition instance as that passed to install_user_type.

Parameters

definition
The instance of the definition that was passed to install_user_type.

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : name is NULL.
  • mi::nservices::NRS_ERROR_NOT_FOUND : a user type with this name is not registered.
  • mi::nservices::NRS_ERROR_NEURAY : unable to remove the user type from the neuray library.
  • mi::nservices::NRS_ERROR_FAILED : general failure.

virtual Sint32 mi::​rswservices::​IExtension_context::remove_websocket_handler( IWebsocket_handler* websocket_handler) [pure virtual]

Removes a websocket handler from RealityServer Web Services. This method will only remove the websocket handler if websocket_handler contains the same websocket handler instance as that passed to install_websocket_handler.

Parameters

websocket_handler
The instance of the websocket handler passed to install_render_handler.

Returns

  • mi::nservices::NRS_ERROR_NONE : success.
  • mi::nservices::NRS_ERROR_MEMORY : out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS : name is NULL.
  • mi::nservices::NRS_ERROR_NOT_FOUND : a websocket handler with this name is not registered.
  • mi::nservices::NRS_ERROR_FAILED : general failure.