3.3.4.5 RestoreHistory (Opnum 38)

The RestoreHistory method restores a metabase history entry for a specific history version.

 HRESULT RestoreHistory(
   [unique, in, string] LPCWSTR pszMDHistoryLocation,
   [in] DWORD dwMDMajorVersion,
   [in] DWORD dwMDMinorVersion,
   [in] DWORD dwMDFlags
 );

pszMDHistoryLocation: A pointer to a Unicode string containing the absolute path to the location of the history files for the metabase. If an empty string is passed to this function, the server SHOULD use the default history path.<25>

dwMDMajorVersion: An integer value containing the predecimal version value of the history entry to restore from. If the dwMDFlags parameter contains the MD_HISTORY_LATEST flag, this value MUST be set to zero.

dwMDMinorVersion: An integer value containing the postdecimal version value of the history entry to restore from. If the dwMDFlags parameter contains the MD_HISTORY_LATEST flag, this value MUST be set to zero.

dwMDFlags: A set of bit flags specifying the options to be executed during the RestoreHistory call.

Value

Meaning

MD_HISTORY_LATEST

0x00000001

Restore to the most recent history file. If this is set, the dwMDMajorVersion and dwMDMinorVersion parameters must be set to zero.

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.

0x80070002

ERROR_FILE_NOT_FOUND

The system cannot find the file specified.

0x80070003

ERROR_PATH_NOT_FOUND

The system cannot find the path specified.

0x8007000E

E_OUTOFMEMORY

Ran out of memory.

0x80070008

ERROR_NOT_ENOUGH_MEMORY

Not enough storage is available to process this command.

0x80070057

E_INVALIDARG

One or more arguments are invalid.

0x80070013

ERROR_INVALID_DATA

One or more arguments are invalid.

0x800703EC

ERROR_INVALID_FLAGS

Invalid flags were passed.

0x80070005

ERROR_ACCESS_DENIED

Access is denied.

0x800CC802

MD_ERROR_INVALID_VERSION

The version specified in metadata storage was not recognized.

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

The opnum field value for this method is 38.

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

  • The server MUST restore the history from the location passed in the pszMDHistoryLocation value. If this location does not exist the server returns the HRESULT derived from the Win32 error code ERROR_PATH_NOT_FOUND.

  • If the pszMDHistoryLocation value passed in is an empty string, the server uses the default history location as defined by the server specific implementation.

  • If the MD_HISTORY_LATEST flag is passed, the server MUST check that dwMDMajorVersion and dwMDMinorVersion are 0 and return the HRESULT derived from the Win32 error code E_INVALIDARG.

  • If the version requested does not exist, the server MUST return the MD_ERROR_INVALID_VERSION error code.

  • If the dwMDFlags value contains anything beyond the expected flag values, the server MUST return the ERROR_INVALID_FLAGS error code.

  • The server replaces the current metabase data with the data from the history entry specified.