Win32 helpers

WIL Win32 helpers assist with various functions and data types used by Win32.

Usage

The Win32 helpers can be used by including the correct header file:

#include <wil/win32_helpers.h>

String length constants

All string length constants are in the wil namespace and have type size_t.

Name	Value	Meaning
max_path_segment_length	254	Maximum length of a directory or file name. Does not include terminating null.
max_path_length	259	Maximum length of a MAX_PATH path. Does not include terminating null.
max_extended_path_length	32743	Maximum length of an extended path. Does not include terminating null.
guid_string_buffer_length	39	Size of buffer to hold a GUID string, including enclosing curly braces and terminating null.
guid_string_length	39	Length of a GUID string, including enclosing curly braces but not the terminating null.

The unusual value for max_extended_path_length comes from the system limit of 0x7FFF minus 24, where 24 is the length of the \Device\HardDiskVolume# prefix. If the path refers to the 10th through 99th hard disk volume, then the prefix grows to 25 characters, and the corresponding maximum length decreases by one.

File time constants

The file time constants are in the wil::filetime_duration namespace. They are all long long and represent the number of FILETIME units (100ns) contained in various well-known durations.

Name	Value
one_millisecond	10000
one_second	10000000
one_minute	600000000
one_hour	36000000000
one_day	864000000000

File time helpers

The file time helpers are in the wil::filetime namespace.

• unsigned long long to_int64(const FILETIME &ft)
FILETIME from_int64(unsigned long long i64)

  • The conversion functions convert between a FILETIME structure (two 32-bit integers) and a 64-bit unsigned integer.

• FILETIME add(_In_ FILETIME const &ft, long long delta)

  • Adjusts the value in an existing FILETIME structure by the specified number of ticks.

• bool is_empty(const FILETIME &ft)

  • Returns true if the FILETIME is all zeros.

• FILETIME get_system_time()

  • Returns the system time as a FILETIME.

Functions returning variable-sized strings

Many Win32 functions return a variable-sized string into a caller-provided buffer. The AdaptFixedSizeToAllocatedResult template function implements the common pattern of requesting the string into a buffer, retrying with a larger buffer if needed.

template<typename string-type, size_t stackBufferLength = 256>
HRESULT AdaptFixedSizeToAllocatedResult(string_type& result, wistd::function<HRESULT(PWSTR, size_t, size_t*)> callback);

Calls the callback repeatedly with larger and larger buffers until it is able to produce the desired string. The buffer is then returned in the form of a string_type. Returns a COM error code on failure, in which case the result is left unchanged.

• string_type can be any type supported by string_maker.
• stackBufferLength is the size of the stack buffer used by the initial query. Choose a value that is likely to be sufficient for most use cases, since that provides the shorter execution path where no retry is needed.
• callback retrieves the return into the provided buffer and returns the actual or required size. It is usually passed as a lambda.

HRESULT callback(PWSTR value, size_t valueLength, size_t* valueLengthNeededWithNul);

• value is a pointer to a buffer to be filled.
• valueLength is the size of the buffer, including the space for the null terminator.
• valueLengthNeededWithNul receives the required size of the buffer, including the space for the null terminator.

If the callback is able to read the entire string, then valueLengthNeededWithNul receives the exact size of the result string (including the null terminator), and the callback returns S_OK.

If the callback is not able to read the entire string due to the buffer being too small, then valueLengthNeededWithNul receives the size of the buffer to be used for the next iteration, and the callback returns S_OK. Most of the time, the Win32 function you are wrapping will give you a suggested size for the next iteration. Otherwise, you may need to use a heuristic, like (std::max)(40, valueLength * 2), but taking care to avoid integer overflow.

If the callback is unable to obtain the string at all, then it returns a COM error code, which is propagated as the return value from AdaptFixedSizeToAllocatedResult. In this case, the value in valueLengthNeededWithNul is not used.

Note: The parameters used by AdaptFixedSizeToAllocatedResult do not follow the usual naming convention that Length is the length without the null terminator, and Size is the size including the null terminator. For that we apologize.