Conventions for Function Prototypes

The Azure Service Runtime Native Library provides function prototypes in generic, UTF-8, and Unicode versions. The prototypes can be compiled to produce either UTF-8 prototypes or Unicode prototypes. All three prototypes are discussed in this topic and are illustrated by code samples for the RoleEnvironmentGetConfigurationSetting Function function.

The Azure Service Runtime Native Library defines all functions using STDAPI, which indicates that the function returns an HRESULT.

The following is an example of a generic prototype.

STDAPI
RoleEnvironmentGetConfigurationSettingValue(
    __in LPCTSTR name,
    __out_ecount(cchDest) LPTSTR pszDest,
    __in size_t cchDest,
    __out_opt size_t *pcchRequiredDestSize);

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

#ifdef UNICODE
#define RoleEnvironmentGetConfigurationSettingValue  \ 
        RoleEnvironmentGetConfigurationSettingValueW
#else
#define RoleEnvironmentGetConfigurationSettingValue \ 
        RoleEnvironmentGetConfigurationSettingValueA
#endif /* !UNICODE */
#endif

The preprocessor expands the macro into either the UTF-8 or Unicode function name. The letter "A" (UTF-8) or "W" (Unicode) is added at the end of the generic function name, as appropriate. The header file then provides two specific prototypes, one for UTF-8 and one for Unicode, as shown in the following examples.

STDAPI
RoleEnvironmentGetConfigurationSettingValueA(
    __in LPCSTR name,
    __out_ecount(cchDest) LPSTR pszDest,
    __in size_t cchDest,
    __out_opt size_t *pcchRequiredDestSize

STDAPI
RoleEnvironmentGetConfigurationSettingValueW(
    __in LPCWSTR name,
    __out_ecount(cchDest) LPWSTR pszDest,
    __in size_t cchDest,
    __out_opt size_t *pcchRequiredDestSize);

As explained in Windows Data Types for Strings, the generic function prototype uses the data type LPCTSTR for the text parameter. However, the Windows code page prototype uses the type LPCSTR, and the Unicode prototype uses LPCWSTR.

For all functions with text arguments, applications should normally use the generic function prototypes. If an application defines "UNICODE" either before the #include statements for the header files or during compilation, the statements will be compiled into Unicode functions.

Your application should always use a generic function prototype with the generic string and character types. All function names that end with an uppercase "W" take Unicode, that is, wide character, parameters.

See Also

Conventions for Function Prototypes (Windows API)
Unicode in the Windows API
STDAPI