Sessions

Session abstraction. More...

Typedefs

typedef struct LWMsgSession LWMsgSession
 A session. More...
 
typedef struct LWMsgHandle LWMsgHandle
 A handle. More...
 
typedef void(* LWMsgHandleCleanupFunction )(void *handle)
 Handle cleanup callback. More...
 
typedef LWMsgStatus(* LWMsgSessionConstructFunction )(LWMsgSecurityToken *token, void *data, void **session_data)
 Session constructor callback. More...
 
typedef void(* LWMsgSessionDestructFunction )(LWMsgSecurityToken *token, void *session_data)
 Session destructor callback. More...
 

Enumerations

enum  LWMsgHandleType {
  LWMSG_HANDLE_NULL,
  LWMSG_HANDLE_LOCAL,
  LWMSG_HANDLE_REMOTE
}
 Handle type. More...
 

Functions

LWMsgStatus lwmsg_session_register_handle (LWMsgSession *session, const char *typename, void *data, LWMsgHandleCleanupFunction cleanup, LWMsgHandle **handle)
 Register local handle. More...
 
void lwmsg_session_retain_handle (LWMsgSession *session, LWMsgHandle *handle)
 Increase handle reference count. More...
 
void lwmsg_session_release_handle (LWMsgSession *session, LWMsgHandle *handle)
 Decrease handle reference count. More...
 
LWMsgStatus lwmsg_session_unregister_handle (LWMsgSession *session, LWMsgHandle *handle)
 Unregister handle. More...
 
LWMsgStatus lwmsg_session_get_handle_data (LWMsgSession *session, LWMsgHandle *handle, void **data)
 Get handle data. More...
 
LWMsgStatus lwmsg_session_get_handle_location (LWMsgSession *session, LWMsgHandle *handle, LWMsgHandleType *location)
 Query handle type. More...
 
void * lwmsg_session_get_data (LWMsgSession *session)
 Get custom session data. More...
 
LWMsgSecurityTokenlwmsg_session_get_peer_security_token (LWMsgSession *session)
 Get peer security token. More...
 
LWMsgStatus lwmsg_session_acquire_call (LWMsgSession *session, struct LWMsgCall **call)
 Acquire a call handle. More...
 

Detailed Description

A session is an abstract connection with a peer that allows calls to be made and state to be shared.

Typedef Documentation

typedef struct LWMsgSession LWMsgSession

An opaque session structure

typedef struct LWMsgHandle LWMsgHandle

An opaque handle structure

typedef void(* LWMsgHandleCleanupFunction)(void *handle)

A callback used to clean up a handle after it is no longer in use. A cleanup callback can be registered as part of lwmsg_session_register_handle(). The cleanup callback will be invoked when the last reference to the handle is dropped, or when the session containing the handle is torn down.

Parameters
[in]handlethe handle to clean up
typedef LWMsgStatus(* LWMsgSessionConstructFunction)(LWMsgSecurityToken *token, void *data, void **session_data)

A callback function which is invoked when a session is first establish. It may set a session data pointer which will be attached to the session to track custom user information. It may inspect the provided security token and choose to reject the session entirely.

Parameters
[in]tokena security token representing the identity of the peer
[in]dataa user data pointer
[out]session_dataa session data pointer which contains custom per-session information
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_SECURITYthe peer is denied access
typedef void(* LWMsgSessionDestructFunction)(LWMsgSecurityToken *token, void *session_data)

A callback function which is invoked by the session manager when a session is no longer in use. It should clean up the session data created by the constructor function.

Parameters
[in]tokena security token representing the identity of the peer
[in,out]session_datathe custom session data created by the constructor

Enumeration Type Documentation

Specifies the type of an opaque handle within a session. Only handles which are local may be safely dereferenced. Handles marked as remote are proxies for objects created by the peer and have undefined contents.

Enumerator
LWMSG_HANDLE_NULL 

The handle is NULL

LWMSG_HANDLE_LOCAL 

The handle is local

LWMSG_HANDLE_REMOTE 

The handle is remote

Function Documentation

LWMsgStatus lwmsg_session_register_handle ( LWMsgSession session,
const char *  typename,
void *  data,
LWMsgHandleCleanupFunction  cleanup,
LWMsgHandle **  handle 
)

Registers a local handle so that it may be passed to the peer in subsequent calls.

Parameters
[in,out]sessionthe session
[in]typenamea string constant describing the type of the handle. This should be the same as the type name given to the LWMSG_HANDLE() or LWMSG_MEMBER_HANDLE() macro in the type specification.
[in]datathe local data to associate with the handle
[in]cleanupa cleanup function which should be invoked when the handle is no longer referenced
[out]handleset to the created handle
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
void lwmsg_session_retain_handle ( LWMsgSession session,
LWMsgHandle handle 
)

Takes an extra reference to the given handle. When the last reference to a handle is released, the handle will be cleaned up using the function passed to lwmsg_session_register_handle().

Parameters
[in,out]sessionthe session
[in,out]handlethe handle
void lwmsg_session_release_handle ( LWMsgSession session,
LWMsgHandle handle 
)

Releases a reference to the given handle. When the last reference to a handle is released, the handle will be cleaned up using the function passed to lwmsg_session_register_handle().

Parameters
[in,out]sessionthe session
[in,out]handlethe handle
LWMsgStatus lwmsg_session_unregister_handle ( LWMsgSession session,
LWMsgHandle handle 
)

Unregisters a handle. In addition to releasing a reference as by lwmsg_session_release_handle(), this also marks the handle as invalid and will not allow any further use of it in the session. After a handle is unregistered, it may only be retained or released – all other operations treat it as invalid.

A handle should only be unregistered by the creator that originally registered it. All other users of the handle should release their reference with lwmsg_session_release_handle().

Parameters
[in,out]sessionthe session
[in]handlethe handle
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_HANDLEthe handle was not previously registered with the session, or was already unregistered
LWMsgStatus lwmsg_session_get_handle_data ( LWMsgSession session,
LWMsgHandle handle,
void **  data 
)

Gets the data associated with a handle when it was originally registered.

This function may only safely be called by the creator of the handle that originally registered it. In particular, attempting to use this function on a remote handle has undefined behavior.

Parameters
[in]sessionthe session
[in]handlethe handle
[out]dataset to the data associated with the handle
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_HANDLEthe handle is invalid or has been invalidated
LWMsgStatus lwmsg_session_get_handle_location ( LWMsgSession session,
LWMsgHandle handle,
LWMsgHandleType location 
)

Queries the type of a given handle: local or remote.

Parameters
[in]sessionthe session
[in]handlethe handle
[out]locationthe location of the handle
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_HANDLEthe handle is not registered
void* lwmsg_session_get_data ( LWMsgSession session)

Retrieves the custom session data pointer created by the session's construtor function.

Parameters
[in]sessionthe session
Returns
the session data pointer
LWMsgSecurityToken* lwmsg_session_get_peer_security_token ( LWMsgSession session)

Retrives the security token for the remote peer. The token remains valid for the duration of the session.

Parameters
[in]sessionthe session
Returns
the security token, or NULL if the session is unauthenticated
LWMsgStatus lwmsg_session_acquire_call ( LWMsgSession session,
struct LWMsgCall **  call 
)

Acquires a handle suitable for making a call to the session peer.

Parameters
[in]sessionthe session
[out]callset to the acquired call handle
Return values
LWMSG_STATUS_SUCCESSsuccess