SHLWAPI Wrapper Functions

[These functions are available through Windows XP Service Pack 2 (SP2) and Windows Server 2003. They might be altered or unavailable in subsequent versions of Windows.]

The tables in this document list wrapper functions from Shlwapi.dll that provide limited Unicode functionality to Windows 95, Windows 98, and Windows Millennium Edition (Windows Me).

Windows 95, Windows 98, and Windows Millennium Edition (Windows Me) are referred to here as "native ANSI platforms". On native ANSI platforms, these wrapper functions convert the Unicode input string parameters to ANSI and call ANSI versions of functions in the Forwards To column. For example, AppendMenuWrapW calls AppendMenuA, which is the ANSI version of AppendMenu. The other functions follow the same pattern. Any strings returned by the ANSI function are converted to Unicode and returned to the calling application. Aside from the exceptions noted in the Remarks column, the wrapper function has the same syntax and provides the same functionality as the function in the Forwards To column. You should refer to that reference page for detailed usage information.

Security Warning: Multiple Unicode strings can convert to the same ANSI string. Unexpected collisions after conversion could result in unexpected behavior. For example, if CreateEventWrapW is used to create two differently-named events whose names match after conversion from Unicode to ANSI, the second call will return a handle to the same event as the first call, even though the original Unicode strings were different.

Microsoft Windows NT, Windows 2000, Windows XP, Windows Server 2003, and later operating systems are referred to here as "native Unicode platforms". For the most part, on native Unicode platforms, these wrapper functions simply forward input string parameters to the Unicode version of the function in the Forwards To column. For example, AppendMenuWrapW forwards to AppendMenuW, which is the Unicode version of AppendMenu. The other functions follow the same pattern. Any strings that are returned by the Unicode function are returned to the calling application. Aside from the exceptions noted in the Remarks column, the wrapper function has the same syntax and provides the same functionality as the function in the Forwards To column. You should refer to that reference page for detailed usage information.

Security Warning: The security issues noted for the functions in the Forwards To column also apply to the corresponding wrapper functions. For details, see the reference documentation for the function in the Forwards To column.

The wrapper functions in this table are all contained in Shlwapi.dll. To call them, you must use the ordinal listed in the table.

The wrapper functions in the following table do not perform any character set conversion. Instead, they provide limited support for operating system features not available on earlier platforms.

Remarks

(a)

If string conversion is necessary, all strings are converted through the CP_ACP code page.

These functions employ best-fit characters and do not perform default checking when converting from Unicode to ANSI. Furthermore, if the string cannot be converted from Unicode to ANSI, the wrapper function passes a NULL string to the underlying ANSI function. This can occur, for example, when there is insufficient memory. Passing a NULL string may cause some functions to fail with an invalid parameter error, but other functions accept the NULL string and treat it as the intended parameter. For example, an error occurs when the CreateWindowExWrapW function attempts to convert the lpWindowName parameter to ANSI, and CreateWindowEx creates a window with an empty caption. The wrapper does not notify you when these problems have occurred.

The Microsoft Layer for Unicode (MSLU) checks for errors during conversion from Unicode to ANSI and returns appropriate error values. For example, the AppendMenu wrapper function in the MSLU returns 0 if the item was not successfully appended.

(b)

These functions use a delay-loaded link to the appropriate function. This means that the DLL that contains the function in the "Forwards To" column is not loaded by the Shlwapi.dll until a function in that DLL is called. The Microsoft Visual C++ linker supports this functionality more generally via the /DELAYLOAD option.

(c)

This function manipulates filenames. As noted in (a), the functions convert all strings through the CP_ACP code page. They do not check whether the file I/O functions have been set to ANSI mode. If the file I/O functions are in OEM mode, the strings will be converted to and from the wrong character set. An application can set the file I/O functions to OEM mode explicitly by calling the SetFileApisToOEM function.

**Security Warning:  ** Using these wrapper functions for file names can compromise the security of your application. Since no default checking is performed and best-fit characters are employed, filename characters can be converted in unexpected ways. This could result in file system spoofing attacks. Also, silent data loss can occur during the conversion from Unicode to ANSI.

The MSLU does not have these limitations.

(d)

If the string being drawn requires a character set that is not available in the font that is selected into the device context, these wrapper functions use the Font Linking feature of the MLang library to render each character in an appropriate font. Unlike most other wrapper functions, these are functional on Microsoft Windows NT 4.0 in addition to native ANSI platforms.

(e)

Full Unicode implementations of these functions are available on native ANSI platforms. These functions do not call the related ANSI function.

