3.3.4.2 EnumHistory (Opnum 39)

  • Article

The EnumHistory method returns an enumerated history entry with a supplied index.

 HRESULT EnumHistory(
     [in, out, size_is(MD_BACKUP_MAX_LEN)] LPWSTR  pszMDHistoryLocation,
     [out] DWORD *pdwMDMajorVersion,
     [out] DWORD *pdwMDMinorVersion,
     [out] PFILETIME  pftMDHistoryTime,
     [in]  DWORD dwMDEnumIndex);
 };

pszMDHistoryLocation: A pointer to a Unicode string that on input contains the path to the history files being enumerated. If this is an empty string, the server SHOULD use a default path. If an empty string is passed in, the default history path will be written to the buffer.<22>

pwdMDMajorVersion: A pointer to an integer value containing the predecimal version number for the current enumerated history entry.

pwdMDMinorVersion: A pointer to an integer value containing the postdecimal version number for the current enumerated history entry.

pftdMDHistoryTime: A pointer to a FILETIME structure containing the time stamp for the current enumerated history entry.

dwMDEnumIndex: An integer value containing the current index of the history entry to be enumerated. This value SHOULD start at zero on the first call and SHOULD be increased by one on subsequent calls until the last entry in the history is reached. This indexing is controlled by the client, so the client is responsible for selecting the next history file to be enumerated.

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.

0x00000002

ERROR_PATH_NOT_FOUND

The system cannot find the file specified.

0x00000008

ERROR_NOT_ENOUGH_MEMORY

Not enough storage is available to process this command.

0x00000012

ERROR_NO_MORE_ITEMS

There are no more history versions.

0x0000007A

ERROR_INSUFFICIENT_BUFFER

The data area passed to a system call is too small. In this case the location string does not have enough space to return the path to the history location.

0x80070005

ERROR_ACCESS_DENIED

Access is denied.

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 39.

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

  • If the string passed by the client in the pszMDHistoryLocation parameter is not null-terminated and less than 100 WCHARs, an E_INVALIDARG error code will be returned.

  • If the pszMDHistoryLocation parameter is an empty string, the default history directory will be used, and this value will be written to the pszMDHistoryLocation buffer. Therefore, the history location buffer needs to be large enough to hold this string. Thus, it is expected that the client pass a buffer of 100 WCHARs, even in the case where an empty string is passed.

  • The server will find the history entry that corresponds to the location passed in and the index number. For instance:

    If the index is zero based, then:

    • If the index passed is 3, then the server looks for the fourth file (file number 4) in the directory.

    • If the index passed is 4, then the server looks for the fifth file (file number 5) in the directory.

  • Once the history entry is found, the server will return the version number of the history entry in the two version parameters. The server also will return the file time stamp information in the pftdMDHistoryTime parameter.

  • If the index is past the last file in the history location, the server MUST return an ERROR_NO_MORE_ITEMS error code to indicate that there are no more items to the client.