93.4 Function Prototypes

Function prototypes are also provided in three sets, as shown below. The generic function prototype consists of the standard function name implemented as a macro. It evaluates into one of the explicit function prototypes depending on whether the compile time variable UNICODE is defined. The letters A and W are added at the end of the function names in the explicit function prototypes. Note how the generic prototype uses the generic type LPTSTR for the text parameter, but the A&W prototypes use the 8-bit or wide character type LPSTR and LPWSTR instead.

SetWindowText(HANDLE hwnd, LPTSTR lpText);

SetWindowTextA(HANDLE hwnd, LPSTR lpText);

SetWindowTextW(HANDLE hwnd, LPWSTR lpText);

With this mechanism an application can either use the generic function to work transparently with Unicode dependent on the #define UNICODE variable, or, alteratively, it can make mixed calls by using the explicit function names with A and W.

This three-prototype approach applies to all functions with TEXT arguments. In every case, a function whose name ends in W expects wide-character arguments, etc. A generic function prototype should always be used with the generic string and character types.

Where the documentation shows a function prototype with only W/A arguments, this is a function that can only be used with the appropriate data type, independently from the state of the UNICODE variable at compile time.

Note:

Wherever a function has a length parameter for a character string this length should be given as a count of characters in the string (that is, the number of TCHAR units). Exceptions are functions that require or return pointers to untyped memory blocks, such as GlobalAlloc.