(f)

If the user-default UI language uses a different character set than the system-default UI language, the system attempts to rewrite dialog templates and subclass controls and convert menu items to owner-draw, so that strings in the user-default UI language continue to display correctly. The only controls supported by the dialog template rewrite rules are static, button, listbox, and combobox controls. These controls are subclassed such that the SendMessageWrapW function can obtain the original Unicode string without being translated through the ANSI character set. Unlike most of the other wrapper functions, these are functional on Microsoft Windows NT 4.0 as well as native ANSI platforms. See the remarks in the documentation of the MLLoadLibrary function for further discussion of how the user-default UI language and system-default UI language are determined.

(g)

If string conversion is necessary, all strings are converted through the CP_ACP code page.

When converting from ANSI to Unicode for output, if the returned string does not fit in the buffer that was provided, the wrapper functions truncate the string. Those functions that return the number of characters copied to the buffer or the number of characters necessary to avoid truncation do not return the number of Unicode characters copied to the buffer provided by or required from the caller of the wrapper function. They return the number of ANSI characters copied to the buffer or required by the underlying ANSI function. The MSLU does not have these limitations.

(h)

On systems prior to Windows XP, these functions implement a simplified thread pool and timer queue. On Windows XP and later, these functions use the system thread pool and system timer queue. For the timer queue functions, the hQueue parameter must be set to NULL to indicate that the operation is to be performed on the default timer queue.

(i)

On Unicode platforms, these functions translate the message from Unicode to ANSI if the destination window is ANSI. These functions do not perform message translation on native ANSI platforms. Therefore, calling applications calling this function must ensure that the message is in Unicode format on Unicode platforms and in ANSI format on ANSI platforms. For instance, in the following function call, the wParam must be a Unicode code point if the program is running on a Unicode platform and must be an ANSI character if the program is running on an ANSI platform.

CallWindowProcWrapW(prevWndProc, hwnd, WM_CHAR, wParam, lParam);

The MSLU tracks the character set of the destination window procedure and converts the message as necessary.

(j)

On ANSI platforms, these functions return the length of the underlying ANSI string, not the length of the translated Unicode string. The MSLU does not have these limitations.

(CompareExchange)

The syntax for SHInterlockedCompareExchange is somewhat different from that of InterlockedCompareExchangePointer, but it functions identically.

void* SHInterlockedCompareExchange(void **ppDest, void *pExch, void *pComp);

(CompareString)

Remember that on native ANSI platforms, both strings are converted to ANSI and compared as ANSI strings. If the Unicode strings contain characters that cannot be represented in ANSI, the results may be unexpected. For example, if the default ANSI code page does not support CJK characters, then the strings L"\x66F0" and L"\x6708" would compare as equal on native ANSI platforms because they both map to the ANSI string "?".

(DateTime)

On Shlwapi.dll version 5.0, which shipped with Windows 2000, the code page of the locale identifier that you pass as the first parameter of GetDateFormatWrapW and GetTimeFormatWrapW must match the current ANSI codepage. Otherwise, the returned string may be converted incorrectly. This limitation does not apply to Shlwapi.dll versions 5.5 or higher. This means that Windows XP and later systems are not subject to this limitation. The MSLU does not have this limitation.

(DialogBoxParam)

The lpTemplateName parameter for the DialogBoxParamWrapW function cannot be a string. It must be an ordinal created by the MAKEINTRESOURCE macro. The dialog procedure specified by the lpDialogFunc parameter receives ANSI messages on native ANSI platforms and Unicode messages on native Unicode platforms. The dialog procedure must be prepared to handle both cases. The MSLU does not have these limitations.

(ExtTextOut)

Native ANSI platforms implement the ExtTextOutW function as well as native Unicode platforms. The purpose of ExtTextOutWrapW is to perform font linking, as described in a separate remark.

(DragQueryFile)

The DragQueryFileWrapW function does not allow you to query for the length of a file in the drop handle by passing NULL as the lpszFile parameter. The MSLU does not have these limitations.

(FormatMessage)

On native ANSI platforms, the formats in the string are not converted from Unicode to ANSI. For example, the following code example is in error.

WCHAR szBuffer[MAX_PATH];
DWORD_PTR Arguments[2] = { L"String1", L"String2" };

FormatMessageWrapW(FORMAT_MESSAGE_FROM_STRING, 
               L"%1!s! %2", 
               0, 0, 
               szBuffer, 
               MAX_PATH, 
               (va_list*)Arguments);

