Моникеры и композиция

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

Следующее отображаемое имя показывает, как моникер элемента использован в тандеме с классовым моникером:

clsid:571F1680-CC83-11d0-8C48-0080C73925BA:!Ursus

Отметим использование символа "!" для отделения отображаемого имени Class Moniker от имени элемента (item name) «Ursus». При анализе MkParseDisplayName сначала использует префикс "clsid " в качестве ProgID для контакта с реализацией Сlass Moniker. Затем MkParseDisplayName предложит реализации Class Moniker проанализировать часть строки – столько, сколько она сможет распознать. Это означает, что после того, как Сlass Moniker извлек свой GUID из строки, ее следующий фрагмент все еще нуждается в анализе: !Ursus

Поскольку это имя имеет смысл только в области действия объекта, именованного моникером слева от него, фактически MkParseDisplayName присваивает значение крайнему левому моникеру (моникеру классового типа) и запрашивает объект, который он именует (объект класса Gorilla) проанализировать оставшуюся часть строки. Для поддержки анализа отображаемых имен СОМ определяет стандартный интерфейс IParseDisplayName:

[ object,uuid(0000011a-0000-0000-C000-000000000046) ]

interface IParseDisplayName : IUnknown

{

// convert display name to a moniker

// преобразуем отображаемое имя в моникер

HRESULT ParseDisplayName( [in, unique] IBindCtx *pbc, [in] LPOLESTR pszDisplayName, [out] ULONG *pchEaten, [out] IMoniker **ppmkOut );

}

В случае отображаемого имени, использованного в этом примере, объекту класса Gorilla потребуется реализовать IParseDisplayName и преобразовать строку "!Ursus" в моникер, который MkParseDisplayName поставит справа от моникера классового типа. Поскольку требуется стандартный моникер элемента, то достаточно будет такой реализации:

STDMETHODIMP GorillaClass::ParseDisplayName(IBindCtx *pbc, LPOLESTR pszDisplayName, ULONG *pchEaten, IMoniker **ppmkOut)

{

// create an item moniker using explicit API function

// создаем отдельный моникер, используя явную API-функцию

HRESULT hr = CreateItemMoniker(OLESTR("!"), pszDisplayName + 1, ppmkOut);

// indicate how many characters were parsed

// показываем, сколько символов было проанализировано

if (SUCCEEDED(hr)) *pchEaten = wcslen(pszDisplayName);

else *pchEaten = 0; return hr;

}

Отметим, что в данном примере не делается попытки проверить правильность анализируемого имени. Здесь просто убирается начальный символ "!", и из оставшейся части отображаемого имени создается новый моникер элемента.

Так как было проанализировано два моникера, то MkParseDisplayName будет собирать эти моникеры вместе, используя групповой композитный моникер (generic composite moniker). Групповой композитный моникер просто удерживает два моникера вместе. Реализация группового композитного моникера BindToObject сначала связывает моникер справа, передавая ему указатель на моникер слева через параметр pmkToLeft. Это иллюстрируется следующим псевдокодом:

// pseudo-code from OLE32.0LL

// псевдокод из OLE32.DLL

STDMETHODIMP GenericComposite::BindToObject (IBindCtx *pbc, IMoniker *pmkToLeft, REFIID riid, void **ppv)

{

return m_pmkRight->BindToObject(pbc, m_pmkLeft, riid, ppv);

}

Эта реализация демонстрирует, что моникер справа является значащим только в области действия моникера, находящегося слева от него. В случае группового композитного моникера, использованного в данном примере, моникер элемента получит классовый моникер как параметр pmkToLeft во время связывания.

Ранее мы установили, что моникер элемента использует интерфейс IOleItemContainer для связывания интерфейсного указателя. Ниже приведен псевдокод для реализации моникера элемента ВindToObject:

// pseudo-code from OLE32.DLL

// псевдокод из OLE32.DLL

STDMETHODIMP ItemMoniker::BindToObject(

IBindCtx *pbc, IMoniker *pmkToLeft, REFIID riid, void **ppv)

{

// assume failure

// допускаем возможность сбоя

*ppv = 0;

if (pmkToLeft == 0)

//requires a scope – требуется область действия return

E_INVALIDARG;

// first bind moniker to left

// сначала привязываем моникер слева

IOleItemContainer *poic = 0;

HRESULT hr = pmkToLeft->BindToObject(pbc, 0, IID_IOleItemContainer, (void**)&poic);

if (SUCCEEDED(hr))

{

// cache the bound object in binding context

// кэшируем связанный объект в контексте связывания

pbc->RegisterObjectBound(poic);

// get bind speed from Bind Context

// получаем быстроту связывания из контекста связывания

DWORD dwBindSpeed = this->MyGetSpeedFromCtx(pbc);

// ask object for named sub-object

// запрашиваем объект об именованном подобъекте

hr = poic->GetObject(m_pszItem, dwBindSpeed, pbc, riid, ppv);

poic->Release();

}

}

