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

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