C++ _Inout_updates_bytes_ syntax

Question

I am using the mmeapi.h library and went across the functionwaveOutUnprepareHeader() that I would like to know how its syntax works.

mmeapi.h

DECLARE_HANDLE(HWAVEIN);
DECLARE_HANDLE(HWAVEOUT);
FAR *LPWAVEHDR;

minwindef.h

typedef unsigned int        UINT;

mmeapi.h

waveOutUnprepareHeader(
    _In_ HWAVEOUT hwo,
    _Inout_updates_bytes_(cbwh) LPWAVEHDR pwh,
    _In_ UINT cbwh
    );

1. What does _Inout_updates_bytes_(cbwh) do?
2. What does DECLARE_HANDLE do?

Answer 1

These are Microsoft-specific macros which are part of something called SAL.

Microsoft have this to say about the purpose of these macros:

SAL is the Microsoft source code annotation language. By using source code annotations, you can make the intent behind your code explicit. These annotations also enable automated static analysis tools to analyze your code more accurately, with significantly fewer false positives and false negatives.

You will find them liberally scattered about in Microsoft's own header files, so presumably they find them helpful in detecting coding errors. Visual Studio has a code analysis tool that uses them, see:

https://learn.microsoft.com/en-us/cpp/code-quality/code-analysis-for-c-cpp-overview

The purpose of DECLARE_HANDLE is described here.