Share via

3.1.4.4 S_DSCreateObject (Opnum 0)

  • Article

This method creates a new directory object, assigns the specified properties and security descriptor to that directory object, and returns a unique GUID identifier for that directory object.

 HRESULT S_DSCreateObject(
   [in] handle_t hBind,
   [in, range(1,58)] unsigned long dwObjectType,
   [in, unique] const wchar_t* pwcsPathName,
   [in, range(0,524288)] unsigned long dwSDLength,
   [in, size_is(dwSDLength), unique] 
     unsigned char* SecurityDescriptor,
   [in, range(1,128)] unsigned long cp,
   [in, size_is(cp)] unsigned long aProp[],
   [in, size_is(cp)] PROPVARIANT apVar[],
   [in, out, unique] GUID* pObjGuid
 );

hBind:  MUST specify an RPC binding handle, as specified in [MS-RPCE] section 2.

dwObjectType:  Specifies the type of directory object to create. MUST be set to one of the object types, as specified in section 2.2.8.

pwcsPathName:  Pointer to a NULL-terminated 16-bit Unicode string that MUST contain the directory service pathname, as specified in section 2.2.9 for the object to be created in the directory service. If the object is of a type that is not referenced by pathname, as specified in section 2.2.9, this pointer MUST be NULL.

dwSDLength:  MUST contain the size in bytes of the buffer pointed to by SecurityDescriptor.

SecurityDescriptor:  MUST contain a pointer to a security descriptor, as specified in [MS-DTYP] section 2.4.6, or NULL.

cp:  MUST be set to the size (in elements) of the arrays aProp and apVar. The arrays aProp and apVar MUST have an identical number of elements and MUST contain at least one element.

aProp:  An array of property identifiers of properties to associate with the created object. Each element MUST specify a value from the property identifiers table as specified in section 2.2.10.1, for the directory object type specified in dwObjectType. Each element MUST specify the property identifier for the corresponding property value at the same element index in apVar. The array MUST contain at least one element.

apVar:  An array of property values to associate with the created object. Each element MUST specify the property value for the corresponding property identifier at the same element index in aProp. The array MUST contain at least one element.

pObjGuid: SHOULD be set by the server to the GUID of the created object if the dwObjectType is equal to MQDS_QUEUE, MQDS_ROUTINGLINK, or MQDS_MACHINE.<19>

Return Values:  If the method succeeds, the return value is 0. If the method fails, the return value is an implementation-specific error code.

MQ_OK (0x00000000)

MQ_ERROR_ILLEGAL_PROPERTY_VALUE (0xC00E0018)

MQ_ERROR_ILLEGAL_ENTERPRISE_OPERATION (0xC00E0071)

MQ_ERROR (0xC00E0001)

MQ_ERROR_DS_ERROR (0xC00E0043)

MQDS_OBJECT_NOT_FOUND (0xC00E050F)

E_ADS_PROPERTY_NOT_FOUND (0x8000500D)

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol, as specified in [MS-RPCE].

