Share via

3.1.4.11.4 RegisterModule2 (Opnum 8)

  • Article

This method is called by a client to register the components in one or more modules and to create component full configurations for those modules in an existing conglomeration. This method supports conglomerations in any partition.

Alternatively, this method can be called to verify modules without actually registering the components. As a side effect, this method returns implementation-specific detailed results of the registration or verification operation for informational purposes.

 HRESULT RegisterModule2(
   [in] GUID ConglomerationIdentifier,
   [in] GUID PartitionIdentifier,
   [in, string, size_is(cModules,)] 
     LPWSTR* ppModules,
   [in] DWORD cModules,
   [in] DWORD dwFlags,
   [in, size_is(cRequested), unique] 
     GUID* pRequestedCLSIDs,
   [in] DWORD cRequested,
   [out, size_is(,cModules)] DWORD** ppModuleFlags,
   [out] DWORD* pcResults,
   [out, size_is(,*pcResults)] GUID** ppResultCLSIDs,
   [out, string, size_is(,*pcResults)] 
     LPWSTR** ppResultNames,
   [out, size_is(,*pcResults)] DWORD** ppResultFlags,
   [out, size_is(,*pcResults)] LONG** ppResultHRs
 );

ConglomerationIdentifier:  The conglomeration identifier of an existing conglomeration on the server, in which the component full configurations are to be created, or against which the modules are to be verified.

PartitionIdentifier:  The partition identifier of the partition in which the conglomeration identified by ConglomerationIdentifier is contained, or against which the modules are to be verified.

ppModules:  An array of one or more strings, each of which is a path in UNC to a file that the server will recognize as a module.

cModules:  The number of elements in ppModules.

dwFlags:  A combination of zero or more of the following flags.

Flag

Meaning

fREGISTER_VERIFYONLY

0x00000020

The server SHOULD verify the modules, but MUST NOT actually register any components.

fREGISTER_EVENTCLASSES

0x00000400

The server MUST configure the components registered by this operation as event classes.

pRequestedCLSIDs:  Either an array of one or more CLSIDs of components to be registered (or verified), or NULL to specify that all components in the modules are to be registered (or verified).

cRequested:  The number of elements in pRequestedCLSIDs.

ppModuleFlags:  A pointer to a variable that, upon successful completion, SHOULD be set to an array of fModuleStatus (section 2.2.3) values representing the detailed results of registration for the modules located by the paths in ppModules, in the same order.

pcResults:  A pointer to a variable that, upon successful completion, MUST be set to the number of result items, as specified later.

ppResultCLSIDs:  A pointer to a variable that, upon successful completion, MUST be set to an array of GUID values, each being the CLSID of a result item, as specified later.

ppResultNames:  A pointer to a variable that, upon successful completion, MUST be set to an array of string values, each being an implementation-specific<325> name of a result item, as specified later, in the same order as ppResultCLSIDs.

ppResultFlags:  A pointer to a variable that, upon successful completion, MUST be set to an array of fComponentStatus (section 2.2.4) values, each representing detailed results for a result item, as specified later, in the same order as ppResultCLSIDs.

ppResultHRs:  A pointer to a variable that, upon successful completion, MUST be set to an array of values, each representing an HRESULT ([MS-ERREF] section 2.1) for a result item, as specified later, in the same order as ppResultCLSIDs.

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:

  • If cModules is zero, the server MUST fail the call.

  • For each element of ppModules, the server MUST verify that its value is not NULL. If ppModules is NULL, the server MUST fail the call.

  • The server SHOULD<326> verify that dwFlags is a valid combination of the flags specified previously, and fail the call if not.

A server MAY legally reject a call with a nonzero number of elements in pRequestedCLSIDs as unsupported, returning a failure result immediately. A server also MAY<327> support a nonzero number of elements in pRequestedCLSIDs for only a subset of the types of modules it supports, returning a failure result after it has analyzed the modules.

If the fREGISTER_VERIFYONLY flag is not set in the dwFlags parameter, the server MUST verify that there exists a partition with the partition identifier specified in PartitionIdentifier, and that there exists a conglomeration in this partition with the conglomeration identifier specified in ConglomerationIdentifier, and fail the call if not. The registration procedure specified later MUST be performed with this conglomeration as the target conglomeration.

If the fREGISTER_VERIFYONLY flag is set in the dwFlags parameter, the server MUST determine whether there exists a partition with the partition identifier specified in PartitionIdentifier and, if so, whether there exists a conglomeration in this partition with the conglomeration identifier specified in ConglomerationIdentifier. If there exists such a conglomeration, the verification procedure MUST be performed as a targeted verification, as specified later, with this conglomeration as the target conglomeration. If not, the verification procedure MUST be performed as an untargeted verification, as specified later.

The remainder of the protocol behavior specified for this method SHOULD<328> 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 process each element of ppModules as specified later, in an arbitrary order selected by the server. Any failure point that follows in this section that specifies the server fail for the module indicates that the server MAY<329> tolerate the failure and continue to the next element of ppModules. If the server tolerates failures, and this failure tolerance results in the call returning S_OK (0x00000000), the server MUST set the flags in the results returned in ppModuleFlags for each module as specified later, so that the client can determine which elements succeeded and which elements failed.

