IServiceProvider::QueryService

Returns an interface that is part of a requested service.

HRESULT QueryService(
REFGUID rsid,
REFIID iid,
VOID ** ppvObj
);

Parameters

rsid

[in] Pointer to a service identifier (SID).

iid

[in] Identifier of the interface the caller needs to gain access to.

ppvObj

[out] Indirect pointer to the requested interface.

Return Values

The return value obtained from the returned HRESULT is one of the following:

Return Value	Meaning

S_OK	Success.
E_INVALIDARG	One or more of the arguments is invalid.
E_NOINTERFACE	The requested interface is not part of this service, or the service is unknown.
E_OUTOFMEMORY	Out of memory.

Comments

QueryService returns an indirect pointer to the requested interface in the specified service. The caller is responsible for releasing this pointer when it is no longer needed.

QueryService is similar to the QueryInterface method of IUnknown. The key difference is that QueryInterface on an object returns an interface on the same object, whereas QueryService makes no such guarantee. QueryService on an object may return an interface on the same object or on a different object.

When you call QueryService, you pass both a service identifier (rsid) and an interface identifier (iid). The rsid specifies the service to which you want access, and the iid identifies an interface that is part of the service. In return, you receive an indirect pointer to the interface.

The object that implements the interface may also implement interfaces that are part of other services. Keep in mind the following:

Some of these interfaces may be optional. Not all the interfaces defined in the service description are necessarily present on every implementation of the service (or on every returned object).
Unlike calls to QueryInterface, passing a different service identifier does not necessarily mean that a different COM object will be returned.
The returned object may have additional interfaces that are not part of the definition of the service.

Two different services (SID_SMyService and SID_SYourService, for example) can both specify the use of the same interface, even though the implementation of the interface may have nothing in common between the two services. This works because a call to QueryService (SID_SMyService, IID_IDispatch) can return a different object than QueryService (SID_SYourService, IID_IDispatch). Remember that object identity is not assumed when you specify a different service identifier.

Example

The following example requests the ITrackSelection interface, which is part of the STrackSelection service:

hr = QueryService (SID_STrackSelection, IID_ITrackSelection, &pITS);

For additional information, see Chapter 6, "Services."