3.1.5.2.1 CreateObject Method (Opnum 3)

  • Article

The CreateObject method MUST execute an LDAP command under machine security credentials to create an Active Directory object that has a specified distinguished name and attributes.<43>

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

domainControllerName: MUST be the FQDN of the domain controller to which the method sends the LDAP request.

distinguishedName: MUST be the distinguished name of the Active Directory object that is being created. The distinguished name of any object in Active Directory can be used. The format of the distinguished name is specified in [RFC2251] section 4.1.3.

attributes: The safe array of attributes that MUST be created for the new object. As an input parameter, the SAFEARRAY is created by the client.

verifyNameDomainControllerName: If the attributes of the object refer to an object in another domain, the client MUST specify the domain controller in that domain that will be used to verify the reference. The LDAP_SERVER_VERIFY_NAME_OID control will be added to the LDAP command. If this parameter does not specify a domain controller that can be contacted to validate these references, the method MUST fail and return an LDAP protocol failure.

The LDAP control is specified in [MS-ADTS] section 3.1.1.3.4.1.16.

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, between 0x80000000 and 0xFFFFFFFF, as specified in [MS-ERREF] section 2.1. For protocol purposes, all nonzero values MUST be treated as equivalent failures.

When the server receives this message, it MUST check whether the caller has sufficient rights to perform the operation. The implementation MUST perform a check to verify that the rights are appropriate for the creation 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. <44>

If the server fails to perform this 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.

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

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

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

  • Verify that attributes are not NULL and present a valid one-dimensional safe array. SAFEARRAY is as specified in [MS-OAUT]. For more information, see [SAFEARRAY].

If parameter validation fails, the server MUST immediately fail the operation 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 creating a new Active Directory object that has the specified distinguished name and attributes.

If the verifyNameDomainControllerName parameter is not NULL or is an empty string, the server MUST append the LDAP_SERVER_VERIFY_NAME_OID control to the LDAP command. The value of the verifyNameDomainControllerName parameter MUST be passed to this control as a value. If for any reason this control cannot be created or appended to the command, the server MUST fail the operation immediately and return the dfsrHelperErrorCreateVerifyServerControl error code as its response to the client.<45>

Otherwise, the server MUST execute the 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 returned 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.