Send and receive messages with a peer.
More...
|
enum | LWMsgAssocState {
LWMSG_ASSOC_STATE_NONE,
LWMSG_ASSOC_STATE_NOT_ESTABLISHED,
LWMSG_ASSOC_STATE_IDLE,
LWMSG_ASSOC_STATE_BLOCKED_SEND,
LWMSG_ASSOC_STATE_BLOCKED_RECV,
LWMSG_ASSOC_STATE_BLOCKED_SEND_RECV,
LWMSG_ASSOC_STATE_CLOSED,
LWMSG_ASSOC_STATE_BUSY,
LWMSG_ASSOC_STATE_ERROR
} |
| Association state. More...
|
|
enum | LWMsgTimeout {
LWMSG_TIMEOUT_MESSAGE,
LWMSG_TIMEOUT_ESTABLISH,
LWMSG_TIMEOUT_IDLE
} |
| Timeout classification. More...
|
|
|
void | lwmsg_assoc_delete (LWMsgAssoc *assoc) |
| Delete an association. More...
|
|
LWMsgProtocol * | lwmsg_assoc_get_protocol (LWMsgAssoc *assoc) |
| Get association protocol. More...
|
|
LWMsgStatus | lwmsg_assoc_send_message (LWMsgAssoc *assoc, LWMsgMessage *message) |
| Send a message. More...
|
|
LWMsgStatus | lwmsg_assoc_recv_message (LWMsgAssoc *assoc, LWMsgMessage *message) |
| Receive a message. More...
|
|
LWMsgStatus | lwmsg_assoc_send_message_transact (LWMsgAssoc *assoc, LWMsgMessage *send_message, LWMsgMessage *recv_message) |
| Send a message and receive a reply [deprecated]. More...
|
|
LWMsgStatus | lwmsg_assoc_close (LWMsgAssoc *assoc) |
| Close an association. More...
|
|
LWMsgStatus | lwmsg_assoc_reset (LWMsgAssoc *assoc) |
| Reset an association. More...
|
|
LWMsgStatus | lwmsg_assoc_destroy_message (LWMsgAssoc *assoc, LWMsgMessage *message) |
| Destroy a message. More...
|
|
LWMsgStatus | lwmsg_assoc_free_graph (LWMsgAssoc *assoc, LWMsgTag tag, void *root) |
| Free a message (simple) [DEPRECATED] More...
|
|
LWMsgStatus | lwmsg_assoc_get_session (LWMsgAssoc *assoc, LWMsgSession **session) |
| Get current session. More...
|
|
LWMsgAssocState | lwmsg_assoc_get_state (LWMsgAssoc *assoc) |
| Get association state. More...
|
|
LWMsgStatus | lwmsg_assoc_set_timeout (LWMsgAssoc *assoc, LWMsgTimeout type, LWMsgTime *value) |
| Set timeout. More...
|
|
LWMsgStatus | lwmsg_assoc_connect (LWMsgAssoc *assoc, LWMsgSession *session) |
| Connect association to peer. More...
|
|
LWMsgStatus | lwmsg_assoc_accept (LWMsgAssoc *assoc, LWMsgSession *session) |
| Accept connection from peer on assocation. More...
|
|
LWMsgStatus | lwmsg_assoc_print_message_alloc (LWMsgAssoc *assoc, LWMsgMessage *message, char **result) |
| Print message in human-readable form. More...
|
|
LWMsgStatus | lwmsg_assoc_acquire_call (LWMsgAssoc *assoc, LWMsgCall **call) |
| Acquire call handle [DEPRECATED]. More...
|
|
Associations are a message-oriented abstraction which provide a more convenient mechanism for communication than raw access to the marshalling facility:
-
Straightforward message sending and receiving
-
Stateful communication using handles
-
Access to metadata such as peer credentials
Messages consist of a message type and a payload which is marshalled and unmarshalled automatically. The marshaller type of the associated payload and the set of available messages are defined by a protocol.
Associations are an abstract data type. For a concrete implementation useful in interprocess or network communication, see Connections.
An opaque, abstract structure for message-oriented communication. Associations are not inherently thread-safe and must not be used concurrently from multiple threads.
Represents the current state of an association as returned by lwmsg_assoc_get_state().
Enumerator |
---|
LWMSG_ASSOC_STATE_NONE |
Unspecified state.
|
LWMSG_ASSOC_STATE_NOT_ESTABLISHED |
Association is not established.
|
LWMSG_ASSOC_STATE_IDLE |
Association is idle.
|
LWMSG_ASSOC_STATE_BLOCKED_SEND |
Association is blocked waiting to send.
|
LWMSG_ASSOC_STATE_BLOCKED_RECV |
Association is blocked waiting to receive.
|
LWMSG_ASSOC_STATE_BLOCKED_SEND_RECV |
Association is blocked waiting to send and/or receive.
|
LWMSG_ASSOC_STATE_CLOSED |
Association is closed.
|
LWMSG_ASSOC_STATE_BUSY |
Association is busy.
|
LWMSG_ASSOC_STATE_ERROR |
Association experienced an error.
|
Represents a class of timeout which may be set on an association with lwmsg_assoc_set_timeout()
Enumerator |
---|
LWMSG_TIMEOUT_MESSAGE |
Timeout for a message send or receive.
|
LWMSG_TIMEOUT_ESTABLISH |
Timeout for session establishment.
|
LWMSG_TIMEOUT_IDLE |
Idle timeout.
|
Deletes an association, releasing all allocated resources
- Parameters
-
[in] | assoc | the association to delete |
Returns the protocol used by the association.
- Parameters
-
- Returns
- the protocol specified when the association was created
Sends a message on the specified association. This function uses the full LWMsgMessage data structure to specify the message
- Parameters
-
[in] | assoc | the association |
[in] | message | the message to send |
- Return values
-
Receives a message on the specified association. This function uses the full LWMsgMessage data structure to return the received message.
- Parameters
-
[in] | assoc | the association |
[out] | message | the received message |
- Return values
-
This function sends a message and receives a reply in a single operation.
- Parameters
-
[in] | assoc | the association |
[in] | send_message | the message to send (request) |
[out] | recv_message | the received message (reply) |
- Return values
-
- Deprecated:
- use lwmsg_assoc_send_message followed by lwmsg_assoc_recv_message, or the call interface
Closes the specified assocation, which may include notifying the peer and shutting down the underlying communication channel. Unlike lwmsg_assoc_delete(), which aggressively closes the association and releases all resources in constant time, this function may block indefinitely, time out, or fail, but allows for a controlled, orderly shutdown. After an association is closed, the result of performing further sends or receives is unspecified.
- Parameters
-
- Return values
-
Resets an association to its baseline state, which is similar in immediate effect to closing it (e.g. shutting down the underlying communication channel). However, while closing an association with lwmsg_assoc_close() generally represents an intent to cease further communication, a reset implies that communication may resume once the problem that necessitated the reset has been remedied. For example, a server which times out an idle client connection will typically reset it rather than close it, indicating to the client that it should reset the association locally and resume communication if it is still alive.
The difference between close and reset is not purely symbolic. The association implementation may release additional resources and state it considers obsolete when closed but keep such state intact when it is reset.
A reset, like a close, removes an association from its session. If this was the last association in that session, the session and all its handles are no longer valid.
- Parameters
-
- Return values
-
Destroys a message structure, freeing any data payload it may contain.
- Parameters
-
[in] | assoc | the assocation |
[in] | message | the message to destroy |
- Return values
-
Frees the object graph of a message using the memory manager and protocol of the specified association. This function does not require a complete LWMsgMessage structure.
- Parameters
-
[in] | assoc | the assocation |
[in] | tag | the tag of the message to free |
[in] | root | the root of the object graph |
- Return values
-
- Deprecated:
- Use lwmsg_assoc_destroy_message()
Gets the current session for the specified association. The session can be used for handle management and authentication of the peer. A session will only be available after calling lwmsg_assoc_connect() or lwmsg_assoc_accept() and before calling lwmsg_assoc_close(). Some types of associations may not support sessions, in which case this function will return LWMSG_STATUS_SUCCESS and set session to NULL.
- Parameters
-
[in] | assoc | the association |
[out] | session | the session |
- Return values
-
Gets the current state of the specified association. This may reveal details such as:
- Whether the association has been closed
- Whether the association is part of an established session
- If the association is ready to send a message or receive a message
- Parameters
-
- Returns
- the current state of the association
Sets a timeout that should be used for subsequent operations.
- Parameters
-
[in] | assoc | the association |
[in] | type | the type of timeout |
[in] | value | the value of the timeout, or NULL for no timeout |
- Return values
-
Connects an association to a peer. The peer should call lwmsg_assoc_accept() to accept the connection. An existing session can be passed in the session
parameter – otherwise, a new session will be created automatically and can be accessed later with lwmsg_assoc_get_session().
- Parameters
-
[in,out] | assoc | the association |
[in,out] | session | an optional existing session to use for the association |
- Return values
-
Accepts a connection from a peer on the given association. The peer should call lwmsg_assoc_connect() to initiate the connection. An existing session can be passed as the session
parameter. Otherwise, the association will create one automatically.
- Parameters
-
[in,out] | assoc | the association |
[in,out] | session | (optional) an existing session to use |
- Return values
-
Prints a message in a human-readable using the protocol information for the given association. The result is allocated using the same memory manager as the association.
- Parameters
-
[in] | assoc | the association |
[in] | message | the message to print |
[out] | result | the printed form of the message |
- Return values
-