File: mw_srvc_aware.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 (279 lines) | stat: -rw-r--r-- 7,876 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

/*
  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_SRVC_AWARE_H
#define _MW_SRVC_AWARE_H


/** @file mw_srvc_aware.h

    The aware service...

    @todo remove the whole idea of an instantiated mwAwareList and
    instead use arbitrary pointers (including NULL) as keys to
    internally stored lists. This removes the problem of the service
    free'ing its lists and invalidating mwAwareList references from
    client code.
*/


#include "mw_common.h"


#ifdef __cplusplus
extern "C" {
#endif


/** Type identifier for the aware service */
#define mwService_AWARE  0x00000011


/** @struct mwServiceAware

    Instance of an Aware Service. The members of this structure are
    not made available. Accessing the parts of an aware service should
    be performed through the appropriate functions. Note that
    instances of this structure can be safely cast to a mwService.
*/
struct mwServiceAware;


/** @struct mwAwareList

    Instance of an Aware List. The members of this structure are not
    made available. Access to the parts of an aware list should be
    handled through the appropriate functions.

    Any references to an aware list are rendered invalid when the
    parent service is free'd
*/
struct mwAwareList;


/** @struct mwAwareAttribute

    Key/Opaque pair indicating an identity's attribute.
 */
struct mwAwareAttribute;


/** Predefined keys appropriate for a mwAwareAttribute
 */
enum mwAwareAttributeKeys {
  mwAttribute_AV_PREFS_SET   = 0x01, /**< A/V prefs specified, gboolean */
  mwAttribute_MICROPHONE     = 0x02, /**< has a microphone, gboolean */
  mwAttribute_SPEAKERS       = 0x03, /**< has speakers, gboolean */
  mwAttribute_VIDEO_CAMERA   = 0x04, /**< has a video camera, gboolean */
  mwAttribute_FILE_TRANSFER  = 0x06, /**< supports file transfers, gboolean */
};


typedef void (*mwAwareAttributeHandler)
     (struct mwServiceAware *srvc,
      struct mwAwareAttribute *attrib);


struct mwAwareHandler {
  mwAwareAttributeHandler on_attrib;
  void (*clear)(struct mwServiceAware *srvc);
};


/** Appropriate function type for the on-aware signal

    @param list  mwAwareList emiting the signal
    @param id    awareness status information
    @param data  user-specified data
*/
typedef void (*mwAwareSnapshotHandler)
     (struct mwAwareList *list,
      struct mwAwareSnapshot *id);


/** Appropriate function type for the on-option signal. The option's
    value may need to be explicitly loaded in some instances,
    resulting in this handler being triggered again.

    @param list    mwAwareList emiting the signal
    @param id      awareness the attribute belongs to
    @param attrib  attribute
*/
typedef void (*mwAwareIdAttributeHandler)
     (struct mwAwareList *list,
      struct mwAwareIdBlock *id,
      struct mwAwareAttribute *attrib);


struct mwAwareListHandler {
  /** handle aware updates */
  mwAwareSnapshotHandler on_aware;

  /** handle attribute updates */
  mwAwareIdAttributeHandler on_attrib;

  /** optional. Called from mwAwareList_free */
  void (*clear)(struct mwAwareList *list);
};


struct mwServiceAware *
mwServiceAware_new(struct mwSession *session,
		   struct mwAwareHandler *handler);


/** Set an attribute value for this session */
int mwServiceAware_setAttribute(struct mwServiceAware *srvc,
				guint32 key, struct mwOpaque *opaque);


int mwServiceAware_setAttributeBoolean(struct mwServiceAware *srvc,
				       guint32 key, gboolean val);


int mwServiceAware_setAttributeInteger(struct mwServiceAware *srvc,
				       guint32 key, guint32 val);


int mwServiceAware_setAttributeString(struct mwServiceAware *srvc,
				      guint32 key, const char *str);


/** Unset an attribute for this session */
int mwServiceAware_unsetAttribute(struct mwServiceAware *srvc,
				  guint32 key);


guint32 mwAwareAttribute_getKey(const struct mwAwareAttribute *attrib);


gboolean mwAwareAttribute_asBoolean(const struct mwAwareAttribute *attrib);


guint32 mwAwareAttribute_asInteger(const struct mwAwareAttribute *attrib);


/** Copy of attribute string, must be g_free'd. If the attribute's
    content cannot be loaded as a string, returns NULL */
char *mwAwareAttribute_asString(const struct mwAwareAttribute *attrib);


/** Direct access to an attribute's underlying opaque */
const struct mwOpaque *
mwAwareAttribute_asOpaque(const struct mwAwareAttribute *attrib);


/** Allocate and initialize an aware list */
struct mwAwareList *
mwAwareList_new(struct mwServiceAware *srvc,
		struct mwAwareListHandler *handler);


/** Clean and free an aware list */
void mwAwareList_free(struct mwAwareList *list);


struct mwAwareListHandler *mwAwareList_getHandler(struct mwAwareList *list);


/** Add a collection of user IDs to an aware list.
    @param list     mwAwareList to add user ID to
    @param id_list  mwAwareIdBlock list of user IDs to add
    @return         0 for success, non-zero to indicate an error.
*/
int mwAwareList_addAware(struct mwAwareList *list, GList *id_list);


/** Remove a collection of user IDs from an aware list.
    @param list     mwAwareList to remove user ID from
    @param id_list  mwAwareIdBlock list of user IDs to remove
    @return  0      for success, non-zero to indicate an error.
*/
int mwAwareList_removeAware(struct mwAwareList *list, GList *id_list);


int mwAwareList_removeAllAware(struct mwAwareList *list);


/** watch an NULL terminated array of keys */
int mwAwareList_watchAttributeArray(struct mwAwareList *list,
				    guint32 *keys);


/** watch a NULL terminated list of keys */
int mwAwareList_watchAttributes(struct mwAwareList *list,
				guint32 key, ...);


/** stop watching a NULL terminated array of keys */
int mwAwareList_unwatchAttributeArray(struct mwAwareList *list,
				      guint32 *keys);


/** stop watching a NULL terminated list of keys */
int mwAwareList_unwatchAttributes(struct mwAwareList *list,
				  guint32 key, ...);


/** remove all watched attributes */
int mwAwareList_unwatchAllAttributes(struct mwAwareList *list);


guint32 *mwAwareList_getWatchedAttributes(struct mwAwareList *list);


void mwAwareList_setClientData(struct mwAwareList *list,
			       gpointer data, GDestroyNotify cleanup);


void mwAwareList_removeClientData(struct mwAwareList *list);


gpointer mwAwareList_getClientData(struct mwAwareList *list);


/** trigger a got_aware event constructed from the passed user and
    status information. Useful for adding false users and having the
    getText function work for them */
void mwServiceAware_setStatus(struct mwServiceAware *srvc,
			      struct mwAwareIdBlock *user,
			      struct mwUserStatus *stat);


/** look up the status description for a user */
const char *mwServiceAware_getText(struct mwServiceAware *srvc,
				   struct mwAwareIdBlock *user);


/** look up the last known copy of an attribute for a user by the
    attribute's key */
const struct mwAwareAttribute *
mwServiceAware_getAttribute(struct mwServiceAware *srvc,
			    struct mwAwareIdBlock *user,
			    guint32 key);


#ifdef __cplusplus
}
#endif


#endif /* _MW_SRVC_AWARE_H */