IServiceProvider::QueryService

Returns a pointer to 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 to which the caller needs to gain access.

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	Not enough memory is available to complete the operation.

Comments

The host implements this method.

A designer calls QueryService to get an indirect pointer to a requested interface in a specified service. The designer 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 calling QueryService, a designer passes both a service identifier (rsid) and an interface identifier (iid). The rsid specifies the service to which the designer requires access, and the iid identifies an interface that is part of the service. In return, the designer receives 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 the same 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);

See Chapter 6, "Services," for more information.