|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here.|
TheValue property is used to indicate an invalid function return value that the caller - by mistake - might test for to see whether a function succeeded or failed. This property is allowed on InvalidCheck attribute.
The InvalidCheck attribute and the Value property provide a mechanism to help test against the correct return value from a function. It tries to address the problem that usually occurs when a function returns 1 for success and 0 for failure and another function returns 1 for success and -1 to indicate failure. The use of slightly different values to indicate different results causes confusion and therefore introduces errors in code. By annotating functions using Value property, you can help callers check the correct return value.
The following code shows how to use the Value property:
[returnvalue:SA_InvalidCheck(Value=0)] int f( ); // 1 and -1 are valid
The Value=0 indicates that checking for the return value of 0 is an error because this function can only return 1 or -1 and 0 is an invalid value.
At the call site, a warning is issued if the caller checks the return value using the following code because 0 is not a valid return value:
if ( f() == 0 )