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 <[e-mail]>

--- /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
+