Blame src/mw_session.h

Packit Service 37472d
Packit Service 37472d
/*
Packit Service 37472d
  Meanwhile - Unofficial Lotus Sametime Community Client Library
Packit Service 37472d
  Copyright (C) 2004  Christopher (siege) O'Brien
Packit Service 37472d
  
Packit Service 37472d
  This library is free software; you can redistribute it and/or
Packit Service 37472d
  modify it under the terms of the GNU Library General Public
Packit Service 37472d
  License as published by the Free Software Foundation; either
Packit Service 37472d
  version 2 of the License, or (at your option) any later version.
Packit Service 37472d
  
Packit Service 37472d
  This library is distributed in the hope that it will be useful,
Packit Service 37472d
  but WITHOUT ANY WARRANTY; without even the implied warranty of
Packit Service 37472d
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Packit Service 37472d
  Library General Public License for more details.
Packit Service 37472d
  
Packit Service 37472d
  You should have received a copy of the GNU Library General Public
Packit Service 37472d
  License along with this library; if not, write to the Free
Packit Service 37472d
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
Packit Service 37472d
*/
Packit Service 37472d
Packit Service 37472d
#ifndef _MW_SESSION_H
Packit Service 37472d
#define _MW_SESSION_H
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** @file mw_session.h
Packit Service 37472d
Packit Service 37472d
    A client session with a Sametime server is encapsulated in the
Packit Service 37472d
    mwSession structure. The session controls channels, provides
Packit Service 37472d
    encryption ciphers, and manages services using messages over the
Packit Service 37472d
    Master channel.
Packit Service 37472d
Packit Service 37472d
    A session does not directly communicate with a socket or stream,
Packit Service 37472d
    instead the session is initialized from client code with an
Packit Service 37472d
    instance of a mwSessionHandler structure. This session handler
Packit Service 37472d
    provides functions as call-backs for common session events, and
Packit Service 37472d
    provides functions for writing-to and closing the connection to
Packit Service 37472d
    the server.
Packit Service 37472d
Packit Service 37472d
    A session does not perform reads on a socket directly. Instead, it
Packit Service 37472d
    must be fed from an outside source via the mwSession_recv
Packit Service 37472d
    function. The session will buffer and merge data passed to this
Packit Service 37472d
    function to build complete protocol messages, and will act upon
Packit Service 37472d
    each complete message accordingly.
