IADsContainer：：MoveHere 方法 (iads.h)

發行項
03/05/2024

IADsContainer：：MoveHere 方法會將指定的物件移至實作此介面的容器。方法可用來重新命名物件。

語法

HRESULT MoveHere(
  [in]  BSTR      SourceName,
  [in]  BSTR      NewName,
  [out] IDispatch **ppObject
);

參數

[in] SourceName

Null 終止的 Unicode 字串，指定要移動之物件的 ADsPath 。

[in] NewName

Null 終止的 Unicode 字串，指定容器內新對象的相對名稱。這可以是 NULL，在此情況下，物件會移動。如果不是 NULL，則會在進程中據以重新命名物件。

[out] ppObject

指向已移動物件上 IDispatch 介面指標的指標。

傳回值

這個方法支援成功作業的標準傳回值，包括 S_OK。如需錯誤碼的詳細資訊，請參閱 ADSI 錯誤碼。

備註

在 Active Directory 中，您可以在相同網域內或從相同目錄樹系中的不同網域移動物件。針對跨網域移動，適用下列限制：

目的地網域必須處於原生模式。
要移動的對象必須是分葉物件或空的容器。
NT LAN Manager (NTLM) 無法執行驗證;使用 Kerberos 驗證或委派。請注意，如果未使用 Kerberos 驗證，密碼會透過網路以純文本傳輸。若要避免這種情況，請使用委派搭配安全驗證。
您無法將安全性主體 (例如，使用者、群組、計算機等) 屬於全域群組。移動安全性主體時，會為目的地的物件建立新的 SID。不過，會保留其來自來源的舊 SID，儲存在 sIDHistory 屬性中，以及對象的密碼。

注意使用 Movetree.exe 公用程式，在不同的網域之間移動子樹。若要使用 Movetree 命令行工具將物件從來源網域移至目的地網域，您必須連線到持有來源網域 RID 主機角色的域控制器。如果 RID 主機無法使用，則對象無法移至其他網域。如果您嘗試使用 Movetree.exe 工具將物件從某個網域移至另一個網域，而且您指定不是 RID 主機的來源域控制器，則會產生非特定的「Movetree 失敗」錯誤訊息。

注意使用 ADsOpenObject 函式系結至 ADSI 物件時，您必須使用此函式 dwReserved 參數中ADS_AUTHENTICATION_ENUM的ADS_USE_DELEGATION旗標，才能使用 IADsContainer：：MoveHere 建立跨網域移動。 ADsOpenObject 函式相當於 IADsOpenDSObject：：OpenDsObject 方法。同樣地，使用 OpenDsObject 方法系結至 ADSI 物件，此方法的 InReserved 參數必須包含 ADS_AUTHENTICATION_ENUM 的 ADS_USE_DELEGATION 旗標，才能使用 IADsContainer：：MoveHere 進行跨網域移動。

下列程式代碼範例會將使用者「jeffsmith」從「South.Fabrikam.Com」網域移至「North.Fabrikam.Com」網域。首先，它會取得目的地容器的 IADsContainer 指標，然後 MoveHere 呼叫會指定要移動的物件路徑。

Set ou = GetObject("LDAP://server1/OU=Support,DC=North,DC=Fabrikam,DC=COM")
ou.MoveHere("LDAP://server2/CN=jeffsmith,OU=Sales,DC=South,DC=Fabrikam,DC=Com", vbNullString)

無伺服器 ADsPath 可用於來源或目的地或兩者。

IADsContainer：：MoveHere 方法可用來重新命名相同容器內的物件，或在不同的容器之間移動物件。移動物件會保留物件 RDN，而重新命名物件會改變 RDN。

例如，下列程式代碼範例會執行重新命名動作。

set cont = GetObject("LDAP://dc=dom,dc=com")
set newobj = cont.MoveHere("LDAP://cn=Jeff Smith,dc=dom,dc=com", "cn=Denise Smith")

下列程式代碼範例會執行移動。

set cont = GetObject("LDAP://dc=dom,dc=com")
set newobj = cont.MoveHere("LDAP://cn=jeffsmith,ou=sales,dc=dom,dc=com", "cn=jeffsmith")

在 Visual Basic 應用程式中，您可以將 vbNullString 當做第二個參數，將物件從一個容器移至另一個容器時傳遞。

Set newobj =  cont.MoveHere("LDAP://cn=jeffsmith,ou=sale,dc=dom,dc=com", vbNullString)

不過，您無法使用 VBScript 執行相同的動作。這是因為 VBScript 會將 vbNullString 對應至空字元串，而不是對應至 Null 字串，就像 Visual Basic 一樣。您必須明確使用 RDN，如上一個範例所示。

注意 WinNT 提供者支援 IADsContainer：：MoveHere，但僅適用於在網域內重新命名使用者 & 群組。

範例

下列程式代碼範例示範如何使用這個方法來重新命名物件。

Dim cont As IADsContainer
Dim usr As IADsUser

On Error GoTo Cleanup
' Rename an object.
Set cont = GetObject("LDAP://OU=Sales, DC=Fabrikam,DC=com")
Set usr = cont.MoveHere("LDAP://CN=jeffsmith,OU=Sales, DC=Fabrikam,DC=com", "CN=jayhenningsen")
 
' Move an object.
cont.MoveHere("LDAP://CN=denisesmith,OU=Engineer,DC=Fabrikam,DC=com", vbNullString)

Cleanup:
    If (Err.Number<>0) Then
        MsgBox("An error has occurred. " & Err.Number)
    End If
    Set cont = Nothing
    Set usr = Nothing

下列程式代碼範例會使用 IADsContainer：：MoveHere 方法移動用戶物件。

/////////////////////////////////////////////
// First, bind to the destination container.
////////////////////////////////////////////
HRESULT hr;
IADsContainer *pCont=NULL;
CoInitialize(NULL);
hr = ADsGetObject(
        L"LDAP://OU=MCS,DC=windows2000,DC=mytest,DC=fabrikam,DC=com",
        IID_IADsContainer,
        (void**) &pCont );
 
if ( !SUCCEEDED(hr) )
{
    goto Cleanup;
}
 
//////////////////////////////////////////////////
// Second, move the object to the bound container.
//////////////////////////////////////////////////
IDispatch *pDisp=NULL;
 
hr = pCont->MoveHere(CComBSTR("LDAP://CN=Jeff Smith,OU=DSys,DC=windows2000,DC=mytest,DC=fabrikam,DC=com"), NULL, &pDisp );
pCont->Release();
 
if (SUCCEEDED(hr) )
{ 
// You can perform another operation here, such as updating attributes.
pDisp->Release();
}

Cleanup:
    if(pCont)
        pCont->Release(); 

    if(pDisp)
        pDisp->Release();

    CoUninitialize();