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

   1 .TH LDAP_FIRST_REFERENCE 3 "19 September 2001" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldap_first_reference, ldap_next_reference, ldap_count_references \- Stepping
   7 through continuation references in a result chain
   8 .SH SYNOPSIS
   9 .nf
  10 .ft B
  11 #include <ldap.h>
  12 .LP
  13 .ft B
  14 int ldap_count_references( LDAP *ld, LDAPMessage *result )
  15 .LP
  16 .ft B
  17 LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *result )
  18 .LP
  19 .ft B
  20 LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *reference )
  21 .SH DESCRIPTION
  22 .LP
  23 These routines are used to step through the continuation references in a
  24 result chain received from
  25 .BR ldap_result (3)
  26 or the synchronous LDAP search operation routines.
  27 .LP
  28 The
  29 .B ldap_first_reference()
  30 routine is used to retrieve the first reference message in a
  31 result chain.  It takes the \fIresult\fP as returned by a call to
  32 .BR ldap_result (3) ,
  33 .BR ldap_search_s (3)
  34 or
  35 .BR ldap_search_st (3)
  36 and returns a pointer to the first reference message in the
  37 result chain.
  38 .LP
  39 This pointer should be supplied on a subsequent call to
  40 .B ldap_next_reference()
  41 to get the next reference message, the result of which should be
  42 supplied to the next call to
  43 .BR ldap_next_reference() ,
  44 etc.
  45 .B ldap_next_reference()
  46 will return NULL when there are no more reference messages.
  47 The reference messages returned from these calls are used by
  48 .BR ldap_parse_reference (3)
  49 to extract referrals and controls.
  50 .LP
  51 A count of the number of reference messages in the search result can be
  52 obtained by calling
  53 .BR ldap_count_references() .
  54 It can also be used to count the number of reference messages remaining
  55 in a result chain.
  56 .SH ERRORS
  57 If an error occurs in
  58 .B ldap_first_reference()
  59 or
  60 .BR ldap_next_reference() ,
  61 NULL is returned.  If an error occurs in
  62 .BR ldap_count_references() ,
  63 -1 is returned.
  64 .SH SEE ALSO
  65 .BR ldap(3),
  66 .BR ldap_result(3),
  67 .BR ldap_search(3),
  68 .BR ldap_parse_reference(3)
  69 .SH ACKNOWLEDGEMENTS
  70 .B      OpenLDAP
  71 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
  72 .B      OpenLDAP
  73 is derived from University of Michigan LDAP 3.3 Release.