annotate 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]>

/*
  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