Annotation (SAL) of the day: __reserved

I just stumbled across the __reserved (as in reserved for future or system use) annotation today.  Unlike the __fallthrough annotation (which I wrote about before because I liked the standardized way of conveying its meaning) __reserved will actually affect how PreFAST evaluates your code, or in this case, how it evaluates the function your code is calling.  __reserved enforces that the parameter being passed in must by NULL or 0.  While you could have reserved parameters in your own functions and it to your own code, it is more likely that you will encounter this annotation when PreFAST's analyzes your code calling a function provided by Microsoft. 

Here are 2 examples of functions that use this annotation, one from kernel mode and one from user mode

 NTSYSAPI
NTSTATUS
NTAPI
ZwCreateKey(
    __out PHANDLE KeyHandle,
    __in ACCESS_MASK DesiredAccess,
    __in POBJECT_ATTRIBUTES ObjectAttributes,
     __reserved ULONG TitleIndex,
    __in_opt PUNICODE_STRING Class,
    __in ULONG CreateOptions,
    __out_opt PULONG Disposition
    );


WINSETUPAPI
BOOL
WINAPI
SetupIterateCabinetW(
    __in PCWSTR CabinetFile,
     __reserved DWORD Reserved,
    __in PSP_FILE_CALLBACK_W MsgHandler,
    __in PVOID Context
    );