IRegisterServiceProvider::RegisterService

  • Article
 
Microsoft DirectShow 9.0

IRegisterServiceProvider::RegisterService

The RegisterService method registers an object as a service.

Syntax

  HRESULT RegisterService(
  REFGUID guidService,
  IUnknown *pUnkObject
);

Parameters

guidService

[in] Service identifier (SID) of the service.

pUnkObject

[in] Pointer to the IUnknown interface of the service object, or NULL to unregister the service.

Return Value

Returns an HRESULT value.

Remarks

A service is an interface that a client discovers through the COM IServiceProvider::QueryService method, instead of through the usual IUnknown::QueryInterface method. The difference between the two methods is that QueryInterface returns an interface on the original object, whereas QueryService may return an interface on another object. (More precisely, QueryInterface guarantees that you can query the original interface and the returned interface for IUnknown, and you will get back identical pointers. QueryService does not have this guarantee.)

The RegisterService method enables you to register a service with the Filter Graph Manager. Other objects can then use the IServiceProvider interface to retrieve your object. This facilitates communication between separate COM objects, using the Filter Graph Manager as the central communication point.

A service is identified by a GUID, called the service identifier (SID). One service can support multiple interfaces. To register the service, call RegisterService, as shown in the following code:

DEFINE_GUID(SID_MyService, ....);
IRegisterServiceProvider *pRSP;
hr = pGraph->QueryInterface(IID_IRegisterServiceProvider, (void**)&pRSP);
if (SUCCEEDED(hr))
{
    IUnknown pServiceObj;
    MyCreateServiceHelper(SID_MyService, &pServiceObj);
    pRSP->RegisterService(SID_MyService, pServiceObj);
    pRSP->Release();
    pServiceObj->Release();
}

This example assumes that MyCreateServiceHelper is a helper function that creates the service object. A client could get a pointer to the service object by calling IServiceProvider::QueryService:

IServiceProvider *pSP;
hr = pGraph->QueryInterface(IID_IServiceProvider, (void**)&pSP);
if (SUCCEEDED(hr))
{
    ISomeInterface *pService;
    hr = pSP->QueryService(SID_MyService, IID_ISomeInterface, (void**)&pService);
    pSP->Release();
    if (SUCCEEDED(hr))
    {
        pService->SomeMethod();
        pService->Release();
    }
};

To unregister the service, call RegisterService with a NULL pointer in the second parameter:

pRSP->RegisterService(SID_MyService, NULL);

When the Filter Graph Manager is released, it unregisters all services.

The Filter Graph Manager keeps a reference count on the service object until the service is unregistered. To prevent circular reference counts, the service object should not hold a reference count on the Filter Graph Manager. For example, you cannot use the destructor method of the service object to unregister the service, because as long as the service holds a reference count on the Filter Graph Manager, the destructor will never be called. One solution is to create a separate object that registers and unregisters the service. Or, you can simply release the service object after you register it and let the Filter Graph Manager control its lifetime.

Requirements

Header: Declared in Strmif.h; include Dshow.h.

Library: Use Strmiids.lib.

See Also