Should an implementor of IShellBrowser::QueryActiveShellView Method call AddRef for the caller?

Question

I am attempting to implement an IShellBrowser. One method of such is:

HRESULT STDMETHODCALLTYPE IShellBrowser::QueryActiveShellView(/* [out] */ __RPC__deref_out_opt IShellView **ppshv)

This gets the active shell view pointer for the caller (in my case, there is only one shell view at any given time).

But it is very unclear whether I should call AddRef on behalf of the caller, or whether it is in fact the caller's responsibility to do their own AddRef/Release?

I'm not at all a fan of programming-by-side-effect - and that's exactly what AddRef would be - a hidden expectation on the caller, that the caller wouldn't necessarily know about.

And looking at the docs for IShellBrowser::QueryActiveShellView, they make no mention of it at all. But looking at IUnknown::AddRef, we see that any method that makes a copy of an interface pointer should call AddRef - http://msdn.microsoft.com/en-us/library/ms691379%28VS.85%29.aspx

Call this method for every new copy of an interface pointer that you make. For example, if you are passing a copy of a pointer back from a method, you must call AddRef on that pointer.

Answer 1

Yes, COM has a very detailed contract on this behavior: all [out] parameters must be copied (in the case of value types) or AddRef:ed (in the case of interface pointers).

So, you should definitely AddRef.

Answer 2

It's a typical situation - you pass ownership of the interface pointer to the caller. So you call AddRef() and the caller will call Release() when it no longer needs the object pointed to.