ldap_modrdnW函式（winldap.h）

發行項
11/20/2024

ldap_modrdn 函式會變更LDAP項目的相對辨別名稱。

此函式已經過時，且已提供給舊版LDAP的回溯相容性。針對LDAP 3或更新版本，請使用 ldap_rename_ext 或 ldap_rename_ext_s 函式。

語法

WINLDAPAPI ULONG LDAPAPI ldap_modrdnW(
  [in]  LDAP        *ExternalHandle,
  [in]  const PWSTR DistinguishedName,
  [out] const PWSTR NewDistinguishedName
);

參數

[in] ExternalHandle

會話句柄。

[in] DistinguishedName

Null 終止字串的指標，其中包含要變更之專案的辨別名稱。

[out] NewDistinguishedName

Null 終止字串的指標，其中包含要提供專案的新相對辨別名稱。

傳回值

如果函式成功，它會傳回修改作業的訊息標識碼。

如果函式失敗，它會傳回 –1，並在LDAP數據結構中設定會話錯誤參數。

言論

使用 ldap_modrdn 函式或其同步對等的 ldap_modrdn_s來變更 LDAP 項目的名稱。 LDAP 2 透過 ldap_modrdn2 和 ldap_modrdn2_s支援其他功能。

作為異步函式，ldap_modrdn 傳回作業的訊息標識碼。使用訊息標識符呼叫 ldap_result，以取得作業的結果。若要在完成之前取消異步新增作業，請呼叫 ldap_abandon。

請注意，各種 ldap_modrdn 函式只允許您變更相對辨別名稱，這是物件辨別名稱中最小重要元件。 LDAP 可透過第 3 版提供修改辨別名稱通訊協定作業，以允許更一般的名稱變更存取。呼叫 ldap_rename_ext 或 ldap_rename_ext_s即可取得此功能。建議使用這些函式，而不是 ldap_modrdn 函式來變更項目名稱。

多線程：ldap_modrdn 呼叫是安全線程的，前提是 LdapGetLastError 是在函數調用傳回 -1 失敗碼時，用來擷取實際的會話錯誤碼。

注意連線到LDAP 2 伺服器時，應用程式必須先呼叫其中一個 ldap_bind 或 ldap_simple_bind 例程來執行系結作業，再嘗試其他作業。 ldap_modrdn 已經過時，僅針對LDAP 1實作的相容性而提供。

注意

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

要求

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