Explaining the declaration/definition of HRESULT

Question

I just looked at the definition of HRESULT in VS2008. WinNT.h has the following line:

typedef __success(return >= 0) long HRESULT;

What exactly does it mean? It doesn't even look like C or C++ to my untrained eye

Answer 1

It is an annotation. In short,

__success(expr)

means that expr describes the conditions under which a function is considered to have succeeded. For functions returning HRESULT, that condition is that the return value (since HRESULT is a long) is non-negative. All functions returning HRESULT have this annotation applied to them because of this typedef.

Probably way more detail than you will ever want in MSDN on SAL Annotations, The Evolution of HRESULT From Win32 and Success and Failure Annotations.

Answer 2

The Windows API is using macro black magic here to create thier own programming language. You needed to keep digging.

__success is defined as:

sal.h:

#define __success(expr)                     __inner_success(expr)

...and inner_success is defined as:

#define __inner_success(expr)

...which is nothing. So the HRESULT typedef reduces to:

typedef long HRESULT;

Answer 3

This MS-specific keyword is for static code analysis tools.

It helps by hint on how to check whether function's return code means that it completed the task properly.

For instance, see http://msdn.microsoft.com/en-us/library/aa468782.aspx