Previous Topic: SmDirRemoveMemberFromRole()Next Topic: SmDirSearchCount()

Programming Guides › Programming Guide for C › Directory API Guidance › Directory API Reference › SmDirSearch()

SmDirSearch()

SiteMinder calls SmDirSearch() to search on the criteria specified in the search filter lpszSearchFilter. You could use SmDirSearch() to execute a query, such as an SQL select, on your custom directory.

In addition to the search filter, the function SmDirSearch() passes directory search parameters. In the SiteMinder Administrative UI, on the Directory Setup tab, you can specify parameters in the following fields:

The nSearchTimeout and nSearchResults parameters of SmDirSearch() pass the information entered in those fields.

SiteMinder calls SmDirFreeStringArray() to free the lpszDNs array.

Syntax

int SM_EXTERN SmDirSearch (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   char***                  lpszDNs,
   const char*              lpszSearchFilter,
   const char*              lpszSearchRoot,
   const int                nSearchResults,
   const int                nSearchTimeout,
   const int                nSearchScope
);

Parameter

I/O

Description

lpApiContext

I

Pointer to the API context structure.

pHandle

I

The address of the pointer returned by SmDirInit().

pInstanceHandle

I

The address of a pointer to the directory instance handle.

lpszDNs

O

Distinguished names of the users found as a result of the search.

lpszSearchFilter

I

Buffer containing the search expression.

lpszSearchRoot

I

This parameter is designed to hold the search root—that is, the starting point for the search. In a hierarchical directory, when authenticating a user, SiteMinder starts at the root and works down the tree.

In the SiteMinder Administrative UI, on the Directory Setup tab, in the Custom Namespace group box, the value entered in the Parameter field is passed in through lpszSearchRoot.

Note: The string entered in the Parameter field is also passed to lpszParameter for use with SmDirInit() and SmDirInitDirInstance(). If your code for SmDirInit() needs to use lpszParameter and your code for SmDirSearch() needs a search root, you will have to parse the string from the Parameter field.

nSearchResults

I

This parameter holds the maximum number of records that can be returned for a single search of the directory.

nSearchTimeout

I

This parameter holds the maximum time in seconds that the API should keep searching the directory for results.

nSearchScope

I

This parameter indicates how far below the root (lpszSearchRoot) the API will query the directory to find a match. Depending on the value in nSearchScope, the search could go down only one level or through the entire subtree. The default value is 2.

Returns

Returns 0 if successful or -1 if not successful.