Packit Service 37472d
*/
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
#include "mw_common.h"
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
#ifdef __cplusplus
Packit Service 37472d
extern "C" {
Packit Service 37472d
#endif
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
struct mwChannelSet;
Packit Service 37472d
struct mwCipher;
Packit Service 37472d
struct mwMessage;
Packit Service 37472d
struct mwService;
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** default protocol major version */
Packit Service 37472d
#define MW_PROTOCOL_VERSION_MAJOR  0x001e
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** default protocol minor version */
Packit Service 37472d
#define MW_PROTOCOL_VERSION_MINOR  0x001d
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** @section Session Properties
Packit Service 37472d
    for use with mwSession_setProperty, et al.
Packit Service 37472d
*/
Packit Service 37472d
/*@{*/
Packit Service 37472d
Packit Service 37472d
/** char *, session user ID */
Packit Service 37472d
#define mwSession_AUTH_USER_ID      "session.auth.user"
Packit Service 37472d
Packit Service 37472d
/** char *, plaintext password */
Packit Service 37472d
#define mwSession_AUTH_PASSWORD     "session.auth.password"
Packit Service 37472d
Packit Service 37472d
/** struct mwOpaque *, authentication token */
Packit Service 37472d
#define mwSession_AUTH_TOKEN        "session.auth.token"
Packit Service 37472d
Packit Service 37472d
/** char *, hostname of client */
Packit Service 37472d
#define mwSession_CLIENT_HOST       "client.host"
Packit Service 37472d
Packit Service 37472d
/** guint32, local IP of client */
Packit Service 37472d
#define mwSession_CLIENT_IP         "client.ip"
Packit Service 37472d
Packit Service 37472d
/** guint16, major version of client protocol */
Packit Service 37472d
#define mwSession_CLIENT_VER_MAJOR  "client.version.major"
Packit Service 37472d
Packit Service 37472d
/** guint16, minor version of client protocol */
Packit Service 37472d
#define mwSession_CLIENT_VER_MINOR  "client.version.minor"
Packit Service 37472d
Packit Service 37472d
/** guint16, client type identifier */
Packit Service 37472d
#define mwSession_CLIENT_TYPE_ID    "client.id"
Packit Service 37472d
Packit Service 37472d
/** guint16, major version of server protocol */
Packit Service 37472d
#define mwSession_SERVER_VER_MAJOR  "server.version.major"
Packit Service 37472d
Packit Service 37472d
/** guint16, minor version of server protocol */
Packit Service 37472d
#define mwSession_SERVER_VER_MINOR  "server.version.minor"
Packit Service 37472d
Packit Service 37472d
/*@}*/
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
enum mwSessionState {
Packit Service 37472d
  mwSession_STARTING,      /**< session is starting */
Packit Service 37472d
  mwSession_HANDSHAKE,     /**< session has sent handshake */
Packit Service 37472d
  mwSession_HANDSHAKE_ACK, /**< session has received handshake ack */
Packit Service 37472d
  mwSession_LOGIN,         /**< session has sent login */
Packit Service 37472d
  mwSession_LOGIN_REDIR,   /**< session has been redirected */
Packit Service 37472d
  mwSession_LOGIN_ACK,     /**< session has received login ack */
Packit Service 37472d
  mwSession_STARTED,       /**< session is active */
Packit Service 37472d
  mwSession_STOPPING,      /**< session is shutting down */
Packit Service 37472d
  mwSession_STOPPED,       /**< session is stopped */
Packit Service 37472d
  mwSession_UNKNOWN,       /**< indicates an error determining state */
Packit Service 37472d
  mwSession_LOGIN_CONT,    /**< session has sent a login continue */
Packit Service 37472d
};
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
#define mwSession_isState(session, state) \
Packit Service 37472d
  (mwSession_getState((session)) == (state))
Packit Service 37472d
Packit Service 37472d
#define mwSession_isStarting(s) \
Packit Service 37472d
  (mwSession_isState((s), mwSession_STARTING)  || \
Packit Service 37472d
   mwSession_isState((s), mwSession_HANDSHAKE) || \
Packit Service 37472d
   mwSession_isState((s), mwSession_HANDSHAKE_ACK) || \
Packit Service 37472d
   mwSession_isState((s), mwSession_LOGIN) || \
Packit Service 37472d
   mwSession_isState((s), mwSession_LOGIN_ACK) || \
Packit Service 37472d
   mwSession_isState((s), mwSession_LOGIN_REDIR) || \
Packit Service 37472d
   mwSession_isState((s), mwSession_LOGIN_CONT))
Packit Service 37472d
Packit Service 37472d
#define mwSession_isStarted(s) \
Packit Service 37472d
  (mwSession_isState((s), mwSession_STARTED))
Packit Service 37472d
Packit Service 37472d
#define mwSession_isStopping(s) \
Packit Service 37472d
  (mwSession_isState((s), mwSession_STOPPING))
Packit Service 37472d
Packit Service 37472d
#define mwSession_isStopped(s) \
Packit Service 37472d
  (mwSession_isState((s), mwSession_STOPPED))
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** @struct mwSession
Packit Service 37472d
Packit Service 37472d
    Represents a Sametime client session */
Packit Service 37472d
struct mwSession;
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** @struct mwSessionHandler
Packit Service 37472d
Packit Service 37472d
    session handler. Structure which interfaces a session with client
Packit Service 37472d
    code to provide I/O and event handling */
Packit Service 37472d
struct mwSessionHandler {
Packit Service 37472d
  
Packit Service 37472d
  /** write data to the server connection. Required. Should return
Packit Service 37472d
      zero for success, non-zero for error */
Packit Service 37472d
  int (*io_write)(struct mwSession *, const guchar *buf, gsize len);
Packit Service 37472d
  
Packit Service 37472d
  /** close the server connection. Required */
Packit Service 37472d
  void (*io_close)(struct mwSession *);
Packit Service 37472d
Packit Service 37472d
  /** triggered by mwSession_free. Optional. Put cleanup code here */
Packit Service 37472d
  void (*clear)(struct mwSession *);
Packit Service 37472d
Packit Service 37472d
  /** Called when the session has changed status.
Packit Service 37472d
Packit Service 37472d
      @see mwSession_getStateInfo for uses of info field
Packit Service 37472d
Packit Service 37472d
      @param s      the session
Packit Service 37472d
      @param state  the session's state
Packit Service 37472d
      @param info   additional state information */
Packit Service 37472d
  void (*on_stateChange)(struct mwSession *s,
Packit Service 37472d
			 enum mwSessionState state, gpointer info);
Packit Service 37472d
Packit Service 37472d
  /** called when privacy information has been sent or received
Packit Service 37472d
Packit Service 37472d
      @see mwSession_getPrivacyInfo
Packit Service 37472d
  */
Packit Service 37472d
  void (*on_setPrivacyInfo)(struct mwSession *);
Packit Service 37472d
Packit Service 37472d
  /** called when user status has changed
Packit Service 37472d
Packit Service 37472d
      @see mwSession_getUserStatus */
Packit Service 37472d
  void (*on_setUserStatus)(struct mwSession *);
Packit Service 37472d
Packit Service 37472d
  /** called when an admin messages has been received */
Packit Service 37472d
  void (*on_admin)(struct mwSession *, const char *text);
Packit Service 37472d
Packit Service 37472d
  /** called when an announcement arrives */
Packit Service 37472d
  void (*on_announce)(struct mwSession *, struct mwLoginInfo *from,
Packit Service 37472d
		      gboolean may_reply, const char *text);
Packit Service 37472d
Packit Service 37472d
};
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** allocate a new session */
Packit Service 37472d
struct mwSession *mwSession_new(struct mwSessionHandler *);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** stop, clear, free a session. Does not free contained ciphers or
Packit Service 37472d
    services, these must be taken care of explicitly. */
Packit Service 37472d
void mwSession_free(struct mwSession *);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** obtain a reference to the session's handler */
Packit Service 37472d
struct mwSessionHandler *mwSession_getHandler(struct mwSession *);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** instruct the session to begin. This will result in the initial
Packit Service 37472d
    handshake message being sent. */
Packit Service 37472d
void mwSession_start(struct mwSession *);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** instruct the session to shut down with the following reason
Packit Service 37472d
    code. */
Packit Service 37472d
void mwSession_stop(struct mwSession *, guint32 reason);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** Data is buffered, unpacked, and parsed into a message, then
Packit Service 37472d
    processed accordingly. */
Packit Service 37472d
void mwSession_recv(struct mwSession *, const guchar *, gsize);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** primarily used by services to have messages serialized and sent
Packit Service 37472d
    @param s    session to send message over
Packit Service 37472d
    @param msg  message to serialize and send
Packit Service 37472d
    @returns    0 for success */
Packit Service 37472d
int mwSession_send(struct mwSession *s, struct mwMessage *msg);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** sends the keepalive byte */
Packit Service 37472d
int mwSession_sendKeepalive(struct mwSession *s);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** respond to a login redirect message by forcing the login sequence
Packit Service 37472d
    to continue through the immediate server. */
Packit Service 37472d
int mwSession_forceLogin(struct mwSession *s);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** send an announcement to a list of users/groups. Targets of
Packit Service 37472d
    announcement must be in the same community as the session.
Packit Service 37472d
Packit Service 37472d
    @param s          session to send announcement from
Packit Service 37472d
    @param may_reply  permit clients to reply. Not all clients honor this.
Packit Service 37472d
    @param text       text of announcement
Packit Service 37472d
    @param recipients list of recipients. Each recipient is specified
Packit Service 37472d
                      by a single string, prefix with "@U " for users
Packit Service 37472d
                      and "@G " for Notes Address Book groups.
Packit Service 37472d
*/
Packit Service 37472d
int mwSession_sendAnnounce(struct mwSession *s, gboolean may_reply,
Packit Service 37472d
			   const char *text, const GList *recipients);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** set the internal privacy information, and inform the server as
Packit Service 37472d
    necessary. Triggers the on_setPrivacyInfo call-back. */
Packit Service 37472d
int mwSession_setPrivacyInfo(struct mwSession *, struct mwPrivacyInfo *);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** direct reference to the session's internal privacy structure */
Packit Service 37472d
struct mwPrivacyInfo *mwSession_getPrivacyInfo(struct mwSession *);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** reference the login information for the session */
Packit Service 37472d
struct mwLoginInfo *mwSession_getLoginInfo(struct mwSession *);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** set the internal user status state, and inform the server as
Packit Service 37472d
    necessary. Triggers the on_setUserStatus call-back */
Packit Service 37472d
int mwSession_setUserStatus(struct mwSession *, struct mwUserStatus *);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
struct mwUserStatus *mwSession_getUserStatus(struct mwSession *);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** current status of the session */
Packit Service 37472d
enum mwSessionState mwSession_getState(struct mwSession *);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** additional status-specific information. Depending on the state of
Packit Service 37472d
    the session, this value has different meaning.
Packit Service 37472d
Packit Service 37472d
    @li @c mwSession_STOPPING guint32 error code causing
Packit Service 37472d
    the session to shut down
Packit Service 37472d
Packit Service 37472d
    @li @c mwSession_STOPPED guint32 error code causing
Packit Service 37472d
    the session to shut down
Packit Service 37472d
Packit Service 37472d
    @li @c mwSession_LOGIN_REDIR (char *) host to redirect
Packit Service 37472d
    to
Packit Service 37472d
*/
Packit Service 37472d
gpointer mwSession_getStateInfo(struct mwSession *);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
struct mwChannelSet *mwSession_getChannels(struct mwSession *);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** adds a service to the session. If the session is started (or when
Packit Service 37472d
    the session is successfully started) and the service has a start
Packit Service 37472d
    function, the session will request service availability from the
Packit Service 37472d
    server. On receipt of the service availability notification, the
Packit Service 37472d
    session will call the service's start function.
Packit Service 37472d
Packit Service 37472d
    @return TRUE if the session was added correctly */
Packit Service 37472d
gboolean mwSession_addService(struct mwSession *, struct mwService *);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** find a service by its type identifier */
Packit Service 37472d
struct mwService *mwSession_getService(struct mwSession *, guint32 type);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** removes a service from the session. If the session is started and
Packit Service 37472d
    the service has a stop function, it will be called. Returns the
Packit Service 37472d
    removed service */
Packit Service 37472d
struct mwService *mwSession_removeService(struct mwSession *, guint32 type);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** a GList of services in this session. The GList needs to be freed
Packit Service 37472d
    after use */
Packit Service 37472d
GList *mwSession_getServices(struct mwSession *);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** instruct a STARTED session to check the server for the presense of
Packit Service 37472d
    a given service. The service will be automatically started upon
Packit Service 37472d
    receipt of an affirmative reply from the server. This function is
Packit Service 37472d
    automatically called upon all services in a session when the
Packit Service 37472d
    session is fully STARTED.
Packit Service 37472d
Packit Service 37472d
    Services which terminate due to an error may call this on
Packit Service 37472d
    themselves to re-initialize when their server-side counterpart is
Packit Service 37472d
    made available again.
Packit Service 37472d
Packit Service 37472d
    @param s     owning session
Packit Service 37472d
    @param type  service type ID */
Packit Service 37472d
void mwSession_senseService(struct mwSession *s, guint32 type);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** adds a cipher to the session. */
Packit Service 37472d
gboolean mwSession_addCipher(struct mwSession *, struct mwCipher *);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** find a cipher by its type identifier */
Packit Service 37472d
struct mwCipher *mwSession_getCipher(struct mwSession *, guint16 type);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** remove a cipher from the session */
Packit Service 37472d
struct mwCipher *mwSession_removeCipher(struct mwSession *, guint16 type);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** a GList of ciphers in this session. The GList needs to be freed
Packit Service 37472d
    after use */
Packit Service 37472d
GList *mwSession_getCiphers(struct mwSession *);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** associate a key:value pair with the session. If an existing value is
Packit Service 37472d
    associated with the same key, it will have its clear function called
Packit Service 37472d
    and will be replaced with the new value */
Packit Service 37472d
void mwSession_setProperty(struct mwSession *, const char *key,
Packit Service 37472d
			   gpointer val, GDestroyNotify clear);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** obtain the value of a previously set property, or NULL */
Packit Service 37472d
gpointer mwSession_getProperty(struct mwSession *, const char *key);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** remove a property, calling the optional GDestroyNotify function
Packit Service 37472d
    indicated in mwSession_setProperty if applicable */
Packit Service 37472d
void mwSession_removeProperty(struct mwSession *, const char *key);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** associate arbitrary data with the session for use by the client
Packit Service 37472d
    code. Only client applications should use this, never services.
Packit Service 37472d
Packit Service 37472d
    @param session  the session to associate the data with
Packit Service 37472d
    @param data     arbitrary client data
Packit Service 37472d
    @param clear    optional cleanup function called on data from
Packit Service 37472d
                    mwSession_removeClientData and mwSession_free
Packit Service 37472d
*/
Packit Service 37472d
void mwSession_setClientData(struct mwSession *session,
Packit Service 37472d
			     gpointer data, GDestroyNotify clear);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
gpointer mwSession_getClientData(struct mwSession *session);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
/** remove client data, calling the optional GDestroyNotify function
Packit Service 37472d
    indicated in mwSession_setClientData if applicable */
Packit Service 37472d
void mwSession_removeClientData(struct mwSession *session);
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
#ifdef __cplusplus
Packit Service 37472d
}
Packit Service 37472d
#endif
Packit Service 37472d
Packit Service 37472d
Packit Service 37472d
#endif /* _MW_SESSION_H */
Packit Service 37472d