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

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