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.
#include "mw_common.h"
Go to the source code of this file.
Data Structures | |
struct | mwSessionHandler |
session handler. More... | |
#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_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 | |
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)) |
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. | |
mwChannelSet * | mwSession_getChannels (struct mwSession *) |
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) |
mwSessionHandler * | mwSession_getHandler (struct mwSession *) |
obtain a reference to the session's handler | |
mwLoginInfo * | mwSession_getLoginInfo (struct mwSession *) |
reference the login information for the session | |
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 | |
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. | |
mwUserStatus * | mwSession_getUserStatus (struct mwSession *) |
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. | |
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 | |
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. |
|
default protocol major version
|
|
default protocol minor version
|
|
char *, plaintext password
|
|
struct mwOpaque *, authentication token
|
|
char *, session user ID
|
|
char *, hostname of client
|
|
guint32, local IP of client
|
|
guint16, client type identifier
|
|
guint16, major version of client protocol
|
|
guint16, minor version of client protocol
|
|
|
|
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)) |
|
|
|
|
|
|
|
guint16, major version of server protocol
|
|
guint16, minor version of server protocol
|
|
|
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.
|
|
respond to a login redirect message by forcing the login sequence to continue through the immediate server.
|
|
stop, clear, free a session. Does not free contained ciphers or services, these must be taken care of explicitly. |
|
|
|
find a cipher by its type identifier
|
|
a GList of ciphers in this session. The GList needs to be freed after use |
|
|
|
obtain a reference to the session's handler
|
|
reference the login information for the session
|
|
direct reference to the session's internal privacy structure
|
|
obtain the value of a previously set property, or NULL
|
|
find a service by its type identifier
|
|
a GList of services in this session. The GList needs to be freed after use |
|
current status of the session
|
|
additional status-specific information. Depending on the state of the session, this value has different meaning.
|
|
|
|
allocate a new session
|
|
Data is buffered, unpacked, and parsed into a message, then processed accordingly.
|
|
remove a cipher from the session
|
|
remove client data, calling the optional GDestroyNotify function indicated in mwSession_setClientData if applicable
|
|
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
|
|
send an announcement to a list of users/groups. Targets of announcement must be in the same community as the session.
|
|
sends the keepalive byte
|
|
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.
|
|
associate arbitrary data with the session for use by the client code. Only client applications should use this, never services.
|
|
set the internal privacy information, and inform the server as necessary. Triggers the on_setPrivacyInfo call-back. |
|
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 |
|
set the internal user status state, and inform the server as necessary. Triggers the on_setUserStatus call-back |
|
instruct the session to begin. This will result in the initial handshake message being sent. |
|
instruct the session to shut down with the following reason code.
|