This code example uses the "!s!" format. On native ANSI platforms, this string is passed to the ANSI version of the FormatMessage function. Consequently, an ANSI string is expected instead of a Unicode string. Similarly, the "%2" format implies a string argument. When it is passed to the ANSI FormatMessage function, it is interpreted as an ANSI string rather than a Unicode string. The correct format string is L"%1!ws! %2!ws!". This prints strings correctly on both ANSI and Unicode platforms.

The function does not support the "%0" special format string.

The MSLU does not have these limitations.

(GetClassInfo)

On native ANSI platforms, the lpszMenuName and lpszClassName members of the WNDCLASS structure are not translated to Unicode and are always set to NULL. Furthermore, the window procedure returned in the lpfnWndProc member of the WNDCLASS structure is not translated to Unicode, and refers to an ANSI window procedure. The MSLU does not have these limitations.

(Menu)

On Shlwapi.dll version 5.0, which shipped with Windows 2000, menu item strings that contain tab characters (\t) may not display correctly. This limitation does not apply to Shlwapi.dll versions 5.5 or higher. This means that Windows XP and later systems are not subject to this limitation. The MSLU does not have this limitation.

(MenuItemInfo)

This function only supports the Microsoft Windows NT 4.0 version of the MENUITEMINFOW structure. This structure lacks an hbmpItem member. In addition, the function does not support the MIIM_BITMAP flag. The MSLU does not have these limitations.

(OpenFileName)

The cbSize member of the OPENFILENAMEW structure must be set to sizeof(OPENFILENAME_NT4W).

The lpstrCustomFilter member of the OPENFILENAMEW structure must be set to NULL.

The values of the nMaxFile and nMaxFileTitle members of the OPENFILENAMEW structure must not exceed MAX_PATH.

If the lpfnHook member of the OPENFILENAMEW structure is not NULL, it must refer to an ANSI hook procedure on native ANSI platforms and a Unicode hook procedure on native Unicode platforms.

The MSLU does not have these limitations.

(PeekMessage and PostMessage)

On native ANSI platforms, no translation is performed on the transmitted or retrieved message. The transmitted/retrieved message is ANSI on native ANSI platforms and Unicode on native Unicode platforms. The calling application must be prepared to handle both cases. For example, if the retrieved message is WM_CHAR, then the wParam is an ANSI character code on native ANSI platforms but it is a Unicode code point on native Unicode platforms. The MSLU does not have these limitations.

(QueueUserWorkItem)

The SHQueueUserWorkItem function is slightly different from the corresponding QueueUserWorkItem function. The syntax for SHQueueUserWorkItem is shown here.

BOOL SHQueueUserWorkItem(LPTHREAD_START_ROUTINE pfnCallback,
                     LPVOID pContext,
                     LONG lPriority,
                     DWORD_PTR dwTag,
                     DWORD_PTR * pdwId,
                     LPCSTR pszModule,
                     DWORD dwFlags);

The parameters should be set as follows:

• The pfnCallback and pContext parameters have the same meanings as the Function and Context parameters, respectively, of QueueUserWorkItem.

• The dwTag parameter is unused and must be set to 0.

• The pdwld parameter is unused and must be set to NULL.

• The pszModule parameter points to an optional null-terminated ANSI string that specifies the name of a library to be loaded before the work item begins and unloaded after the work item completes. This parameter can be NULL.

• The dwFlags parameter supports only a subset of the values supported by QueueUserWorkItem. The following flags are recognized.

  Name	Value	Meaning
  TPS_EXECUTEIO	0x00000001	Same as WT_EXECUTEINIOTHREAD.
  TPS_LONGEXECTIME	0x00000008	Same as WT_EXECUTELONGFUNCTION.

   

  Note

  The TPS_LONGEXECTIME flag does not have the same numerical value as the WT_EXECUTELONGFUNCTION flag. When using SHQueueUserWorkItem, the dwFlags parameter must be a combination of TPS_* values, not WT_* values.

   

SHQueueUserWorkItem returns a nonzero value if the work item was successfully queued and 0 otherwise. If the function fails, you can use GetLastError to obtain additional information.

(RegisterClass)

On native ANSI platforms, no translation is performed on the lpfnWndProc member of the WNDCLASSW structure. The window will receive ANSI window messages on native ANSI platforms and Unicode window messages on native Unicode platforms. The window procedure must be prepared to handle both cases. The MSLU does not have these limitations.

(RegQueryValueExW)

RegQueryValueExWrapW has also been called under the name RegQueryValueExW. As with any unnamed function exported strictly by ordinal, you can choose the name that the function is known by in your code.

