Дональд Бокс - Сущность технологии СОМ. Библиотека программиста

{

if (riid == IID_IShutdownNotify)

*ppcp = IID_IShutdownNotify;

else if (riid == IID_ISurfboardUser)

*ppcp = &m_xcpSurfboardUser;

else

return (*ppcp = 0), CONNECT_E_NOCONNECTION;

(*ppcp)->AddRef();

return S_OK;

}

Отметим, что объект выдает интерфейсные указатели IConnectionPoint только при запросе тех интерфейсов, на которые он сможет сделать обратный запрос. Необходимо указать также на поразительное сходство с большинством реализации QueryInterface. Основное различие состоит в том, что QueryInterface имеет дело с импортируемыми (inbound) интерфейсами, в то время как FindConnectionPoint – с экспортируемыми (outbound) интерфейсами.

Поскольку метод IConnectionPoint::Advise принимает только интерфейс IUnknown, статически типизированный как интерфейсный указатель обратного вызова [1], то реализации Advise должны использовать QueryInterface для того, чтобы привязать указатель обратного вызова к соответствующему типу интерфейса:

STDMETHODIMP Surfboard::XCPShutdownNotify::Advise(IUnknown *pUnk, DWORD *pdwCookie)

{

assert (pdwCookie && pUnk);

*pdwCookie = 0;

if (This()->m_pShutdownNotify) // already have one

// уже имеем один

return CONNECT_E_ADVISELIMIT;

// QueryInterface for correct callback type

// QueryInterface для корректирования типа обратного вызова

HRESULT hr = pUnk->QueryInterface(IID_IShutdownNotify,

(void**)&(This()->m_pShutdownNotify));

if (hr == E_NOINTERFACE)

hr = CONNECT_E_NOCONNECTION;

if (SUCCEEDED(hr)) // make up a meaningful cookie

// готовим значимый маркер

*pdwCookie = DWORD(This()->m_pShutdownNotify);

return hr;

}

Напомним, что QueryInterface неявно вызывает AddRef, что означает следующее: объект Surfboard теперь хранит ссылку обратного вызова, причем она остается легальной за пределами области действия метода Advise. Отметим также, что если объект обратного вызова не реализует соответствующий интерфейс, то результирующий HRESULT преобразуется в CONNECT_E_NOCONNECTION. Если же сбой QueryInterface последовал по какой-либо иной причине, то HRESULT от QueryInterface передается вызывающей программе [2].

Основанный на приведенной выше реализации Advise соответствующий метод Unadvise имеет следующий вид:

STDMETHODIMP Surfboard::XCPShutdownNotify::Unadvise(DWORD dwCookie)

{

// ensure that the cookie corresponds to a valid connection

// убеждаемся, что маркер соответствует допустимому соединению

if (DWORD (This()->m_pShutdownNotify) != dwCookie)

return CONNECT_E_NOCONNECTION;

// release the connection

// освобождаем соединение

This()->m_pShutdownNotify->Release();

This()->m_pShutdownNotify = 0;

return S_OK;

}

В интерфейсе IConnectionPoint имеется три дополнительных вспомогательных метода, два из которых реализуются тривиально:

STDMETHODIMP Surfboard::XCPShutdownNotify::GetConnectionInterface( IID *piid)

{

assert (piid);

// return IID of the interface managed by this subobject

// возвращаем IID интерфейса, управляемого этим подобъектом

*piid = IID_IShutdownNofify;

return S_OK;

}

STDMETHODIMP Surfboard::XCPShutdownNotify::GetConnectionPointContainer(

IConnectionPointContainer **ppcpc)

{

assert(ppcpc);

(*ppcpc = This())->AddRef();

// return containing object

// возвращаем объект-контейнер

return S_OK;

}

Последний из этих трех методов, EnumConnections, позволяет вызывающим программам перенумеровывать соединенные интерфейсы. Данный метод является дополнительным, так что реализации могут законно возвращать E_NOTIMPL.

Для объявления о том, какие из экспортируемых интерфейсов класс реализации поддерживает, в IDL предусмотрен атрибут [source]:

[uuid(315BC280-DEA7-11d0-8C5E-0080C73925BA) ]

coclass Surfboard {

[default] interface ISurfboard;

interface IHazardousDevice;

interface ISharkBait;

[source] interface IShutdownNotify;

[source, default] interface ISurfboardUser;

}

