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)
#define	mwSession_isStarting(s)
#define	mwSession_isState(session, state)
#define	mwSession_isStopped(s)
#define	mwSession_isStopping(s)
#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

)

Value:

(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 )

Value:

(mwSession_getState((session)) == (state))

mwSession_isStopped

#define mwSession_isStopped

(

s

)

Value:

(mwSession_isState((s), mwSession_STOPPED))

mwSession_isStopping

#define mwSession_isStopping

(

s

)

Value:

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

References mwSession_addCipher().

Referenced by mwSession_addCipher().

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

References mwSession_addService().

Referenced by mwSession_addService().

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.

References mwSession_forceLogin().

Referenced by mwSession_forceLogin().

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.

References mwSession_free().

Referenced by mwSession_free().

mwSession_getChannels()

struct mwChannelSet * mwSession_getChannels

(

struct mwSession *

)

References mwSession_getChannels().

Referenced by mwSession_getChannels().

mwSession_getCipher()

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

find a cipher by its type identifier

References mwSession_getCipher().

Referenced by mwSession_getCipher().

mwSession_getCiphers()

GList * mwSession_getCiphers

(

struct mwSession *

)

a GList of ciphers in this session.

The GList needs to be freed after use

References mwSession_getCiphers().

Referenced by mwSession_getCiphers().

mwSession_getClientData()

gpointer mwSession_getClientData

(

struct mwSession *

session

)

References mwSession_getClientData().

Referenced by mwSession_getClientData().

mwSession_getHandler()

struct mwSessionHandler * mwSession_getHandler

(

struct mwSession *

)

obtain a reference to the session's handler

References mwSession_getHandler().

Referenced by mwSession_getHandler().

mwSession_getLoginInfo()

struct mwLoginInfo * mwSession_getLoginInfo

(

struct mwSession *

)

reference the login information for the session

References mwSession_getLoginInfo().

Referenced by mwSession_getLoginInfo().

mwSession_getPrivacyInfo()

struct mwPrivacyInfo * mwSession_getPrivacyInfo

(

struct mwSession *

)

direct reference to the session's internal privacy structure

References mwSession_getPrivacyInfo().

Referenced by mwSession_getPrivacyInfo().

mwSession_getProperty()

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

obtain the value of a previously set property, or NULL

References mwSession_getProperty().

Referenced by mwSession_getProperty().

mwSession_getService()

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

find a service by its type identifier

References mwSession_getService().

Referenced by mwSession_getService().

mwSession_getServices()

GList * mwSession_getServices

(

struct mwSession *

)

a GList of services in this session.

The GList needs to be freed after use

References mwSession_getServices().

Referenced by mwSession_getServices().

mwSession_getState()

enum mwSessionState mwSession_getState

(

struct mwSession *

)

current status of the session

References mwSession_getState().

Referenced by mwSession_getState().

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

References mwSession_getStateInfo().

Referenced by mwSession_getStateInfo().

mwSession_getUserStatus()

struct mwUserStatus * mwSession_getUserStatus

(

struct mwSession *

)

References mwSession_getUserStatus().

Referenced by mwSession_getUserStatus().

mwSession_new()

struct mwSession * mwSession_new

(

struct mwSessionHandler *

)

allocate a new session

References mwSession_new().

Referenced by mwSession_new().

mwSession_recv()

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

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

References mwSession_recv().

Referenced by mwSession_recv().

mwSession_removeCipher()

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

remove a cipher from the session

References mwSession_removeCipher().

Referenced by mwSession_removeCipher().

mwSession_removeClientData()

void mwSession_removeClientData

(

struct mwSession *

session

)

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

References mwSession_removeClientData().

Referenced by mwSession_removeClientData().

mwSession_removeProperty()

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

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

References mwSession_removeProperty().

Referenced by mwSession_removeProperty().

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

References mwSession_removeService().

Referenced by mwSession_removeService().

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

References mwSession_send().

Referenced by mwSession_send().

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.

References mwSession_sendAnnounce().

Referenced by mwSession_sendAnnounce().

mwSession_sendKeepalive()

int mwSession_sendKeepalive

(

struct mwSession *

s

)

sends the keepalive byte

References mwSession_sendKeepalive().

Referenced by mwSession_sendKeepalive().

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

References mwSession_senseService().

Referenced by mwSession_senseService().

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

References mwSession_setClientData().

Referenced by mwSession_setClientData().

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.

References mwSession_setPrivacyInfo().

Referenced by mwSession_setPrivacyInfo().

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

References mwSession_setProperty().

Referenced by mwSession_setProperty().

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

References mwSession_setUserStatus().

Referenced by mwSession_setUserStatus().

mwSession_start()

void mwSession_start

(

struct mwSession *

)

instruct the session to begin.

This will result in the initial handshake message being sent.

References mwSession_start().

Referenced by mwSession_start().

mwSession_stop()

void mwSession_stop	(	struct mwSession *	,
		guint32	reason )

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

References mwSession_stop().

Referenced by mwSession_stop().