(SendMessage)

On native Unicode platforms, the SendMessageWrapW function forwards to the SendMessageW function. On native ANSI platforms, SendMessageWrapW provides limited support for translating Unicode messages to ANSI. The list of supported messages is given in the following table. The function will not translate any other messages.

The MSLU does not have these limitations.

• (a) The ANSI string being measured or retrieved must satisfy the following condition: the length of the corresponding Unicode version of the string cannot exceed the length of the ANSI version of the string. If this condition is not met, the returned length will be short. If there is insufficient memory to determine the length of the Unicode string, the function returns zero, not LB_ERR or CB_ERR as might be expected.

• (b) If string conversion is necessary, all strings are converted through the CP_ACP code page.

  This function employs best-fit characters and does not perform default checking when converting from Unicode to ANSI. Furthermore, if the string cannot be converted from Unicode to ANSI, the function passes a null string to the underlying ANSI function. This can occur, for example, when there is insufficient memory. Passing a null string may cause some functions to fail with an invalid parameter error, but other functions accept the null string and treat it as the intended parameter. For example, if an error occurs when the WM_SETTEXT wrapper attempts to convert the window title to ANSI, the window will have an empty caption. The function does not notify you when these problems occur. The MSLU does not have these limitations.

• (c) The specified window handle must be the handle to a ComboBox or ComboBoxEx control. If the handle is to a combobox control that is owner-draw and was not created with the List Box Styles style, then the translation of this message will fail and may even crash.

• (d) The specified window handle must be the handle to a listbox control. If the listbox is owner-draw and was not created with the List Box Styles style, then the translation of this message will fail and may even crash.

• (e) If string conversion is necessary, all strings are converted through the CP_ACP code page.

  When converting from ANSI to Unicode for output, the wrapper functions truncate the returned string if it does not fit in the provided buffer. The return value for functions that return the number of characters copied to the buffer or the number of characters necessary to avoid truncation refers to the number of ANSI characters copied to the buffer or required by the underlying ANSI function, not the number of Unicode characters copied to the buffer provided by or required from the calling application that called the wrapper function. The MSLU does not have this limitation. For further details, see Microsoft Layer for Unicode on Windows 95/98/Me Systems.

(SetTimerQueueTimer)

The SHSetTimerQueueTimer function is slightly different from the corresponding CreateTimerQueueTimer function. Its syntax is as follows:

HANDLE SHSetTimerQueueTimer(HANDLE hQueue,
                        WAITORTIMERCALLBACK pfnCallback,
                        LPVOID pContext,
                        DWORD dwDueTime,
                        DWORD dwPeriod,
                        LPCSTR lpszLibrary,
                        DWORD dwFlags);

The parameters should be set as follows:

• The hQueue parameter must be set to NULL, specifying the default timer queue.

• The pfnCallback, pContext, dwDueTime, and dwPeriod parameters have the same meanings as the Callback, Parameter, DueTime, and Period parameters, respectively, of CreateTimerQueueTimer.

• The lpszLibrary parameter is unused and must be set to NULL.

• The Flags parameter supports only a subset of the values supported by CreateTimerQueueTimer.

  Name	Value	Meaning
  TPS_EXECUTEIO	0x00000001	Same as WT_EXECUTEINIOTHREAD
  TPS_LONGEXECTIME	0x00000008	Same as WT_EXECUTELONGFUNCTION

   

  Note

  The TPS_LONGEXECTIME flag does not have the same numerical value as the WT_EXECUTELONGFUNCTION flag. When using SHSetTimerQueueTimer, the dwFlags parameter must be a combination of TPS_* values, not WT_* values.

   

SHSetTimerQueueTimer returns the handle of the created timer on success and NULL otherwise.

(ShellExecuteEx)

The lpFile member of the SHELLEXECUTEINFO structure passed in this function's only parameter may not exceed INTERNET_MAX_URL_LENGTH characters. If the SEE_MASK_CLASSNAME flag is omitted, the lpClass member must be initialized to NULL.

(ValueEx)

Only the following registry data types are supported: REG_SZ, REG_EXPAND_SZ, REG_BINARY, and REG_DWORD. Unlike these wrapper functions, the MSLU also supports REG_MULTI_EXPAND_SZ.

(WindowLong)

On native ANSI platforms, the function performs no translation on any of the window longs. For example, if you pass GWLP_WNDPROC, the function returns the ANSI window procedure, not a thunk. The MSLU does not have these limitations.