Edit

Service Map Macros

  • Article

These macros define service maps and entries.

Name Description
BEGIN_SERVICE_MAP Marks the beginning of an ATL service map.
END_SERVICE_MAP Marks the end of an ATL service map.
SERVICE_ENTRY Indicates that the object supports a specific service ID.
SERVICE_ENTRY_CHAIN Instructs IServiceProviderImpl::QueryService to chain to the specified object.

Requirements

Header: atlcom.h

BEGIN_SERVICE_MAP

Marks the beginning of the service map.

BEGIN_SERVICE_MAP(theClass)

Parameters

theClass
[in] Specifies the class containing the service map.

Remarks

Use the service map to implement service provider functionality on your COM object. First, you must derive your class from IServiceProviderImpl. There are two types of entries:

Example

BEGIN_SERVICE_MAP(CMyService)
   SERVICE_ENTRY(SID_SBindHost)  // This object supports the SBindHost service
   SERVICE_ENTRY_CHAIN(m_spClientSite) // Everything else, just ask the container
END_SERVICE_MAP()

END_SERVICE_MAP

Marks the end of the service map.

END_SERVICE_MAP()

Example

See the example for BEGIN_SERVICE_MAP.

SERVICE_ENTRY

Indicates that the object supports the service id specified by SID.

SERVICE_ENTRY( SID )

Parameters

SID
The service ID.

Example

See the example for BEGIN_SERVICE_MAP.

SERVICE_ENTRY_CHAIN

Instructs IServiceProviderImpl::QueryService to chain to the object specified by punk.

SERVICE_ENTRY_CHAIN( punk )

Parameters

punk
A pointer to the IUnknown interface to which to chain.

Example

See the example for BEGIN_SERVICE_MAP.

IServiceProviderImpl::QueryService

Creates or accesses the specified service and returns an interface pointer to the specified interface for the service.

STDMETHOD(QueryService)(
    REFGUID guidService,
    REFIID riid,
    void** ppvObject);

Parameters

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

riid
[in] Identifier of the interface to which the caller is to gain access.

ppvObj
[out] Indirect pointer to the requested interface.

Return Value

The returned HRESULT is one of the following values:

Return value Meaning
S_OK The service was successfully created or retrieved.
E_INVALIDARG One or more of the arguments is invalid.
E_OUTOFMEMORY Memory is insufficient to create the service.
E_UNEXPECTED An unknown error occurred.
E_NOINTERFACE The requested interface isn't part of this service, or the service is unknown.

Remarks

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

When you call QueryService, you pass both a service identifier (guidService) and an interface identifier (riid). The guidService specifies the service to which you want access, and the riid 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 might also implement interfaces that are part of other services. Consider the following possibilities:

  • Some of these interfaces might be optional. Not all 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 doesn't necessarily mean that a different Component Object Model (COM) object is returned.

  • The returned object might have other interfaces that aren't part of the definition of the service.

Two different services, such as SID_SMyService and SID_SYourService, can both specify the use of the same interface, even though the implementation of the interface might have nothing in common between the two services. This approach works, because a call to QueryService (SID_SMyService, IID_IDispatch) can return a different object than QueryService (SID_SYourService, IID_IDispatch). Object identity isn't assumed when you specify a different service identifier.

See also

Macros