mw_session.h File Reference

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

## Macros

#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"
| char *, session user ID
#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)
#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_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.

## Detailed Description

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.

## Macro Definition Documentation

## MW_PROTOCOL_VERSION_MAJOR

#define MW_PROTOCOL_VERSION_MAJOR 0x001e

default protocol major version

## MW_PROTOCOL_VERSION_MINOR

#define MW_PROTOCOL_VERSION_MINOR 0x001d

default protocol minor version

## mwSession_AUTH_PASSWORD

#define mwSession_AUTH_PASSWORD "session.auth.password"

char *, plaintext password

## mwSession_AUTH_TOKEN

#define mwSession_AUTH_TOKEN "session.auth.token"

struct mwOpaque *, authentication token

## mwSession_AUTH_USER_ID

#define mwSession_AUTH_USER_ID "session.auth.user"

char *, session user ID

# Properties

for use with mwSession_setProperty, et al.

## mwSession_CLIENT_HOST

#define mwSession_CLIENT_HOST "client.host"

char *, hostname of client

## mwSession_CLIENT_IP

#define mwSession_CLIENT_IP "client.ip"

guint32, local IP of client

## mwSession_CLIENT_TYPE_ID

#define mwSession_CLIENT_TYPE_ID "client.id"

guint16, client type identifier

## mwSession_CLIENT_VER_MAJOR

#define mwSession_CLIENT_VER_MAJOR "client.version.major"

guint16, major version of client protocol

## mwSession_CLIENT_VER_MINOR

#define mwSession_CLIENT_VER_MINOR "client.version.minor"

guint16, minor version of client protocol

## mwSession_isStarted

#define mwSession_isStarted | ( |  | s | ) | (mwSession_isState((s), mwSession_STARTED))

## mwSession_isStarting

#define mwSession_isStarting | ( |  | s | ) |

Value:
(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))
mwSession_isState
#define mwSession_isState(session, state)
Definition mw_session.h:122
mwSession_LOGIN_ACK
@ mwSession_LOGIN_ACK
session has received login ack
Definition mw_session.h:113
mwSession_HANDSHAKE
@ mwSession_HANDSHAKE
session has sent handshake
Definition mw_session.h:109
mwSession_LOGIN_CONT
@ mwSession_LOGIN_CONT
session has sent a login continue
Definition mw_session.h:118
mwSession_LOGIN_REDIR
@ mwSession_LOGIN_REDIR
session has been redirected
Definition mw_session.h:112
mwSession_STARTING
@ mwSession_STARTING
session is starting
Definition mw_session.h:108
mwSession_HANDSHAKE_ACK
@ mwSession_HANDSHAKE_ACK
session has received handshake ack
Definition mw_session.h:110
mwSession_LOGIN
@ mwSession_LOGIN
session has sent login
Definition mw_session.h:111

## mwSession_isState

#define mwSession_isState | ( |  | session,
|  |  | state
| ) |  | (mwSession_getState((session)) == (state))

## mwSession_isStopped

#define mwSession_isStopped | ( |  | s | ) | (mwSession_isState((s), mwSession_STOPPED))

## mwSession_isStopping

#define mwSession_isStopping | ( |  | s | ) | (mwSession_isState((s), mwSession_STOPPING))

## mwSession_SERVER_VER_MAJOR

#define mwSession_SERVER_VER_MAJOR "server.version.major"

guint16, major version of server protocol

## mwSession_SERVER_VER_MINOR

#define mwSession_SERVER_VER_MINOR "server.version.minor"

guint16, minor version of server protocol

## Enumeration Type Documentation

## mwSessionState

enum mwSessionState

Enumerator
mwSession_STARTING | session is starting
mwSession_HANDSHAKE | session has sent handshake
mwSession_HANDSHAKE_ACK | session has received handshake ack
mwSession_LOGIN | session has sent login
mwSession_LOGIN_REDIR | session has been redirected
mwSession_LOGIN_ACK | session has received login ack
mwSession_STARTED | session is active
mwSession_STOPPING | session is shutting down
mwSession_STOPPED | session is stopped
mwSession_UNKNOWN | indicates an error determining state
mwSession_LOGIN_CONT | session has sent a login continue

## Function Documentation

## mwSession_addCipher()

gboolean mwSession_addCipher | ( | struct mwSession * | ,
|  | struct mwCipher * |
| ) |  |

adds a cipher to the session.

## mwSession_addService()

gboolean mwSession_addService | ( | struct mwSession * | ,
|  | struct mwService * |
| ) |  |

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.

Returns
  TRUE if the session was added correctly

## mwSession_forceLogin()

int mwSession_forceLogin | ( | struct mwSession * | s | ) |

