The ModifyObject method MUST execute an LDAP command under machine security credentials to add, delete, or modify attributes of an Active Directory object that has a specified distinguished name.<48>

 HRESULT ModifyObject(
   [in] BSTR domainControllerName,
   [in] BSTR distinguishedName,
   [in] SAFEARRAY (_AdAttributeData)* attributes
 );

domainControllerName: MUST be the FQDN of the domain controller to which the method sends the LDAP request. The format of the distinguished name is specified in [RFC2251] section 4.1.3.

distinguishedName: MUST be the distinguished name of the Active Directory object being modified. The distinguished name of any object in Active Directory MAY be used. <49>

attributes: MUST be the safe array of attributes that are to be added, modified, or deleted.

Return Values: The method MUST return:

• Zero on success.

• For LDAP protocol failures:

  • If the LDAP error is LDAP_OPERATIONS_ERROR, dfsrHelperLdapErrorBase + the server-side error code.

  • For all other LDAP errors, dfsrHelperLdapErrorBase + the LDAP return code. For more information, see [LDAP-ERR].

• For all other failures, an implementation-specific nonzero HRESULT error code, as specified in [MS-ERREF] section 2.1, between 0x80000000 and 0xFFFFFFFF. For protocol purposes, all nonzero values MUST be treated as equivalent failures.

After the server receives this message, it MUST check whether the caller has sufficient rights to perform the operation. The implementation MUST perform a platform-specific check to verify that the rights are appropriate for the modification of Active Directory objects.

• If the user does not have sufficient rights, the server MUST fail the operation immediately and return the E_ACCESS_DENIED (0x80070005) error code as its response to the client.

• If the server fails to perform this security check because of an implementation-specific failure, the server MUST fail the operation immediately and return an appropriate error as its response to the client.<50>

If the security check succeeds and the server can verify that the user has sufficient rights, the server MUST proceed to the next steps of the method.

When the server receives this message, it MUST validate the parameters:

• Verify that domainControllerName and distinguishedName are not NULL and are not empty strings.

If parameter validation fails, the server MUST fail the operation immediately and return an appropriate error as its response to the client.

If both the security check and the parameter validation succeed, the server MUST create a new LDAP command for modifying an existing Active Directory object that has the specified distinguished name and attributes.

The server MUST execute this LDAP command against the domain controller that is specified in domainControllerName and check the return value of the LDAP protocol.

If the LDAP protocol returns LDAP_SUCCESS, the server MUST return zero to the caller to indicate the success of the call; otherwise, if the LDAP protocol returns any return code other than LDAP_SUCCESS, the server MUST return the following error code to the caller:

• If the error is LDAP_OPERATIONS_ERROR, the server gets the server-side error code of the LDAP operation and MUST return dfsrHelperLdapErrorBase + the server-side error code to the caller.

• For all other LDAP errors, the server MUST return dfsrHelperLdapErrorBase + the LDAP return code to the caller.