18.6. slapi_search_internal_set_pb()

This function sets up the parameter block, for subsequent use by slapi_search_internal_pb(), to contain the following data for an internal search operation.
For unique ID-based search:
  • SLAPI_TARGET_DN set to the DN that allows to select the right backend.
  • SLAPI_TARGET_UNIQUEID set to the unique ID of the entry.
For DN-based search:
  • SLAPI_TARGET_DN set to the search base.
  • SLAPI_SEARCH_SCOPE set to the search scope.
  • SLAPI_SEARCH_STRFILTER set to the search filter.
  • SLAPI_CONTROLS_ARG set to request controls, if present.
  • SLAPI_SEARCH_ATTRS set to the list of attributes to return.
  • SLAPI_SEARCH_ATTRSONLY indicates whether attribute values should be returned.
Syntax

  

#include "slapi-plugin.h"
void slapi_search_internal_set_pb(Slapi_PBlock *pb, const char *base, int scope, const char *filter, char **attrs, 
int attrsonly, LDAPControl **controls, const char *uniqueid, Slapi_ComponentId *plugin_identity, int operation_flags);
Parameters

This function takes the following parameters:

pb Parameter block that is populated with search parameters.
base Search base.
scope Search scope (LDAP_SCOPE_SUBTREE, etc.).
filter Search filter.
attrs Attributes to be returned.
attrsonly Flag specifying whether to return just attribute names or names and values.
controls List of controls associated with the operation.
uniqueid Unique identifier of the entry. Non-NULL value indicates unique ID-based search. In this case, scope and filter are ignored; however, base is still required and is used to select the correct backend. All directory entries contain a unique identifier. Unlike the distinguished name (DN), the unique identifier of an entry never changes, providing a good way to refer unambiguously to an entry in a distributed/replicated environment.
plugin_identity Plug-in identity; a cookie that identifies the plug-in to the Directory Server during an internal operation. This cookie is used by the server to retrieve the plug-in configuration in order to determine whether to allow the operation and which actions to take during the operation processing. Plug-in identity is passed to the plug-in initialization function in the SLAPI_PLUGIN_IDENTITY pblock parameter. A plug-in must save this information and pass it to every internal operation issued by the plug-in.
operation_flags Actions taken during operation processing.
Memory Concerns

The controls passed with slapi_search_internal_set_pb() must be an allocated array. Additionally, this array must be freed by slapi_pblock_destroy().

If the user passes memory allocated on the stack or frees the controls himself, then when slapi_pblock_destroy() is called, the function can double-free the memory or corrupt the memory structures. This potentially leads to segfaults or other problems when the allocated memory is taken by any Slapi_* function.