Associations

Send and receive messages with a peer. More...

Typedefs

typedef struct LWMsgAssoc LWMsgAssoc
 An association. More...
 

Enumerations

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...
 

Functions

void lwmsg_assoc_delete (LWMsgAssoc *assoc)
 Delete an association. More...
 
LWMsgProtocollwmsg_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...
 

Detailed Description

Associations are a message-oriented abstraction which provide a more convenient mechanism for communication than raw access to the marshalling facility:

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.

Typedef Documentation

typedef struct LWMsgAssoc LWMsgAssoc

An opaque, abstract structure for message-oriented communication. Associations are not inherently thread-safe and must not be used concurrently from multiple threads.

Enumeration Type Documentation

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.

Function Documentation

void lwmsg_assoc_delete ( LWMsgAssoc assoc)

Deletes an association, releasing all allocated resources

Parameters
[in]assocthe association to delete
LWMsgProtocol* lwmsg_assoc_get_protocol ( LWMsgAssoc assoc)

Returns the protocol used by the association.

Parameters
[in]assocthe association
Returns
the protocol specified when the association was created
LWMsgStatus lwmsg_assoc_send_message ( LWMsgAssoc assoc,
LWMsgMessage message 
)

Sends a message on the specified association. This function uses the full LWMsgMessage data structure to specify the message

Parameters
[in]assocthe association
[in]messagethe message to send
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_TIMEOUToperation timed out
...implementation-specific failure
LWMsgStatus lwmsg_assoc_recv_message ( LWMsgAssoc assoc,
LWMsgMessage message 
)

Receives a message on the specified association. This function uses the full LWMsgMessage data structure to return the received message.

Parameters
[in]assocthe association
[out]messagethe received message
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_TIMEOUToperation timed out
...implementation-specific failure
LWMsgStatus lwmsg_assoc_send_message_transact ( LWMsgAssoc assoc,
LWMsgMessage send_message,
LWMsgMessage recv_message 
)

This function sends a message and receives a reply in a single operation.

Parameters
[in]assocthe association
[in]send_messagethe message to send (request)
[out]recv_messagethe received message (reply)
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_TIMEOUToperation timed out
...implementation-specific failure
Deprecated:
use lwmsg_assoc_send_message followed by lwmsg_assoc_recv_message, or the call interface
LWMsgStatus lwmsg_assoc_close ( LWMsgAssoc assoc)

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
[in]assocthe association
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_TIMEOUToperation timed out
...implementation-specific failure
LWMsgStatus lwmsg_assoc_reset ( LWMsgAssoc assoc)

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
[in]assocthe association
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_TIMEOUToperation timed out
...implementation-specific failure
LWMsgStatus lwmsg_assoc_destroy_message ( LWMsgAssoc assoc,
LWMsgMessage message 
)

Destroys a message structure, freeing any data payload it may contain.

Parameters
[in]assocthe assocation
[in]messagethe message to destroy
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_NOT_FOUNDthe message tag is not known by the association's protocol
...an error returned by the memory manager
LWMsgStatus lwmsg_assoc_free_graph ( LWMsgAssoc assoc,
LWMsgTag  tag,
void *  root 
)

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]assocthe assocation
[in]tagthe tag of the message to free
[in]rootthe root of the object graph
Return values
LWMSG_STATUS_SUCCESSsuccess
Deprecated:
Use lwmsg_assoc_destroy_message()
LWMsgStatus lwmsg_assoc_get_session ( LWMsgAssoc assoc,
LWMsgSession **  session 
)

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]assocthe association
[out]sessionthe session
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_STATEthe association is closed or not yet established
LWMsgAssocState lwmsg_assoc_get_state ( LWMsgAssoc assoc)

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
[in]assocthe association
Returns
the current state of the association
LWMsgStatus lwmsg_assoc_set_timeout ( LWMsgAssoc assoc,
LWMsgTimeout  type,
LWMsgTime *  value 
)

Sets a timeout that should be used for subsequent operations.

Parameters
[in]assocthe association
[in]typethe type of timeout
[in]valuethe value of the timeout, or NULL for no timeout
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_UNSUPPORTEDthe association does not support the specified timeout type
...implementation-specific error
LWMsgStatus lwmsg_assoc_connect ( LWMsgAssoc assoc,
LWMsgSession session 
)

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]assocthe association
[in,out]sessionan optional existing session to use for the association
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMSG_STATUS_CONNECTION_REFUSEDconnection refused
LWMsgStatus lwmsg_assoc_accept ( LWMsgAssoc assoc,
LWMsgSession session 
)

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]assocthe association
[in,out]session(optional) an existing session to use
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMSG_STATUS_CONNECTION_REFUSEDconnection refused
LWMsgStatus lwmsg_assoc_print_message_alloc ( LWMsgAssoc assoc,
LWMsgMessage message,
char **  result 
)

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]assocthe association
[in]messagethe message to print
[out]resultthe printed form of the message
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMsgStatus lwmsg_assoc_acquire_call ( LWMsgAssoc assoc,
LWMsgCall **  call 
)

Acquires a call handle that can be used to make a call across an association as a send followed by a receive. Only one such call handle may be acquired until it is released with lwmsg_call_release().

Parameters
[in,out]assocthe association
[out]callthe call handle
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_BUSYa call handle has already been acquired
LWMSG_STATUS_UNSUPPORTEDthe association does not support calls
Deprecated:
Use lwmsg_session_acquire_call() with the session passed to lwmsg_assoc_connect() or lwmsg_assoc_accept(). If you did not pass a session yourself, you can use lwmsg_assoc_get_session() to get the active session.