Input and Output Parameter Annotations

The C programming language passes parameters by value, so parameters themselves are always input parameters to a function. However, because C can pass a pointer by value, it is impossible to tell just by looking at the function prototype whether the value that is passed by using a pointer is intended as input to the function, output from the function, or both input and output.

Use the __in, __out, and __inout annotations to direct PFD to check parameters that have these annotations and report any errors if it finds that uninitialized values are used incorrectly:

• If a parameter is marked __in, PFD confirms that the parameter is initialized before the call.

  Note   You can also annotate scalar parameters such as integers or enumerated types with __in. The __in annotation is optional for scalar parameters, but it helps to make code more consistent and readable.

• If a parameter is marked __out, PFD does not check that it is initialized before the call, but assumes that it is initialized after the call and thus is safe to use as an __in parameter to a subsequent function. PFD ignores any __success annotation, and always assumes that the parameter marked __out is valid. To indicate that an __out parameter is not valid in a failure case, use the __on_failure annotation. For more information, see Success and Failure Annotations.

• If a parameter is marked __inout, PFD confirms that the parameter is initialized before the call and assumes that it is safe to use as an __in parameter to a subsequent function.

Note  The __in annotation is typically all that is needed for opaque types like KMDF handles such as WDFDEVICE.

 

 

Send comments about this topic to Microsoft

Build date: 5/3/2011