При рассмотрении следующей допустимой реализации функции:
STDMETHODIMP MyClass::f(short *ps)
{
static short n = 0;
*ps = n++;
return S_OK;
}
очевидно, что выделение памяти для короткого целого числа и передача ссылки на память в качестве аргумента функции является обязанностью вызывающей программы. О только что приведенной реализации заметим, что для функции неважно, откуда взялась эта память (например, динамически выделена из «кучи», объявлена как переменная auto в стеке), до тех пор, пока текущий аргумент ссылается на допустимую область памяти. Для подкрепления этого положения СОМ требует, чтобы все параметры с атрибутами [out], являющиеся указателями, были ссылочными указателями.
Ситуация становится менее очевидной, когда вместо простых целых типов используются типы, определенные пользователем. Рассмотрим следующее IDL-определение:
typedef struct tagPoint {
short x;
short у;
} Point;
HRESULT g([out] Point *pPoint);
Как и в предыдущем примере, правильной является такая схема: вызывающая программа выделяет память для значений и передает ссылку на память, выделенную вызывающей программой:
Point pt;
HRESULT hr = p->g(&pt);
Если вызывающая программа передала неверный указатель:
Point *ppt;
// random unitialized pointer
// случайный неинициализированный указатель
HRESULT hr = p->g(ppt);
// where should proxy copy x & у to?
// куда заместитель должен копировать x и у ?
то не найдется легальной памяти, куда метод (или интерфейсный заместитель) мог бы записать значения x и y.
Чем более сложные типы определяются пользователем, тем интереснее становится сценарий. Рассмотрим следующий код IDL:
[uuid(E02E5345-l473-11d1-8C85-0080C73925BA),object ]
interface IDogManager : IUnknown {
typedef struct tagHUMAN {
long nHumanID;
} HUMAN;
typedef struct tagDOG {
long nDogID;
[unique] HUMAN *pOwner;
} DOG;
HRESULT GetFromPound([out] DOG *pDog);
HRESULT TakeToGroomer([in] const DOG *pDog);
HRESULT SendToVet([in, out] DOG *pDog);
}
Отличительная особенность этого интерфейса состоит в том, что теперь вызывающая программа должна передать указатель на такой участок памяти, который уже содержит указатель. Можно показать, что для приведенного выше определения метода следующий код является правильным:
DOG fido;
// argument is a DOG *, so caller needs a DOG
// аргументом является DOG *, поэтому вызывающей программе нужен DOG
HUMAN dummy;
// the DOG refers to an owner, so alloc space?
// DOG ссылается на владельца, поэтому выделяем память?
fido.pOwner = &dummy;
HRESULT hr = p->GetFromPound(&fido);
// is this correct?
// правильно ли это?
В данном коде предполагается, что вызывающая программа ответственна за выделение памяти для DOG, который передается по ссылке. В этом смысле код правилен. Однако в этом коде также предполагается, что он отвечает за управление любой памятью более низкого уровня, на которую могут сослаться обновленные значения объекта DOG. Именно здесь данный код отступает от правил СОМ.
СОМ разделяет указатели, участвующие в вызове метода, на две категории. Любые именованные параметры метода, являющиеся указателями, относятся к указателям высшего уровня (top-level). Любой подчиненный указатель, который получен путем разыменования указателя высшего уровня, является вложенным (embedded) указателем. В методе GetFromPound параметр pDog считается указателем высшего уровня. Подчиненный указатель pDog->pOwner рассматривается как вложенный указатель. Отметим, что определение структуры DOG использует атрибут [unique] для явной квалификации семантики указателя для элемента структуры pOwner. Если бы семантика указателя не была квалифицирована явно, разработчик интерфейса мог бы применить принятый по умолчанию во всех интерфейсах для всех вложенных указателей атрибут [pointer_default]:
[ uuid(E02E5345-1473-11d1-8C85-0080C73925BA), object,
pointer_default(ref)
// default embedded ptrs to [ref]
// по умолчанию вложенные указатели [ref]
]
interface IUseStructs : IUnknown {
typedef struct tagNODE {
long val;
[unique] struct tagNODE *pNode;
// explicitly [unique]
// явно [unique]
} NODE;
typedef struct tagFOO {
long val;
long *pVal;
// implicitly [ref]
// неявно [ref]
} FOO;
HRESULT Method([in] FOO *pFoo, [in, unique] NODE *pHead);
}
Атрибут [pointer_default] применяется только к тем вложенным указателям, семантика которых не квалифицирована явно. В приведенном выше определении интерфейса единственный указатель, к которому это относится, – это элемент данных pVal структуры FOO. Элемент pNode структуры NODE явно квалифицирован как уникальный указатель, поэтому установка [pointer_default] на него не влияет. На параметры метода pFoo и pHead атрибут [pointer_default] также не влияет, поскольку они являются указателями высшего уровня и по умолчанию [ref], если только они не квалифицированы явно иным образом (как в случае с pHead).
Основная причина, по которой вложенные указатели имеют в СОМ отдельный статус, заключается в том, что они предъявляют особые требования к организации памяти. Для параметров с атрибутом [in] различие между указателями высшего уровня и вложенными указателями не слишком существенно, так как вызывающая программа обеспечивает метод всеми значениями и поэтому должна заранее выделить память, которую эти значения будут занимать:
HUMAN bob = { 2231 };
DOG fido = { 12288, &bob };
// fido is owned by bob
// fido принадлежит bob'y
HRESULT hr = p->TakeToGroomer(&fido);
// this is correct!
// это правильно!
В то же время разграничение между указателями высшего уровня и вложенными является существенным, когда оно касается организации памяти для параметров [out] и [in,out]. Для обоих параметров, [out] и [in,out], память, на которую ссылаются указатели высшего уровня, управляется вызывающим оператором, как и в случае параметров [in]. Для вложенных же указателей, которые появляются в параметрах [out] и [in, out], память управляется вызываемым оператором (самим методом). Причина появления этого правила заключается в том, что глубина вложения типов данных может быть сколь угодно большой. Например, в таком определении типа:
typedef struct tagNODE {
short value;
[unique] struct tagNODE *pNext;
} NODE:
вызывающему оператору невозможно заранее определить, сколько подэлементов понадобится разместить. Однако, поскольку вызываемый оператор (данный метод) будет снабжать данными каждый узел, он благополучно может выделить память для каждого необходимого узла.
При наличии правила, по которому разработчики метода должны выделять память при инициализации любых вложенных указателей, возникает естественный вопрос, откуда методы должны получить эту память, чтобы вызывающие операторы знали, как освободить ее после прочтения всех возвращенных значений? Ответом является распределитель памяти (task allocator) СОМ-задачи. Распределителем памяти задачи СОМ называется распределитель памяти, индивидуальный для каждого процесса, используемый исключительно для выделения памяти вложенным указателям с атрибутами [out] и [in,out]. Проще всего использовать этот распределитель памяти СОМ-задачи посредством применения трех API-функций СОМ:
void *CoTaskMemAlloc(DWORD cb);
// allocate cb bytes
// размещаем cb байтов
void CoTaskMemFree(void *pv);
// deallocate memory at *pv
// освобождаем память в *pv