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