meanwhile  1.0.2
mw_session.h
Go to the documentation of this file.
1 
2 /*
3  Meanwhile - Unofficial Lotus Sametime Community Client Library
4  Copyright (C) 2004 Christopher (siege) O'Brien
5 
6  This library is free software; you can redistribute it and/or
7  modify it under the terms of the GNU Library General Public
8  License as published by the Free Software Foundation; either
9  version 2 of the License, or (at your option) any later version.
10 
11  This library is distributed in the hope that it will be useful,
12  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  Library General Public License for more details.
15 
16  You should have received a copy of the GNU Library General Public
17  License along with this library; if not, write to the Free
18  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 */
20 
21 #ifndef _MW_SESSION_H
22 #define _MW_SESSION_H
23 
24 
47 #include "mw_common.h"
48 
49 
50 #ifdef __cplusplus
51 extern "C" {
52 #endif
53 
54 
55 struct mwChannelSet;
56 struct mwCipher;
57 struct mwMessage;
58 struct mwService;
59 
60 
62 #define MW_PROTOCOL_VERSION_MAJOR 0x001e
63 
64 
66 #define MW_PROTOCOL_VERSION_MINOR 0x001d
67 
68 
73 
75 #define mwSession_AUTH_USER_ID "session.auth.user"
76 
78 #define mwSession_AUTH_PASSWORD "session.auth.password"
79 
81 #define mwSession_AUTH_TOKEN "session.auth.token"
82 
84 #define mwSession_CLIENT_HOST "client.host"
85 
87 #define mwSession_CLIENT_IP "client.ip"
88 
90 #define mwSession_CLIENT_VER_MAJOR "client.version.major"
91 
93 #define mwSession_CLIENT_VER_MINOR "client.version.minor"
94 
96 #define mwSession_CLIENT_TYPE_ID "client.id"
97 
99 #define mwSession_SERVER_VER_MAJOR "server.version.major"
100 
102 #define mwSession_SERVER_VER_MINOR "server.version.minor"
103 
119 };
120 
121 
122 #define mwSession_isState(session, state) \
123  (mwSession_getState((session)) == (state))
124 
125 #define mwSession_isStarting(s) \
126  (mwSession_isState((s), mwSession_STARTING) || \
127  mwSession_isState((s), mwSession_HANDSHAKE) || \
128  mwSession_isState((s), mwSession_HANDSHAKE_ACK) || \
129  mwSession_isState((s), mwSession_LOGIN) || \
130  mwSession_isState((s), mwSession_LOGIN_ACK) || \
131  mwSession_isState((s), mwSession_LOGIN_REDIR) || \
132  mwSession_isState((s), mwSession_LOGIN_CONT))
133 
134 #define mwSession_isStarted(s) \
135  (mwSession_isState((s), mwSession_STARTED))
136 
137 #define mwSession_isStopping(s) \
138  (mwSession_isState((s), mwSession_STOPPING))
139 
140 #define mwSession_isStopped(s) \
141  (mwSession_isState((s), mwSession_STOPPED))
142 
143 
147 struct mwSession;
148 
149 
155 
158  int (*io_write)(struct mwSession *, const guchar *buf, gsize len);
159 
161  void (*io_close)(struct mwSession *);
162 
164  void (*clear)(struct mwSession *);
165 
173  void (*on_stateChange)(struct mwSession *s,
174  enum mwSessionState state, gpointer info);
175 
180  void (*on_setPrivacyInfo)(struct mwSession *);
181 
185  void (*on_setUserStatus)(struct mwSession *);
186 
188  void (*on_admin)(struct mwSession *, const char *text);
189 
191  void (*on_announce)(struct mwSession *, struct mwLoginInfo *from,
192  gboolean may_reply, const char *text);
193 
194 };
195 
196 
198 struct mwSession *mwSession_new(struct mwSessionHandler *);
199 
200 
203 void mwSession_free(struct mwSession *);
204 
205 
208 
209 
212 void mwSession_start(struct mwSession *);
213 
214 
217 void mwSession_stop(struct mwSession *, guint32 reason);
218 
219 
222 void mwSession_recv(struct mwSession *, const guchar *, gsize);
223 
224 
229 int mwSession_send(struct mwSession *s, struct mwMessage *msg);
230 
231 
233 int mwSession_sendKeepalive(struct mwSession *s);
234 
235 
238 int mwSession_forceLogin(struct mwSession *s);
239 
240 
251 int mwSession_sendAnnounce(struct mwSession *s, gboolean may_reply,
252  const char *text, const GList *recipients);
253 
254 
257 int mwSession_setPrivacyInfo(struct mwSession *, struct mwPrivacyInfo *);
258 
259 
262 
263 
266 
267 
270 int mwSession_setUserStatus(struct mwSession *, struct mwUserStatus *);
271 
272 
274 
275 
278 
279 
292 gpointer mwSession_getStateInfo(struct mwSession *);
293 
294 
296 
297 
305 gboolean mwSession_addService(struct mwSession *, struct mwService *);
306 
307 
309 struct mwService *mwSession_getService(struct mwSession *, guint32 type);
310 
311 
315 struct mwService *mwSession_removeService(struct mwSession *, guint32 type);
316 
317 
320 GList *mwSession_getServices(struct mwSession *);
321 
322 
335 void mwSession_senseService(struct mwSession *s, guint32 type);
336 
337 
339 gboolean mwSession_addCipher(struct mwSession *, struct mwCipher *);
340 
341 
343 struct mwCipher *mwSession_getCipher(struct mwSession *, guint16 type);
344 
345 
347 struct mwCipher *mwSession_removeCipher(struct mwSession *, guint16 type);
348 
349 
352 GList *mwSession_getCiphers(struct mwSession *);
353 
354 
358 void mwSession_setProperty(struct mwSession *, const char *key,
359  gpointer val, GDestroyNotify clear);
360 
361 
363 gpointer mwSession_getProperty(struct mwSession *, const char *key);
364 
365 
368 void mwSession_removeProperty(struct mwSession *, const char *key);
369 
370 
380  gpointer data, GDestroyNotify clear);
381 
382 
383 gpointer mwSession_getClientData(struct mwSession *session);
384 
385 
389 
390 
391 #ifdef __cplusplus
392 }
393 #endif
394 
395 
396 #endif /* _MW_SESSION_H */
397 
Definition: mw_common.h:123
session is stopped
Definition: mw_session.h:116
void mwSession_setProperty(struct mwSession *, const char *key, gpointer val, GDestroyNotify clear)
associate a key:value pair with the session.
struct mwCipher * mwSession_getCipher(struct mwSession *, guint16 type)
find a cipher by its type identifier
void(* on_setPrivacyInfo)(struct mwSession *)
called when privacy information has been sent or received
Definition: mw_session.h:180
indicates an error determining state
Definition: mw_session.h:117
session is starting
Definition: mw_session.h:108
struct mwSession * session
service this cipher is providing for
Definition: mw_cipher.h:74
void mwSession_start(struct mwSession *)
instruct the session to begin.
void mwSession_removeClientData(struct mwSession *session)
remove client data, calling the optional GDestroyNotify function indicated in mwSession_setClientData...
void mwSession_setClientData(struct mwSession *session, gpointer data, GDestroyNotify clear)
associate arbitrary data with the session for use by the client code.
session has received login ack
Definition: mw_session.h:113
struct mwCipher * mwSession_removeCipher(struct mwSession *, guint16 type)
remove a cipher from the session
void mwSession_recv(struct mwSession *, const guchar *, gsize)
Data is buffered, unpacked, and parsed into a message, then processed accordingly.
session is shutting down
Definition: mw_session.h:115
void(* clear)(struct mwSession *)
triggered by mwSession_free.
Definition: mw_session.h:164
gpointer mwSession_getStateInfo(struct mwSession *)
additional status-specific information.
struct mwSession * mwSession_new(struct mwSessionHandler *)
allocate a new session
void mwSession_removeProperty(struct mwSession *, const char *key)
remove a property, calling the optional GDestroyNotify function indicated in mwSession_setProperty if...
Collection of channels.
Definition: mw_channel.h:101
GList * mwSession_getCiphers(struct mwSession *)
a GList of ciphers in this session.
gboolean mwSession_addService(struct mwSession *, struct mwService *)
adds a service to the session.
guint32 type
the unique identifier by which this service is registered.
Definition: mw_service.h:128
GList * mwSession_getServices(struct mwSession *)
a GList of services in this session.
int mwSession_setPrivacyInfo(struct mwSession *, struct mwPrivacyInfo *)
set the internal privacy information, and inform the server as necessary.
gpointer mwSession_getProperty(struct mwSession *, const char *key)
obtain the value of a previously set property, or NULL
session is active
Definition: mw_session.h:114
int mwSession_setUserStatus(struct mwSession *, struct mwUserStatus *)
set the internal user status state, and inform the server as necessary.
Represents a Sametime client session.
A cipher.
Definition: mw_cipher.h:70
void(* on_admin)(struct mwSession *, const char *text)
called when an admin messages has been received
Definition: mw_session.h:188
void(* on_announce)(struct mwSession *, struct mwLoginInfo *from, gboolean may_reply, const char *text)
called when an announcement arrives
Definition: mw_session.h:191
struct mwService * mwSession_getService(struct mwSession *, guint32 type)
find a service by its type identifier
gboolean mwSession_addCipher(struct mwSession *, struct mwCipher *)
adds a cipher to the session.
Common data types and functions for handling those types.
void mwSession_senseService(struct mwSession *s, guint32 type)
instruct a STARTED session to check the server for the presense of a given service.
struct mwLoginInfo * mwSession_getLoginInfo(struct mwSession *)
reference the login information for the session
session has sent handshake
Definition: mw_session.h:109
A service is the recipient of sendOnCnl messages sent over channels marked with the corresponding ser...
Definition: mw_service.h:123
session has sent login
Definition: mw_session.h:111
void mwSession_free(struct mwSession *)
stop, clear, free a session.
struct mwPrivacyInfo * mwSession_getPrivacyInfo(struct mwSession *)
direct reference to the session's internal privacy structure
struct mwSessionHandler * mwSession_getHandler(struct mwSession *)
obtain a reference to the session's handler
session handler.
Definition: mw_session.h:154
void(* on_stateChange)(struct mwSession *s, enum mwSessionState state, gpointer info)
Called when the session has changed status.
Definition: mw_session.h:173
void mwSession_stop(struct mwSession *, guint32 reason)
instruct the session to shut down with the following reason code.
session has been redirected
Definition: mw_session.h:112
void(* io_close)(struct mwSession *)
close the server connection.
Definition: mw_session.h:161
Definition: mw_common.h:165
guint16 type
Definition: mw_cipher.h:76
gpointer mwSession_getClientData(struct mwSession *session)
int mwSession_sendKeepalive(struct mwSession *s)
sends the keepalive byte
Definition: mw_common.h:146
mwSessionState
Definition: mw_session.h:107
struct mwUserStatus * mwSession_getUserStatus(struct mwSession *)
int(* io_write)(struct mwSession *, const guchar *buf, gsize len)
write data to the server connection.
Definition: mw_session.h:158
struct mwService * mwSession_removeService(struct mwSession *, guint32 type)
removes a service from the session.
session has sent a login continue
Definition: mw_session.h:118
session has received handshake ack
Definition: mw_session.h:110
int mwSession_sendAnnounce(struct mwSession *s, gboolean may_reply, const char *text, const GList *recipients)
send an announcement to a list of users/groups.
enum mwSessionState mwSession_getState(struct mwSession *)
current status of the session
void(* on_setUserStatus)(struct mwSession *)
called when user status has changed
Definition: mw_session.h:185
int mwSession_forceLogin(struct mwSession *s)
respond to a login redirect message by forcing the login sequence to continue through the immediate s...
struct mwChannelSet * mwSession_getChannels(struct mwSession *)
Definition: mw_message.h:72
int mwSession_send(struct mwSession *s, struct mwMessage *msg)
primarily used by services to have messages serialized and sent