1.lf 1 stdin 2.TH LDAP_PARSE_RESULT 3 "2020/04/28" "OpenLDAP 2.4.50" 3.\" $OpenLDAP$ 4.\" Copyright 1998-2020 The OpenLDAP Foundation All Rights Reserved. 5.\" Copying restrictions apply. See COPYRIGHT/LICENSE. 6.SH NAME 7ldap_parse_result \- Parsing results 8.SH LIBRARY 9OpenLDAP LDAP (libldap, \-lldap) 10.SH SYNOPSIS 11.nf 12.ft B 13#include <ldap.h> 14.LP 15.ft B 16int ldap_parse_result( LDAP *ld, LDAPMessage *result, 17 int *errcodep, char **matcheddnp, char **errmsgp, 18 char ***referralsp, LDAPControl ***serverctrlsp, 19 int freeit ) 20.LP 21.ft B 22int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *result, 23 struct berval **servercredp, int freeit ) 24.LP 25.ft B 26int ldap_parse_extended_result( LDAP *ld, LDAPMessage *result, 27 char **retoidp, struct berval **retdatap, int freeit ) 28.SH DESCRIPTION 29.LP 30These routines are used to extract information from a result message. 31They will operate on the first result message in a chain of search 32results (skipping past other message types). They take the \fIresult\fP 33as returned by a call to 34.BR ldap_result (3), 35.BR ldap_search_s (3) 36or 37.BR ldap_search_st (3). 38In addition to 39.BR ldap_parse_result() , 40the routines 41.B ldap_parse_sasl_bind_result() 42and 43.B ldap_parse_extended_result() 44are used to get all the result information from SASL bind and extended 45operations. 46.LP 47The \fIerrcodep\fP parameter will be filled in with the result code from 48the result message. 49.LP 50The server might supply a matched DN string in the message indicating 51how much of a name in a request was recognized. The \fImatcheddnp\fP 52parameter will be filled in with this string if supplied, else it will 53be NULL. If a string is returned, it should be freed using 54.BR ldap_memfree (3). 55.LP 56The \fIerrmsgp\fP parameter will be filled in with the error message 57field from the parsed message. This string should be freed using 58.BR ldap_memfree (3). 59.LP 60The \fIreferralsp\fP parameter will be filled in with an allocated array of 61referral strings from the parsed message. This array should be freed using 62.BR ldap_memvfree (3). 63If no referrals were returned, \fI*referralsp\fP is set to NULL. 64.LP 65The \fIserverctrlsp\fP parameter will be filled in with an allocated array of 66controls copied from the parsed message. The array should be freed using 67.BR ldap_controls_free (3). 68If no controls were returned, \fI*serverctrlsp\fP is set to NULL. 69.LP 70The \fIfreeit\fP parameter determines whether the parsed message is 71freed or not after the extraction. Any non-zero value will make it 72free the message. The 73.BR ldap_msgfree (3) 74routine can also be used to free the message later. 75.LP 76For SASL bind results, the \fIservercredp\fP parameter will be filled in 77with an allocated berval structure containing the credentials from the 78server if present. The structure should be freed using 79.BR ber_bvfree (3). 80.LP 81For extended results, the \fIretoidp\fP parameter will be filled in 82with the dotted-OID text representation of the name of the extended 83operation response. The string should be freed using 84.BR ldap_memfree (3). 85If no OID was returned, \fI*retoidp\fP is set to NULL. 86.LP 87For extended results, the \fIretdatap\fP parameter will be filled in 88with a pointer to a berval structure containing the data from the 89extended operation response. The structure should be freed using 90.BR ber_bvfree (3). 91If no data were returned, \fI*retdatap\fP is set to NULL. 92.LP 93For all the above result parameters, NULL values can be used in calls 94in order to ignore certain fields. 95.SH ERRORS 96Upon success LDAP_SUCCESS is returned. Otherwise the values of the 97result parameters are undefined. 98.SH SEE ALSO 99.BR ldap (3), 100.BR ldap_result (3), 101.BR ldap_search (3), 102.BR ldap_memfree (3), 103.BR ldap_memvfree (3), 104.BR ldap_get_values (3), 105.BR ldap_controls_free (3), 106.BR lber-types (3) 107.SH ACKNOWLEDGEMENTS 108.lf 1 ./../Project 109.\" Shared Project Acknowledgement Text 110.B "OpenLDAP Software" 111is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. 112.B "OpenLDAP Software" 113is derived from the University of Michigan LDAP 3.3 Release. 114.lf 108 stdin 115