ldap_parse_result(3)

LDAP_PARSE_RESULT(3)   C LIBRARY FUNCTIONS   LDAP_PARSE_RESULT(3)

NAME

     ldap_parse_result - Parsing results

LIBRARY

     OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS

     #include <ldap.h>

     int ldap_parse_result( LDAP *ld, LDAPMessage *result,
          int *errcodep, char **matcheddnp, char **errmsgp,
          char ***referralsp, LDAPControl ***serverctrlsp,
          int freeit )

     int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *result,
          struct berval **servercredp, int freeit )

     int ldap_parse_extended_result( LDAP *ld, LDAPMessage *result,
          char **retoidp, struct berval **retdatap, int freeit )

DESCRIPTION

     These routines are used to extract information from a result
     message.  They will operate on the first result message in a
     chain of search results (skipping past other message types).
     They   take   the   result   as   returned   by  a  call  to
     ldap_result(3), ldap_search_s(3) or  ldap_search_st(3).   In
     addition     to     ldap_parse_result(),     the    routines
     ldap_parse_sasl_bind_result()                            and
     ldap_parse_extended_result()  are used to get all the result
     information from SASL bind and extended operations.

     The errcodep parameter will be filled  in  with  the  result
     code from the result message.

     The server might supply a matched DN string in  the  message
     indicating  how  much of a name in a request was recognized.
     The matcheddnp parameter will be filled in with this  string
     if  supplied, else it will be NULL. If a string is returned,
     it should be freed using ldap_memfree(3).

     The errmsgp parameter will be filled in with the error  mes-
     sage  field  from  the parsed message. This string should be
     freed using ldap_memfree(3).

     The referralsp parameter will be filled in with an allocated
     array  of  referral  strings  from  the parsed message. This
     array should  be  freed  using  ldap_value_free(3).   If  no
     referrals were returned, *referralsp is set to NULL.

     The serverctrlsp parameter will be filled in with  an  allo-
     cated  array of controls copied from the parsed message. The
     array should be freed using  ldap_controls_free(3).   If  no

OpenLDAP LDVERSION  Last change: RELEASEDATE                    1

LDAP_PARSE_RESULT(3)   C LIBRARY FUNCTIONS   LDAP_PARSE_RESULT(3)

     controls were returned, *serverctrlsp is set to NULL.

     The freeit parameter determines whether the  parsed  message
     is  freed  or  not  after the extraction. Any non-zero value
     will make it free the message. The  ldap_msgfree(3)  routine
     can also be used to free the message later.

     For SASL bind results, the  servercredp  parameter  will  be
     filled  in with an allocated berval structure containing the
     credentials from the server if present. The structure should
     be freed using ber_bvfree(3).

     For extended results, the retoidp parameter will  be  filled
     in  with  the  dotted-OID text representation of the name of
     the extended operation response. The string should be  freed
     using  ldap_memfree(3).  If no OID was returned, *retoidp is
     set to NULL.

     For extended results, the retdatap parameter will be  filled
     in  with a pointer to a berval structure containing the data
     from the extended operation response. The  structure  should
     be  freed  using  ber_bvfree(3).   If no data were returned,
     *retdatap is set to NULL.

     For all the above result parameters, NULL values can be used
     in calls in order to ignore certain fields.

ERRORS

     Upon success LDAP_SUCCESS is returned. Otherwise the  values
     of the result parameters are undefined.

SEE ALSO

     ldap(3),  ldap_result(3),  ldap_search(3),  ldap_memfree(3),
     ldap_get_values(3), ldap_controls_free(3), lber-types(3)

ACKNOWLEDGEMENTS

     OpenLDAP is developed and maintained by The OpenLDAP Project
     (http://www.openldap.org/).    OpenLDAP   is   derived  from
     University of Michigan LDAP 3.3 Release.

OpenLDAP LDVERSION  Last change: RELEASEDATE                    2