Win32 API Utilizing MSDN Documentation Using Function Documentation

Example

The documentation for a function is broken down into several sections:

Overview

Describes what the function is used for. This section will also show information about whether the function is depreciated, or may be unavailable in future versions.

Syntax

Shows the declaration of the function from the appropriate source header. It is a quick reference to the function's signature.

Parameters

Explains each of the parameters, whether the parameter is input or output, and other important considerations.

Return Value

This section explains the result of the function call, including how to detect errors, and what additional information is available. (For example, this section will state explicitly if GetLastError will provide additional error handling information.)

Remarks

Covers any additional information required to use the function, such as, information about supporting functions, obtaining appropriate handles, and disposal of resources.

Examples

If this section is available, it has an example of the appropriate use of the function to use as a starting point for implementation.

Requirements

Gives important information about prerequisites for calling the function. This information includes:

• Minimum Supported Client/Server First version of the operating system (supported by Microsoft) to provide the function.
  _{(Note that this field is notoriously misleading. Often, functions are supported in an earlier version of the operating system, but this field only shows the earliest version that is currently supported by Microsoft. For example, the CreateWindow function has been supported since Windows 1.0, but the documentation only shows that it has been supported since Windows 2000. The online version of the MSDN documentation does not indicate that any function was supported in a version of Windows prior to 2000, even though many were. For legacy development, you will need to consult an older version of the SDK documentation, such as might have been shipped on an MSDN CD-ROM. Or, just look in the header files.)}
• Header The SDK header to #include that contains the function declaration. If the function isn't available in a header, this will show information about the procedure to call the function (usually calling GetProcAddress to do run-time dynamic linking).
• Library The library file to pass to the linker to resolve the exported functions.
• DLL The file (as shipped with the operating system) that contains the exported function.
• End of Client/Server Support The last version of Windows to officially support the API.
• Unicode and ANSI names For string functions that have both Unicode and ANSI variants, this lists the actual exported names for the two functions. This is usually just the function name with a W or A suffix (respectively).