Эта реализация означает, что такой код:

HRESULT GetUrsus(IApe *&rpApe)

{

const OLECHAR pwsz[] = OLESTR(«clsid:571F1680-CC83-11d0-8C48-0080C73925BA:!Ursus»);

return CoGetObject(pwsz, 0, IID_IApe, (void**)&rpApe);

}

эквивалентен следующему:

HRESULT GetUrsus(IApe *&rpApe) {

IOleItemContainer *poic = 0;

HRESULT hr = CoGetClassObject(CLSID_Gorilla, CLSCTX_ALL,

0, IID_IOleItemContainer, (void**)&poic);

if (SUCCEEDED(hr)) {

hr = poic->GetObject(OLESTR(«Ursus»), BINDSPEED_INFINITE,

0, IID_IApe, (void**)&rpApe);

poic->Release();

}

return hr; }

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

Моникеры и сохраняемость

Обсуждение моникеров не может быть полным без обсуждения файлового моникера (File Moniker). Напомним, что СОМ предусматривает три примитива активации: привязывание к объектам класса, привязывание к новым экземплярам класса и привязывание к постоянным объектам, хранящимся в файлах. В данной главе детально анализировались первые два из этих примитивов. Третий примитив основан на API-функции СОМ CoGetInstanceFromFile:

HRESULT CoGetInstanceFromFile( [in, unique] COSERVERINFO *pcsi,

// host/security info – информация о хосте/безопасности

[in, unique] CLSID *pClsid,

// explicit CLSID (opt) – явный CLSID (opt)

[in, unique] IUnknown *punk0uter,

// for aggregation – для агрегирования

[in] DWORD dwClsCtx,

// locality? – локализация?

[in] DWORD grfMode,

// file open mode – режим открытия файла

[in] OLECHAR *pwszName,

// file name of object – файловое имя объекта

[in] DWORD cmqi,

// how many interfaces? – сколько интерфейсов?

[out, size_is(cmqi)] MULTI_QI *prgmq

// where to put itfs – куда поместить интерфейсы

);

Эта функция принимает на вход имя файла, которое относится к постоянному состоянию (persistent state) объекта[1]. CoGetInstanceFromFile удостоверяется в том, что объект исполняется, после чего возвращает один или несколько интерфейсных указателей на (ре)активированный объект. Чтобы выполнить эту работу, CoGetInstanceFromFile в первую очередь требуется определить CLSID данного объекта. CLSID требуется по двум причинам. Если объект не исполняется, то CLSID необходим СОМ для создания нового экземпляра, который будет инициализирован от постоянного (находящегося в файле) образа. Во-вторых, если вызывающий объект не указывает определенное хост-имя до запроса на активацию, то СОМ будет использовать CLSID для выяснения того, на какой машине следует активировать объект[2].

Если CLSID не передается явно вызывающим объектом, то CoGetInstanceFromFile извлекает CLSID из самого файла с помощью вызова API-функции СОМ GetClassFile:

HRESULT GetClassFile([in, string) OLECHAR *pwszFileName, [out] CLSID *pclsid);

Для определения типа объекта, содержащегося в файле, GetClassFile использует информацию из заголовка файла, а также информацию из реестра.

После того как определены класс и хост-машина, СОМ исследует ROT (Running Object Table – таблица исполняющихся объектов) на целевой хост-машине для того, чтобы выяснить, является ли объект уже активированным. Таблица ROT является инструментом SCM, который преобразует произвольные моникеры в экземпляры объектов, исполняющихся на локальной хост-машине. Ожидается, что постоянные объекты будут регистрировать себя в локальной ROT во время загрузки. Чтобы представить файловое имя постоянного объекта в качестве моникера, СОМ предусматривает стандартный тип моникера – файловый моникер, который оборачивает имя файла в интерфейс IMoniker. Файловые моникеры могут создаваться либо путем передачи файлового имени в МkParseDisplayName , либо вызовом явной API-функции CreateFileMoniker:

HRESULT CreateFileMoniker( [in, string] const OLECHAR *pszFileName, [out] IMoniker **ppmk);

