diff src/protocols/sametime/meanwhile/mw_srvc_resolve.h @ 10969:3ef77720e577

[gaim-migrate @ 12790] importing meanwhile library for use in the sametime plugin committer: Tailor Script <[e-mail]>

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/protocols/sametime/meanwhile/mw_srvc_resolve.h	Sun Jun 05 02:50:13 2005 +0000
@@ -0,0 +1,139 @@
+
+/*
+  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>
+
+
+/** Type identifier for the conference service */
+#define SERVICE_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 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);
+
+
+#endif