Mercurial > pidgin
diff src/protocols/sametime/meanwhile/mw_session.h @ 10969:3ef77720e577
[gaim-migrate @ 12790]
importing meanwhile library for use in the sametime plugin
committer: Tailor Script <tailor@pidgin.im>
author | Christopher O'Brien <siege@pidgin.im> |
---|---|
date | Sun, 05 Jun 2005 02:50:13 +0000 |
parents | |
children | 0110fc7c6a8a |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/protocols/sametime/meanwhile/mw_session.h Sun Jun 05 02:50:13 2005 +0000 @@ -0,0 +1,357 @@ + +/* + Meanwhile - Unofficial Lotus Sametime Community Client Library + Copyright (C) 2004 Christopher (siege) O'Brien + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public + License along with this library; if not, write to the Free + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +*/ + +#ifndef _MW_SESSION_H +#define _MW_SESSION_H + + +#include "mw_common.h" + + +/** @file session.h + + 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. +*/ + + +struct mwCipher; +struct mwMessage; + + +/** default protocol major version */ +#define MW_PROTOCOL_VERSION_MAJOR 0x001e + + +/** default protocol minor version */ +#define MW_PROTOCOL_VERSION_MINOR 0x001d + + +/** @section Session Properties + ... +*/ +/*@{*/ + +/** char *, session user ID */ +#define mwSession_AUTH_USER_ID "session.auth.user" + +/** char *, plaintext password */ +#define mwSession_AUTH_PASSWORD "session.auth.password" + +/** struct mwOpaque *, authentication token */ +#define mwSession_AUTH_TOKEN "session.auth.token" + +/** guint16, major version of client protocol */ +#define mwSession_CLIENT_VER_MAJOR "client.version.major" + +/** guint16, minor version of client protocol */ +#define mwSession_CLIENT_VER_MINOR "client.version.minor" + +/** guint16, client type identifier */ +#define mwSession_CLIENT_TYPE_ID "client.id" + +/** guint16, major version of server protocol */ +#define mwSession_SERVER_VER_MAJOR "server.version.major" + +/** guint16, minor version of server protocol */ +#define mwSession_SERVER_VER_MINOR "server.version.minor" + +/*@}*/ + + +enum mwSessionState { + 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 */ +}; + + +#define mwSession_isState(session, state) \ + (mwSession_getState((session)) == (state)) + +#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_isStarted(s) \ + (mwSession_isState((s), mwSession_STARTED)) + +#define mwSession_isStopping(s) \ + (mwSession_isState((s), mwSession_STOPPING)) + +#define mwSession_isStopped(s) \ + (mwSession_isState((s), mwSession_STOPPED)) + + +/** @struct mwSession + + Represents a Sametime client session */ +struct mwSession; + + +/** @struct mwSessionHandler + + session handler. Structure which interfaces a session with client + code to provide I/O and event handling */ +struct mwSessionHandler { + + /** write data to the server connection. Required. Should return + zero for success, non-zero for error */ + int (*io_write)(struct mwSession *, const char *buf, gsize len); + + /** close the server connection. Required */ + void (*io_close)(struct mwSession *); + + /** triggered by mwSession_free. Optional. Put cleanup code here */ + void (*clear)(struct mwSession *); + + /** Called when the session has changed status. + + Uses of the info param: + - <code>STOPPING</code> error code causing the session to shut down + + @todo change info to a gpointer + + @param s the session + @param state the session's state + @param info additional state info. */ + void (*on_stateChange)(struct mwSession *s, + enum mwSessionState state, guint32 info); + + /** called when privacy information has been sent or received + + @see mwSession_getPrivacyInfo + */ + void (*on_setPrivacyInfo)(struct mwSession *); + + /** called when user status has changed + + @see mwSession_getUserStatus */ + void (*on_setUserStatus)(struct mwSession *); + + /** called when an admin messages has been received */ + void (*on_admin)(struct mwSession *, const char *text); + + /** called when a login redirect message is received + + @todo remove in favour of on_stateChange, passing host as a + gpointer in info */ + void (*on_loginRedirect)(struct mwSession *, const char *host); +}; + + +/** allocate a new session */ +struct mwSession *mwSession_new(struct mwSessionHandler *); + + +/** stop, clear, free a session. Does not free contained ciphers or + services, these must be taken care of explicitly. */ +void mwSession_free(struct mwSession *); + + +/** obtain a reference to the session's handler */ +struct mwSessionHandler *mwSession_getHandler(struct mwSession *); + + +/** instruct the session to begin. This will result in the initial + handshake message being sent. */ +void mwSession_start(struct mwSession *); + + +/** instruct the session to shut down with the following reason + code. */ +void mwSession_stop(struct mwSession *, guint32 reason); + + +/** Data is buffered, unpacked, and parsed into a message, then + processed accordingly. */ +void mwSession_recv(struct mwSession *, const char *, gsize); + + +/** primarily used by services to have messages serialized and sent + @param s session to send message over + @param msg message to serialize and send + @returns 0 for success */ +int mwSession_send(struct mwSession *s, struct mwMessage *msg); + + +/** sends the keepalive byte */ +int mwSession_sendKeepalive(struct mwSession *s); + + +/** respond to a login redirect message by forcing the login sequence + to continue through the immediate server. */ +int mwSession_forceLogin(struct mwSession *s); + + +/** set the internal privacy information, and inform the server as + necessary. Triggers the on_setPrivacyInfo call-back. */ +int mwSession_setPrivacyInfo(struct mwSession *, struct mwPrivacyInfo *); + + +struct mwPrivacyInfo *mwSession_getPrivacyInfo(struct mwSession *); + + +/** reference the login information for the session */ +struct mwLoginInfo *mwSession_getLoginInfo(struct mwSession *); + + +/** set the internal user status state, and inform the server as + necessary. Triggers the on_setUserStatus call-back */ +int mwSession_setUserStatus(struct mwSession *, struct mwUserStatus *); + + +struct mwUserStatus *mwSession_getUserStatus(struct mwSession *); + + +/** current status of the session */ +enum mwSessionState mwSession_getState(struct mwSession *); + + +/** additional status-specific information */ +guint32 mwSession_getStateInfo(struct mwSession *); + + +struct mwChannelSet *mwSession_getChannels(struct mwSession *); + + +/** 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. + + @return TRUE if the session was added correctly */ +gboolean mwSession_addService(struct mwSession *, struct mwService *); + + +/** find a service by its type identifier */ +struct mwService *mwSession_getService(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 */ +struct mwService *mwSession_removeService(struct mwSession *, guint32 type); + + +/** a GList of services in this session. The GList needs to be freed + after use */ +GList *mwSession_getServices(struct mwSession *); + + +/** 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. + + @param s owning session + @param type service type ID */ +void mwSession_senseService(struct mwSession *s, guint32 type); + + +/** adds a cipher to the session. */ +gboolean mwSession_addCipher(struct mwSession *, struct mwCipher *); + + +/** find a cipher by its type identifier */ +struct mwCipher *mwSession_getCipher(struct mwSession *, guint16 type); + + +/** remove a cipher from the session */ +struct mwCipher *mwSession_removeCipher(struct mwSession *, guint16 type); + + +/** a GList of ciphers in this session. The GList needs to be freed + after use */ +GList *mwSession_getCiphers(struct mwSession *); + + +/** 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 */ +void mwSession_setProperty(struct mwSession *, const char *key, + gpointer val, GDestroyNotify clear); + + +/** obtain the value of a previously set property, or NULL */ +gpointer mwSession_getProperty(struct mwSession *, const char *key); + + +/** remove a property, calling the optional GDestroyNotify function + indicated in mwSession_setProperty if applicable */ +void mwSession_removeProperty(struct mwSession *, const char *key); + + +/** associate arbitrary data with the session for use by the client + code. Only client applications should use this, never services. + + @param session the session to associate the data with + @param data arbitrary client data + @param clear optional cleanup function called on data from + mwSession_removeClientData and mwSession_free +*/ +void mwSession_setClientData(struct mwSession *session, + gpointer data, GDestroyNotify clear); + + +gpointer mwSession_getClientData(struct mwSession *session); + + +/** remove client data, calling the optional GDestroyNotify function + indicated in mwSession_setClientData if applicable */ +void mwSession_removeClientData(struct mwSession *session); + + +#endif +