共用方式為

3.1.4.11.3 PromoteLegacyConfiguration (Opnum 5)

  • 發行項

This method is called by a client to convert an existing component legacy configuration for a component into a component full configuration for that component.

 HRESULT PromoteLegacyConfiguration(
   [in, string] LPCWSTR pwszConglomerationIdOrName,
   [in, string] LPCWSTR pwszCLSIDOrProgId,
   [in] eComponentType ctComponentType
 );

pwszConglomerationIdOrName:  A string containing either the Curly Braced GUID String Syntax ([MS-DTYP] section 2.3.4.3) representation of a conglomeration identifier or the Name property (see section 3.1.1.3.3) of a conglomeration.

pwszCLSIDOrProgId:  A string containing either the Curly Braced GUID String Syntax ([MS-DTYP] section 2.3.4.3) representation of a CLSID or the ProgID property (see section 3.1.1.3.1) of a component.

ctComponentType:  An eComponentType (section 2.2.5) value to select the bitness of the component, when there might be multiple bitnesses.

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 perform parameter validation as follows:

  • The server MUST verify that ctComponentType is a valid eComponentType value, that it is not eCT_UNKNOWN, and that it represents a bitness that is supported by the server.

The server then MUST select a target conglomeration based on the value of pwszConglomerationIdOrName as follows:

  • If pwszConglomerationIdOrName is in Curly Braced GUID String Syntax ([MS-DTYP] section 2.3.4.3), the server MUST do the following:

    • The server MUST convert this string to a GUID.

    • If this GUID is the conglomeration identifier of a conglomeration that exists on the server, then the server MUST select that conglomeration. Otherwise, the server MUST return a failure result, as specified in [MS-ERREF] section 2.1.

  • If pwszConglomerationIdOrName is not in Curly Braced GUID String Syntax ([MS-DTYP] section 2.3.4.3), the server MUST verify that there exists a conglomeration with the value pwszConglomerationIdOrName for the Name property (see section 3.1.1.3.3). If so, the server MUST select that conglomeration.

The server then MUST verify that the target conglomeration is contained in the global partition.

The server then MUST select a component to configure, based on the value of pwszCLSIDOrProgId as follows:

  • If the first character of pwszCLSIDOrProgId is not "{", the server MUST determine whether or not there exists a component legacy configuration in the selected conglomeration for which the value of the ProgID (see section 3.1.1.3.1) property is pwszCLSIDOrProgId. If such a component exists, then the server MUST select that component. If no such component exists, the server MUST return a failure result (as specified in [MS-ERREF] (section 2.1)).

  • If the first character of pwszCLSIDOrProgId is "{", the server MUST verify that pwszCLSIDOrProgId is in Curly Braced GUID String Syntax ([MS-DTYP] section 2.3.4.3). The server then MUST determine whether or not there exists a component legacy configuration in the selected conglomeration with the CLSID represented by pwszCLSIDOrProgId. If such a component exists, then the server MUST select that component. If no such component exists, the server MUST return a failure result, as specified in [MS-ERREF] section 2.1.

The server then MUST verify that the existing component legacy configuration for the selected component has the component full configuration specified by ctComponentType.

The server then MUST attempt to remove the existing component legacy configuration for the selected component and create a component full configuration for the selected component and component full configuration in the same conglomeration, using implementation-specific default values for the properties, and fail the call if it cannot.