SHGetPerScreenResName

This function obtains a string to describe the screen resolution for use with a view state.

Declaration

int
SHGetPerScreenResName (
    LPWSTR pszBuffer,
    int cchBuffer,
    DWORD dwReserved);

Parameters

The pszBuffer and cchBuffer arguments provide the address and size, in Unicode characters, of a buffer in which to receive the per-screen resolution name as a null-terminated Unicode string.

The dwReserved argument has unknown significance except that it must be zero.

Return Value

The function returns the length, in characters, of the generated name. It returns zero on failure.

Behaviour

The function fails trivially if dwReserved is not zero. Otherwise, the per-screen resolution name is generated and as much as possible is copied to the given buffer. The name is formed as the screen width and height, separated by an “x”, followed by the number of monitors, in brackets. All three numbers are decimal.

Use by Microsoft

The only known use that Microsoft makes of this function in executables distributed with Windows is for BROWSEUI.DLL and SHELL32.DLL when loading and saving view states for browsed folders. Though the function is used by two executables, it really is joint use: the relevant code is from the one source file (PROPERTYBAG.CPP) that the two executables share at link-time via a library (STOCK4.LIB). Five properties have a screen resolution string added to their names. BROWSEUI manages the MinPos, MaxPos and WinPos properties. SHELL32 manages ItemPos and ScrollPos.

Availability

The SHGetPerScreenResName function is exported from SHLWAPI as ordinal 533 in version 6.00 and higher.

Though this function dates from 2001, it was still not documented by Microsoft in the MSDN Library at least as late as the CD edition dated January 2004.