10969
|
1 /*
|
|
2 Meanwhile - Unofficial Lotus Sametime Community Client Library
|
|
3 Copyright (C) 2004 Christopher (siege) O'Brien
|
|
4
|
|
5 This library is free software; you can redistribute it and/or
|
|
6 modify it under the terms of the GNU Library General Public
|
|
7 License as published by the Free Software Foundation; either
|
|
8 version 2 of the License, or (at your option) any later version.
|
|
9
|
|
10 This library is distributed in the hope that it will be useful,
|
|
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
13 Library General Public License for more details.
|
|
14
|
|
15 You should have received a copy of the GNU Library General Public
|
|
16 License along with this library; if not, write to the Free
|
|
17 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
18 */
|
|
19
|
|
20 #ifndef _MW_SRVC_DIR_H
|
|
21 #define _MW_SERV_DIR_H
|
|
22
|
|
23
|
|
24 #include <glib.h>
|
|
25 #include <glib/glist.h>
|
|
26
|
|
27
|
|
28 struct mwSession;
|
|
29
|
|
30
|
|
31 #define SERVICE_DIRECTORY 0x0000001a
|
|
32
|
|
33
|
|
34 /** @struct mwServiceDirectory
|
|
35
|
|
36 the directory service. */
|
|
37 struct mwServiceDirectory;
|
|
38
|
|
39
|
|
40 /** @struct mwAddressBook
|
|
41
|
|
42 server-side collection of users and groups. Open a directory
|
|
43 based on an address book to search or list its contents */
|
|
44 struct mwAddressBook;
|
|
45
|
|
46
|
|
47 /** @struct mwDirectory
|
|
48
|
|
49 searchable directory, based off of an address book */
|
|
50 struct mwDirectory;
|
|
51
|
|
52
|
|
53 enum mwDirectoryState {
|
|
54 mwDirectory_NEW, /**< directory is created, but not open */
|
|
55 mwDirectory_PENDING, /**< directory has in the process of opening */
|
|
56 mwDirectory_OPEN, /**< directory is open */
|
|
57 mwDirectory_ERROR, /**< error opening or using directory */
|
|
58 mwDirectory_UNKNOWN, /**< error determining directory state */
|
|
59 };
|
|
60
|
|
61
|
|
62 /** return value of directory searches that fail */
|
|
63 #define DIR_SEARCH_ERROR 0x00000000
|
|
64
|
|
65
|
|
66 #define MW_DIRECTORY_IS_STATE(dir, state) \
|
|
67 (mwDirectory_getState(dir) == (state))
|
|
68
|
|
69 #define MW_DIRECTORY_IS_NEW(dir) \
|
|
70 MW_DIRECTORY_IS_STATE((dir), mwDirectory_NEW)
|
|
71
|
|
72 #define MW_DIRECTORY_IS_PENDING(dir) \
|
|
73 MW_DIRECTORY_IS_STATE((dir), mwDirectory_PENDING)
|
|
74
|
|
75 #define MW_DIRECTORY_IS_OPEN(dir) \
|
|
76 MW_DIRECTORY_IS_STATE((dir), mwDirectory_OPEN)
|
|
77
|
|
78
|
|
79 enum mwDirectoryMemberType {
|
|
80 mwDirectoryMember_USER = 0x0000,
|
|
81 mwDirectoryMember_GROUP = 0x0001,
|
|
82 };
|
|
83
|
|
84
|
|
85 struct mwDirectoryMember {
|
|
86 guint16 type; /**< @see mwDirectoryMemberType */
|
|
87 char *id; /**< proper ID for member */
|
|
88 char *long_name; /**< full name of member (USER type only) */
|
|
89 char *short_name; /**< short name of member */
|
|
90 guint16 foo; /**< unknown */
|
|
91 };
|
|
92
|
|
93
|
|
94 /** Appropriate function signature for handling directory search results */
|
|
95 typedef void (*mwSearchHandler)
|
|
96 (struct mwDirectory *dir,
|
|
97 guint32 code, guint32 offset, GList *members);
|
|
98
|
|
99
|
|
100 /** handles asynchronous events for a directory service instance */
|
|
101 struct mwDirectoryHandler {
|
|
102
|
|
103 /** handle receipt of the address book list from the service.
|
|
104 Initially triggered by mwServiceDirectory_refreshAddressBooks
|
|
105 and at service startup */
|
|
106 void (*on_book_list)(struct mwServiceDirectory *srvc, GList *books);
|
|
107
|
|
108 /** triggered when a directory has been successfully opened */
|
|
109 void (*dir_opened)(struct mwDirectory *dir);
|
|
110
|
|
111 /** triggered when a directory has been closed */
|
|
112 void (*dir_closed)(struct mwDirectory *dir, guint32 reason);
|
|
113
|
|
114 /** optional. called from mwService_free */
|
|
115 void (*clear)(struct mwServiceDirectory *srvc);
|
|
116 };
|
|
117
|
|
118
|
|
119 /** Allocate a new directory service instance for use with session */
|
|
120 struct mwServiceDirectory *
|
|
121 mwServiceDirectory_new(struct mwSession *session,
|
|
122 struct mwDirectoryHandler *handler);
|
|
123
|
|
124
|
|
125 /** the handler associated with the service at its creation */
|
|
126 struct mwDirectoryHandler *
|
|
127 mwServiceDirectory_getHandler(struct mwServiceDirectory *srvc);
|
|
128
|
|
129
|
|
130 /** most recent list of address books available in service */
|
|
131 GList *mwServiceDirectory_getAddressBooks(struct mwServiceDirectory *srvc);
|
|
132
|
|
133
|
|
134 /** submit a request to obtain an updated list of address books from
|
|
135 service */
|
|
136 int mwServiceDirectory_refreshAddressBooks(struct mwServiceDirectory *srvc);
|
|
137
|
|
138
|
|
139 /** list of directories in the service */
|
|
140 GList *mwServiceDirectory_getDirectories(struct mwServiceDirectory *srvc);
|
|
141
|
|
142
|
|
143 /** list of directories associated with address book. Note that the
|
|
144 returned GList will need to be free'd after use */
|
|
145 GList *mwAddressBook_getDirectories(struct mwAddressBook *book);
|
|
146
|
|
147
|
|
148 /** the name of the address book */
|
|
149 const char *mwAddressBook_getName(struct mwAddressBook *book);
|
|
150
|
|
151
|
|
152 /** allocate a new directory based off the given address book */
|
|
153 struct mwDirectory *mwDirectory_new(struct mwAddressBook *book);
|
|
154
|
|
155
|
|
156 enum mwDirectoryState mwDirectory_getState(struct mwDirectory *dir);
|
|
157
|
|
158
|
|
159 /** set client data. If there is an existing clear function, it will
|
|
160 not be called */
|
|
161 void mwDirectory_setClientData(struct mwDirectory *dir,
|
|
162 gpointer data, GDestroyNotify clear);
|
|
163
|
|
164
|
|
165 /** reference associated client data */
|
|
166 gpointer mwDirectory_getClientData(struct mwDirectory *dir);
|
|
167
|
|
168
|
|
169 /** remove and cleanup user data */
|
|
170 void mwDirectory_removeClientData(struct mwDirectory *dir);
|
|
171
|
|
172
|
|
173 /** reference owning service */
|
|
174 struct mwServiceDirectory *mwDirectory_getService(struct mwDirectory *dir);
|
|
175
|
|
176
|
|
177 /** reference owning address book */
|
|
178 struct mwAddressBook *mwDirectory_getAddressBook(struct mwDirectory *dir);
|
|
179
|
|
180
|
|
181 /** initialize a directory. */
|
|
182 int mwDirectory_open(struct mwDirectory *dir, mwSearchHandler cb);
|
|
183
|
|
184
|
|
185 /** continue a search into its next results */
|
|
186 int mwDirectory_next(struct mwDirectory *dir);
|
|
187
|
|
188
|
|
189 /** continue a search into its previous results */
|
|
190 int mwDirectory_previous(struct mwDirectory *dir);
|
|
191
|
|
192
|
|
193 /** initiate a search on an open directory */
|
|
194 int mwDirectory_search(struct mwDirectory *dir, const char *query);
|
|
195
|
|
196
|
|
197 /** close and free the directory, and unassociate it with its owning
|
|
198 address book and service */
|
|
199 int mwDirectory_destroy(struct mwDirectory *dir);
|
|
200
|
|
201
|
|
202 #endif
|