共用方式為

3.1.4.12.1 ImportFromFile (Opnum 3)

  • 發行項

This method is called by a client to import one or more conglomerations from an installer package file. Importing a conglomeration from an installer package file conceptually consists of installation of modules, including the registration of the components in those modules, and creating a conglomeration and component configurations equivalent to the conglomeration and the component configurations that were exported to create the installer package file. As a side effect, this method returns implementation-specific detailed results of the registration operation for informational purposes.

 HRESULT ImportFromFile(
   [in, string, unique] WCHAR* pwszModuleDestination,
   [in, string] WCHAR* pwszInstallerPackage,
   [in, string, unique] WCHAR* pwszUser,
   [in, string, unique] WCHAR* pwszPassword,
   [in, string, unique] WCHAR* pwszRemoteServerName,
   [in] DWORD dwFlags,
   [in] GUID* reserved1,
   [in] DWORD reserved2,
   [out] DWORD* pcModules,
   [out, size_is(,*pcModules)] DWORD** ppModuleFlags,
   [out, string, size_is(,*pcModules)] 
     LPWSTR** ppModules,
   [out] DWORD* pcComponents,
   [out, size_is(,*pcComponents)] GUID** ppResultCLSIDs,
   [out, string, size_is(,*pcComponents)] 
     LPWSTR** ppResultNames,
   [out, size_is(,*pcComponents)] DWORD** ppResultFlags,
   [out, size_is(,*pcComponents)] LONG** ppResultHRs
 );

pwszModuleDestination:  Either a path in UNC to a directory that is to be used as the installation target location for modules and other files, or NULL to indicate that a directory is to be selected by the server.

pwszInstallerPackage: A path in UNC to a file that the server will recognize as an installer package file.

pwszUser: Either a user account name to be used as the RunAsUser property (see section 3.1.1.3.6) for the newly created conglomerations, or NULL to specify that the RunAsUser property for each conglomeration represented in the installer package file is to be used.

pwszPassword: Either a password to be used as the Password property (see section 3.1.1.3.3) for the newly created conglomerations, or NULL to specify that the Password property is to be set to NULL.

pwszRemoteServerName:  Either a remote server name to be used as the ServerName property (see section 3.1.1.3.6) for the newly created conglomerations if the conglomerations represented in the installer package file are proxy conglomerations; that is, if they have the IsProxyApp property (see section 3.1.1.3.27) set to TRUE (0x00000001)), or NULL for nonproxy conglomerations.

dwFlags: MUST be a combination of zero or more of the following flags.

Flag

Meaning

fIMPORT_OVERWRITE

0x00000001

The server is requested to overwrite existing files when installing modules.

fIMPORT_WITHUSERS

0x00000010

The server is requested to create the role members represented in the installer package file.

reserved1:  A pointer to a GUID value that MUST be GUID_NULL and MUST be ignored on receipt.

reserved2: MUST be set to zero when sent and MUST be ignored on receipt.

pcModules:  A pointer to a variable that, upon successful completion, MUST be set to the number of modules installed from the installer package file.

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

ppModules:  A pointer to a variable that, upon successful completion, MUST be set to an array of strings representing file names of modules installed from the installer package file.

pcComponents:  A pointer to a variable that, upon successful completion, MUST be set to the number of components that the server registered or attempted to register.

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 component that the server registered or attempted to register.

ppResultNames:  A pointer to a variable that, upon successful completion, SHOULD be set to an array of string values, each being an implementation-specific name of a component that the server registered or attempted to register, in the same order as ppResultClsids.

ppResultFlags:  A pointer to a variable that, upon successful completion, SHOULD be set to an array of fComponentStatus (section 2.2.4) values, each representing detailed results for a component that the server registered or attempted to register, in the same order as ppResultClsids.

ppResultHRs:  A pointer to a variable that, upon successful completion, SHOULD be set to an array of LONG values, each representing an HRESULT ([MS-ERREF] section 2.1) for a component that the server registered or attempted to register, 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.

Return value/code

Description

0x00000000

S_OK

The call was successful.

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 pwszModuleDestination is not NULL, the server SHOULD<335> verify that it is a path in UNC, and fail the call if not.

  • The server SHOULD<336> verify that pwszInstallerPackage is a path in UNC, and fail the call if not.

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

The server then MUST verify that the file located by the path exists and is accessible, and that the server recognizes the file as an installer package file, and fail the call if not.

The server then MUST select a GUID to use as the partition identifier for the target partition, as follows:

  • If the import target partition identifier (section 3.1.1.5) is not the partition identifier of the global partition, the server MUST select the import target partition identifier. This behavior enables clients to explicitly specify a target partition.

  • If the client did not explicitly specify a target partition by setting the import target partition identifier, but the installer package file was created by a call to IExport2::ExportPartition (opnum 3) (section 3.1.4.15.1), the server MUST select the partition identifier of the exported partition.

  • If the target partition is not explicitly specified by the client or by an installer package file created by a call to, the server MUST select the partition identifier of the global partition.

