如何理解“NTSTATUS”、“NT_SUCCESS” Windows ddk 中的 typedef ？

Question

两个问题：

1.

在“ntdef.h”中，NTSTATUS定义如下：

typedef __success(return >= 0) LONG NTSTATUS;

“__success(return >= 0)”到底是什么？

2、

在“ntstatus.h”中，STATUS_SUCCESS被定义为0。

#define STATUS_SUCCESS   ((NTSTATUS)0x00000000L) // ntsubauth

但是“ntdef.h”中的NT_SUCCESS宏是：

#define NT_SUCCESS(Status) (((NTSTATUS)(Status)) >= 0)

不是应该是“Status == 0”？

Answer 1

__success 是 SpecStrings_strict.h 中定义的“高级注释”，其定义如下。

*  __success(expr) T f() :  indicates whether function f succeeded or
*  not. If  is true at exit, all the function's guarantees (as given
*  by other annotations) must hold. If  is false at exit, the caller
*  should not expect any of the function's guarantees to hold. If not used,
*  the function must always satisfy its guarantees. Added automatically to
*  functions that indicate success in standard ways, such as by returning an
*  HRESULT.

NT_SUCCESS 没有对 STATUS_SUCCESS (0) 进行严格测试的原因可能是其他代码（如 STATUS_PENDING）实际上并不是失败。

Answer 2

片段 __success(return >= 0) 是一个 SAL 注释，它为 PreFast 工具提供了有关宏的预期语义的线索。这用于进行静态分析并识别潜在的错误。

NT_SUCCESS 宏测试 >= 0，因为除了 STATUS_SUCCESS 之外还有其他成功代码。一些成功代码包含有关操作结果的额外信息，尽管目前我只能想到S_FALSE，它通知调用者操作成功，但结果是错误的。通常，成功代码等于或大于零，失败代码小于零。

[严格来说，S_FALSE 是 HRESULT，而不是 NT_STATUS，尽管这两种类型具有相同的大小和相似的约定。]

Answer 3

Michael Fourre 的文章 Annotating for __success() 很好地描述了 __success (存档链接）。

2 的答案是“否”，所有正代码都没有失败。但它们可能意味着“OK”以外的其他含义。