DsCrackNamesA 函式 (ntdsapi.h)
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 字串的內容。
#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
PDS_NAME_RESULT 值的指標 ，這個值會接收包含已轉換名稱 DS_NAME_RESULT 結構。 呼叫端必須藉由呼叫 DsFreeNameResult 來釋出此記憶體。
傳回值
傳回 Win32 錯誤值、RPC 錯誤值或下列其中一項。
備註
名稱轉換要求的成功取決於客戶端系結的位置。 用戶端會使用 DsBind 的一些變體系結至目錄服務的特定實例。 如果系結至全域編錄，則名稱對應的範圍是整個樹系。 如果未系結至全域編錄，名稱對應的範圍就是該域控制器的全域編錄未涵蓋的網域。 如果未系結至全域編錄且找不到名稱，但輸入名稱明確識別其網域，且此網域位於樹系中，則傳回數據會識別感興趣的網域的 DNS 功能變數名稱。 客戶端應該使用此數據來系結至正確的域控制器或全域編錄，並使用新的系結句柄再次呼叫 DsCrackNames 。
DsCrackNames 的傳回值表示錯誤，例如無效的參數或記憶體不足。 不過，轉換個別名稱的問題會報告在每個輸入名稱所傳回之DS_NAME_RESULT_ITEM結構的狀態成員中。
注意
ntdsapi.h 標頭會將 DsCrackNames 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows Vista |
| 最低支援的伺服器 | Windows Server 2008 |
| 目標平台 | Windows |
| 標頭 | ntdsapi.h |
| 程式庫 | Ntdsapi.lib |
| Dll | Ntdsapi.dll |