3.3.4.1 BackupWithPasswd (Opnum 34)

The BackupWithPasswd method backs up the metabase using a supplied password to encrypt all secure data.

 HRESULT BackupWithPasswd(
   [unique, in, string] LPCWSTR pszMDBackupName,
   [in] DWORD dwMDVersion,
   [in] DWORD dwMDFlags,
   [unique, in, string] LPCWSTR pszPasswd
 );

pszMDBackupName: The name of the backup that is being created.

dwMDVersion: An integer value specifying either the specific version number to be used for the backup or one of the following flag values. If the version number is an explicit version number, it SHOULD be less than MD_BACKUP_MAX_VERSION (9999).

Value

Meaning

MD_BACKUP_HIGHEST_VERSION

0xFFFFFFFE

Use the highest existing backup version for the backup name specified.

MD_BACKUP_NEXT_VERSION

0xFFFFFFFF

Use the highest existing backup version number plus one for the backup name specified.

dwMDFlags: An integer value containing the bit flags to alter backup functionality. The flags can be zero or one or more of the following values.

Value

Meaning

MD_BACKUP_FORCE_BACKUP

0x00000004

Force the backup even if the SaveData operation specified by MD_BACKUP_SAVE_FIRST fails.

This flag is only specified if MD_BACKUP_SAVE_FIRST is specified.

MD_BACKUP_OVERWRITE

0x00000001

Back up even if a backup of the same name and version exists in the specified backup location, overwriting it if necessary.

MD_BACKUP_SAVE_FIRST

0x00000002

Perform a SaveData operation before the backup.

pszPasswd: A password string used to encrypt the secure properties in the metabase backup. If a password is not supplied, this method functions exactly the same as the Backup method.

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.

0x80070057

E_INVALIDARG

One or more arguments are invalid.

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

The opnum field value for this method is 34.

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

  • Check the pszMDBackupName parameter. If the length of the string is 100 characters or more, or if it contains any characters in the following set ('/', '\', '*', '.', '?', '"', '&', '!', '@', '#', '$', '%', '^', '(', ')', '=', '+', '|', '`', '~'), return E_INVALIDARG.

  • Check the version parameter. If it is greater than the maximum allowed version number and is not MD_BACKUP_HIGHEST_VERSION or MD_BACKUP_NEXT_VERSION, return E_INVALIDARG.

  • If the parameter flags have the MD_BACKUP_SAVE_FIRST bit set, flush the in-memory configuration data first. If this operation fails, check the MD_BACKUP_FORCE_BACKUP bit. If this bit is reset, return an error, otherwise continue the operation.

  • Check the MD_BACKUP_OVERWRITE bit. If it is reset, check whether a backup with the target version exists. If it is true, return an error; otherwise, overwrite the existing backup.

  • If the pszMDBackupName parameter is an empty string, the server uses a default name for the backup.

  • The server saves the persisted data using the backup location and version number as a key so that the data can be restored later.

  • Any encrypted data MUST be stored encrypted with the password the client has provided. If no password is provided, the function behaves exactly as the Backup method.