[SOLVED] Microsoft SAL annotation -optional parameter

Microsoft SAL annotation -optional parameter

In winbase.h, DeviceIoControl function is defined like this.

BOOL
WINAPI
DeviceIoControl(
    __in        HANDLE hDevice,
    __in        DWORD dwIoControlCode,
    __in_bcount_opt(nInBufferSize) LPVOID lpInBuffer,
    __in        DWORD nInBufferSize,
    __out_bcount_part_opt(nOutBufferSize, *lpBytesReturned) LPVOID lpOutBuffer,
    __in        DWORD nOutBufferSize,
    __out_opt   LPDWORD lpBytesReturned,
    __inout_opt LPOVERLAPPED lpOverlapped
    );

The parameter lpBytesReturned's annotation is defined optional.
But it is not an optional parameter if caller uses synchronous I/O.
If caller puts Null to lpBytesReturned and uses synchronous I/O, application could be die.

When I make a function, I often face to this problem.
I have no idea how to express this from the SAL.

Is there an annotation to express this?

P.S Please make SAL tag if you can. There is no tag in SO yet.

Solution

This is a limitation of the current version of SAL annotations. The annotations in the SDK and DDK headers have to use _opt when a parameter could be NULL. Without the _opt suffix, you will get too many false positives.

Annotations in the DDK are more powerful and include conditional annotations which allow better control. So if you could figure out from other parameters when the parameter is allowed to be NULL, you could use __drv_when to get better annotations.