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

   1 .TH LDAP_PARSE_REFERENCE 3 "RELEASEDATE" "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_parse_reference \- Extract referrals and controls from a reference message
   7 .SH LIBRARY
   8 OpenlDAP LDAP (libldap, -lldap)
   9 .SH SYNOPSIS
  10 .nf
  11 .ft B
  12 #include <ldap.h>
  13 .LP
  14 .ft B
  15 int ldap_parse_reference( LDAP *ld, LDAPMessage *reference,
  16         char ***referralsp, LDAPControl ***serverctrlsp, int freeit )
  17 .SH DESCRIPTION
  18 .LP
  19 The
  20 .B ldap_parse_reference()
  21 routine is used to extract referrals and controls from a reference message.
  22 The \fIreference\fP parameter is a reference message as returned by a
  23 call to
  24 .BR ldap_first_reference (3) ,
  25 .BR ldap_next_reference (3) ,
  26 .BR ldap_first_message (3) ,
  27 .BR ldap_next_message (3) ,
  28 or
  29 .BR ldap_result (3) .
  30 .LP
  31 The \fIreferralsp\fP parameter will be filled in with an allocated array of
  32 character strings. The strings are copies of the referrals contained in
  33 the parsed message. The array should be freed by calling
  34 .BR ldap_value_free (3) .
  35 If \fIreferralsp\fP is NULL, no referrals are returned.
  36 If no referrals were returned, \fI*referralsp\fP is set to NULL.
  37 .LP
  38 The \fIserverctrlsp\fP parameter will be filled in with an allocated array of
  39 controls copied from the parsed message. The array should be freed by calling
  40 .BR ldap_controls_free (3) .
  41 If \fIserverctrlsp\fP is NULL, no controls are returned.
  42 If no controls were returned, \fI*serverctrlsp\fP is set to NULL.
  43 .LP
  44 The \fIfreeit\fP parameter determines whether the parsed message is
  45 freed or not after the extraction. Any non-zero value will make it
  46 free the message. The
  47 .BR ldap_msgfree (3)
  48 routine can also be used to free the message later.
  49 .SH ERRORS
  50 Upon success LDAP_SUCCESS is returned. Otherwise the values of the
  51 \fIreferralsp\fP and \fIserverctrlsp\fP parameters are undefined.
  52 .SH SEE ALSO
  53 .BR ldap (3),
  54 .BR ldap_first_reference (3),
  55 .BR ldap_first_message (3),
  56 .BR ldap_result (3),
  57 .BR ldap_get_values (3),
  58 .BR ldap_controls_free (3)
  59 .SH ACKNOWLEDGEMENTS
  60 .B      OpenLDAP
  61 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
  62 .B      OpenLDAP
  63 is derived from University of Michigan LDAP 3.3 Release.