MoleQueue  0.8.0
 All Classes Functions Variables Enumerations Enumerator Pages
Public Types | Public Member Functions | List of all members
Message Class Reference

#include <molequeue/servercore/message.h>

Public Types

enum  MessageType {
  Request = 0x1,
  Notification = 0x2,
  Response = 0x4,
  Error = 0x8,
  Raw = 0x10,
  Invalid = 0x20
}
 

Public Member Functions

 Message (Connection *conn=NULL, EndpointIdType endpoint_=EndpointIdType())
 
 Message (MessageType type_, Connection *conn=NULL, EndpointIdType endpoint_=EndpointIdType())
 
 Message (const QJsonObject &rawJson, Connection *conn=NULL, EndpointIdType endpoint_=EndpointIdType())
 
 Message (const Message &other)
 
Messageoperator= (const Message &other)
 
MessageType type () const
 
QJsonObject toJsonObject () const
 
PacketType toJson () const
 
bool send ()
 
Message generateResponse () const
 
Message generateErrorResponse () const
 
QString method () const
 
void setMethod (const QString &m)
 
QJsonValue params () const
 
QJsonValue & paramsRef ()
 
void setParams (const QJsonArray &p)
 
void setParams (const QJsonObject &p)
 
QJsonValue result () const
 
QJsonValue & resultRef ()
 
void setResult (const QJsonValue &r)
 
int errorCode () const
 
void setErrorCode (int e)
 
QString errorMessage () const
 
void setErrorMessage (const QString &e)
 
QJsonValue errorData () const
 
QJsonValue & errorDataRef ()
 
void setErrorData (const QJsonValue &e)
 
Connectionconnection () const
 
void setConnection (Connection *c)
 
EndpointIdType endpoint () const
 
void setEndpoint (const EndpointIdType &e)
 
bool parse ()
 
bool parse (Message &errorMessage_)
 
MessageIdType id () const
 
void setId (const MessageIdType &i)
 

Detailed Description

The Message class encaspulates a single JSON-RPC transmission.

Author
David C. Lonie

The Message class provides an interface to construct, interpret, and manipulate JSON-RPC messages.

There are four types of valid JSON-RPC messages: Requests, notifications, responses, and errors. The type() method can be used to determine a given Message's MessageType. A subset of the Message API is valid for each type; the allowed attributes are dependent on the message type:

Attempting to access an attribute that is invalid for the current type will cause a warning to be printed and a default-constructed value is returned.

A Message may be constructed from a QJsonObject by using the QJsonObject constructor and calling parse(). See the parse() documentation for more details.

When handling a Request Message, the generateResponse() and generateErrorResponse() methods may be used to easily construct an empty reply with the method, id, connection, and endpoint of the request.

Once a message is ready to send, call the send() method. This will assign and set a unique id to outgoing requests and call Connection::send() with a JSON representation of the Message. If the application needs to track the id of a request in order to identify the reply, record the id after calling send().

The Request ids and methods are stored in an internal lookup table upon sending. This is used to set the method of the incoming reply. If the lookup fails, the message will be parsed properly, but the method attribute will not be set.

The JSON representation can be generated and obtained by calling toJson(), and a QJsonObject representation is available from the toJsonObject() method.

Member Enumeration Documentation

Flags representing different types of JSON-RPC messages.

Enumerator
Request 

A JSON-RPC request, with id, method, and params attributes.

Notification 

A JSON-RPC notification, with method and params attributes.

Response 

A JSON-RPC response, with id, method, and result attributes.

Error 

A JSON-RPC error, with id, method, and errorCode, errorMessage, and errorData attributes.

Raw 

This MessageType indicates that this Message holds a raw QJsonObject that has not been interpreted. Call parse() to convert this Message into an appropriate type.

Invalid 

This Message is invalid.

Constructor & Destructor Documentation

Message ( Connection conn = NULL,
EndpointIdType  endpoint_ = EndpointIdType() 
)

Construct an Invalid Message using the conn and endpoint_.

Message ( MessageType  type_,
Connection conn = NULL,
EndpointIdType  endpoint_ = EndpointIdType() 
)

Construct an empty Message with the specified type that uses the conn and endpoint_.

Message ( const QJsonObject &  rawJson,
Connection conn = NULL,
EndpointIdType  endpoint_ = EndpointIdType() 
)

Construct a Raw Message with the specified type that uses the conn and endpoint_. The rawJson QJsonObject will be cached to be parsed by parse() later.

Message ( const Message other)

Copy constructor.

Member Function Documentation

Message& operator= ( const Message other)

Assignment operator.

MessageType type ( ) const
Returns
The MessageType of this Message.
QString method ( ) const

The name of the method used in the remote procedure call.

Note
This function is only valid for Request, Notification, Response, and Error messages.
void setMethod ( const QString &  m)

The name of the method used in the remote procedure call.

Note
This function is only valid for Request, Notification, Response, and Error messages.
QJsonValue params ( ) const

The parameters used in the remote procedure call.

Note
This function is only valid for Request and Notification messages.
QJsonValue& paramsRef ( )

The parameters used in the remote procedure call.

Note
This function is only valid for Request and Notification messages.
void setParams ( const QJsonArray &  p)

The parameters used in the remote procedure call.

Note
This function is only valid for Request and Notification messages.
void setParams ( const QJsonObject &  p)

The parameters used in the remote procedure call.

