Blame src/mw_srvc_resolve.h

Packit 16808d
Packit 16808d
/*
Packit 16808d
  Meanwhile - Unofficial Lotus Sametime Community Client Library
Packit 16808d
  Copyright (C) 2004  Christopher (siege) O'Brien
Packit 16808d
  
Packit 16808d
  This library is free software; you can redistribute it and/or
Packit 16808d
  modify it under the terms of the GNU Library General Public
Packit 16808d
  License as published by the Free Software Foundation; either
Packit 16808d
  version 2 of the License, or (at your option) any later version.
Packit 16808d
  
Packit 16808d
  This library is distributed in the hope that it will be useful,
Packit 16808d
  but WITHOUT ANY WARRANTY; without even the implied warranty of
Packit 16808d
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Packit 16808d
  Library General Public License for more details.
Packit 16808d
  
Packit 16808d
  You should have received a copy of the GNU Library General Public
Packit 16808d
  License along with this library; if not, write to the Free
Packit 16808d
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
Packit 16808d
*/
Packit 16808d
Packit 16808d
#ifndef _MW_SRVC_RESOLVE_H
Packit 16808d
#define _MW_SRVC_RESOLVE_H
Packit 16808d
Packit 16808d
Packit 16808d
#include <glib.h>
Packit 16808d
Packit 16808d
Packit 16808d
#ifdef __cplusplus
Packit 16808d
extern "C" {
Packit 16808d
#endif
Packit 16808d
Packit 16808d
Packit 16808d
/** Type identifier for the conference service */
Packit 16808d
#define mwService_RESOLVE  0x00000015
Packit 16808d
Packit 16808d
Packit 16808d
/** Return value of mwServiceResolve_search indicating an error */
Packit 16808d
#define SEARCH_ERROR  0x00
Packit 16808d
Packit 16808d
Packit 16808d
/** @struct mwServiceResolve
Packit 16808d
    User lookup service */
Packit 16808d
struct mwServiceResolve;
Packit 16808d
Packit 16808d
Packit 16808d
enum mwResolveFlag {
Packit 16808d
  /** return unique results or none at all */
Packit 16808d
  mwResolveFlag_UNIQUE    = 0x00000001,
Packit 16808d
Packit 16808d
  /** return only the first result */
Packit 16808d
  mwResolveFlag_FIRST     = 0x00000002,
Packit 16808d
Packit 16808d
  /** search all directories, not just the first with a match */
Packit 16808d
  mwResolveFlag_ALL_DIRS  = 0x00000004,
Packit 16808d
Packit 16808d
  /** search for users */
Packit 16808d
  mwResolveFlag_USERS     = 0x00000008,
Packit 16808d
Packit 16808d
  /** search for groups */
Packit 16808d
  mwResolveFlag_GROUPS    = 0x00000010,
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/** @see mwResolveResult */
Packit 16808d
enum mwResolveCode {
Packit 16808d
  /** successful search */
Packit 16808d
  mwResolveCode_SUCCESS     = 0x00000000,
Packit 16808d
Packit 16808d
  /** only some of the nested searches were successful */
Packit 16808d
  mwResolveCode_PARTIAL     = 0x00010000,
Packit 16808d
Packit 16808d
  /** more than one result (occurs when mwResolveFlag_UNIQUE is used
Packit 16808d
      and more than one result would have been otherwise returned) */
Packit 16808d
  mwResolveCode_MULTIPLE    = 0x80020000,
Packit 16808d
Packit 16808d
  /** the name is not resolvable due to its format */
Packit 16808d
  mwResolveCode_BAD_FORMAT  = 0x80030000,
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
enum mwResolveMatchType {
Packit 16808d
  mwResolveMatch_USER   = 0x00000001,
Packit 16808d
  mwResolveMatch_GROUP  = 0x00000002,
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
struct mwResolveMatch {
Packit 16808d
  char *id;      /**< user id */
Packit 16808d
  char *name;    /**< user name */
Packit 16808d
  char *desc;    /**< description */
Packit 16808d
  guint32 type;  /**< @see mwResolveMatchType */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
struct mwResolveResult {
Packit 16808d
  guint32 code;    /**< @see mwResolveCode */
Packit 16808d
  char *name;      /**< name of the result */
Packit 16808d
  GList *matches;  /**< list of mwResolveMatch */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/** Handle the results of a resolve request. If there was a cleanup
Packit 16808d
    function specified to mwServiceResolve_search, it will be called
Packit 16808d
    upon the user data after this callback returns.
Packit 16808d
Packit 16808d
    @param srvc     the resolve service
Packit 16808d
    @param id       the resolve request ID
Packit 16808d
    @param code     return code
Packit 16808d
    @param results  list of mwResolveResult
Packit 16808d
    @param data     optional user data attached to the request
Packit 16808d
*/
Packit 16808d
typedef void (*mwResolveHandler)
Packit 16808d
     (struct mwServiceResolve *srvc,
Packit 16808d
      guint32 id, guint32 code, GList *results,
Packit 16808d
      gpointer data);
Packit 16808d
Packit 16808d
Packit 16808d
/** Allocate a new resolve service */
Packit 16808d
struct mwServiceResolve *mwServiceResolve_new(struct mwSession *);
Packit 16808d
Packit 16808d
Packit 16808d
/** Inisitate a resolve request.
Packit 16808d
Packit 16808d
    @param srvc     the resolve service
Packit 16808d
    @param queries  list query strings
Packit 16808d
    @param flags    search flags
Packit 16808d
    @param handler  result handling function
Packit 16808d
    @param data     optional user data attached to the request
Packit 16808d
    @param cleanup  optional function to clean up user data
Packit 16808d
    @return         generated ID for the search request, or SEARCH_ERROR
Packit 16808d
*/
Packit 16808d
guint32 mwServiceResolve_resolve(struct mwServiceResolve *srvc,
Packit 16808d
				 GList *queries, enum mwResolveFlag flags,
Packit 16808d
				 mwResolveHandler handler,
Packit 16808d
				 gpointer data, GDestroyNotify cleanup);
Packit 16808d
Packit 16808d
Packit 16808d
/** Cancel a resolve request by its generated ID. The handler function
Packit 16808d
    will not be called, and the optional cleanup function will be
Packit 16808d
    called upon the optional user data for the request */
Packit 16808d
void mwServiceResolve_cancelResolve(struct mwServiceResolve *, guint32);
Packit 16808d
Packit 16808d
Packit 16808d
#ifdef __cplusplus
Packit 16808d
}
Packit 16808d
#endif
Packit 16808d
Packit 16808d
Packit 16808d
#endif /* _MW_SRVC_RESOLVE_H */