Share via

3.1.4.18.3 AliasComponent (Opnum 5)

  • Article

This method is called by a client to create an alias component full configuration, a component full configuration of a virtual aliased component equivalent to the original component except in CLSID and ProgID.

 HRESULT AliasComponent(
   [in, string] LPCWSTR pwszSourceConglomeration,
   [in, string] LPCWSTR pwszComponent,
   [in, string] LPCWSTR pwszDestConglomeration,
   [in] GUID* pNewCLSID,
   [in, string] LPCWSTR pwszNewProgID
 );

pwszSourceConglomeration: 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 from which the component configuration is to be copied.

pwszComponent: The Curly Braced GUID String Syntax ([MS-DTYP] section 2.3.4.3) representation of the CLSID or the ProgID property of a component configured in the specified by pwszSourceConglomeration.

pwszDestConglomeration: 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 into which the component configuration is to be copied.

pNewCLSID: A GUID to use as the CLSID of the aliased component.

pwszNewProgID: A string to be used as the ProgID of the aliased component.

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 conglomeration as follows:

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

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

The server then MUST select the destination conglomeration as follows:

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

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

The server then MUST select the component configuration to be aliased as follows:

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

  • Otherwise, the server MUST select the component with a ProgID property equal to pwszComponent, and fail the call if no such component exists.

  • The server then MUST select the component full configuration for the selected component in the source conglomeration, and fail the call if no such component full configuration exists.<343>

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

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

  • The server MUST verify that there does not exist a component with the CLSID specified in pNewCLSID, and fail the call if this component does exist.

  • The server MUST verify that there does not exist a component with the ProgID specified in pwszNewProgID, and fail the call if this component does exist.

  • The server MUST verify that the Changeable property (see section 3.1.1.3.6) of the destination conglomeration is set to TRUE (0x00000001), 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.

The server MUST attempt to create a new component full configuration for an implementation-specific<344> aliased component in the destination conglomeration, copying all properties other than CLSID, ProgID, PartitionIdentifier, and ConglomerationIdentifier from the original component full configuration, and fail the call if it cannot.