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