RealityServer Web Services API Programmer's Manual

mi::rswservices::IProtocol Class Reference

[Protocol Processing]

Description

Implements a protocol. Protocols take an http request and extract the service commands from it. They are also responsible for converting command responses back to response bodies.

Public Enumerations

enum Protocol_confidence{ PROTOCOL_CONFIDENCE_OVERRIDE = 4, PROTOCOL_CONFIDENCE_HIGH = 3, PROTOCOL_CONFIDENCE_MEDIUM = 2, PROTOCOL_CONFIDENCE_LOW = 1, PROTOCOL_CONFIDENCE_NONE = 0, PROTOCOL_CONFIDENCE_FORCE_32_BIT = 0xffffffffU}
Protocol confidence enumerator. More...

Public Member Functions

virtual Sint32 deserialize( IProtocol_context* context, http::IRequest* request) =0
Analyzes the HTTP request and, if the request is using this protocol, extracts the commands to execute and returns true. More...
virtual const char* get_name() const =0
The name of the protocol. More...
virtual Sint32 serialize( IProtocol_context* context, http::IConnection* connection, const IDynamic_array* command_responses) =0
Serializes the service response back to the connection. More...
virtual Protocol_confidence test_request( const http::IRequest* request) const =0
Indicated whether the protocol can handle the request. More...

Enums

enum mi::​rswservices::​IProtocol::Protocol_confidence

Protocol confidence enumerator. Returned by protocol modules so the core can decide which protocol to attempt decoding with

Enumerator:

PROTOCOL_CONFIDENCE_OVERRIDE = 4
PROTOCOL_CONFIDENCE_HIGH = 3
PROTOCOL_CONFIDENCE_MEDIUM = 2
PROTOCOL_CONFIDENCE_LOW = 1
PROTOCOL_CONFIDENCE_NONE = 0
PROTOCOL_CONFIDENCE_FORCE_32_BIT = 0xffffffffU

Member Functions

virtual Sint32 mi::​rswservices::​IProtocol::deserialize( IProtocol_context* context, http::IRequest* request) [pure virtual]

Analyzes the HTTP request and, if the request is using this protocol, extracts the commands to execute and returns true. If the protocol does not support the request it returns false.

Parameters

context
the protocol context
request
the http request

Returns

  • mi::nservices::NRS_ERROR_NONE success, commands have been added context.
  • mi::nservices::NRS_ERROR_MEMORY out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS request is NULL or has no body
  • mi::nservices::NRS_ERROR_INVALID_OPERATION this request cannot be decoded by this protocol.
  • mi::nservices::NRS_ERROR_FAILED general failure.
virtual const char* mi::​rswservices::​IProtocol::get_name() const [pure virtual]

The name of the protocol.

Returns

name

virtual Sint32 mi::​rswservices::​IProtocol::serialize( IProtocol_context* context, http::IConnection* connection, const IDynamic_array* command_responses) [pure virtual]

Serializes the service response back to the connection. command_responses contains one reponse for every command in context::get_command_array().

The elements of command_responses array are either const mi::nservices::ICommand_response or mi::neuraylib::IConst_pointer pointing to an mi::nservices::ICommand_response. The user should use mi::nservices::IFactory::unwrap() to extract the individual response elements.

Parameters

context
the protocol context
connection
the connection to serialize to
command_responses
an array of ICommand_response objects to return.

Returns

  • mi::nservices::NRS_ERROR_NONE success, commands have been returned.
  • mi::nservices::NRS_ERROR_MEMORY out of memory.
  • mi::nservices::NRS_ERROR_INVALID_PARAMETERS a parameter is NULL
  • mi::nservices::NRS_ERROR_FAILED general failure.
virtual Protocol_confidence mi::​rswservices::​IProtocol::test_request( const http::IRequest* request) const [pure virtual]

Indicated whether the protocol can handle the request. For each HTTP request test_request is called for all protocols, protocols that return PROTOCOL_CONFIDENCE_NONE are discarded. All others are called in descending confidence order until a protocol module processes the request. test_request should make it's decision by decoding as little of the request as possible.

Parameters

request
the http request

Returns

the confidence level that the protocol supports this request