IRpcStubBuffer::DebugServerQueryInterface

HRESULT IRpcStubBuffer::DebugServerQueryInterface(ppv)

This function exists in order to facilitate the support of debuggers which wish to provide transparency when single-stepping, and so forth, across remote invocations on objects. As such, the semantics of this function are a little strange in order to avoid unnecessarily disturbing the state of the actual server object.

If the stub is not presently connected, then set *ppv to NULL (per the usual error-case convention) and return E_UNEXPECTED. If connected but this stub does not support the indicated interface (in the sense expressed in IsIIDSupported()), then (set *ppv to NULL and) return E_NOINTERFACE instead.

Otherwise, return the interface pointer on the connected server object which would be used by an immediate subsequent invocation of Invoke() on this interface stub (see the discussion above regarding how interface stubs implicitly know the IID which they are servicing). DebugServerQueryInterface() is analogous to invoking QueryInterface() on the server itself, with the important difference that the caller will later call DebugServerRelease() to indicate that he is done with the pointer instead of releasing the returned pointer himself. It is required that DebugServerRelease() be called before the interface stub itself is destroyed or, in fact, before it is disconnected.

In the vast majority of interface stub implementations, DebugServerQueryInterface() can therefore be implemented simply by returning an internal state variable inside the interface stub itself without doing an AddRef() on the server or otherwise running any code in the actual server object. In such implementations, DebugServerRelease() will be a completely empty no-op. The other rational implementation is one where DebugServerQueryInterface() does a QueryInterface() on the server object and DebugServerRelease() does a corresponding Release(), but as this actually runs server code, the former implementation is highly preferred if at all achievable.

Argument

Type

Description

ppv

void**

The place at which the interface pointer is to be returned.

return value

HRESULT

S_OK, E_NOINTERFACE, E_UNEXPECTED