ldap_search_ext_s関数 (winldap.h)
ldap_search_ext_s関数は、LDAP ディレクトリを同期的に検索し、一致するエントリごとに要求された属性セットを返します。
構文
WINLDAPAPI ULONG LDAPAPI ldap_search_ext_s(
[in] LDAP *ld,
[in] PSTR base,
[in] ULONG scope,
[in] PSTR filter,
[in] PZPSTR attrs,
[in] ULONG attrsonly,
[in] PLDAPControlA *ServerControls,
[in] PLDAPControlA *ClientControls,
[in] l_timeval *timeout,
[in] ULONG SizeLimit,
[out] PLDAPMessage *res
);
パラメーター
[in] ld
セッション ハンドル。
[in] base
検索を開始するエントリの識別名を含む null で終わる文字列へのポインター。
[in] scope
検索範囲を示す次のいずれかの値を指定します。
LDAP_SCOPE_BASE
基本エントリのみを検索します。
LDAP_SCOPE_ONELEVEL
基本エントリを除き、基本エントリの下の最初のレベルのすべてのエントリを検索します。
LDAP_SCOPE_SUBTREE
基本エントリと、ベースの下のツリー内のすべてのエントリを検索します。
[in] filter
検索フィルターを指定する null で終わる文字列へのポインター。 詳細については、「 検索フィルター構文」を参照してください。
[in] attrs
一致するエントリごとに返す属性を示す null で終わる文字列へのポインターの null で終わる配列。 NULL を渡して、使用可能なすべての属性を取得します。
[in] attrsonly
属性の型と値の両方を返す場合は 0 にする必要があるブール値。型のみが必要な場合は 0 以外。
[in] ServerControls
LDAP サーバー コントロールの一覧。
[in] ClientControls
クライアント コントロールの一覧。
[in] timeout
ローカル検索タイムアウト値 (秒単位) と、検索要求内でサーバーに送信される操作時間制限の両方を指定します。
[in] SizeLimit
検索から返されるエントリの数に関する制限。 値 0 は制限がないことを意味します。
[out] res
呼び出しの完了時の検索結果を格納します。 関数呼び出しがエラー コードで失敗した場合に、部分的な結果や拡張データを含めることもできます。 アプリケーションで不要 になったldap_msgfreeの 呼び出しで、無料で結果が返されます。
戻り値
関数が成功した場合、戻り値は LDAP_SUCCESS。
関数が失敗した場合はエラー コードを返しますが、 ldap_search_ext_s は失敗する可能性があり、 pMsg を割り当てることもできます。 たとえば、 LDAP_PARTIAL_RESULTS エラー コードと LDAP_REFERRAL エラー コードの両方で pMsg が割り当てられます。 詳細については、次のコード例を参照してください。 詳細については、「 戻り値」を参照してください。
注釈
ldap_search_ext_s関数は同期検索操作を開始します。 ldap_search_ext_sのパラメーターと効果には、ldap_search_sのものが含まれます。 拡張ルーチンには、クライアントとサーバーのコントロールをサポートし、各検索操作のサイズと時間制限を指定するための追加のパラメーターが含まれています。
ld セッション ハンドルと共に ldap_set_option 関数を使用して、検索の実行方法を決定するLDAP_OPT_DEREF オプションを設定します。 詳細については、「 セッション オプション」を参照してください。 他の 2 つの検索オプション (LDAP_OPT_SIZELIMIT と LDAP_OPT_TIMELIMIT) は、この関数の SizeLimit オプション パラメーターと TimeLimit オプション パラメーターを優先して無視されます。
検索操作が完了すると、 ldap_search_ext_s は呼び出し元に戻ります。 ldap_search_extを使用して、操作を非同期的に実行します。
マルチスレッド: ldap_search_ext_s の呼び出しはスレッド セーフです。
次のコード例は、ldap_search_ext_sが失敗した場合に pMsg を解放する方法を示しています。
// Initialize return value to NULL.
LDAPMessage *pMsg = NULL;
// Perform the search request.
dwErr = ldap_search_ext_s (i_pldap,
i_lpszBase,
i_ulScope,
i_lpszSearchFilter,
lpszAttributes,
0,
pServerControls,
pClientControls,
lpsTimeout,
0,
&pMsg
);
// Cleanup calling parameters.
if (lpszAttributes != NULL)
delete [] lpszAttributes;
// Convert error code and cleanup pMsg if necessary.
if (dwErr != LDAP_SUCCESS)
{
DebugOutLDAPError(i_pldap, dwErr, _T("ldap_search_ext_s"));
hr = HRESULT_FROM_WIN32(dwErr);
// Be aware that pMsg can contain valid data, even if
// the call to ldap_search_ext_s returned an error code.
// This can be caused by the server returning codes
// such as LDAP_RESULTS_TOO_LARGE or other codes
// that indicate that the search returned partial
// results. The user code can handle these cases
// if required, this example frees pMsg on any
// error code.
if (pMsg != NULL) ldap_msgfree(pMsg);
}
else
{
// Process the search results.
...
// Free the results when complete.
if (pMsg != NULL) ldap_msgfree(pMsg);
}
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows Vista |
| サポートされている最小のサーバー | Windows Server 2008 |
| 対象プラットフォーム | Windows |
| ヘッダー | winldap.h |
| Library | Wldap32.lib |
| [DLL] | Wldap32.dll |