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