respond to a login redirect message by forcing the login sequence to continue through the immediate server.

## mwSession_free()

void mwSession_free | ( | struct mwSession * |  | ) |

stop, clear, free a session.

Does not free contained ciphers or services, these must be taken care of explicitly.

## mwSession_getChannels()

struct mwChannelSet * mwSession_getChannels | ( | struct mwSession * |  | ) |

## mwSession_getCipher()

struct mwCipher * mwSession_getCipher | ( | struct mwSession * | ,
|  | guint16 | type
| ) |  |

find a cipher by its type identifier

## mwSession_getCiphers()

GList * mwSession_getCiphers | ( | struct mwSession * |  | ) |

a GList of ciphers in this session.

The GList needs to be freed after use

## mwSession_getClientData()

gpointer mwSession_getClientData | ( | struct mwSession * | session | ) |

## mwSession_getHandler()

struct mwSessionHandler * mwSession_getHandler | ( | struct mwSession * |  | ) |

obtain a reference to the session's handler

## mwSession_getLoginInfo()

struct mwLoginInfo * mwSession_getLoginInfo | ( | struct mwSession * |  | ) |

reference the login information for the session

## mwSession_getPrivacyInfo()

struct mwPrivacyInfo * mwSession_getPrivacyInfo | ( | struct mwSession * |  | ) |

direct reference to the session's internal privacy structure

## mwSession_getProperty()

gpointer mwSession_getProperty | ( | struct mwSession * | ,
|  | const char * | key
| ) |  |

obtain the value of a previously set property, or NULL

## mwSession_getService()

struct mwService * mwSession_getService | ( | struct mwSession * | ,
|  | guint32 | type
| ) |  |

find a service by its type identifier

## mwSession_getServices()

GList * mwSession_getServices | ( | struct mwSession * |  | ) |

a GList of services in this session.

The GList needs to be freed after use

## mwSession_getState()

enum mwSessionState mwSession_getState | ( | struct mwSession * |  | ) |

current status of the session

## mwSession_getStateInfo()

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 down

- `mwSession_STOPPED` guint32 error code causing the session to shut down

- `mwSession_LOGIN_REDIR` (char *) host to redirect to

## mwSession_getUserStatus()

struct mwUserStatus * mwSession_getUserStatus | ( | struct mwSession * |  | ) |

## mwSession_new()

struct mwSession * mwSession_new | ( | struct mwSessionHandler * |  | ) |

allocate a new session

## mwSession_recv()

void mwSession_recv | ( | struct mwSession * | ,
|  | const guchar * | ,
|  | gsize |
| ) |  |

Data is buffered, unpacked, and parsed into a message, then processed accordingly.

## mwSession_removeCipher()

struct mwCipher * mwSession_removeCipher | ( | struct mwSession * | ,
|  | guint16 | type
| ) |  |

remove a cipher from the session

## mwSession_removeClientData()

void mwSession_removeClientData | ( | struct mwSession * | session | ) |

remove client data, calling the optional GDestroyNotify function indicated in mwSession_setClientData if applicable

## mwSession_removeProperty()

void mwSession_removeProperty | ( | struct mwSession * | ,
|  | const char * | key
| ) |  |

remove a property, calling the optional GDestroyNotify function indicated in mwSession_setProperty if applicable

## mwSession_removeService()

struct mwService * mwSession_removeService | ( | struct mwSession * | ,
|  | guint32 | type
| ) |  |

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

## mwSession_send()

int mwSession_send | ( | struct mwSession * | s,
|  | struct mwMessage * | msg
| ) |  |

primarily used by services to have messages serialized and sent

Parameters

  s | session to send message over
  msg | message to serialize and send

Returns
  0 for success

## mwSession_sendAnnounce()

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.

Parameters

  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.

## mwSession_sendKeepalive()

int mwSession_sendKeepalive | ( | struct mwSession * | s | ) |

sends the keepalive byte

## mwSession_senseService()

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.

Parameters

  s | owning session
  type | service type ID

## mwSession_setClientData()

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.

Parameters

  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

## mwSession_setPrivacyInfo()

int mwSession_setPrivacyInfo | ( | struct mwSession * | ,
|  | struct mwPrivacyInfo * |
| ) |  |

set the internal privacy information, and inform the server as necessary.

Triggers the on_setPrivacyInfo call-back.

## mwSession_setProperty()

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

## mwSession_setUserStatus()

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

## mwSession_start()

void mwSession_start | ( | struct mwSession * |  | ) |

instruct the session to begin.

This will result in the initial handshake message being sent.

## mwSession_stop()

void mwSession_stop | ( | struct mwSession * | ,
|  | guint32 | reason
| ) |  |

instruct the session to shut down with the following reason code.