/*
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_RESOLVE_H
#define _MW_SRVC_RESOLVE_H
#include <glib.h>
#include <glib/glist.h>
#ifdef __cplusplus
extern "C" {
#endif
/** Type identifier for the conference service */
#define mwService_RESOLVE 0x00000015
/** Return value of mwServiceResolve_search indicating an error */
#define SEARCH_ERROR 0x00
/** @struct mwServiceResolve
User lookup service */
struct mwServiceResolve;
enum mwResolveFlag {
/** return unique results or none at all */
mwResolveFlag_UNIQUE = 0x00000001,
/** return only the first result */
mwResolveFlag_FIRST = 0x00000002,
/** search all directories, not just the first with a match */
mwResolveFlag_ALL_DIRS = 0x00000004,
/** search for users */
mwResolveFlag_USERS = 0x00000008,
/** search for groups */
mwResolveFlag_GROUPS = 0x00000010,
};
/** @see mwResolveResult */
enum mwResolveCode {
/** successful search */
mwResolveCode_SUCCESS = 0x00000000,
/** only some of the nested searches were successful */
mwResolveCode_PARTIAL = 0x00010000,
/** more than one result (occurs when mwResolveFlag_UNIQUE is used
and more than one result would have been otherwise returned) */
mwResolveCode_MULTIPLE = 0x80020000,
/** the name is not resolvable due to its format */
mwResolveCode_BAD_FORMAT = 0x80030000,
};
enum mwResolveMatchType {
mwResolveMatch_USER = 0x00000001,
mwResolveMatch_GROUP = 0x00000002,
};
struct mwResolveMatch {
char *id; /**< user id */
char *name; /**< user name */
char *desc; /**< description */
guint32 type; /**< @see mwResolveMatchType */
};
struct mwResolveResult {
guint32 code; /**< @see mwResolveCode */
char *name; /**< name of the result */
GList *matches; /**< list of mwResolveMatch */
};
/** Handle the results of a resolve request. If there was a cleanup
function specified to mwServiceResolve_search, it will be called
upon the user data after this callback returns.
@param srvc the resolve service
@param id the resolve request ID
@param code return code
@param results list of mwResolveResult
@param data optional user data attached to the request
*/
typedef void (*mwResolveHandler)
(struct mwServiceResolve *srvc,
guint32 id, guint32 code, GList *results,
gpointer data);
/** Allocate a new resolve service */
struct mwServiceResolve *mwServiceResolve_new(struct mwSession *);
/** Inisitate a resolve request.
@param srvc the resolve service
@param queries list query strings
@param flags search flags
@param handler result handling function
@param data optional user data attached to the request
@param cleanup optional function to clean up user data
@return generated ID for the search request, or SEARCH_ERROR
*/
guint32 mwServiceResolve_resolve(struct mwServiceResolve *srvc,
GList *queries, enum mwResolveFlag flags,
mwResolveHandler handler,
gpointer data, GDestroyNotify cleanup);
/** Cancel a resolve request by its generated ID. The handler function
will not be called, and the optional cleanup function will be
called upon the optional user data for the request */
void mwServiceResolve_cancelResolve(struct mwServiceResolve *, guint32);
#ifdef __cplusplus
}
#endif
#endif /* _MW_SRVC_RESOLVE_H */