Если постоянный объект уже зарегистрировал в ROT свой файловый моникер, то CoGetInstanceFromFile просто возвращает указатель на уже работающий объект. Если же объект в ROT не найден, то СОМ создает новый экземпляр файлового класса и инициализирует его из постоянного объекта с помощью метода IPersistFile::Load этого экземпляра:

[object, uuid(0000010b-0000-0000-C000-000000000046)]

interface IPersistFile : IPersist

{

// called by CoGetInstanceFromFile to initialize object

// вызывается функцией CoGetInstanceFromFile для

// инициализации объекта

HRESULT Load(

[in, string] const OLECHAR * pszFileName, [in] DWORD grfMode

);

// remaining methods deleted for clarity // остальные методы удалены для ясности

}

Реализация объекта отвечает за загрузку из файла всех постоянных элементов и за саморегистрацию в локальной таблице ROT – с целью убедиться, что для каждого файла в каждый момент может исполняться только один экземпляр:

STDMETHODIMP::Load(const OLECHAR *pszFileName, DWORD grfMode)

{

// read in persisted object state

// считываем сохраненное состояние объекта

HRESULT hr = this->MyReadStateFromFile(pszFile, grfMode);

if (FAILED(hr)) return hr;

// get pointer to ROT from SCM

// берем указатель на ROT от SCM

IRunningObjectTable *prot = 0;

hr = GetRunningObjectTable(0, &prot);

if (SUCCEEDED(hr))

{

// create a file moniker to register in ROT

// создаем файловый моникер для регистрации в ROT

IMoniker *pmk = 0;

hr = CreateFileMoniker(pszFileName, &pmk);

if (SUCCEEDED(hr))

{

// register self in ROT

// саморегистрация в ROT

hr = prot->Register(0, this, pmk, &m_dwReg);

pmk->Release();

}

prot->Release();

}

return hr;

}

Метод IPersistFile::Load нового созданного экземпляра будет вызван диспетчером SCM во время выполнения CoGetInstanceFromFile . В приведенном выше примере для получения указателя на интерфейс IRunningObjectTable в SCM используется API-функция СОМ GetRunningObjectTable. Этот интерфейс затем используется для регистрации своего моникера в ROT, так что последующие вызовы CoGetInstanceFromFile , использующие то же файловое имя, не будут создавать новые объекты, а вместо этого возвратят ссылки на этот объект[3].

Существование File Moniker обусловлено двумя причинами. Во-первых, он нужен, чтобы позволить объектам самим регистрироваться в ROT, чтобы их мог найти CoGetInstanceFromFile. Во-вторых, чтобы скрыть от клиента использование CoGetInstanceFromFile за интерфейсом IMoniker. Реализация File Moniker из BindToObject просто вызывает CoGetInstanceFromFile:

// pseudo-code from OLE32.DLL // псевдокод из OLE32.DLL

STDMETHODIMP FileMoniker::BindToObject(IBindCtx *pbc,

IMoniker *pmkToLeft,

REFIID riid, void **ppv) {

// assume failure – на случай сбоя

*ppv = О;

HRESULT hr = E_FAIL;

if (pmkToLeft == 0) {

// no moniker to left – слева моникеров нет

MULTI_QI mqi = { &riid, 0, 0 };

COSERVERINFO *pcsi;

DWORD grfMode;

DWORD dwClsCtx;

// these three parameters are attributes of the BindCtx

// эти три параметра являются атрибутами BindCtx

this->MyGetFromBindCtx(pbc, &pcsi, &grfMode, &dwClsCtx);

hr = CoGetInstanceFromFile(pcsi, 0, 0, dwClsCtx,

grfMode, this->m_pszFileName,

1, &mqi);

if (SUCCEEDED(hr))

*ppv = mqi.pItf;

} else {

// there's a moniker to the left – слева есть моникер

// ask object to left for IClassActivator

// or IClassFactory

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

// IClassFactory

}

return hr; }

При таком поведении File Moniker следующая функция, вызывающая CoGetInstanceFromFile

HRESULT GetCornelius(IApe * &rpApe)

{

OLECHAR *pwszObject = OLESTR(\\\\server\\public\\cornelius.chmp);

MULTI_QI mqi = { &IID_IApe, 0, 0 };

HRESULT hr = CoGetInstanceFromFile(0, 0, 0, CLSCTX_SERVER, STCM_READWRITE, pwszObject, 1, &mqi);

if (SUCCEEDED(hr)) rpApe = mqi.pItf;

else rpApe = 0;

return hr;

}

