slapi_search_internal_callback_pb()

Performs an LDAP search operation based on a parameter block to search the directory. Unlike slapi_search_internal_pb(), this function allows you to specify callback functions that are invoked when the search operation finds matching entries or entries with referrals.

Syntax

#include "slapi-plugin.h"
int slapi_search_internal_callback_pb(Slapi_PBlock *pb,
    void *callback_data, plugin_result_callback prc,
    plugin_search_entry_callback psec,
    plugin_referral_entry_callback prec);

Parameters

This function takes the following parameters:

pb

A parameter block that has been initialized using slapi_search_internal_set_pb().

callback_data

A pointer to arbitrary plug-in or operation-specific data that you would like to pass to your callback functions.

prc

Callback function that the server calls to send result codes. The function must have the prototype specified by plugin_result_callback .

psec

Callback function that the server calls when finding a matching entry in the directory. The function must have the prototype specified by plugin_search_entry_callback.

prec

Callback function that the server calls when finding an entry that contains LDAP v3 referrals. The function must have the prototype specified by plugin_referral_entry_callback.

Returns

This function returns -1 if the parameter passed is a NULL pointer. Otherwise, it returns 0.

After your code calls this function, the server sets SLAPI_PLUGIN_INTOP_RESULT in the parameter block to the appropriate LDAP result code. You can therefore check SLAPI_PLUGIN_INTOP_RESULT in the parameter block to determine whether an error has occurred.

Description

Like slapi_search_internal_pb(), this function allows you to search the directory from a plug-in function.

Unlike a search operation requested by a client, no result code, search entries, or referrals are sent to a client by slapi_search_internal_callback_pb() . However, you can write your own callback functions that are invoked when these events occur:

• You can write a callback function that is invoked when the search operation normally sends a result code to the client. This function must have the prototype specified by plugin_result_callback. You specify this function in the prc argument of slapi_search_internal_callback_pb() .

• You can write a callback function that is invoked when the search operation normally sends a search entry to the client. This function must have the prototype specified by plugin_search_entry_callback. You specify this function in the psec argument of slapi_search_internal_callback_pb() .

• You can write a callback function that is invoked when the search operation normally sends LDAP v3 search result references. This function must have the prototype specified by plugin_referral_entry_callback . You specify this function in the prec argument of slapi_search_internal_callback_pb().

  You can also pass arbitrary plug-in or operation-specific data to these callback functions. Specify the data that you want to pass as the callback_data argument of slapi_search_internal_callback_pb() .

Memory Concerns

The entries passed to the search entry callback function do not need to be freed. If you need to access an entry after returning from the callback function, call slapi_entry_dup() to make a copy.

The referral URLs passed to the referral entry callback function do not need to be freed. If you need to access a referral string after returning from the callback function, call slapi_ch_strdup() to make a copy.

You do not need to call slapi_free_search_results_internal() after calling slapi_search_internal_callback_pb().