共用方式為


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

包含從 DSBindDSBindWithCred 函式 取得的目錄服務句柄。 如果旗標包含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

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

傳回值

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

備註

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

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

注意請勿將 DsCrackNames 函式所使用的 formatOffered 參數格式專案值與 IADsNameTranslate 介面所使用的ADS_NAME_TYPE_ENUM列舉中所定義的類似命名格式元素混淆。 兩組元素格式不相等,而且無法交換。
 

注意

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

規格需求

需求
最低支援的用戶端 Windows Vista
最低支援的伺服器 Windows Server 2008
目標平台 Windows
標頭 ntdsapi.h
程式庫 Ntdsapi.lib
Dll Ntdsapi.dll

另請參閱

ADS_NAME_TYPE_ENUM

DS_NAME_FLAGS

DS_NAME_FORMAT

DS_NAME_RESULT

DS_NAME_RESULT_ITEM

域控制器和復寫管理功能

DsFreeNameResult

IADsNameTranslate