File: mw_srvc_dir.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 (211 lines) | stat: -rw-r--r-- 5,948 bytes parent folder | download | duplicates (2)
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
/*
  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_DIR_H
#define _MW_SERV_DIR_H


#include <glib.h>


#ifdef __cplusplus
extern "C" {
#endif


struct mwSession;


#define SERVICE_DIRECTORY  0x0000001a


/** @struct mwServiceDirectory

    the directory service. */
struct mwServiceDirectory;


/** @struct mwAddressBook

    server-side collection of users and groups. Open a directory
    based on an address book to search or list its contents */
struct mwAddressBook;


/** @struct mwDirectory

    searchable directory, based off of an address book */
struct mwDirectory;


enum mwDirectoryState {
  mwDirectory_NEW,      /**< directory is created, but not open */
  mwDirectory_PENDING,  /**< directory has in the process of opening */
  mwDirectory_OPEN,     /**< directory is open */
  mwDirectory_ERROR,    /**< error opening or using directory */
  mwDirectory_UNKNOWN,  /**< error determining directory state */
};


/** return value of directory searches that fail */
#define DIR_SEARCH_ERROR  0x00000000


#define MW_DIRECTORY_IS_STATE(dir, state) \
  (mwDirectory_getState(dir) == (state))

#define MW_DIRECTORY_IS_NEW(dir) \
  MW_DIRECTORY_IS_STATE((dir), mwDirectory_NEW)

#define MW_DIRECTORY_IS_PENDING(dir) \
  MW_DIRECTORY_IS_STATE((dir), mwDirectory_PENDING)

#define MW_DIRECTORY_IS_OPEN(dir) \
  MW_DIRECTORY_IS_STATE((dir), mwDirectory_OPEN)


enum mwDirectoryMemberType {
  mwDirectoryMember_USER   = 0x0000,
  mwDirectoryMember_GROUP  = 0x0001,
};


struct mwDirectoryMember {
  guint16 type;      /**< @see mwDirectoryMemberType */
  char *id;          /**< proper ID for member */
  char *long_name;   /**< full name of member (USER type only) */
  char *short_name;  /**< short name of member */
  guint16 foo;       /**< unknown */
};


/** Appropriate function signature for handling directory search results */
typedef void (*mwSearchHandler)
     (struct mwDirectory *dir,
      guint32 code, guint32 offset, GList *members);


/** handles asynchronous events for a directory service instance */
struct mwDirectoryHandler {

  /** handle receipt of the address book list from the service.
      Initially triggered by mwServiceDirectory_refreshAddressBooks
      and at service startup */
  void (*on_book_list)(struct mwServiceDirectory *srvc, GList *books);

  /** triggered when a directory has been successfully opened */
  void (*dir_opened)(struct mwDirectory *dir);

  /** triggered when a directory has been closed */
  void (*dir_closed)(struct mwDirectory *dir, guint32 reason);

  /** optional. called from mwService_free */
  void (*clear)(struct mwServiceDirectory *srvc);
};


/** Allocate a new directory service instance for use with session */
struct mwServiceDirectory *
mwServiceDirectory_new(struct mwSession *session,
		       struct mwDirectoryHandler *handler);


/** the handler associated with the service at its creation */
struct mwDirectoryHandler *
mwServiceDirectory_getHandler(struct mwServiceDirectory *srvc);


/** most recent list of address books available in service */
GList *mwServiceDirectory_getAddressBooks(struct mwServiceDirectory *srvc);


/** submit a request to obtain an updated list of address books from
    service */
int mwServiceDirectory_refreshAddressBooks(struct mwServiceDirectory *srvc);


/** list of directories in the service */
GList *mwServiceDirectory_getDirectories(struct mwServiceDirectory *srvc);


/** list of directories associated with address book. Note that the
    returned GList will need to be free'd after use */
GList *mwAddressBook_getDirectories(struct mwAddressBook *book);


/** the name of the address book */
const char *mwAddressBook_getName(struct mwAddressBook *book);


/** allocate a new directory based off the given address book */
struct mwDirectory *mwDirectory_new(struct mwAddressBook *book);


enum mwDirectoryState mwDirectory_getState(struct mwDirectory *dir);


/** set client data. If there is an existing clear function, it will
    not be called */
void mwDirectory_setClientData(struct mwDirectory *dir,
			       gpointer data, GDestroyNotify clear);


/** reference associated client data */
gpointer mwDirectory_getClientData(struct mwDirectory *dir);


/** remove and cleanup user data */
void mwDirectory_removeClientData(struct mwDirectory *dir);


/** reference owning service */
struct mwServiceDirectory *mwDirectory_getService(struct mwDirectory *dir);


/** reference owning address book */
struct mwAddressBook *mwDirectory_getAddressBook(struct mwDirectory *dir);


/** initialize a directory. */
int mwDirectory_open(struct mwDirectory *dir, mwSearchHandler cb);


/** continue a search into its next results */
int mwDirectory_next(struct mwDirectory *dir);


/** continue a search into its previous results */
int mwDirectory_previous(struct mwDirectory *dir);


/** initiate a search on an open directory */
int mwDirectory_search(struct mwDirectory *dir, const char *query);


/** close and free the directory, and unassociate it with its owning
    address book and service */
int mwDirectory_destroy(struct mwDirectory *dir);


#ifdef __cplusplus
}
#endif


#endif /* _MW_SRVC_DIR_H */