The remainder of the protocol behavior specified for this method SHOULD be performed as an atomic transaction, in other words either the operation fully succeeds or the server makes 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 select an existing partition as the target partition, or create a new partition, which will be the target partition, as follows:

  • If the GUID selected previously is the partition identifier of an existing partition on the server, the server MUST perform the following:

    • If the value of the Changeable property (see section 3.1.1.3.6) of the partition is TRUE (0x00000001), the server MUST select the partition as the target partition.

    • Otherwise, the server MUST fail the call.

  • If the GUID selected previously is not the partition identifier of an existing partition, the server MUST perform the following:

    • If the server does not support the multiple-partition capability, as specified in section 3.1.4.3, the server MUST fail the call.

    • If the value of the PartitionsEnabled property (see section 3.1.1.3.8) of the machine settings is FALSE (0x00000000), the server MUST fail the call.

    • Otherwise, the server MUST attempt to create a new partition with the selected GUID as the partition identifier and implementation-specific default values for the rest of the properties, and fail the call if it cannot.

Having selected a target partition, the server then MUST select a GUID to be used as the conglomeration identifier for each conglomeration represented in the installer package file as follows:

  • For each conglomeration represented in the installer package file, the server MUST perform the following:

    • If the conglomeration identifier of the conglomeration represented in the installer package file is equal to the conglomeration identifier of an existing conglomeration on the server, the server MUST perform the following:

      • If the existing conglomeration is in the target partition, the server MUST fail the call.

      • Otherwise, the server MUST attempt to generate a GUID using the mechanism as specified in [C706] section A.2.5, and fail the call if it cannot.

    • Otherwise, the server MUST select the conglomeration identifier of the conglomeration represented in the installer package file.

For each conglomeration represented in the installer package file, the server then MUST attempt to perform an implementation-specific import procedure, and fail the call if it cannot. This document does not specify how this procedure is performed, except that the implementation's export and import procedures SHOULD have round-trip consistency, defined as follows:

  • If a conglomeration on a server is successfully exported to an installer package file by a call to either IExport::ExportConglomeration (opnum 3) (section 3.1.4.14.1) or a call to IExport2::ExportPartition (opnum 3)), and the conglomeration is then successfully imported onto a second server, identical to the first except that the conglomeration possibly does not exist on the second server, then the newly created conglomeration on the second server SHOULD have identical configuration as visible via COMA, with the following exceptions:

    • The partition in which the conglomeration is created MUST be selected as specified previously.

    • The conglomeration identifier of the newly created conglomeration MUST be selected as specified previously.

    • The locations of the files, including modules, created as part of the import operation SHOULD be the location specified by pwszModuleDestination if so specified, and an implementation-specific location if not. Those properties of the entries created that represent paths to files (properties of type ImplementationSpecificPathProperty) SHOULD therefore be based on this destination regardless of their original values on the first server.

    • Files that already exist at the location specified above SHOULD be overwritten only if at least one of the following is true:

      • The fIMPORT_OVERWRITE flag is set in the dwFlags parameter.

      • The installer package file contains an overwrite directive taht was set by a call to IExport::ExportConglomeration (opnum 3) with fEXPORT_OVERWRITE passed in its dwFlags Parameter

    • If neither of the previous conditions is true, and if the import requires that existing files be overwritten, then the server SHOULD fail the call.

    • The RunAsUser property (see section 3.1.1.3.6) SHOULD be the value specified by pwszUser if not NULL.

    • The Password property (see section 3.1.1.3.3) SHOULD be the value specified by pwszPassword.

    • If the exported conglomeration was created as a proxy (see sections 3.1.4.14.1 and 3.1.4.15.1) the IsProxyApp property SHOULD be set to TRUE (0x00000001).

    • The ServerName property (see section 3.1.1.3.6) SHOULD be the value specified by pwszRemoteServerName.

    • If the fIMPORT_WITHUSERS (0x00000010) flag is not set in dwFlags, or if the installer package file was created without exporting user account information (see sections 3.1.4.14.1 and 3.1.4.15.1), each of the newly created conglomeration's roles SHOULD be empty.

The server then SHOULD construct detailed results to return to the client for informational purposes. If the server constructs detailed results, this MUST be performed as follows:

  • If the import was a success, the server MUST select as the set of processed CLSIDs the set of CLSIDs of components that were registered as part of the import. Otherwise, the set of processed CLSIDs SHOULD represent the components that the server attempted to register as part of the import.

  • For each component, 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 implementation-specific DWORD value representing 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 SHOULD set the value reference by ppModules to an array of strings representing file names of modules in the import package file.

  • The server SHOULD set the value referenced by ppModuleFlags to an array of fModuleStatus values, each of which represents the detailed results of the registration or attempt to register a module. 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.