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_SRVC_RESOLVE_H 22 #define _MW_SRVC_RESOLVE_H 23 24 25 #include <glib.h> 26 #include <glib.h> 27 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 34 /** Type identifier for the conference service */ 35 #define mwService_RESOLVE 0x00000015 36 37 38 /** Return value of mwServiceResolve_search indicating an error */ 39 #define SEARCH_ERROR 0x00 40 41 42 /** @struct mwServiceResolve 43 User lookup service */ 44 struct mwServiceResolve; 45 46 47 enum mwResolveFlag { 48 /** return unique results or none at all */ 49 mwResolveFlag_UNIQUE = 0x00000001, 50 51 /** return only the first result */ 52 mwResolveFlag_FIRST = 0x00000002, 53 54 /** search all directories, not just the first with a match */ 55 mwResolveFlag_ALL_DIRS = 0x00000004, 56 57 /** search for users */ 58 mwResolveFlag_USERS = 0x00000008, 59 60 /** search for groups */ 61 mwResolveFlag_GROUPS = 0x00000010, 62 }; 63 64 65 /** @see mwResolveResult */ 66 enum mwResolveCode { 67 /** successful search */ 68 mwResolveCode_SUCCESS = 0x00000000, 69 70 /** only some of the nested searches were successful */ 71 mwResolveCode_PARTIAL = 0x00010000, 72 73 /** more than one result (occurs when mwResolveFlag_UNIQUE is used 74 and more than one result would have been otherwise returned) */ 75 mwResolveCode_MULTIPLE = 0x80020000, 76 77 /** the name is not resolvable due to its format */ 78 mwResolveCode_BAD_FORMAT = 0x80030000, 79 }; 80 81 82 enum mwResolveMatchType { 83 mwResolveMatch_USER = 0x00000001, 84 mwResolveMatch_GROUP = 0x00000002, 85 }; 86 87 88 struct mwResolveMatch { 89 char *id; /**< user id */ 90 char *name; /**< user name */ 91 char *desc; /**< description */ 92 guint32 type; /**< @see mwResolveMatchType */ 93 }; 94 95 96 struct mwResolveResult { 97 guint32 code; /**< @see mwResolveCode */ 98 char *name; /**< name of the result */ 99 GList *matches; /**< list of mwResolveMatch */ 100 }; 101 102 103 /** Handle the results of a resolve request. If there was a cleanup 104 function specified to mwServiceResolve_search, it will be called 105 upon the user data after this callback returns. 106 107 @param srvc the resolve service 108 @param id the resolve request ID 109 @param code return code 110 @param results list of mwResolveResult 111 @param data optional user data attached to the request 112 */ 113 typedef void (*mwResolveHandler) 114 (struct mwServiceResolve *srvc, 115 guint32 id, guint32 code, GList *results, 116 gpointer data); 117 118 119 /** Allocate a new resolve service */ 120 struct mwServiceResolve *mwServiceResolve_new(struct mwSession *); 121 122 123 /** Inisitate a resolve request. 124 125 @param srvc the resolve service 126 @param queries list query strings 127 @param flags search flags 128 @param handler result handling function 129 @param data optional user data attached to the request 130 @param cleanup optional function to clean up user data 131 @return generated ID for the search request, or SEARCH_ERROR 132 */ 133 guint32 mwServiceResolve_resolve(struct mwServiceResolve *srvc, 134 GList *queries, enum mwResolveFlag flags, 135 mwResolveHandler handler, 136 gpointer data, GDestroyNotify cleanup); 137 138 139 /** Cancel a resolve request by its generated ID. The handler function 140 will not be called, and the optional cleanup function will be 141 called upon the optional user data for the request */ 142 void mwServiceResolve_cancelResolve(struct mwServiceResolve *, guint32); 143 144 145 #ifdef __cplusplus 146 } 147 #endif 148 149 150 #endif /* _MW_SRVC_RESOLVE_H */ 151