File: mw_session.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 (397 lines) | stat: -rw-r--r-- 12,887 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
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397

/*
  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_SESSION_H
#define _MW_SESSION_H


/** @file mw_session.h

    A client session with a Sametime server is encapsulated in the
    mwSession structure. The session controls channels, provides
    encryption ciphers, and manages services using messages over the
    Master channel.

    A session does not directly communicate with a socket or stream,
    instead the session is initialized from client code with an
    instance of a mwSessionHandler structure. This session handler
    provides functions as call-backs for common session events, and
    provides functions for writing-to and closing the connection to
    the server.

    A session does not perform reads on a socket directly. Instead, it
    must be fed from an outside source via the mwSession_recv
    function. The session will buffer and merge data passed to this
    function to build complete protocol messages, and will act upon
    each complete message accordingly.
*/


#include "mw_common.h"


#ifdef __cplusplus
extern "C" {
#endif


struct mwChannelSet;
struct mwCipher;
struct mwMessage;
struct mwService;


/** default protocol major version */
#define MW_PROTOCOL_VERSION_MAJOR  0x001e


/** default protocol minor version */
#define MW_PROTOCOL_VERSION_MINOR  0x001d


/** @section Session Properties
    for use with mwSession_setProperty, et al.
*/
/*@{*/

/** char *, session user ID */
#define mwSession_AUTH_USER_ID      "session.auth.user"

/** char *, plaintext password */
#define mwSession_AUTH_PASSWORD     "session.auth.password"

/** struct mwOpaque *, authentication token */
#define mwSession_AUTH_TOKEN        "session.auth.token"

/** char *, hostname of client */
#define mwSession_CLIENT_HOST       "client.host"

/** guint32, local IP of client */
#define mwSession_CLIENT_IP         "client.ip"

/** guint16, major version of client protocol */
#define mwSession_CLIENT_VER_MAJOR  "client.version.major"

/** guint16, minor version of client protocol */
#define mwSession_CLIENT_VER_MINOR  "client.version.minor"

/** guint16, client type identifier */
#define mwSession_CLIENT_TYPE_ID    "client.id"

/** guint16, major version of server protocol */
#define mwSession_SERVER_VER_MAJOR  "server.version.major"

/** guint16, minor version of server protocol */
#define mwSession_SERVER_VER_MINOR  "server.version.minor"

/*@}*/


enum mwSessionState {
  mwSession_STARTING,      /**< session is starting */
  mwSession_HANDSHAKE,     /**< session has sent handshake */
  mwSession_HANDSHAKE_ACK, /**< session has received handshake ack */
  mwSession_LOGIN,         /**< session has sent login */
  mwSession_LOGIN_REDIR,   /**< session has been redirected */
  mwSession_LOGIN_ACK,     /**< session has received login ack */
  mwSession_STARTED,       /**< session is active */
  mwSession_STOPPING,      /**< session is shutting down */
  mwSession_STOPPED,       /**< session is stopped */
  mwSession_UNKNOWN,       /**< indicates an error determining state */
  mwSession_LOGIN_CONT,    /**< session has sent a login continue */
};


#define mwSession_isState(session, state) \
  (mwSession_getState((session)) == (state))

#define mwSession_isStarting(s) \
  (mwSession_isState((s), mwSession_STARTING)  || \
   mwSession_isState((s), mwSession_HANDSHAKE) || \
   mwSession_isState((s), mwSession_HANDSHAKE_ACK) || \
   mwSession_isState((s), mwSession_LOGIN) || \
   mwSession_isState((s), mwSession_LOGIN_ACK) || \
   mwSession_isState((s), mwSession_LOGIN_REDIR) || \
   mwSession_isState((s), mwSession_LOGIN_CONT))

#define mwSession_isStarted(s) \
  (mwSession_isState((s), mwSession_STARTED))

#define mwSession_isStopping(s) \
  (mwSession_isState((s), mwSession_STOPPING))

#define mwSession_isStopped(s) \
  (mwSession_isState((s), mwSession_STOPPED))


/** @struct mwSession

    Represents a Sametime client session */
struct mwSession;


/** @struct mwSessionHandler

    session handler. Structure which interfaces a session with client
    code to provide I/O and event handling */
struct mwSessionHandler {
  
  /** write data to the server connection. Required. Should return
      zero for success, non-zero for error */
  int (*io_write)(struct mwSession *, const guchar *buf, gsize len);
  
  /** close the server connection. Required */
  void (*io_close)(struct mwSession *);

  /** triggered by mwSession_free. Optional. Put cleanup code here */
  void (*clear)(struct mwSession *);

  /** Called when the session has changed status.

      @see mwSession_getStateInfo for uses of info field

      @param s      the session
      @param state  the session's state
      @param info   additional state information */
  void (*on_stateChange)(struct mwSession *s,
			 enum mwSessionState state, gpointer info);

  /** called when privacy information has been sent or received

      @see mwSession_getPrivacyInfo
  */
  void (*on_setPrivacyInfo)(struct mwSession *);

  /** called when user status has changed

      @see mwSession_getUserStatus */
  void (*on_setUserStatus)(struct mwSession *);

  /** called when an admin messages has been received */
  void (*on_admin)(struct mwSession *, const char *text);

  /** called when an announcement arrives */
  void (*on_announce)(struct mwSession *, struct mwLoginInfo *from,
		      gboolean may_reply, const char *text);

};


/** allocate a new session */
struct mwSession *mwSession_new(struct mwSessionHandler *);


/** stop, clear, free a session. Does not free contained ciphers or
    services, these must be taken care of explicitly. */
void mwSession_free(struct mwSession *);


/** obtain a reference to the session's handler */
struct mwSessionHandler *mwSession_getHandler(struct mwSession *);


/** instruct the session to begin. This will result in the initial
    handshake message being sent. */
void mwSession_start(struct mwSession *);


/** instruct the session to shut down with the following reason
    code. */
void mwSession_stop(struct mwSession *, guint32 reason);


/** Data is buffered, unpacked, and parsed into a message, then
    processed accordingly. */
void mwSession_recv(struct mwSession *, const guchar *, gsize);


/** primarily used by services to have messages serialized and sent
    @param s    session to send message over
    @param msg  message to serialize and send
    @returns    0 for success */
int mwSession_send(struct mwSession *s, struct mwMessage *msg);


/** sends the keepalive byte */
int mwSession_sendKeepalive(struct mwSession *s);


/** respond to a login redirect message by forcing the login sequence
    to continue through the immediate server. */
int mwSession_forceLogin(struct mwSession *s);


/** send an announcement to a list of users/groups. Targets of
    announcement must be in the same community as the session.

    @param s          session to send announcement from
    @param may_reply  permit clients to reply. Not all clients honor this.
    @param text       text of announcement
    @param recipients list of recipients. Each recipient is specified
                      by a single string, prefix with "@U " for users
                      and "@G " for Notes Address Book groups.
*/
int mwSession_sendAnnounce(struct mwSession *s, gboolean may_reply,
			   const char *text, const GList *recipients);


/** set the internal privacy information, and inform the server as
    necessary. Triggers the on_setPrivacyInfo call-back. */
int mwSession_setPrivacyInfo(struct mwSession *, struct mwPrivacyInfo *);


/** direct reference to the session's internal privacy structure */
struct mwPrivacyInfo *mwSession_getPrivacyInfo(struct mwSession *);


/** reference the login information for the session */
struct mwLoginInfo *mwSession_getLoginInfo(struct mwSession *);


/** set the internal user status state, and inform the server as
    necessary. Triggers the on_setUserStatus call-back */
int mwSession_setUserStatus(struct mwSession *, struct mwUserStatus *);


struct mwUserStatus *mwSession_getUserStatus(struct mwSession *);


/** current status of the session */
enum mwSessionState mwSession_getState(struct mwSession *);


/** additional status-specific information. Depending on the state of
    the session, this value has different meaning.

    @li @c mwSession_STOPPING guint32 error code causing
    the session to shut down

    @li @c mwSession_STOPPED guint32 error code causing
    the session to shut down

    @li @c mwSession_LOGIN_REDIR (char *) host to redirect
    to
*/
gpointer mwSession_getStateInfo(struct mwSession *);


struct mwChannelSet *mwSession_getChannels(struct mwSession *);


/** adds a service to the session. If the session is started (or when
    the session is successfully started) and the service has a start
    function, the session will request service availability from the
    server. On receipt of the service availability notification, the
    session will call the service's start function.

    @return TRUE if the session was added correctly */
gboolean mwSession_addService(struct mwSession *, struct mwService *);


/** find a service by its type identifier */
struct mwService *mwSession_getService(struct mwSession *, guint32 type);


/** removes a service from the session. If the session is started and
    the service has a stop function, it will be called. Returns the
    removed service */
struct mwService *mwSession_removeService(struct mwSession *, guint32 type);


/** a GList of services in this session. The GList needs to be freed
    after use */
GList *mwSession_getServices(struct mwSession *);


/** instruct a STARTED session to check the server for the presense of
    a given service. The service will be automatically started upon
    receipt of an affirmative reply from the server. This function is
    automatically called upon all services in a session when the
    session is fully STARTED.

    Services which terminate due to an error may call this on
    themselves to re-initialize when their server-side counterpart is
    made available again.

    @param s     owning session
    @param type  service type ID */
void mwSession_senseService(struct mwSession *s, guint32 type);


/** adds a cipher to the session. */
gboolean mwSession_addCipher(struct mwSession *, struct mwCipher *);


/** find a cipher by its type identifier */
struct mwCipher *mwSession_getCipher(struct mwSession *, guint16 type);


/** remove a cipher from the session */
struct mwCipher *mwSession_removeCipher(struct mwSession *, guint16 type);


/** a GList of ciphers in this session. The GList needs to be freed
    after use */
GList *mwSession_getCiphers(struct mwSession *);


/** associate a key:value pair with the session. If an existing value is
    associated with the same key, it will have its clear function called
    and will be replaced with the new value */
void mwSession_setProperty(struct mwSession *, const char *key,
			   gpointer val, GDestroyNotify clear);


/** obtain the value of a previously set property, or NULL */
gpointer mwSession_getProperty(struct mwSession *, const char *key);


/** remove a property, calling the optional GDestroyNotify function
    indicated in mwSession_setProperty if applicable */
void mwSession_removeProperty(struct mwSession *, const char *key);


/** associate arbitrary data with the session for use by the client
    code. Only client applications should use this, never services.

    @param session  the session to associate the data with
    @param data     arbitrary client data
    @param clear    optional cleanup function called on data from
                    mwSession_removeClientData and mwSession_free
*/
void mwSession_setClientData(struct mwSession *session,
			     gpointer data, GDestroyNotify clear);


gpointer mwSession_getClientData(struct mwSession *session);


/** remove client data, calling the optional GDestroyNotify function
    indicated in mwSession_setClientData if applicable */
void mwSession_removeClientData(struct mwSession *session);


#ifdef __cplusplus
}
#endif


#endif /* _MW_SESSION_H */