Chapter 40. Functions for Sending Entries and Results to the Client

This chapter contains reference information on routines for sending entries and results to the client.

Table 40.1. Routines for Sending Entries and Results to Clients

Function Description
slapi_send_ldap_referral() Processes an entry's LDAP v3 referrals.
slapi_send_ldap_result() Sends an LDAP result code back to the client.
slapi_send_ldap_search_entry() Sends an entry found by a search back to the client.

40.1. slapi_send_ldap_referral()

Description

When you call this function, the server processes the LDAP referrals specified in the refs argument. The server processes referrals in different ways, depending on the version of the LDAP protocol supported by the client:

  • In the LDAPv3 protocol, references to other LDAP servers (search result references) can be sent to clients as search results. For example, a server can send a mixture of entries found by the search and references to other LDAP servers as the results of a search.
    This function processes an entry's LDAPv3 referrals, which are found in the entry's ref attribute. For LDAPv3 clients, this function sends the LDAP referrals back to the client.
When you call the slapi_send_ldap_referral() function for LDAPv3 clients, the server sends the referrals specified in the refs argument back to the client as search result references. The urls argument is not used in this case.
  • In the LDAPv2 protocol, servers can send the LDAP result code LDAP_PARTIAL_RESULTS to refer the client to other LDAP server.
    For LDAPv2 clients, this function copies the referrals to an array of berval structures that you can pass to slapi_send_ldap_referral() function at a later time.
When you call the slapi_send_ldap_referral() function for LDAPv2 clients, the server collects the referrals specified in refs in the urls argument. No data is sent to the LDAPv2 client.
To get the referrals to an LDAPv2 client, you need to pass the urls argument (along with an LDAP_PARTIAL_RESULTS result code) to the slapi_send_ldap_result() function. slapi_send_ldap_result() concatenates the referrals specified in the urls argument and sends the resulting string to the client as part of the error message.
If you want to define your own function for sending referrals, write a function that complies with the type definition send_ldap_referral_fn_ptr_tand set the SLAPI_PLUGIN_DB_REFERRAL_FN parameter in the parameter block to the name of your function.
Syntax

#include "slapi-plugin.h"
int slapi_send_ldap_referral( Slapi_PBlock *pb, Slapi_Entry *e, struct berval **refs, struct berval ***urls );

Parameters

This function takes the following parameters:

pb
Parameter block.
e
Pointer to the Section 14.22, “Slapi_Entry” structure representing the entry with which you are working.
refs
Pointer to the NULL-terminated array of berval structures containing the LDAPv3 referrals (search result references) found in the entry.
urls
Pointer to the array of berval structures used to collect LDAP referrals for LDAPv2 clients.
Returns

This function returns one of the following values:

  • 0 if successful.
  • -1 if an error occurs.
See Also