// убеждаемся, что маркер соответствует допустимому соединению
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. Для решения этой проблемы в IDL предусмотрено несколько технологий замещения (aliasing techniques ), которые позволяют разработчику интерфейса составлять подпрограммы преобразования, способные переводить традиционные типы данных и идиомы в легальные, доступные для вызова представления на IDL.
Прекрасным примером ситуации, в которой данная технология полезна, является идиома IEnum . Идиома нумератора СОМ была разработана раньше, чем компилятор IDL, поддерживаемый СОМ. Это означает, что первый разработчик интерфейса IEnum не мог проверить свою разработку на соответствие известным правилам преобразования в IDL. Метод перечислителя Next не может быть чисто преобразован в IDL[1]. Рассмотрим идеальный IDL-прототип метода Next:
HRESULT Next([in] ULONG cElems, [out, size_is(cElems), length_is(*pcFetched)] double *prg, [out] ULONG *pcFetched);
К сожалению, исходное «до-IDL-овское» определение метода Next устанавливало, что вызывающие программы могут передавать в качестве третьего параметра нулевой указатель, при условии, что первый параметр показывал, что запрашивается только один элемент. Это предоставляло вызывающим программам удобную возможность извлекать по одному элементу за раз:
double dblElem;
hr = p->Next(1, &dblElem, 0);
Данное допустимое использование интерфейса противоречит приведенному выше IDL-определению, так как [out] -параметры самого верхнего уровня не имеют права быть нулевыми (нет места, куда интерфейсный заместитель мог бы сохранять результат). Для разрешения этого противоречия каждое определение метода Next должно использовать атрибут [call_as] для замены вызываемой формы (callable form) метода его отправляемой формой (remotable form).
Атрибут [call_as] позволяет разработчику интерфейса выразить один и тот же метод в двух формах. Вызываемая форма метода должна использовать атрибут [local] для подавления генерирования маршалирующего кода. В этом варианте метода согласовывается, какие клиенты будут вызывать и какие объекты – реализовать. Отправляемая форма метода должна использовать атрибут [call_as] для связывания генерируемого маршалера с соответствующим методом в интерфейсной заглушке. Этот вариант метода описывает отправляемую форму интерфейса и должен использовать стандартные структуры IDL для описания запроса и ответных сообщений, необходимых для отзыва метода. Применяя технологию [call_as] к методу Next, получим такой IDL-код:
interface IEnumDoubIe : IUnknown {
// this method is what the caller and object see
// данный метод, как его видят вызывающая программа и объект
[local] HRESULT Next([in] ULONG cElems,
[out] double *prgElems, [out] ULONG *pcFetched);