3.3.4.4 Import (Opnum 37)

  • Article

The Import method imports metabase data from an exported file into the metabase.

 HRESULT Import(
   [unique, in, string] LPCWSTR pszPasswd,
   [unique, in, string] LPCWSTR pszFileName,
   [unique, in, string] LPCWSTR pszSourcePath,
   [unique, in, string] LPCWSTR pszDestPath,
   [in] DWORD dwMDFlags
 );

pszPasswd: A pointer to a Unicode string containing the password that will be used to decrypt the secure properties of the metabase data being imported.

pszFileName: A pointer to a Unicode string containing the name of the file, including directory path, to import settings from. This file will have been created using the Export function.

pszSourcePath: A pointer to a Unicode string containing the path to the metabase node being imported from the file specified in pszFileName.

pszDestPath: A pointer to a Unicode string containing the path to the metabase node into which the file data will be imported.

dwMDFlags: A set of bit flags specifying the import operation to be performed. It can be zero or one or more of the following values.

Value

Meaning

MD_IMPORT_INHERITED

0x00000001

Inherited settings that were exported using the MD_EXPORT_INHERITED flag will be imported.

MD_IMPORT_NODE_ONLY

0x00000002

Child nodes will not be imported.

MD_IMPORT_MERGE

0x00000004

Imported settings will be merged with any matching existing node settings.

When a value for a setting is present in the data file and also in the current metabase, the data file setting will overwrite the existing metabase setting.

If this flag is not set and there is a current node in the metabase that conflicts with the node being imported, the imported node will replace the existing node. All settings from the existing node will be lost regardless of whether the imported node contains the setting or not.

Return Values: A signed 32-bit value that indicates return status. If the method returns a negative value, it failed. If the 12-bit facility code (bits 16–27) is set to 0x007, the value contains a Win32 error code in the lower 16 bits. Zero or positive values indicate success, with the lower 16 bits in positive nonzero values containing warnings or flags defined in the method implementation. For more information about Win32 error codes and HRESULT values, see [MS-ERREF].

Return value/code

Description

0x00000000

S_OK

The call was successful.

0x80070003

ERROR_PATH_NOT_FOUND

The system cannot find the file specified.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].

The opnum field value for this method is 37.

When processing this call, the server MUST do the following:

  • The file specified by the pszFileName parameter MUST exist and be local to the server; otherwise the server MUST return ERROR_FILE_NOT_FOUND.

  • The server MUST decrypt data with the password the client has provided.

  • The source path MUST exist in the exported data; otherwise the server MUST return ERROR_PATH_NOT_FOUND.

  • If the destination path exists on the server, the server SHOULD replace it and all settings on it with the data from the data file unless the client has passed the MD_IMPORT_MERGE flag.<24>

  • If the client has passed the MD_IMPORT_MERGE flag and the destination path exists on the server, the server will overwrite any existing settings with data from the data file, but will keep any settings that are not present in the data file.

  • If the MD_IMPORT_INHERITED flag is passed, the server MUST include inherited properties from the data file when importing the data to the server.

  • If the MD_IMPORT_NODE_ONLY flag is passed, the server MUST import only the specified node and its settings. Child nodes MUST NOT be included.