As the server processes the elements of ppModules, it MUST construct a processed CLSIDs set, starting with an empty set, which is used to determine the overall success or failure of the call once all modules have been process.

For each element of ppModules, the server MUST perform the following:

  • The server SHOULD<330> verify that the value of the element is a path in UNC, and fail for the module if not.

  • The server then SHOULD<331> determine whether the file located by the path exists and is accessible via some implementation-specific mechanism, and fail for the module if not.

  • If the file does exist, the server then SHOULD<332> determine whether it recognizes the file as a module, and fail for the module if not.

  • If the file is recognized as a module, the server then MUST, by using an implementation-specific mechanism, attempt to determine the set of components contained in the module, and fail for the module if it cannot.

  • If the client specified a list of CLSIDs in pRequestedCLSIDs, the server MUST select as the set of processed CLSIDs for the module the intersection of the set of CLSIDs of the components contained in the module and the set of CLSIDs in pRequestedCLSIDs. Otherwise, the server MUST select as the set of processed CLSIDs for the module the set of CLSIDs of the components contained in the module.

  • If the fREGISTER_VERIFYONLY flag is set in the dwFlags parameter, the server MUST perform the following:

    • For each CLSID in the set of processed CLSIDs for the module, the server MUST perform the following:

      • If the server is performing a targeted verification, the server MUST verify that there is not an existing component with this CLSID configured in the target conglomeration, and fail for the module if so. If the server is performing an untargeted verification, then this requirement does not apply.

      • The server MUST verify that there is not an existing component with this CLSID that has an existing component legacy configuration, and fail the module if there is.

  • If the fREGISTER_VERIFYONLY flag is not set in the dwFlags parameter, the server MUST perform the following:

    • For each CLSID in the set of processed CLSIDs for the module, the server MUST perform the following:

      • The server MUST, via an implementation-specific mechanism, attempt to register the component in the module with this CLSID, and fail for the module if it cannot. Whether or not it is considered a failure to attempt to register a component that has the same CLSID as a component that already exists is implementation-specific.

      • The server MUST verify that it is possible, according to the constraints specified for component configurations in sections 3.1.1.3.1 and 3.1.1.3.3, to create a component full configuration for the newly registered component in the target conglomeration, and fail if not.

      • The server MUST attempt to create a component full configuration for that component in the target conglomeration, using implementation-specific default values (see section 3.1.1.2.6) for properties except IsEventClass (section 3.1.1.3.1), and fail for the module if it cannot.

      • If the fREGISTER_EVENTCLASSES flag is set in the dwFlags parameter, the server MUST attempt to set the IsEventClass property of the newly created component full configuration to the value TRUE (0x00000001), and fail for the module if it cannot.

      • If the flag fREGISTER_EVENTCLASSES is not set in the dwFlags parameter, the server MUST attempt to set the IsEventClass property of the newly created component full configuration to the value FALSE (0x00000000), and fail for the module if it cannot.

      • The server MAY<333> attempt to create configured interface and configured method entries for the interfaces supported by the registered component, using implementation-specific default values (see section 3.1.1.2.6) for properties, in the newly created component full configuration, and fail for the module if it cannot.

  • The server then MUST attempt to add the set of processed CLSIDs for the module to the set of processed CLSIDs, and fail for the module if it cannot. Collisions SHOULD be tolerated for an untargeted verification and SHOULD NOT be tolerated for a targeted verification. Note that collisions are not possible for registration due to the constraints on component configurations.

Having processed all of the modules, the server MUST determine the success of the call as follows:

  • If the client specified a list of CLSIDs in pRequestedCLSIDs, the server MUST verify that the set of process CLSIDs is identical to the set of CLSIDs in pRequestedCLSIDs, and fail the call if not.

Upon successful completion of the call, the server SHOULD construct the detailed results to return to the client, as specified later. Upon successful completion in which the server failed for any modules, the server MUST do so. If the server constructs detailed results, this MUST be performed as follows:

  • For each processed CLSID, the server MUST perform the following:

    • The server SHOULD select an implementation-specific name string for the CLSID. If the CLSID is the CLSID of a successfully registered component, this SHOULD be the value of the ProgID (see section 3.1.1.3.1) property of the component.

    • The server SHOULD select an fModuleStatus (section 2.2.3) value that representing the detailed results of the registration or verification attempt for the CLSID for informational purposes.

    • The server MUST select an HRESULT value representing the result of the registration or verification attempt for the CLSID. This MUST be S_OK (0x00000000) to represent success, or a failure result, as specified in [MS-ERREF] section 2.1, to represent failure.

The server then MUST set the values referenced by the out parameters as follows:

  • The server MUST set the value referenced by ppModuleFlags to an array of DWORD values, each of which MUST use the flags specified previously with their indicated meaning.

  • If the server constructed detailed results, it MUST set the values referenced by pcResults, pcResultCLSIDs, pcResultNames, pcResultFlags, and pcResultHRs to represent the detailed results. Otherwise, the server MUST set the value referenced by pcResults to zero and the values referenced by pcResultCLSIDs, pcResultNames, pcResultFlags, and pcResultHRs to NULL.

The server MUST then return S_OK (0x00000000) on successful completion, and an implementation-specific failure result, as specified in [MS-ERREF] section 2.1, on failure.