Метод IRunningObjectTable::Register (objidl.h)

Статья
08/25/2023

Регистрирует объект и его идентифицирующий моникер в таблице выполняющихся объектов (ROT).

Синтаксис

HRESULT Register(
  [in]  DWORD    grfFlags,
  [in]  IUnknown *punkObject,
  [in]  IMoniker *pmkObjectName,
  [out] DWORD    *pdwRegister
);

Параметры

[in] grfFlags

Указывает, является ли ссылка ROT на punkObject слабой или строгой и управляет доступом к объекту через его запись в ROT. Подробные сведения см. в разделе "Заметки".

Значение	Значение
ROTFLAGS_REGISTRATIONKEEPSALIVE	Если задано значение , указывает на строгое регистрацию для объекта .
ROTFLAGS_ALLOWANYCLIENT	Если этот параметр задан, любой клиент может подключиться к выполняемому объекту через его запись в ROT. Если этот параметр не задан, к нему могут подключаться только клиенты в оконной станции, которые зарегистрировали объект .

Значение

ROTFLAGS_REGISTRATIONKEEPSALIVE

Если задано значение , указывает на строгое регистрацию для объекта .

ROTFLAGS_ALLOWANYCLIENT

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

[in] punkObject

Указатель на объект, который регистрируется как выполняющийся.

[in] pmkObjectName

Указатель на моникер, идентифицирующий punkObject.

[out] pdwRegister

Идентификатор этой записи ROT, который можно использовать в последующих вызовах IRunningObjectTable::Revoke или IRunningObjectTable::NoteChangeTime. Вызывающий объект не может указать значение NULL для этого параметра. При возникновении ошибки параметру *pdwRegister присваивается нулевое значение.

Возвращаемое значение

Этот метод может возвращать стандартные возвращаемые значения E_INVALIDARG и E_OUTOFMEMORY, а также следующие значения.

Код возврата	Описание
S_OK	Метод завершился успешно.
MK_S_MONIKERALREADYREGISTERED	Пара моникер/объект успешно зарегистрирована, но другой объект (возможно, тот же объект) уже зарегистрирован с тем же моникером.

Этот метод регистрирует указатель на объект под моникером, который идентифицирует объект . Моникер используется в качестве ключа при поиске в таблице с помощью IRunningObjectTable::GetObject.

При регистрации объекта ROT всегда вызывает AddRef для объекта . Для слабой регистрации (ROTFLAGS_REGISTRATIONKEEPSALIVE не задано), rot освобождает объект при освобождении последней строгой ссылки на объект. При строгой регистрации (ROTFLAGS_REGISTRATIONKEEPSALIVE наборе) rot предотвращает уничтожение объекта до тех пор, пока регистрация объекта не будет явно отозвана.

Сервер, зарегистрированный как LocalService или RunAs, может задать флаг ROTFLAGS_ALLOWANYCLIENT в вызове Register , чтобы разрешить любому клиенту подключаться к нему. Параметр этого бита сервера должен иметь имя исполняемого файла в разделе AppID реестра, который ссылается на AppID для исполняемого файла. Сервер "активировать как активатор" (не зарегистрированный как LocalService или RunAs) не должен устанавливать этот флаг в вызове register. Дополнительные сведения об установке служб см. в разделе Установка в качестве приложения-службы.

При регистрации второго объекта с тем же моникером или повторной регистрации того же объекта с тем же моникером создается вторая запись в ROT. В этом случае функция Register возвращает MK_S_MONIKERALREADYREGISTERED. Каждый вызов Register должен соответствовать вызову IRunningObjectTable::Revoke , так как даже повторяющиеся записи имеют разные идентификаторы pdwRegister . Проблема с повторяющимися регистрациями заключается в том, что невозможно определить, какой объект будет возвращен, если моникер указан при последующем вызове IRunningObjectTable::IsRunning.

Примечания к вызывающим абонентам

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

Наиболее распространенным типом поставщика моникеров является составной источник ссылок на документ. Сюда входят серверные приложения, поддерживающие связывание со своими документами (или частями документа), и приложения-контейнеры, поддерживающие связывание с внедрением в своих документах. Серверные приложения, которые не поддерживают связывание, также могут использовать ROT для взаимодействия с контейнерными приложениями, поддерживающими связывание с внедрением.

Если вы пишете серверное приложение, необходимо зарегистрировать объект в ROT при его запуске, как правило, в реализации IOleObject::D oVerb. Объект должен быть зарегистрирован под полным моникером, что требует получения моникера документа контейнера с помощью IOleClientSite::GetMoniker. Необходимо также отозвать и повторно зарегистрировать объект в реализации IOleObject::SetMoniker, который вызывается при переименовании документа контейнера.

Если вы пишете приложение-контейнер, поддерживающее связывание с внедрением, следует зарегистрировать документ в ROT при его загрузке. Если документ переименован, необходимо отозвать и повторно зарегистрировать его в ROT и вызвать IOleObject::SetMoniker для всех внедренных в документ объектов, чтобы дать им возможность повторно зарегистрировать себя.

Объекты, зарегистрированные в ROT, должны быть явно отозваны, когда объект больше не выполняется или при изменении его моникера. Этот отзыв важен, так как система не может автоматически удалять записи из ROT. Необходимо кэшировать идентификатор, записанный через pdwRegister, и использовать его в вызове IRunningObjectTable::Revoke , чтобы отменить регистрацию. Для строгой регистрации строго ссылка освобождается при отмене регистрации объектов.

Начиная с Windows Server 2003, если в ROT остаются устаревшие записи из-за непредвиденных проблем с сервером, COM автоматически удалит эти устаревшие записи из ROT.

Системная реализация Register вызывает метод IMoniker::Reduce в параметре pmkObjectName , чтобы убедиться, что моникер полностью сокращен перед регистрацией. Если объект известен более чем одним полностью уменьшенным моникером, он должен быть зарегистрирован под всеми такими моникерами.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	objidl.h

См. также раздел

IRunningObjectTable

Share via