|
meanwhile 1.0.2
|
A client session with a Sametime server is encapsulated in the mwSession structure. More...
#include "mw_common.h"Go to the source code of this file.
Data Structures | |
| struct | mwSessionHandler |
| session handler. More... | |
Defines | |
| #define | MW_PROTOCOL_VERSION_MAJOR 0x001e |
| default protocol major version | |
| #define | MW_PROTOCOL_VERSION_MINOR 0x001d |
| default protocol minor version | |
| #define | mwSession_isStarted(s) (mwSession_isState((s), mwSession_STARTED)) |
| #define | mwSession_isStarting(s) |
| #define | mwSession_isState(session, state) (mwSession_getState((session)) == (state)) |
| #define | mwSession_isStopped(s) (mwSession_isState((s), mwSession_STOPPED)) |
| #define | mwSession_isStopping(s) (mwSession_isState((s), mwSession_STOPPING)) |
| #define | mwSession_AUTH_USER_ID "session.auth.user" |
| char *, session user ID | |
| #define | mwSession_AUTH_PASSWORD "session.auth.password" |
| char *, plaintext password | |
| #define | mwSession_AUTH_TOKEN "session.auth.token" |
| struct mwOpaque *, authentication token | |
| #define | mwSession_CLIENT_HOST "client.host" |
| char *, hostname of client | |
| #define | mwSession_CLIENT_IP "client.ip" |
| guint32, local IP of client | |
| #define | mwSession_CLIENT_VER_MAJOR "client.version.major" |
| guint16, major version of client protocol | |
| #define | mwSession_CLIENT_VER_MINOR "client.version.minor" |
| guint16, minor version of client protocol | |
| #define | mwSession_CLIENT_TYPE_ID "client.id" |
| guint16, client type identifier | |
| #define | mwSession_SERVER_VER_MAJOR "server.version.major" |
| guint16, major version of server protocol | |
| #define | mwSession_SERVER_VER_MINOR "server.version.minor" |
| guint16, minor version of server protocol | |
Enumerations | |
| enum | mwSessionState { mwSession_STARTING, mwSession_HANDSHAKE, mwSession_HANDSHAKE_ACK, mwSession_LOGIN, mwSession_LOGIN_REDIR, mwSession_LOGIN_ACK, mwSession_STARTED, mwSession_STOPPING, mwSession_STOPPED, mwSession_UNKNOWN, mwSession_LOGIN_CONT } |
Functions | |
| gboolean | mwSession_addCipher (struct mwSession *, struct mwCipher *) |
| adds a cipher to the session. | |
| gboolean | mwSession_addService (struct mwSession *, struct mwService *) |
| adds a service to the session. | |
| int | mwSession_forceLogin (struct mwSession *s) |
| respond to a login redirect message by forcing the login sequence to continue through the immediate server. | |
| void | mwSession_free (struct mwSession *) |
| stop, clear, free a session. | |
| struct mwChannelSet * | mwSession_getChannels (struct mwSession *) |
| struct mwCipher * | mwSession_getCipher (struct mwSession *, guint16 type) |
| find a cipher by its type identifier | |
| GList * | mwSession_getCiphers (struct mwSession *) |
| a GList of ciphers in this session. | |
| gpointer | mwSession_getClientData (struct mwSession *session) |
| struct mwSessionHandler * | mwSession_getHandler (struct mwSession *) |
| obtain a reference to the session's handler | |
| struct mwLoginInfo * | mwSession_getLoginInfo (struct mwSession *) |
| reference the login information for the session | |
| struct mwPrivacyInfo * | mwSession_getPrivacyInfo (struct mwSession *) |
| direct reference to the session's internal privacy structure | |
| gpointer | mwSession_getProperty (struct mwSession *, const char *key) |
| obtain the value of a previously set property, or NULL | |
| struct mwService * | mwSession_getService (struct mwSession *, guint32 type) |
| find a service by its type identifier | |
| GList * | mwSession_getServices (struct mwSession *) |
| a GList of services in this session. | |
| enum mwSessionState | mwSession_getState (struct mwSession *) |
| current status of the session | |
| gpointer | mwSession_getStateInfo (struct mwSession *) |
| additional status-specific information. | |
| struct mwUserStatus * | mwSession_getUserStatus (struct mwSession *) |
| struct mwSession * | mwSession_new (struct mwSessionHandler *) |
| allocate a new session | |
| void | mwSession_recv (struct mwSession *, const guchar *, gsize) |
| Data is buffered, unpacked, and parsed into a message, then processed accordingly. | |
| struct mwCipher * | mwSession_removeCipher (struct mwSession *, guint16 type) |
| remove a cipher from the session | |
| void | mwSession_removeClientData (struct mwSession *session) |
| remove client data, calling the optional GDestroyNotify function indicated in mwSession_setClientData if applicable | |
| void | mwSession_removeProperty (struct mwSession *, const char *key) |
| remove a property, calling the optional GDestroyNotify function indicated in mwSession_setProperty if applicable | |
| struct mwService * | mwSession_removeService (struct mwSession *, guint32 type) |
| removes a service from the session. | |
| int | mwSession_send (struct mwSession *s, struct mwMessage *msg) |
| primarily used by services to have messages serialized and sent | |
| int | mwSession_sendAnnounce (struct mwSession *s, gboolean may_reply, const char *text, const GList *recipients) |
| send an announcement to a list of users/groups. | |
| int | mwSession_sendKeepalive (struct mwSession *s) |
| sends the keepalive byte | |
| void | mwSession_senseService (struct mwSession *s, guint32 type) |
| instruct a STARTED session to check the server for the presense of a given service. | |
| void | mwSession_setClientData (struct mwSession *session, gpointer data, GDestroyNotify clear) |
| associate arbitrary data with the session for use by the client code. | |
| int | mwSession_setPrivacyInfo (struct mwSession *, struct mwPrivacyInfo *) |
| set the internal privacy information, and inform the server as necessary. | |
| void | mwSession_setProperty (struct mwSession *, const char *key, gpointer val, GDestroyNotify clear) |
| associate a key:value pair with the session. | |
| int | mwSession_setUserStatus (struct mwSession *, struct mwUserStatus *) |
| set the internal user status state, and inform the server as necessary. | |
| void | mwSession_start (struct mwSession *) |
| instruct the session to begin. | |
| void | mwSession_stop (struct mwSession *, guint32 reason) |
| instruct the session to shut down with the following reason code. | |
A client session with a Sametime server is encapsulated in the mwSession structure.
The session controls channels, provides encryption ciphers, and manages services using messages over the Master channel.
A session does not directly communicate with a socket or stream, instead the session is initialized from client code with an instance of a mwSessionHandler structure. This session handler provides functions as call-backs for common session events, and provides functions for writing-to and closing the connection to the server.
A session does not perform reads on a socket directly. Instead, it must be fed from an outside source via the mwSession_recv function. The session will buffer and merge data passed to this function to build complete protocol messages, and will act upon each complete message accordingly.
| #define MW_PROTOCOL_VERSION_MAJOR 0x001e |
default protocol major version
| #define MW_PROTOCOL_VERSION_MINOR 0x001d |
default protocol minor version
| #define mwSession_AUTH_PASSWORD "session.auth.password" |
char *, plaintext password
| #define mwSession_AUTH_TOKEN "session.auth.token" |
struct mwOpaque *, authentication token
| #define mwSession_AUTH_USER_ID "session.auth.user" |
| #define mwSession_CLIENT_HOST "client.host" |
char *, hostname of client
| #define mwSession_CLIENT_IP "client.ip" |
guint32, local IP of client
| #define mwSession_CLIENT_TYPE_ID "client.id" |
guint16, client type identifier
| #define mwSession_CLIENT_VER_MAJOR "client.version.major" |
guint16, major version of client protocol
| #define mwSession_CLIENT_VER_MINOR "client.version.minor" |
guint16, minor version of client protocol
| #define mwSession_isStarted | ( | s | ) | (mwSession_isState((s), mwSession_STARTED)) |
| #define mwSession_isStarting | ( | s | ) |
(mwSession_isState((s), mwSession_STARTING) || \ mwSession_isState((s), mwSession_HANDSHAKE) || \ mwSession_isState((s), mwSession_HANDSHAKE_ACK) || \ mwSession_isState((s), mwSession_LOGIN) || \ mwSession_isState((s), mwSession_LOGIN_ACK) || \ mwSession_isState((s), mwSession_LOGIN_REDIR) || \ mwSession_isState((s), mwSession_LOGIN_CONT))
| #define mwSession_isStopped | ( | s | ) | (mwSession_isState((s), mwSession_STOPPED)) |
| #define mwSession_isStopping | ( | s | ) | (mwSession_isState((s), mwSession_STOPPING)) |
| #define mwSession_SERVER_VER_MAJOR "server.version.major" |
guint16, major version of server protocol
| #define mwSession_SERVER_VER_MINOR "server.version.minor" |
guint16, minor version of server protocol
| enum mwSessionState |
adds a cipher to the session.
adds a service to the session.
If the session is started (or when the session is successfully started) and the service has a start function, the session will request service availability from the server. On receipt of the service availability notification, the session will call the service's start function.
| int mwSession_forceLogin | ( | struct mwSession * | s | ) |
respond to a login redirect message by forcing the login sequence to continue through the immediate server.
| void mwSession_free | ( | struct mwSession * | ) |
stop, clear, free a session.
Does not free contained ciphers or services, these must be taken care of explicitly.
| struct mwChannelSet* mwSession_getChannels | ( | struct mwSession * | ) | [read] |
find a cipher by its type identifier
| GList* mwSession_getCiphers | ( | struct mwSession * | ) |
a GList of ciphers in this session.
The GList needs to be freed after use
| gpointer mwSession_getClientData | ( | struct mwSession * | session | ) |
| struct mwSessionHandler* mwSession_getHandler | ( | struct mwSession * | ) | [read] |
obtain a reference to the session's handler
| struct mwLoginInfo* mwSession_getLoginInfo | ( | struct mwSession * | ) | [read] |
reference the login information for the session
| struct mwPrivacyInfo* mwSession_getPrivacyInfo | ( | struct mwSession * | ) | [read] |
direct reference to the session's internal privacy structure
| gpointer mwSession_getProperty | ( | struct mwSession * | , |
| const char * | key | ||
| ) |
obtain the value of a previously set property, or NULL
find a service by its type identifier
| GList* mwSession_getServices | ( | struct mwSession * | ) |
a GList of services in this session.
The GList needs to be freed after use
| enum mwSessionState mwSession_getState | ( | struct mwSession * | ) |
current status of the session
| gpointer mwSession_getStateInfo | ( | struct mwSession * | ) |
additional status-specific information.
Depending on the state of the session, this value has different meaning.
mwSession_STOPPING guint32 error code causing the session to shut downmwSession_STOPPED guint32 error code causing the session to shut downmwSession_LOGIN_REDIR (char *) host to redirect to | struct mwUserStatus* mwSession_getUserStatus | ( | struct mwSession * | ) | [read] |
| struct mwSession* mwSession_new | ( | struct mwSessionHandler * | ) | [read] |
allocate a new session
| void mwSession_recv | ( | struct mwSession * | , |
| const guchar * | , | ||
| gsize | |||
| ) |
Data is buffered, unpacked, and parsed into a message, then processed accordingly.
remove a cipher from the session
| void mwSession_removeClientData | ( | struct mwSession * | session | ) |
remove client data, calling the optional GDestroyNotify function indicated in mwSession_setClientData if applicable
| void mwSession_removeProperty | ( | struct mwSession * | , |
| const char * | key | ||
| ) |
remove a property, calling the optional GDestroyNotify function indicated in mwSession_setProperty if applicable
removes a service from the session.
If the session is started and the service has a stop function, it will be called. Returns the removed service
primarily used by services to have messages serialized and sent
| s | session to send message over |
| msg | message to serialize and send |
| int mwSession_sendAnnounce | ( | struct mwSession * | s, |
| gboolean | may_reply, | ||
| const char * | text, | ||
| const GList * | recipients | ||
| ) |
send an announcement to a list of users/groups.
Targets of announcement must be in the same community as the session.
| s | session to send announcement from |
| may_reply | permit clients to reply. Not all clients honor this. |
| text | text of announcement |
| recipients | list of recipients. Each recipient is specified by a single string, prefix with "@U " for users and "@G " for Notes Address Book groups. |
| int mwSession_sendKeepalive | ( | struct mwSession * | s | ) |
sends the keepalive byte
| void mwSession_senseService | ( | struct mwSession * | s, |
| guint32 | type | ||
| ) |
instruct a STARTED session to check the server for the presense of a given service.
The service will be automatically started upon receipt of an affirmative reply from the server. This function is automatically called upon all services in a session when the session is fully STARTED.
Services which terminate due to an error may call this on themselves to re-initialize when their server-side counterpart is made available again.
| s | owning session |
| type | service type ID |
| void mwSession_setClientData | ( | struct mwSession * | session, |
| gpointer | data, | ||
| GDestroyNotify | clear | ||
| ) |
associate arbitrary data with the session for use by the client code.
Only client applications should use this, never services.
| session | the session to associate the data with |
| data | arbitrary client data |
| clear | optional cleanup function called on data from mwSession_removeClientData and mwSession_free |
| int mwSession_setPrivacyInfo | ( | struct mwSession * | , |
| struct mwPrivacyInfo * | |||
| ) |
set the internal privacy information, and inform the server as necessary.
Triggers the on_setPrivacyInfo call-back.
| void mwSession_setProperty | ( | struct mwSession * | , |
| const char * | key, | ||
| gpointer | val, | ||
| GDestroyNotify | clear | ||
| ) |
associate a key:value pair with the session.
If an existing value is associated with the same key, it will have its clear function called and will be replaced with the new value
| int mwSession_setUserStatus | ( | struct mwSession * | , |
| struct mwUserStatus * | |||
| ) |
set the internal user status state, and inform the server as necessary.
Triggers the on_setUserStatus call-back
| void mwSession_start | ( | struct mwSession * | ) |
instruct the session to begin.
This will result in the initial handshake message being sent.
| void mwSession_stop | ( | struct mwSession * | , |
| guint32 | reason | ||
| ) |
instruct the session to shut down with the following reason code.
1.7.3