Session abstraction.
More...
|
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...
|
|
LWMsgSecurityToken * | lwmsg_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...
|
|
A session is an abstract connection with a peer that allows calls to be made and state to be shared.
An opaque session structure
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] | handle | the handle to clean up |
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] | token | a security token representing the identity of the peer |
[in] | data | a user data pointer |
[out] | session_data | a session data pointer which contains custom per-session information |
- Return values
-
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] | token | a security token representing the identity of the peer |
[in,out] | session_data | the custom session data created by the constructor |
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
|
Registers a local handle so that it may be passed to the peer in subsequent calls.
- Parameters
-
[in,out] | session | the session |
[in] | typename | a 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] | data | the local data to associate with the handle |
[in] | cleanup | a cleanup function which should be invoked when the handle is no longer referenced |
[out] | handle | set to the created handle |
- Return values
-
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] | session | the session |
[in,out] | handle | the 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] | session | the session |
[in,out] | handle | the 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] | session | the session |
[in] | handle | the handle |
- Return values
-
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] | session | the session |
[in] | handle | the handle |
[out] | data | set to the data associated with the handle |
- Return values
-
LWMSG_STATUS_SUCCESS | success |
LWMSG_STATUS_INVALID_HANDLE | the handle is invalid or has been invalidated |
Queries the type of a given handle: local or remote.
- Parameters
-
[in] | session | the session |
[in] | handle | the handle |
[out] | location | the location of the handle |
- Return values
-
Retrieves the custom session data pointer created by the session's construtor function.
- Parameters
-
- Returns
- the session data pointer
Retrives the security token for the remote peer. The token remains valid for the duration of the session.
- Parameters
-
- Returns
- the security token, or NULL if the session is unauthenticated
Acquires a handle suitable for making a call to the session peer.
- Parameters
-
[in] | session | the session |
[out] | call | set to the acquired call handle |
- Return values
-