ldap_search_s函式 (winldap.h)
ldap_search_s函式會同步搜尋 LDAP 目錄,並針對每個相符項目傳回要求的一組屬性。
語法
WINLDAPAPI ULONG LDAPAPI ldap_search_s(
[in] LDAP *ld,
[in] PSTR base,
[in] ULONG scope,
[in] PSTR filter,
[in] PZPSTR attrs,
[in] ULONG attrsonly,
[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 以擷取所有可用的屬性。
[in] attrsonly
如果傳回屬性類型和值,則為零的布爾值,如果只需要型別,則為非零值。
[out] res
包含完成呼叫時搜尋的結果。 當函數調用失敗並出現錯誤碼時,也可以包含部分結果或擴充數據。 當應用程式不再需要時,傳回呼叫 ldap_msgfree 的免費結果。
傳回值
如果函式成功,傳回值會 LDAP_SUCCESS。
如果函式失敗,它會傳回錯誤碼,不過 ldap_search_s 可能會失敗,而且仍然可以配置 pMsg。 例如, LDAP_PARTIAL_RESULTS 和 LDAP_REFERRAL 錯誤碼都配置 pMsg。 如需詳細資訊,請參閱下列程式代碼範例。 如需詳細資訊,請參閱 傳回值。
備註
ldap_search_s函式會起始同步搜尋。
使用 ldap_set_option 函式搭配 ld 會話句柄來設定 LDAP_OPT_SIZELIMIT、 LDAP_OPT_TIMELIMIT和 LDAP_OPT_DEREF 選項,以決定搜尋的執行方式。 如需詳細資訊,請參閱 會話選項。
完成搜尋作業時, ldap_search_s 傳回給呼叫端。 使用 ldap_search 讓作業以異步方式執行。
多線程: 對ldap_search_s 的呼叫是安全線程。
下列程式代碼範例示範如何在發生ldap_search_s失敗時釋放 pMsg。
// Initialize return value to NULL.
LDAPMessage *pMsg = NULL;
// Perform the search request.
dwErr = ldap_search_s (i_pldap,
i_lpszBase,
i_ulScope,
i_lpszSearchFilter,
lpszAttributes,
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_s"));
hr = HRESULT_FROM_WIN32(dwErr);
// Be aware that pMsg can contain valid data, even if the
// call to ldap_search_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 just frees pMsg on any
// error code.
if (pMsg != NULL)
ldap_msgfree(pMsg);
}
else
{
// Process the search results.
...
// Free the results when no longer required.
if (pMsg != NULL) ldap_msgfree(pMsg);
}
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | Windows Vista |
最低支援的伺服器 | Windows Server 2008 |
目標平台 | Windows |
標頭 | winldap.h |
程式庫 | Wldap32.lib |
Dll | Wldap32.dll |