Кроме этого, в СОМ предусмотрено два интерфейса, которые позволяют средам этапа выполнения запрашивать объект самостоятельно (introspectively) возвращать информацию об импортируемых в него и экспортируемых им типах интерфейсов:

[object,uuid(B196B283-BAB4-101A-B69C-00AA00341D07) ]

interface IProvideClassInfo : Unknown {

// return description of object's coclass

// возвращаем описание кокласса объекта

HRESULT GetClassInfo([out] ITypeInfo ** ppTI);

}

[object, uuid(A6BC3AC0-DBAA-11CE-9DE3-00M004BB851) ]

interface IProvideClassInfo2 : IProvideClassInfo {

typedef enum tagGUIDKIND {

GUIDKIND_DEFAULT_SOURCE_DISP_IID = 1

} GUIDKIND;

// return IID of default outbound dispinterface

// возвращаем IID принятого по умолчанию экспортируемого диспинтерфейса

HRESULT GetGUID([in] DWORD dwGuidKind, [out] GUID * pGUID);

}

Оба этих интерфейса весьма просты для реализации:

STDMETHODIMP Surfboard::GetClassInfo(ITypeInfo **ppti)

{

assert(ppti != 0);

ITypeLib *ptl = 0;

HRESULT hr = LoadRegTypeLib(LIBID_BeachLib, 1, 0, 0, &ptl);

if (SUCCEEDED(hr)) {

hr = ptl->GetTypeInfoOfGuid(CLSID_Surfboard, ppti);

ptl->Release();

}

return hr;

}

STDMETHODIMP Surfboard::GetGUID (DWORD dwKind, GUID *pguid)

{

if (dwKind != GUIDKIND_DEFAULT_SOURCE_DISP_IID || !pguid)

return E_INVALIDARG;

// ISurfboardUser must be defined as a dispinterface

// ISurfboardUser должен быть определен как диспинтерфейс

*pguid = IID_ISurfboardUser;

return S_OK;

}

Хотя экспортируемые интерфейсы не должны быть обязательно диспетчерскими интерфейсами (диспинтерфейсами), но ряд сред сценариев требуют этого, чтобы осуществлять естественное преобразование обратных вызовов в текст сценария.

Предположим, что интерфейс ISurfboardUser определен как диспинтерфейс следующим образом:

[uuid(315BC28A-DEA7-11d0-8C5E-0080C73925BA)]

dispinterface ISurfboardUser {

methods:

[id(1)] void OnTiltingForward( [in] long nAmount);

[id(2)] void OnTiltingSideways( [in] long nAmount);

}

При программировании на Visual Basic можно объявить переменные, понимающие тип интерфейса обратного вызова, принятый по умолчанию, таким образом:

Dim WithEvents sb as Surfboard

Наличие такого описания переменной дает программистам на Visual Basic возможность писать обработчики событий. Обработчики событий – это функции или подпрограммы, использующие соглашение VariableName_EventName. Например, для обработки события обратного вызова ОпТiltingForward на определенную выше переменную sb программисту Visual Basic пришлось бы написать следующий код:

Sub sb_OnTiltingForward(ByVal nAmount as Long)

MsgBox «The surfboard just tilted forward»

End Sub

Виртуальная машина Visual Basic будет действительно на лету обрабатывать реализацию ISurfboardUser, преобразуя поступающие вызовы методов в соответствующие определенные пользователем подпрограммы.

Часто бывает необходимо объединить традиционные (старые) типы данных и идиомы программирования в одну систему на основе СОМ. В идеале существует простое и очевидное преобразование традиционного кода в его аналог, совместимый с IDL. Если у нас именно такой случай, то тогда переход к СОМ будет достаточно простым. Существуют, однако, ситуации, когда традиционные типы данных или идиомы приложения просто не могут разумным образом преобразовываться в IDL. Для решения этой проблемы в IDL предусмотрено несколько технологий замещения ( aliasing techniques ), которые позволяют разработчику интерфейса составлять подпрограммы преобразования, способные переводить традиционные типы данных и идиомы в легальные, доступные для вызова представления на IDL.

Прекрасным примером ситуации, в которой данная технология полезна, является идиома IEnum . Идиома нумератора СОМ была разработана раньше, чем компилятор IDL, поддерживаемый СОМ. Это означает, что первый разработчик интерфейса IEnum не мог проверить свою разработку на соответствие известным правилам преобразования в IDL. Метод перечислителя Next не может быть чисто преобразован в IDL [1]. Рассмотрим идеальный IDL-прототип метода Next :