I have a image detection module which is encapsulated as a COM module. I've exported a Key/Value Getter API like: GetImageAttr(UINT key, void* pValue);. Our product MAY or MAY NOT attach a special structure on image, so my client can query the specific structure through this API.
Possible usage is like:
ImageSpecialAttribute attr = {};
HRESULT hr = pImageDetector->GetImageAttr(IMAGE_SPECIAL_ATTRIBUTE, (void*)&attr);
It is trivial to return S_OK if the image does have such attached structure. But if it doesn't, should I return E_FAIL or S_FALSE?
S_FALSE: Everything is fine, just the image does not have such optional attribute.
- Force user to check hr == S_OK
- Querying a image without such optional attribute is not a error.
E_FAIL: No! Something is wrong. You should not query this key.
- Client can easily check by FAILED(hr)
- Using this key to query this non-existed value is a error.
Updated, (Thanks to Remy Lebeau)
HRESULT_FROM_WIN32(ERROR_NOT_FOUND): No! No such element/attribute existed.
- Client can easily check by FAILED(hr)
- Although it represents a error, users still can know what's the meaning by checking
hr.