Protocols

Describe messages and message contents. More...

Macros

#define LWMSG_MESSAGE(tag, spec)
 Specify a message tag and type. More...
 
#define LWMSG_PROTOCOL_END
 Mark end of protocol specification. More...
 

Typedefs

typedef struct LWMsgProtocol LWMsgProtocol
 A protocol object. More...
 
typedef struct
LWMsgProtocolSpec const 
LWMsgProtocolSpec
 Protocol specification structure. More...
 

Functions

LWMsgStatus lwmsg_protocol_get_message_type (LWMsgProtocol *prot, LWMsgTag tag, LWMsgTypeSpec **out_type)
 Get marshaller type by message tag. More...
 
LWMsgStatus lwmsg_protocol_get_message_name (LWMsgProtocol *prot, LWMsgTag tag, const char **name)
 Get name of message tag. More...
 
LWMsgStatus lwmsg_protocol_new (LWMsgContext *context, LWMsgProtocol **prot)
 Create a new protocol object. More...
 
LWMsgStatus lwmsg_protocol_add_protocol_spec (LWMsgProtocol *prot, LWMsgProtocolSpec *spec)
 Add messages from a protocol specification. More...
 
void lwmsg_protocol_delete (LWMsgProtocol *prot)
 Delete a protocol object. More...
 

Detailed Description

Protocols consist of an enumerated set of message tags. Each message tag has an associated marshaller type which describes the layout of the payload for that message. Protocols fully specify the messages available to peers communicating through an association.

A protocol object includes one or more protocol specifications, which are simple statically-initialized C arrays.

Macro Definition Documentation

#define LWMSG_MESSAGE (   tag,
  spec 
)

This macro is used in the construction of protocol specifications. It declares a message by its integer tag and associated marshaller type specification.

Parameters
tagthe integer identifier for the message
specthe marshaller type specifier that describes the message payload
#define LWMSG_PROTOCOL_END

This macro marks the end of a protocol specification. All protocol specifications must end with this macro.

Typedef Documentation

typedef struct LWMsgProtocol LWMsgProtocol

An opaque protocol object suitable for creating associations

typedef struct LWMsgProtocolSpec const LWMsgProtocolSpec

Defines the messages and payload types available to a protocol. You should initialize a static array of this structure in your source code using LWMSG_MESSAGE() and LWMSG_PROTOCOL_END. The result will be suitable to pass to lwmsg_protocol_add_protocol_spec(). Consider the following example:

* enum FooMessageType
* {
* FOO_REQUEST_BAR = 1,
* FOO_REPLY_BAR = 2,
* FOO_REQUEST_BAZ = 3,
* FOO_REPLY_BAZ = 4
* };
*
* static LWMsgProtocolSpec foo_spec[] =
* {
* LWMSG_MESSAGE(FOO_REQUEST_BAR, foo_request_bar_spec),
* LWMSG_MESSAGE(FOO_REPLY_BAR, foo_reply_bar_spec),
* LWMSG_MESSAGE(FOO_REQUEST_BAZ, foo_request_baz_spec),
* LWMSG_MESSAGE(FOO_REPLY_BAZ, foo_reply_baz_spec),
* };
*

This example assumes the existence of the marshaller type specifications foo_request_bar_spec, foo_request_baz_spec, foo_reply_bar_spec, and foo_reply_baz_spec. See Types for more information on specifying marshaller types.

Function Documentation

LWMsgStatus lwmsg_protocol_get_message_type ( LWMsgProtocol prot,
LWMsgTag  tag,
LWMsgTypeSpec **  out_type 
)

Gets the marshaller type associated with a given message tag. The retrieved type may be passed directly to the marshaller to marshal or unmarshal message payloads of the given type.

Parameters
[in]protthe protocol
[in]tagthe message tag
[out]out_typethe marshaller type
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_NOT_FOUNDno such message tag exists in the specified protocol
LWMsgStatus lwmsg_protocol_get_message_name ( LWMsgProtocol prot,
LWMsgTag  tag,
const char **  name 
)

Gets the symbolic name of the given message tag.

Parameters
[in]protthe protocol
[in]tagthe message tag
[out]namethe symbolic name of the tag
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_NOT_FOUNDno such message tag exists in the specified protocol
LWMsgStatus lwmsg_protocol_new ( LWMsgContext context,
LWMsgProtocol **  prot 
)

Creates a new protocol object with no known messages. Messages must be added with lwmsg_protocol_add_protocol_spec().

Parameters
[in]contexta marshalling context, or NULL for default settings
[out]protthe created protocol
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMsgStatus lwmsg_protocol_add_protocol_spec ( LWMsgProtocol prot,
LWMsgProtocolSpec spec 
)

Adds all messages in the specified protocol specification to the specified protocol object. This may be performed multiple times to aggregate several protocol specifications.

Parameters
[in,out]protthe protocol object
[in]specthe protocol specification
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MALFORMEDan error was detected in the protocol specification or one of the type specifications
void lwmsg_protocol_delete ( LWMsgProtocol prot)

Deletes the specified protocol object. It is the caller's responsibility to ensure than no users of the object remain.

Parameters
[in,out]protthe protocol object to delete