c++ - E_FAIL or S_FALSE，哪个更适合表示没有这个属性？

Question

我有一个图像检测模块，它被封装为一个 COM 模块。我导出了一个 Key/Value Getter API，例如:GetImageAttr(UINT key, void* pValue);。我们的产品可能会或可能不会在图像上附加特殊结构，因此我的客户可以通过此 API 查询特定结构。

可能的用法如下:

ImageSpecialAttribute attr = {};
HRESULT hr = pImageDetector->GetImageAttr(IMAGE_SPECIAL_ATTRIBUTE, (void*)&attr);

如果图像确实有这样的附加结构，则返回 S_OK 是微不足道的。但如果没有，我应该返回 E_FAIL 还是 S_FALSE？

1. S_FALSE:一切正常，只是图像没有这样的可选属性。

   • 强制用户检查 hr == S_OK
   • 查询没有这种可选属性的图像不是错误。

2. E_FAIL:不!出了点问题。你不应该查询这个键。

   • 客户可以通过 FAILED(hr) 轻松检查
   • 使用此键查询此不存在的值是错误的。

已更新，(感谢 Remy Lebeau)

1. HRESULT_FROM_WIN32(ERROR_NOT_FOUND):不!不存在这样的元素/属性。

   • 客户可以通过 FAILED(hr) 轻松检查
   • 虽然表示错误，但用户还是可以通过查看hr来了解其含义。

Answer 1

S_FALSE 是成功值，不是错误值。当方法本身成功但请求的数据不可用，或者请求的操作未执行时，许多 Microsoft 自己的 COM API 都会返回 S_FALSE。 Microsoft 的文档中提到了这一点:

Error Handling in COM

All of the constants with the prefix "E_" are error codes. The constants S_OK and S_FALSE are both success codes. Probably 99% of COM methods return S_OK when they succeed; but do not let this fact mislead you. A method might return other success codes, so always test for errors by using the SUCCEEDED or FAILED macro.
...
The success code S_FALSE deserves mention. Some methods use S_FALSE to mean, roughly, a negative condition that is not a failure. It can also indicate a "no-op"—the method succeeded, but had no effect. For example, the CoInitializeEx function returns S_FALSE if you call it a second time from the same thread. If you need to differentiate between S_OK and S_FALSE in your code, you should test the value directly, but still use FAILED or SUCCEEDED to handle the remaining cases...

我建议您遵循相同的约定，例如:

HRESULT hr = pImageDetector->GetImageAttr(IMAGE_SPECIAL_ATTRIBUTE, (void*)&attr);
if (SUCCEEDED(hr))
{
    if (hr != S_FALSE)
    {
        // use attribute as needed...
    }
    else
    {
        // attribute not found...
    }
}
else
{
    // error...
}

如果您真的想为不存在的属性返回错误代码，我建议您为该特定条件定义自定义 HRESULT，例如:

#define E_ATTR_NOT_FOUND MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, 1)

或者:

#define E_ATTR_NOT_FOUND HRESULT_FROM_WIN32(ERROR_NOT_FOUND)

然后您可以将该错误返回给调用者，例如:

HRESULT hr = pImageDetector->GetImageAttr(IMAGE_SPECIAL_ATTRIBUTE, (void*)&attr);
if (SUCCEEDED(hr))
{
    // use attribute as needed...
}
else if (hr == E_ATTR_NOT_FOUND)
{
    // attribute not found...
}
else
{
    // error...
}

COM 没有为“未找到”条件定义标准化错误 HRESULT 代码(HRESULT_FROM_WIN32(ERROR_NOT_FOUND) 将是最接近的标准等价物)。