|
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_SERVICE_H
|
|
Packit Service |
37472d |
#define _MW_SERVICE_H
|
|
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 |
/* place-holders */
|
|
Packit Service |
37472d |
struct mwChannel;
|
|
Packit Service |
37472d |
struct mwService;
|
|
Packit Service |
37472d |
struct mwSession;
|
|
Packit Service |
37472d |
struct mwMsgChannelCreate;
|
|
Packit Service |
37472d |
struct mwMsgChannelAccept;
|
|
Packit Service |
37472d |
struct mwMsgChannelDestroy;
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** State-tracking for a service */
|
|
Packit Service |
37472d |
enum mwServiceState {
|
|
Packit Service |
37472d |
mwServiceState_STOPPED, /**< the service is not active */
|
|
Packit Service |
37472d |
mwServiceState_STOPPING, /**< the service is shutting down */
|
|
Packit Service |
37472d |
mwServiceState_STARTED, /**< the service is active */
|
|
Packit Service |
37472d |
mwServiceState_STARTING, /**< the service is starting up */
|
|
Packit Service |
37472d |
mwServiceState_ERROR, /**< error in service, shutting down */
|
|
Packit Service |
37472d |
mwServiceState_UNKNOWN, /**< error determining state */
|
|
Packit Service |
37472d |
};
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Casts a concrete service (such as mwServiceAware) into a mwService */
|
|
Packit Service |
37472d |
#define MW_SERVICE(srv) ((struct mwService *) srv)
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
#define MW_SERVICE_IS_STATE(srvc, state) \
|
|
Packit Service |
37472d |
(mwService_getState(MW_SERVICE(srvc)) == (state))
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
#define MW_SERVICE_IS_STOPPED(srvc) \
|
|
Packit Service |
37472d |
MW_SERVICE_IS_STATE(srvc, mwServiceState_STOPPED)
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
#define MW_SERVICE_IS_STOPPING(srvc) \
|
|
Packit Service |
37472d |
MW_SERVICE_IS_STATE(srvc, mwServiceState_STOPPING)
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
#define MW_SERVICE_IS_STARTED(srvc) \
|
|
Packit Service |
37472d |
MW_SERVICE_IS_STATE(srvc, mwServiceState_STARTED)
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
#define MW_SERVICE_IS_STARTING(srvc) \
|
|
Packit Service |
37472d |
MW_SERVICE_IS_STATE(srvc, mwServiceState_STARTING)
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** If a service is STARTING or STARTED, it's considered LIVE */
|
|
Packit Service |
37472d |
#define MW_SERVICE_IS_LIVE(srvc) \
|
|
Packit Service |
37472d |
(MW_SERVICE_IS_STARTING(srvc) || MW_SERVICE_IS_STARTED(srvc))
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** If a service is STOPPING or STOPPED, it's considered DEAD */
|
|
Packit Service |
37472d |
#define MW_SERVICE_IS_DEAD(srvc) \
|
|
Packit Service |
37472d |
(MW_SERVICE_IS_STOPPING(srvc) || MW_SERVICE_IS_STOPPED(srvc))
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
typedef void (*mwService_funcStart)(struct mwService *service);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
typedef void (*mwService_funcStop)(struct mwService *service);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
typedef void (*mwService_funcClear)(struct mwService *service);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
typedef const char *(*mwService_funcGetName)(struct mwService *service);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
typedef const char *(*mwService_funcGetDesc)(struct mwService *service);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @todo remove msg and replace with appropriate additional parameters */
|
|
Packit Service |
37472d |
typedef void (*mwService_funcRecvCreate)
|
|
Packit Service |
37472d |
(struct mwService *service,
|
|
Packit Service |
37472d |
struct mwChannel *channel,
|
|
Packit Service |
37472d |
struct mwMsgChannelCreate *msg);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @todo remove msg and replace with appropriate additional parameters */
|
|
Packit Service |
37472d |
typedef void (*mwService_funcRecvAccept)
|
|
Packit Service |
37472d |
(struct mwService *service,
|
|
Packit Service |
37472d |
struct mwChannel *channel,
|
|
Packit Service |
37472d |
struct mwMsgChannelAccept *msg);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @todo remove msg and replace with appropriate additional parameters */
|
|
Packit Service |
37472d |
typedef void (*mwService_funcRecvDestroy)
|
|
Packit Service |
37472d |
(struct mwService *service,
|
|
Packit Service |
37472d |
struct mwChannel *channel,
|
|
Packit Service |
37472d |
struct mwMsgChannelDestroy *msg);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
typedef void (*mwService_funcRecv)
|
|
Packit Service |
37472d |
(struct mwService *service,
|
|
Packit Service |
37472d |
struct mwChannel *channel,
|
|
Packit Service |
37472d |
guint16 msg_type,
|
|
Packit Service |
37472d |
struct mwOpaque *data);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** A service is the recipient of sendOnCnl messages sent over
|
|
Packit Service |
37472d |
channels marked with the corresponding service id. Services
|
|
Packit Service |
37472d |
provide functionality such as IM relaying, Awareness tracking and
|
|
Packit Service |
37472d |
notification, and Conference handling. It is a service's
|
|
Packit Service |
37472d |
responsibility to accept or destroy channels, and to process data
|
|
Packit Service |
37472d |
sent over those channels */
|
|
Packit Service |
37472d |
struct mwService {
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** the unique identifier by which this service is registered. The
|
|
Packit Service |
37472d |
type value also relates to those channels which will be directed
|
|
Packit Service |
37472d |
to this service */
|
|
Packit Service |
37472d |
guint32 type;
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** the state of this service. Determines whether or not the session
|
|
Packit Service |
37472d |
should call the start function upon receipt of a service
|
|
Packit Service |
37472d |
available message. Should not be set or checked by hand.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@relates mwService_getState */
|
|
Packit Service |
37472d |
enum mwServiceState state;
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** session this service is attached to.
|
|
Packit Service |
37472d |
@relates mwService_getSession */
|
|
Packit Service |
37472d |
struct mwSession *session;
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @return string short name of the service
|
|
Packit Service |
37472d |
@relates mwService_getName */
|
|
Packit Service |
37472d |
mwService_funcGetName get_name;
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @return string short description of the service
|
|
Packit Service |
37472d |
@relates mwService_getDesc */
|
|
Packit Service |
37472d |
mwService_funcGetDesc get_desc;
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** The service's channel create handler. Called when the session
|
|
Packit Service |
37472d |
receives a channel create message with a service matching this
|
|
Packit Service |
37472d |
service's type.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@relates mwService_recvCreate */
|
|
Packit Service |
37472d |
mwService_funcRecvCreate recv_create;
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** The service's channel accept handler. Called when the session
|
|
Packit Service |
37472d |
receives a channel accept message for a channel with a service
|
|
Packit Service |
37472d |
matching this service's type.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@relates mwService_recvAccept */
|
|
Packit Service |
37472d |
mwService_funcRecvAccept recv_accept;
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** The service's channel destroy handler. Called when the session
|
|
Packit Service |
37472d |
receives a channel destroy message for a channel with a service
|
|
Packit Service |
37472d |
matching this service's type.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@relates mwService_recvDestroy */
|
|
Packit Service |
37472d |
mwService_funcRecvDestroy recv_destroy;
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** The service's input handler. Called when the session receives
|
|
Packit Service |
37472d |
data on a channel belonging to this service
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@relates mwService_recv */
|
|
Packit Service |
37472d |
mwService_funcRecv recv;
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** The service's start handler. Called upon the receipt of a
|
|
Packit Service |
37472d |
service available message.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@relates mwService_start */
|
|
Packit Service |
37472d |
mwService_funcStart start;
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** The service's stop handler. Called when the session is shutting
|
|
Packit Service |
37472d |
down, or when the service is free'd.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@relates mwService_stop */
|
|
Packit Service |
37472d |
mwService_funcStop stop;
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** The service's cleanup handler. Service implementations should
|
|
Packit Service |
37472d |
presume that mwService::stop will be called first. The clear
|
|
Packit Service |
37472d |
handler is not for shutting down channels or generating
|
|
Packit Service |
37472d |
non-cleanup side-effects, it is only for handling tear-down of
|
|
Packit Service |
37472d |
the service, and will only be called once for any instance.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@relates mwService_free */
|
|
Packit Service |
37472d |
mwService_funcClear clear;
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Optional client data, not for use by service implementations
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@relates mwService_getClientData
|
|
Packit Service |
37472d |
@relates mwService_setClientData */
|
|
Packit Service |
37472d |
gpointer client_data;
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Optional client data cleanup function. Called with client_data
|
|
Packit Service |
37472d |
from mwService_free
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@relates mwService_getClientData
|
|
Packit Service |
37472d |
@relates mwService_setClientData */
|
|
Packit Service |
37472d |
GDestroyNotify client_cleanup;
|
|
Packit Service |
37472d |
};
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @name Service Extension API
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
These functions are for use by service implementations */
|
|
Packit Service |
37472d |
/*@{*/
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Prepares a newly allocated service for use.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
Intended for use by service implementations, rather than by code
|
|
Packit Service |
37472d |
utilizing a service.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
The service state will be initialized to STOPPED.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@param service the service to initialize
|
|
Packit Service |
37472d |
@param session the service's owning session
|
|
Packit Service |
37472d |
@param service_type the service ID number */
|
|
Packit Service |
37472d |
void mwService_init(struct mwService *service,
|
|
Packit Service |
37472d |
struct mwSession *session,
|
|
Packit Service |
37472d |
guint32 service_type);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Indicate that a service is started. To be used by service
|
|
Packit Service |
37472d |
implementations when the service is fully started. */
|
|
Packit Service |
37472d |
void mwService_started(struct mwService *service);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Indicate that a service is stopped. To be used by service
|
|
Packit Service |
37472d |
implementations when the service is fully stopped. */
|
|
Packit Service |
37472d |
void mwService_stopped(struct mwService *service);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/*@}*/
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @name General Services API
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
These functions provide unified access to the general functions of
|
|
Packit Service |
37472d |
a client service, with some simple sanity-checking. */
|
|
Packit Service |
37472d |
/*@{*/
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Triggers the recv_create handler on the service.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@param service the service to handle the message
|
|
Packit Service |
37472d |
@param channel the channel being created
|
|
Packit Service |
37472d |
@param msg the channel create message */
|
|
Packit Service |
37472d |
void mwService_recvCreate(struct mwService *service,
|
|
Packit Service |
37472d |
struct mwChannel *channel,
|
|
Packit Service |
37472d |
struct mwMsgChannelCreate *msg);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Triggers the recv_accept handler on the service.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@param service the service to handle the message
|
|
Packit Service |
37472d |
@param channel the channel being accepted
|
|
Packit Service |
37472d |
@param msg the channel accept message */
|
|
Packit Service |
37472d |
void mwService_recvAccept(struct mwService *service,
|
|
Packit Service |
37472d |
struct mwChannel *channel,
|
|
Packit Service |
37472d |
struct mwMsgChannelAccept *msg);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Triggers the recv_destroy handler on the service.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@param service the service to handle the message
|
|
Packit Service |
37472d |
@param channel the channel being destroyed
|
|
Packit Service |
37472d |
@param msg the channel destroy message */
|
|
Packit Service |
37472d |
void mwService_recvDestroy(struct mwService *service,
|
|
Packit Service |
37472d |
struct mwChannel *channel,
|
|
Packit Service |
37472d |
struct mwMsgChannelDestroy *msg);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Triggers the input handler on the service
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@param service the service to receive the input
|
|
Packit Service |
37472d |
@param channel the channel the input was received from
|
|
Packit Service |
37472d |
@param msg_type the service-dependant message type
|
|
Packit Service |
37472d |
@param data the message data */
|
|
Packit Service |
37472d |
void mwService_recv(struct mwService *service,
|
|
Packit Service |
37472d |
struct mwChannel *channel,
|
|
Packit Service |
37472d |
guint16 msg_type,
|
|
Packit Service |
37472d |
struct mwOpaque *data);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @return the appropriate type id for the service */
|
|
Packit Service |
37472d |
guint32 mwService_getType(struct mwService *);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @return string short name of the service */
|
|
Packit Service |
37472d |
const char *mwService_getName(struct mwService *);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @return string short description of the service */
|
|
Packit Service |
37472d |
const char *mwService_getDesc(struct mwService *);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @return the service's session */
|
|
Packit Service |
37472d |
struct mwSession *mwService_getSession(struct mwService *service);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @returns the service's state
|
|
Packit Service |
37472d |
*/
|
|
Packit Service |
37472d |
enum mwServiceState mwService_getState(struct mwService *service);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Triggers the start handler for the service. Normally called from
|
|
Packit Service |
37472d |
the session upon receipt of a service available message. Service
|
|
Packit Service |
37472d |
implementations should use this handler to open any necessary
|
|
Packit Service |
37472d |
channels, etc. Checks that the service is STOPPED, or returns.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@param service The service to start
|
|
Packit Service |
37472d |
*/
|
|
Packit Service |
37472d |
void mwService_start(struct mwService *service);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Triggers the stop handler for the service. Normally called from
|
|
Packit Service |
37472d |
the session before closing down the connection. Checks that the
|
|
Packit Service |
37472d |
service is STARTED or STARTING, or returns
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@param service The service to stop
|
|
Packit Service |
37472d |
*/
|
|
Packit Service |
37472d |
void mwService_stop(struct mwService *service);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Frees memory used by a service. Will trigger the stop handler if
|
|
Packit Service |
37472d |
the service is STARTED or STARTING. Triggers clear handler to allow
|
|
Packit Service |
37472d |
cleanup.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@param service The service to clear and free
|
|
Packit Service |
37472d |
*/
|
|
Packit Service |
37472d |
void mwService_free(struct mwService *service);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Associates client data with service. If there is existing data, it
|
|
Packit Service |
37472d |
will not have its cleanup function called. Client data is not for
|
|
Packit Service |
37472d |
use by service implementations. Rather, it is for use by client
|
|
Packit Service |
37472d |
code which may later make use of those service implementations. */
|
|
Packit Service |
37472d |
void mwService_setClientData(struct mwService *service,
|
|
Packit Service |
37472d |
gpointer data, GDestroyNotify cleanup);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Reference associated client data */
|
|
Packit Service |
37472d |
gpointer mwService_getClientData(struct mwService *service);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Removes client data from service. If there is a cleanup function,
|
|
Packit Service |
37472d |
it will be called. */
|
|
Packit Service |
37472d |
void mwService_removeClientData(struct mwService *service);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/*@}*/
|
|
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_SERVICE_H */
|
|
Packit Service |
37472d |
|