Win32 Function Prototypes

Win32 function prototypes are provided in generic, ANSI, and Unicode versions. The documentation provides generic function prototypes, which can be compiled to produce either ANSI or Unicode prototypes. As an example, all three prototypes are shown in the following code sample for the SetWindowText function.

Generic Prototype:

BOOL SetWindowText( 
  HWND hwnd, 
  LPCTSTR lpText 
); 

The header file provides the generic function name implemented as a macro:

#ifdef UNICODE
#define SetWindowText SetWindowTextW
#else
#define SetWindowText SetWindowTextA
#endif // !UNICODE

The preprocessor expands the macro into either the ANSI or Unicode function names, depending on whether UNICODE is defined. The letter A (ANSI) or W (wide) is added at the end of the generic function name, as appropriate. The header file then provides ANSI and Unicode function prototypes, as shown in the following examples.

ANSI Prototype:

BOOL 
WINAPI
SetWindowTextA( 
    HWND hwnd, 
    LPCSTR lpText ); 

Unicode Prototype:

BOOL 
WINAPI
SetWindowTextW( 
    HWND hwnd, 
    LPCWSTR lpText ); 

Note that the generic function prototype uses the generic LPCTSTR for the text parameter, but the ANSI prototype uses LPCSTR, and the Unicode prototype uses LPCWSTR.

You can call the generic function in your application, then define UNICODE when you compile the code to use the Unicode function. To default to the ANSI function, do not define UNICODE. You can mix function calls by using the explicit function names ending with A and W.

This approach applies to all functions with text arguments. Always use a generic function prototype with the generic string and character types. All function names that end with an uppercase W take wide-character arguments. Some functions exist only in wide-character versions and can be used only with the appropriate data types.

The Requirements section in the documentation for each function provides information on the function versions implemented by the system. If there is a line that begins with Unicode, either the function has separate Unicode and ANSI versions, or the function accepts only Unicode strings. Otherwise, the function does not accept strings, or accepts only ANSI strings.

Note  Whenever a function has a length parameter for a character string, the length should be documented as a count of TCHAR values in the string. However, functions that require or return pointers to untyped memory blocks, such as the GlobalAlloc function, are exceptions.