When processing this call, the server MUST:

  • Verify that the arrays aProp and apVar contain at least one element. If not, the server SHOULD<20> take no further action and return a failure HRESULT.

  • If the value of dwObjectType is not one of the values listed in the table in section 2.2.8, or is MQDS_DELETEDOBJECT or MQDS_ENTERPRISE, the server MUST take no further action and return a failure HRESULT.

  • Verify that the property identifiers required to create an object of the type indicated by dwObjectType are present in aProp. If any of the required property identifiers is missing, the server MUST take no further action and return a failure HRESULT. The required property identifiers for each object type, as defined in [MS-MQMQ], are listed in the following table.<21>

    Object Type

    Required property identifiers

    MQDS_QUEUE

    None

    MQDS_MACHINE

    None

    MQDS_SITE

    None

    MQDS_CN

    Object cannot be created

    MQDS_ENTERPRISE

    Object cannot be created

    MQDS_USER

    PROPID_U_SIGN_CERT (section 2.3.6.4)

    PROPID_U_DIGEST (section 2.3.6.5)

    MQDS_ROUTINGLINK

    PROPID_L_NEIGHBOR1 (section 2.3.7.1)

    PROPID_L_NEIGHBOR2 (section 2.3.7.2)

    Exactly one of PROPID_L_COST (section 2.3.7.3) or PROPID_L_ACTUAL_COST (section 2.3.7.12)

  • The server MAY<22> forward the creation to another server.

  • Let dirObject be a directory object initialized to NULL. Let sendNotification be a Boolean initialized to False.

  • If the dwObjectType is anything other than MQDS_QUEUE, and the SecurityDescriptor parameter is not NULL and valid, the server SHOULD take no further action and return MQ_ERROR_ILLEGAL_PROPERTY (0xC00E0018).

  • If the dwObjectType is MQDS_QUEUE:

    • Verify for each property identifier in aProp that the property identifier is valid for an object of type MQDS_QUEUE, and that the corresponding variant in apVar is of the type defined for the property identifier, as specified in [MS-MQMQ] section 2.3.1. If any invalid property identifier or type is found, the server MUST take no further action and return a failure HRESULT.

    • The server MAY expand aProp and apVar by adding to aProp property identifiers that are not already present and by adding to apVar default values for those property identifiers.<23>

    • Map the values contained in aProp and apVar to Queue (section 3.1.4.21.8.1.4) ADM element attributes according to the rules specified in section 3.1.4.21.8.3.3 or, for property identifiers not listed there, in section 3.1.4.21.8.2.4. Property identifiers not listed in either section MUST be ignored. If the rules indicate that any property identifier is invalid, the server MUST take no further action and return a failure HRESULT.

    • Create a new Queue ADM element instance using the mapping from the preceding step and assign it to dirObject.

    • If the Computer portion of the dirObject.PathName (as specified in [MS-MQMQ] section 2.1.1) is different from the LocalQueueManager.ComputerName, set sendNotification to True.

    • If the SecurityDescriptor parameter is NULL:

      • Set dirObject.Security to a default security descriptor with the owner SID set to the SID of the calling user. Grant MQSEC_GET_QUEUE_PROPERTIES and MQSEC_GET_QUEUE_PERMISSIONS access to the group "Everyone". Grant MQSEC_QUEUE_GENERIC_ALL access to the owner.

    • If the SecurityDescriptor parameter is not NULL and valid:

      • Use the following fields from the SecurityDescriptor parameter to create a new security descriptor:

        • OwnerSid

        • GroupSid

        • Dacl

        • Sacl

      • If any of the preceding fields is NULL, the new security descriptor is initialized with default values, with the owner SID set to the SID of the calling user.

      • Set dirObject.Security to the new security descriptor.

  • If the dwObjectType is MQDS_ROUTINGLINK:

    • Verify for each property identifier in aProp that the property identifier is valid for an object of type MQDS_ROUTINGLINK, and that the corresponding variant in apVar is of the type defined for the property identifier, as specified in [MS-MQMQ] section 2.3.7. If any invalid property identifier or type is found, the server MUST take no further action and return a failure HRESULT.

    • If the SecurityDescriptor parameter is not NULL, the server SHOULD take no further action and return MQ_ERROR_ILLEGAL_PROPERTY (0xC00E0018).<24>

    • Map the values contained in aProp and apVar to RoutingLink ADM element attributes according to the rules specified in section 3.1.4.21.8.3.5 or, for property identifiers not listed there, in section 3.1.4.21.8.2.9. Property identifiers not listed in either section MUST be ignored. If the rules indicate that any property identifier is invalid, the server MUST take no further action and return a failure HRESULT.

    • Create a new RoutingLink ADM element instance using the mapping from the preceding step and assign it to dirObject.

  • If the dwObjectType is MQDS_MACHINE:

    • Verify for each property identifier in aProp that the property identifier is valid for an object of type MQDS_MACHINE, and that the corresponding variant in apVar is of the type defined for the property identifier, as specified in [MS-MQMQ] section 2.3.2. If any invalid property identifier or type is found, the server MUST take no further action and return a failure HRESULT.

    • The server MAY expand aProp and apVar by adding to aProp property identifiers that are not already present and by adding to apVar default values for those property identifiers.<25>

      If the SecurityDescriptor parameter is NULL, grant MQSEC_MACHINE_GENERIC_ALL access to the group "Everyone".

    • If the SecurityDescriptor parameter is not NULL, the server SHOULD take no further action and return MQ_ERROR_ILLEGAL_PROPERTY (0xC00E0018).<26>

    • Map the values contained in aProp and apVar to QueueManager attributes according to the rules specified in section 3.1.4.21.8.3.1 or, for property identifiers not listed there, in section 3.1.4.21.8.2.1. Property identifiers not listed in either section MUST be ignored. If the rules indicate that any property identifier is invalid, the server MUST take no further action and return a failure HRESULT.

    • Create a new QueueManager ADM element instance using the mapping from the previous step and assign it to dirObject.

    • dirObject.Security SHOULD be set to a default security descriptor with the owner SID set to the SID of the calling user.<27>

  • If the dwObjectType is MQDS_ENTERPRISE, the server MUST take no further action and return an error HRESULT.

  • If the dwObjectType parameter is MQDS_USER:

    • Verify for each property identifier in aProp that the property identifier is valid for an object of type MQDS_USER, and that the corresponding variant in apVar is of the type defined for the property identifier, as specified in [MS-MQMQ] section 2.3.6. If any invalid property identifier or type is found, the server MUST take no further action and return a failure HRESULT.

    • If the SecurityDescriptor parameter is not NULL, the server SHOULD take no further action and return MQ_ERROR_ILLEGAL_PROPERTY_VALUE (0xC00E0018).<28>

      If the SecurityDescriptor parameter is NULL, grant RIGHT_GENERIC_READ access to the group "Everyone". Grant GENERIC_READ_MAPPING | RIGHT_DS_WRITE_PROPERTY_EXTENDED | RIGHT_DS_WRITE_PROPERTY access to the owner. The bitmasks pertain to Active Directory and are specified in [MS-ADTS] section 5.1.3.2.

    • Map the values contained in aProp and apVar to User (section 3.1.4.21.8.1.11) ADM element attributes according to the rules specified in section 3.1.4.21.8.3.7 or, for property identifiers not listed there, in section 3.1.4.21.8.2.12. Property identifiers not listed in either section MUST be ignored. If the rules indicate that any property identifier is invalid, the server MUST take no further action and return a failure HRESULT.

    • Create a new User ADM element instance using the mapping from the preceding step and assign it to dirObject.

    • If the pwcsPathName parameter is NULL, and if the user's SID, the x.509 signing certificate, and the digest of the certificate as properties with property identifiers PROPID_U_SID ([MS-MQMQ] section 2.3.6.1), PROPID_U_SIGN_CERT ([MS-MQMQ] section 2.3.6.4), and PROPID_U_DIGEST ([MS-MQMQ] section 2.3.6.5), respectively, are provided:

      • The server MUST add the x.509 signing certificate to the dirObject.Certificates list and MUST add the digest of the certificate to the dirObject.CertificateDigestList.

  • If the dwObjectType is MQDS_SITE:

    • Verify for each property identifier in aProp that the property identifier is valid for an object of type MQDS_SITE, and that the corresponding variant in apVar is of the type defined for the property identifier, as specified in [MS-MQMQ] section 2.3.3. If any invalid property identifier or type is found, the server MUST take no further action and return a failure HRESULT.

    • The server MAY expand aProp and apVar by adding to aProp property identifiers that are not already present and by adding to apVar default values for those property identifiers.<29>

    • If the SecurityDescriptor parameter is NULL, construct a default security descriptor with the owner SID set to the SID of the calling user. Grant MQSEC_SITE_GENERIC_READ access to the group "Everyone". Grant MQSEC_SITE_GENERIC_ALL access to the owner.

      If the SecurityDescriptor parameter is not NULL, the server SHOULD take no further action and return MQ_ERROR_ILLEGAL_PROPERTY (0xC00E0018).<30>

    • Map the values contained in aProp and apVar to Site (section 3.1.4.21.8.1.8) ADM element attributes according to the rules specified in section 3.1.4.21.8.3.4 or, for property identifiers not listed there, in section 3.1.4.21.8.2.8. Property identifiers not listed in either section MUST be ignored. If the rules indicate that any property identifier is invalid, then the server MUST take no further action and return a failure HRESULT.

    • Create a new Site ADM element instance using the mapping from the preceding step and assign it to dirObject.

    • dirObject.Security SHOULD be set to the security descriptor constructed in a previous step.<31>

  • If the dwObjectType is MQDS_CN, the server SHOULD take no further action and return an error HRESULT.<32>

  • Generate the Add Object to Directory (section 3.1.6.11) event with the argument iObject set to dirObject. If rStatus returned by the event is not 0x00000000, return rStatus and take no further action.

  • If sendNotification is True:

    • Generate a Send Change Notification ([MS-MQCN] section 3.3.4.1) event with the following arguments:

      • iOperation := QueueCreation

      • iDirectoryObject := dirObject

  • The server MAY<33> contact other servers to propagate the changes.