Mercurial > pidgin.yaz
view src/protocols/sametime/meanwhile/mw_session.h @ 11110:f7ce10cad83d
[gaim-migrate @ 13162]
Make drag-and-drop buddy icon setting work for protocols that don't have file transfer.
committer: Tailor Script <tailor@pidgin.im>
author | Richard Laager <rlaager@wiktel.com> |
---|---|
date | Sun, 17 Jul 2005 21:38:59 +0000 |
parents | 3ef77720e577 |
children | 0110fc7c6a8a |
line wrap: on
line source
/* 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