E_FAIL 或 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

我建议关注the pattern of COM enumerators' Next method 其中检索到的对象数在输出参数中返回。 （S_FALSE 也会在对象计数为零但调用有效时返回）

因为是输出参数，客户端不能忽略，VB等层对用户隐藏HRESULT不会导致信息丢失。

Answer 2

S_FALSE 是成功值，而不是错误值。当方法本身成功但请求的数据不可用或未执行请求的操作时，Microsoft 自己的许多 COM API 都会返回S_FALSE。这在 Microsoft 的文档中有所提及：

Error Handling in COM

所有带有前缀“E_”的常量都是错误代码。常量 S_OK 和 S_FALSE 都是成功代码。大概 99% 的 COM 方法在成功时返回 S_OK；但不要让这个事实误导你。方法可能会返回其他成功代码，因此请始终使用 SUCCEEDED 或 FAILED 宏来测试错误。
...
成功代码 S_FALSE 值得一提。一些方法使用 S_FALSE 粗略地表示不是失败的否定条件。它也可以表示“无操作”——方法成功，但没有效果。例如，如果您从同一线程再次调用CoInitializeEx 函数，它会返回 S_FALSE。如果您需要在代码中区分 S_OK 和 S_FALSE，您应该直接测试该值，但仍然使用FAILED 或SUCCEEDED 来处理其余情况...

我建议你遵循相同的约定，例如：

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) 将是最接近的标准等效项）。