Share via

3.1.4.18.1 CopyConglomerations (Opnum 3)

  • Article

This method is called by a client to copy one or more conglomerations from one partition to another.

 HRESULT CopyConglomerations(
   [in, string] LPCWSTR pwszSourcePartition,
   [in, string] LPCWSTR pwszDestPartition,
   [in] DWORD cConglomerations,
   [in, string, size_is(cConglomerations,)] 
     LPCWSTR* ppwszConglomerationNamesOrIds
 );

pwszSourcePartition: Either the Curly Braced GUID String Syntax ([MS-DTYP] section 2.3.4.3) representation of the partition identifier or the Name property of a partition, from which conglomerations are to be copied.

pwszDestPartition: Either the Curly Braced GUID String Syntax ([MS-DTYP] section 2.3.4.3) representation of the partition identifier or the Name property of a partition, to which conglomerations are to be copied.

cConglomerations: The number of elements in ppwszConglomerationNamesOrIds.

ppwszConglomerationNamesOrIds: An array of values, each of which is either the Curly Braced GUID String Syntax ([MS-DTYP] section 2.3.4.3) representation of the conglomeration identifier or the Name property of a conglomeration to be copied.

Return Values: This method MUST return S_OK (0x00000000) on success, and a failure result, as specified in [MS-ERREF] section 2.1, on failure. All failure results MUST be treated identically.

Upon receiving a call to this method, the server MUST verify that catalog version negotiation has been performed by checking the negotiated catalog version (see section 3.1.1.5), and fail the call if not.

The server then MUST select the source partition as follows:

  • If pwszSourcePartition is in Curly Braced GUID String Syntax ([MS-DTYP] section 2.3.4.3), the server MUST select the partition with partition identifier equal to the GUID represented, and fail the call if no such partition exists.

  • Otherwise, the server MUST select the partition with the Name property equal to pwszSourcePartition, and fail the call if no such partition exists.

The server then MUST select the destination partition as follows:

  • If pwszDestPartition is in Curly Braced GUID String Syntax ([MS-DTYP] section 2.3.4.3), the server MUST select the partition with the partition identifier equal to the GUID represented, and fail the call if no such partition exists.

  • Otherwise, the server MUST select the partition with the Name property equal to pwszDestPartition, and fail the call if no such partition exists.

For each element of ppwszConglomerationNamesOrIds, the server then MUST select the conglomeration to copy as follows:

  • If the value of the element is in Curly Braced GUID String Syntax ([MS-DTYP] section 2.3.4.3), the server MUST select the conglomeration with the conglomeration identifier equal to the GUID represented, and fail the call if no such conglomeration exists.

  • Otherwise, the server MUST select the conglomeration with the Name property equal to the value of the element, and fail the call if no such conglomeration exists.

The server then MUST verify that the specified copy operation is valid, as follows:

  • The server MUST verify that the destination partition is changeable, in other words, the Changeable property is equal to TRUE (0x00000001), and fail the call if not.

  • For each conglomeration selected, the server MUST perform the following:

    • The server MUST verify that the conglomeration is contained in the source partition, and fail the call if not.

    • The server MUST verify that the conglomeration does not contain any component legacy configurations, and fail the call if not.

    • For each component full configuration in the conglomeration, the server MUST verify that there does not already exist in the destination partition a component configuration for the same component, and fail the call if not.

The remainder of the protocol behavior specified for this method SHOULD be performed as an atomic transaction, in other words, either the operation SHOULD fully succeed or the server SHOULD make no changes to the catalog. This described behavior is provided to facilitate the explanation of how the protocol behaves. This document does not mandate that implementations adhere to this model as long as their external behavior is consistent with that described in this document.

For each conglomeration, the server then MUST attempt to perform a copy operation, as follows:

  • The server MUST attempt to generate a GUID, using the mechanism specified in [C706] section 3, to be the conglomeration identifier of the copy, and fail if it cannot.

  • The server then MUST attempt to create a new conglomeration in the destination partition with the generated GUID as its conglomeration identifier, and fail the call if it cannot.

  • The server then MUST attempt to copy the properties, other than PartitionIdentifier and ConglomerationIdentifier, of the conglomeration into the copy, and fail the call if it cannot.

  • For each component full configuration in the conglomeration, the server then MUST attempt to create a new component full configuration in the conglomeration copy, copying all properties other than PartitionIdentifier and ConglomerationIdentifier from the original component full configuration, and fail the call if it cannot.