git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_ufn.3

   1 .TH LDAP_UFN 3 "22 September 1998" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-1999 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldap_ufn_search_s, ldap_ufn_search_c, ldap_ufn_search_ct, ldap_ufn_setfilter, ldap_ufn_setfilter, ldap_ufn_setprefix, ldap_ufn_timeout \- Perform an LDAP user friendly search operation
   7 .SH SYNOPSIS
   8 .nf
   9 .ft B
  10 #include <ldap.h>
  11 .LP
  12 .ft B
  13 int ldap_ufn_search_c(ld, ufn, attrs, attrsonly, res, cancelproc,
  14                         cancelparm)
  15 .ft
  16 LDAP *ld;
  17 char *ufn;
  18 char **attrs;
  19 int attrsonly;
  20 LDAPMessage **res;
  21 int (*cancelproc)();
  22 void *cancelparm;
  23 .LP
  24 .ft B
  25 int ldap_ufn_search_ct(ld, ufn, attrs, attrsonly, res, cancelproc,
  26                         cancelparm, tag1, tag2, tag3)
  27 .ft
  28 LDAP *ld;
  29 char *ufn;
  30 char **attrs;
  31 int attrsonly;
  32 LDAPMessage **res;
  33 int (*cancelproc)();
  34 void *cancelparm;
  35 char *tag1, *tag2, *tag3;
  36 .LP
  37 .ft B
  38 int ldap_ufn_search_s(ld, ufn, attrs, attrsonly, res)
  39 .ft
  40 LDAP *ld;
  41 char *ufn;
  42 char **attrs;
  43 int attrsonly;
  44 LDAPMessage **res;
  45 .LP
  46 .ft B
  47 LDAPFiltDesc *ldap_ufn_setfilter(ld, fname)
  48 .ft
  49 LDAP *ld;
  50 char *fname;
  51 .LP
  52 .ft B
  53 void ldap_ufn_setprefix(ld, prefix)
  54 .ft
  55 LDAP *ld;
  56 char *prefix;
  57 .LP
  58 .ft B
  59 int ldap_ufn_timeout(tvparam)
  60 .ft
  61 void *tvparam;
  62 .SH DESCRIPTION
  63 These routines are used to perform LDAP user friendly search operations.
  64 .B ldap_ufn_search_s()
  65 is the simplest form.  It does the search
  66 synchronously.  It takes \fIld\fP to identify the the LDAP connection.
  67 The \fIufn\fP parameter is the user friendly name for which to search.
  68 The \fIattrs\fP, \fIattrsonly\fP and \fIres\fP parameters are the
  69 same as for
  70 .BR ldap_search (3).
  71 .LP
  72 The
  73 .B ldap_ufn_search_c()
  74 routine functions the same as
  75 .BR ldap_ufn_search_s() ,
  76 except that it takes \fIcancelproc\fP, a function to call periodicly
  77 during the search.  It should be a function taking a single void *
  78 argument, given by \fIcalcelparm\fP.  If \fIcancelproc\fP returns a
  79 non-zero result, the search will be abandoned and no results returned.
  80 The purpose of this routine is to provide a way for the search to be
  81 cancelled, for example, by a user or because some other condition
  82 occurs.
  83 .LP
  84 The
  85 .B ldap_ufn_search_ct()
  86 routine is like
  87 .BR ldap_ufn_search_c() ,
  88 except that it takes three extra parameters.  \fItag1\fP is passed to the
  89 .BR ldap_init_getfilter (3)
  90 routine when resolving the first component of
  91 the UFN.  \fItag2\fP is used when resolving intermediate components.
  92 \fItag3\fP is used when resolving the last component.  By default,
  93 the tags used by the other UFN search routines during these three
  94 phases of the search are "ufn first", "ufn intermediate", and "ufn last".
  95 .LP
  96 The
  97 .B ldap_ufn_setfilter()
  98 routine is used to set the
  99 .BR ldapfilter.conf (5)
 100 file for use with the
 101 .BR ldap_init_getfilter (3)
 102 routine to \fIfname\fP.
 103 .LP
 104 The
 105 .B ldap_ufn_setprefix()
 106 routine is used to set the default prefix
 107 (actually, it's a suffix) appended to UFNs before searhing.  UFNs
 108 with fewer than three components have the prefix appended first,
 109 before searching.  If that fails, the UFN is tried with progressively
 110 shorter versions of the prefix, stripping off components.  If the UFN
 111 has three or more components, it is tried by itself first.  If that
 112 fails, a similar process is applied with the prefix appended.
 113 .LP
 114 The
 115 .B ldap_ufn_timeout()
 116 routine is used to set the timeout associated
 117 with
 118 .B ldap_ufn_search_s()
 119 searches.  The \fItimeout\fP parameter
 120 should actually be a pointer to a struct timeval (this is so
 121 .B ldap_ufn_timeout()
 122 can be used as a cancelproc in the above routines).
 123 .SH NOTES
 124 These routines may dynamically allocate memory.  The caller is
 125 required to free such memory using the supplied deallocation routines.
 126 Return values are contained
 127 in <ldap.h>.
 128 .SH SEE ALSO
 129 .BR gettimeofday (2),
 130 .BR ldap (3),
 131 .BR ldap_search (3),
 132 .BR ldap_getfilter (3),
 133 .BR ldapfilter.conf (5),
 134 .BR ldap_error (3)
 135 .SH ACKNOWLEDGEMENTS
 136 .B      OpenLDAP
 137 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 138 .B      OpenLDAP
 139 is derived from University of Michigan LDAP 3.3 Release.