Note
This function is only valid for Request and Notification messages.
QJsonValue result ( ) const

The result object used in a remote procedure call response.

Note
This function is only valid for Response messages.
QJsonValue& resultRef ( )

The result object used in a remote procedure call response.

Note
This function is only valid for Response messages.
void setResult ( const QJsonValue &  r)

The result object used in a remote procedure call response.

Note
This function is only valid for Response messages.
int errorCode ( ) const

The integral error code used in a remote procedure call error response.

Note
This function is only valid for Error messages.
void setErrorCode ( int  e)

The integral error code used in a remote procedure call error response.

Note
This function is only valid for Error messages.
QString errorMessage ( ) const

The error message string used in a remote procedure call error response.

Note
This function is only valid for Error messages.
void setErrorMessage ( const QString &  e)

The error message string used in a remote procedure call error response.

Note
This function is only valid for Error messages.
QJsonValue errorData ( ) const

The data object used in a remote procedure call error response.

Note
This function is only valid for Error messages.
QJsonValue& errorDataRef ( )

The data object used in a remote procedure call error response.

Note
This function is only valid for Error messages.
void setErrorData ( const QJsonValue &  e)

The data object used in a remote procedure call error response.

Note
This function is only valid for Error messages.
MessageIdType id ( ) const

The message id used in a remote procedure call.

Note
This function is only valid for Request, Response, and Error messages.
void setId ( const MessageIdType &  i)
protected

The message id used in a remote procedure call.

Note
This function is only valid for Request, Response, and Error messages.
Connection* connection ( ) const

The connection associated with the remote procedure call.

void setConnection ( Connection c)

The connection associated with the remote procedure call.

EndpointIdType endpoint ( ) const

The connection endpoint associated with the remote procedure call.

void setEndpoint ( const EndpointIdType &  e)

The connection endpoint associated with the remote procedure call.

QJsonObject toJsonObject ( ) const
Returns
A QJsonObject representation of the remote procedure call.
PacketType toJson ( ) const
Returns
A string representation of the remote procedure call.
bool send ( )

Send the message to the associated connection and endpoint.

Returns
True on success, false on failure.
Note
If this message is a Request, a unique id will be assigned prior to sending. Use the id() method to retrieve the assigned id. The id is registered internally to properly identify the peer's Response or Error message.
Message generateResponse ( ) const

Create a new Response message in reply to a Request. The connection, endpoint, id, and method will be copied from this Message.

Note
This function is only valid for Request messages.
Message generateErrorResponse ( ) const

Create a new Error message in reply to a Request. The connection, endpoint, id, and method will be copied from this Message.

Note
This function is only valid for Request, Raw, and Invalid messages.
bool parse ( )

Interpret the raw QJsonObject passed to the constructor that takes a QJsonObject argument.

Returns
True on success, false on failure.
Note
This function is only valid for Raw messages.

This function will intepret the string as JSON, detect the type of message, and update this message's type, and populate the internal data structures.

The function returns true if the message was successfully interpreted, and false if any error occured during parsing/interpretation. If any errors occurred, the optional Message reference argument will be overwritten with an appropriate error response. The following JSON-RPC 2.0 standard errors are detected:

  • -32600 Invalid request
    • The message type could not be determined.

The JsonRpc class will handle the following errors as message are received:

  • -32700 Parse error
    • Invalid JSON received, an error occurred during parsing.
  • -32603 Internal error
    • Internal JSON-RPC error

The remaining standard JSON-RPC error codes should be handled by the application developer:

  • -32601 Method not found
    • Method not supported by application
  • -32602 Invalid params
    • Inappropriate parameters supplied for requested method.

This method is intended to be used as follows:

QJsonObject jsonObject = ...;
Message message(jsonObject, connection, endpoint);
if (!message.parse(errorMessage))
errorMessage.send();
else
handleValidMessage(message);

The Request ids and methods are stored in an internal lookup table upon sending. This is used to set the method of the incoming reply. If the lookup fails, the message will be parsed properly, but the method attribute will not be set.

bool parse ( Message errorMessage_)

Interpret the raw QJsonObject passed to the constructor that takes a QJsonObject argument.

Returns
True on success, false on failure.
Note
This function is only valid for Raw messages.

This function will intepret the string as JSON, detect the type of message, and update this message's type, and populate the internal data structures.

The function returns true if the message was successfully interpreted, and false if any error occured during parsing/interpretation. If any errors occurred, the optional Message reference argument will be overwritten with an appropriate error response. The following JSON-RPC 2.0 standard errors are detected:

  • -32600 Invalid request
    • The message type could not be determined.

The JsonRpc class will handle the following errors as message are received:

  • -32700 Parse error
    • Invalid JSON received, an error occurred during parsing.
  • -32603 Internal error
    • Internal JSON-RPC error

The remaining standard JSON-RPC error codes should be handled by the application developer:

  • -32601 Method not found
    • Method not supported by application
  • -32602 Invalid params
    • Inappropriate parameters supplied for requested method.

This method is intended to be used as follows:

QJsonObject jsonObject = ...;
Message message(jsonObject, connection, endpoint);
if (!message.parse(errorMessage))
errorMessage.send();
else
handleValidMessage(message);

The Request ids and methods are stored in an internal lookup table upon sending. This is used to set the method of the incoming reply. If the lookup fails, the message will be parsed properly, but the method attribute will not be set.


The documentation for this class was generated from the following file: