DsCrackNamesA 函式（ntdsapi.h）

發行項
11/20/2024

DsCrackNames 函式會將目錄服務物件名稱陣列從一種格式轉換成另一種格式。名稱轉換可讓用戶端應用程式在用來識別各種目錄服務物件的多個名稱之間進行對應。例如，用戶物件可以透過 SAM 帳戶名稱來識別（Domain\UserName）、用戶主體名稱（UserName@Domain.com），或辨別名稱。

語法

NTDSAPI DWORD DsCrackNamesA(
  [in]  HANDLE           hDS,
  [in]  DS_NAME_FLAGS    flags,
  [in]  DS_NAME_FORMAT   formatOffered,
  [in]  DS_NAME_FORMAT   formatDesired,
  [in]  DWORD            cNames,
  [in]  const LPCSTR     *rpNames,
  [out] PDS_NAME_RESULTA *ppResult
);

參數

[in] hDS

包含從 DSBind 或 DSBindWithCred 函式取得的目錄服務句柄。如果旗標包含 DS_NAME_FLAG_SYNTACTICAL_ONLY，hDS 可以 NULL。

[in] flags

包含一或多個用來判斷名稱語法破解方式的 DS_NAME_FLAGS 值。

[in] formatOffered

包含其中一個 DS_NAME_FORMAT 值，可識別輸入名稱的格式。

您也可以針對此參數傳遞 DS_LIST_NCS 值。這會導致 DsCrackNames 傳回目前樹系中所有命名內容的辨別名稱。會忽略 formatDesired 參數。 cNames 至少必須是一個，rpNames 中的所有字串長度必須大於零個字元。會忽略 rpNames 字串的內容。

附註DS_LIST_NCS 未定義於已發佈的頭檔中。若要使用此值，請以如下所示的確切格式加以定義。

#ifndef DS_LIST_NCS
    #define DS_LIST_NCS 0xfffffff6
#endif

[in] formatDesired

包含其中一個 DS_NAME_FORMAT 值，可識別輸出名稱的格式。不支援 DS_SID_OR_SID_HISTORY_NAME 值。

[in] cNames

包含 rpNames 陣列中的元素數目。

[in] rpNames

指標陣列的指標，指向包含要轉換之名稱的 Null 終止字串。

[out] ppResult

接收包含已轉換名稱之 DS_NAME_RESULT 結構的 PDS_NAME_RESULT 值的指標。呼叫端必須藉由呼叫 DsFreeNameResult來釋放此記憶體。

傳回值

傳回 Win32 錯誤值、RPC 錯誤值或下列其中一項。

言論

名稱轉換要求的成功取決於客戶端系結的位置。用戶端會使用 dsBind的一些變體系結至目錄服務的特定實例。如果系結至全域編錄，則名稱對應的範圍是整個樹系。如果未系結至全域編錄，則名稱對應的範圍是該域控制器的全域編錄未涵蓋的網域。如果未系結至全域編錄且找不到名稱，但輸入名稱明確識別其網域，且此網域位於樹系中，則傳回數據會識別感興趣的網域的 DNS 功能變數名稱。客戶端應該使用此數據系結至正確的域控制器或全域編錄，並使用新的系結句柄再次呼叫 DsCrackNames。

DsCrackNames 傳回值表示錯誤，例如無效的參數或記憶體不足。不過，轉換個別名稱時發生問題，會在針對每個輸入名稱傳回之 DS_NAME_RESULT_ITEM 結構成員狀態回報。

Note 請勿混淆 formatOffered 參數的值，DsCrackNames 函式所使用的格式元素與 IADsNameTranslate 介面所使用的 ADS_NAME_TYPE_ENUM 列舉中所定義的類似名稱格式元素。這兩組元素格式不相等，而且無法互換。

注意

ntdsapi.h 標頭會將 DsCrackNames 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows Vista
支援的最低伺服器	Windows Server 2008
目標平臺	窗戶
標頭	ntdsapi.h
連結庫	Ntdsapi.lib
DLL	Ntdsapi.dll