File: mw_service.h

package info (click to toggle)
meanwhile 1.0.2-5
  • links: PTS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 2,732 kB
  • ctags: 3,503
  • sloc: ansic: 13,856; sh: 8,360; makefile: 145
file content (370 lines) | stat: -rw-r--r-- 11,523 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370

/*
  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"


#ifdef __cplusplus
extern "C" {
#endif


/* 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);


/*@}*/


#ifdef __cplusplus
}
#endif


#endif /* _MW_SERVICE_H */