Platform SDK: Active Directory, ADSI, and Directory Services

IADsContainer::MoveHere

The IADsContainer::MoveHere method moves a specified object to the container implementing this interface. The method can also be used for renaming an object.

HRESULT IADsContainer::MoveHere(
  BSTR bstrSourceObject,  
  BSTR bstrNewName,       
  IDispatch ** ppbstrNewObject     
);

Parameters

bstrSourceObject: [in] The string specifying the ADsPath of the object to be moved.
bstrNewName: [in] A relative name the new object within the container. This can be NULL, in which case the object is just moved. If it is not NULL, the object is renamed accordingly in the process.
ppbstrNewObject: [out] Indirect pointer to the IDispatch interface on the moved object.

Return Values

This method supports the standard return values, including S_OK for a successful operation. For error code information, see ADSI Error Codes.

Remarks

In Active Directory, you can move an object within the same domain or from different domains in the same directory forest. For the cross domain move, the following restrictions apply:

The destination domain must be in the native mode.
Objects to be moved must a leaf object or an empty container.
The operation requires the Kerberos authentication. NTLM will not work.
One cannot move security principals (user, group, computer, and so on) belonging to a global group. When a security principal is moved, a new SID is created for the object at the destination. However, its old SID from the source (stored in the sIDHistory attribute) is preserved, as well as the password of the object.

Note You can use the movetree.exe utility to move a subtree among different domains.

The following code snippet moves the user, "jsmith" from the "North.Fabrikam.Com" domain to the "South.Fabrikam.Com" domain:

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

A serverless ADsPath can be used for either the source or the destination or both.

The IADsContainer::MoveHere method can be used either to rename an object within the same container or to move an object among different containers. Moving an object retains the object's RDN, whereas renaming an object alters the RDN.

For example, the following code snippet does the renaming:

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

But the following code snippet does the moving:

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

In Visual Basic applications, you can pass vbNullString as the second parameter when moving an object from one container to another.

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

However, you cannot do the same with VBScript. This is because VBScript maps vbNullString to an empty string instead of to a null string, as does Visual Basic. You must use the RDN explicitly, as shown in the previous example.

Example Code [Visual Basic]

The following code snippet shows how to use this method to rename an object.

'------- Renaming an object ------------------
Set cont = GetObject("LDAP://OU=Sales, DC=Fabrikam,DC=com")
Set usr = cont.MoveHere("LDAP://CN=jsmith,OU=Sales, DC=Fabrikam,DC=com", "CN=jjohnson")
 
'------- Moving an object ----------------------
cont.MoveHere("LDAP://CN=chrisj,OU=Engineer,DC=Fabrikam,DC=com", vbNullString)

Example Code [C++]

The following C++ code snippet moves a user object using the IADsContainer::MoveHere method.

///////////////////////////////////////////////
// First, bind to the destination container.
///////////////////////////////////////////////
HRESULT hr;
IADsContainer *pCont=NULL;
CoInitialize(NULL);
hr = ADsGetObject(
        L"LDAP://OU=MCS,DC=windows2000,DC=nttest,DC=microsoft,DC=com",
        IID_IADsContainer,
        (void**) &pCont );
 
if ( !SUCCEEDED(hr) )
{
    return hr;
}
 
///////////////////////////////////////////////////////
// Now, move the object to the bound container.
///////////////////////////////////////////////////////
IDispatch *pDisp=NULL;
 
hr = pCont->MoveHere(L"LDAP://CN=Mike Smith,OU=DSys,DC=windows2000,DC=nttest,DC=microsoft,DC=com", NULL, &pDisp );
pCont->Release();
 
if (SUCCEEDED(hr) )
{ 
// You may do another operation here, such as updating attributes.
pDisp->Release();
}
 
CoUninitialize();

Requirements

  Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with DSClient).
  Windows 95/98: Requires Windows 95 or later (with DSClient).
  Header: Declared in Iads.h.