E_FAIL or S_FALSE, which is more appropriate to represent no such attribute?
<p>I have a image detection module which is encapsulated as a COM module. I've exported a <code>Key/Value Getter</code> API like: <code>GetImageAttr(UINT key, void* pValue);</code>. Our product MAY or MAY NOT attach a special structure on image, so my client can query the specific structure through this API.</p>

<p>Possible usage is like:</p>

<pre><code>ImageSpecialAttribute attr = {};
HRESULT hr = pImageDetector-&gt;GetImageAttr(IMAGE_SPECIAL_ATTRIBUTE, (void*)&amp;attr);
</code></pre>

<p>It is trivial to return <code>S_OK</code> if the image does have such attached structure. But if it doesn't, should I return E_FAIL or S_FALSE?</p>

<ol>
<li><p>S_FALSE: Everything is fine, just the image does not have such optional attribute.</p>

<ul>
<li>Force user to check hr == S_OK</li>
<li>Querying a image without such optional attribute is not a error.</li>
</ul></li>
<li><p>E_FAIL: No! Something is wrong. You should not query this key.</p>

<ul>
<li>Client can easily check by FAILED(hr)</li>
<li>Using this key to query this non-existed value is a error.</li>
</ul></li>
</ol>

<p>Updated, (Thanks to Remy Lebeau)</p>

<ol start="3">
<li><p>HRESULT_FROM_WIN32(ERROR_NOT_FOUND): No! No such element/attribute existed.</p>

<ul>
<li>Client can easily check by FAILED(hr)</li>
<li>Although it represents a error, users still can know what's the meaning by checking <code>hr</code>.</li>
</ul></li>
</ol>