Table of Contents | Previous | Next | Index

Netscape Directory SDK 3.0 for C Programmer’s Guide
Chapter 18 Functions

ldap_first_message()

Returns a pointer to the first LDAPMessage structure in a chain of search results.

Syntax

#include <ldap.h>
LDAPMessage * ldap_first_message( LDAP *ld, LDAPMessage *res );

Parameters

This function has the following parameters:

ld
Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

res
Chain of search results, represented by a pointer to the LDAPMessage structure.

Returns

One of the following values:

If successful, returns the pointer to the first LDAPMessage structure in the chain of search results.

If no LDAPMessage structures are in the chain or if the function is unsuccessful, returns a NULLMSG.

Description

The ldap_first_message() function returns a pointer to the first LDAPMessage structure in a chain of search results.

You can use this function in conjunction with the ldap_next_message() function to iterate through the chain of search results. You can call the ldap_msgtype() function to determine if each message contains a matching entry (a message of the type LDAP_RES_SEARCH_ENTRY) or a search reference (a message of the type LDAP_RES_SEARCH_REFERENCE).

Do not free the LDAPMessage structure returned by this function. Because this is the first structure within a chain of search results, freeing this structure will free the chain of search results. When you are done working with the search results, you can free the chain itself, rather than individual structures within the chain.

For more information, see "Iterating Through a Chain of Results" on page 124.

Example

See the examples under "Example: Searching the Directory (Asynchronous)" on page 140 and "Example: Searching the Directory (Synchronous)" on page 146..