может быть упрощена, если вместо этого использовать вызов CoGetObject:

HRESULT GetCornelius(IApe * &rpApe)

{

OLECHAR *pwszObject = OLESTR(\\\\server\\public\\cornelius.chmp);

return CoGetObject(pwszObject, 0, IID_IApe, (void**)&rpApe);

}

Как и в предыдущем случае, когда использовался Class Moniker, уровень изоляции, обеспеченный CoGetObject, позволяет клиенту задавать сколь угодно сложную стратегию активации, не меняя ни единой строки кода.

Время жизни сервера

В предыдущих разделах было показано, как СОМ автоматически загружает DLL с целью перенесения реализации объектов в адресное пространство клиентских программ. Однако пока не обсуждалось, как и когда эти DLL выгружаются. Вообще говоря, серверные DLL могут предотвращать преждевременную выгрузку, но именно клиент выбирает момент, когда DLL фактически перестают использоваться. Клиенты, желающие освободить неиспользуемые DLL, вызывают API-функцию СОМ CoFreeUnusedLibraries:

void CoFreeUnusedLibraries(void);

Обычно эта подпрограмма вызывается клиентами в свободное время с целью собрать мусор в своем адресном пространстве. При вызове CoFreeUnusedLibraries СОМ опрашивает каждую из загруженных DLL, чтобы выявить, какие из них не используются. Это делается посредством вызова в каждой DLL функции DllCanUnloadNow, которая должна быть явно экспортирована из этой динамически подключаемой библиотеки.

Функция DllCanUnloadNow, которую экспортирует DLL каждого сервера, должна соответствовать следующей сигнатуре:

HRESULT DllCanUnloadNow(void);

Если DLL желает быть освобожденной, то она возвращает S_OK. Если DLL хочет остаться загруженной, то она возвращает S_FALSE. Серверные DLL должны оставаться загруженными по крайней мере до тех пор, пока сохраняются интерфейсные указатели на ее объекты. Это означает, что в DLL должен быть счетчик всех существующих ссылок на объекты. Чтобы упростить реализацию этого, большинство DLL содержат одну переменную для счетчика блокировок (lock count) и используют две функции для автоматического инкрементирования и декрементирования этого счетчика:

LONG g_cLocks = 0; void LockModule(void)

{ InterlockedIncrement(&g_cLocks); }

void UnlockModule(void)

{ InterlockedDecrement(&g_cLocks); }

При наличии этих подпрограмм реализация DllCanUnloadNow становится чрезвычайно простой:

STDAPI DllCanUnloadNow(void)

{ return g_cLocks == 0 ? S_OK : S_FALSE; }

Oстается только вызывать в подходящее время подпрограммы LockModule и UnlockModule.

Существуют две основные причины, которые должны оставлять DLL сервера загруженной: внешние ссылки на экземпляры объектов и объекты класса, а также невыполненные вызовы IClassFactory::LockServer. Вполне очевидно, как добавить поддержку DllCanUnloadNow в экземпляры и объекты классов. Объекты, расположенные в динамически распределяемой области памяти (такие, как экземпляры классов) просто инкрементируют счетчик блокировок сервера при первом вызове AddRef:

STDMETHODIMP_(ULONG) Chimp::AddRef(void)

{ if (m_cRef == 0) LockModule(); return InterlockedIncrement(&m_cRef); }

и декрементируют счетчик блокировок при заключительном вызове Release:

STDMETHODIMP_(ULONG) Chimp::Release (void)

{ LONG res = InterlockedDecrement(&m_cRef); if (res == 0)

{ delete this; UnlockModule(); }

return res; }

Поскольку объекты, не размещенные в динамически распределяемой области памяти (такие, как объекты классов), не содержат счетчика ссылок, при каждом вызове AddRef и Release нужно инкрементировать или декрементировать счетчик блокировок:

STDMETHODIMP_(ULONG) ChimpClass::AddRef(void) {

LockModule();

return 2;

}

STDMETHODIMP_(ULONG) ChimpClass::Release (void) {

UnlockModule();

return 1;

}

Объекты классов, которые реализуют IClassFactory, должны устанавливать свои серверные счетчики блокировок на вызовы IClassFactory::LockServer:

STDMETHODIMP ChimpClass::LockServer(BOOL bLock)

{

if (bLock) LockModule();

else UnlockModule();

return S_OK;

}

Как будет обсуждаться в главе 6, IClassFactory::LockServer создана в первую очередь для внепроцессных серверов, но она достаточно проста и для использования во внутрипроцессных серверах.