Метод IMarshal::GetMarshalSizeMax (objidl.h)

Статья
08/25/2023

Извлекает максимальный размер буфера, который потребуется во время маршалинга.

Синтаксис

HRESULT GetMarshalSizeMax(
  [in]  REFIID riid,
  [in]  void   *pv,
  [in]  DWORD  dwDestContext,
  [in]  void   *pvDestContext,
  [in]  DWORD  mshlflags,
  [out] DWORD  *pSize
);

Параметры

[in] riid

Ссылка на идентификатор маршалированного интерфейса.

[in] pv

Указатель интерфейса для маршалинга. Этот параметр может принимать значение NULL.

[in] dwDestContext

Контекст назначения, в котором требуется отменить удаление указанного интерфейса. Возможные значения поступают из перечисления MSHCTX. Отмена марширования может происходить либо в другом объекте текущего процесса (MSHCTX_INPROC), либо в другом процессе на том же компьютере, что и текущий процесс (MSHCTX_LOCAL).

[in] pvDestContext

Этот параметр зарезервирован и должен иметь значение NULL.

[in] mshlflags

Указывает, должны ли данные, которые необходимо маршалировать, передаваться обратно в клиентский процесс (типичный случай) или записываться в глобальную таблицу, где их могут получить несколько клиентов. Возможные значения поступают из перечисления MSHLFLAGS .

[out] pSize

Указатель на переменную, получающую максимальный размер буфера.

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

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

Код возврата	Описание
E_NOINTERFACE	Указанный интерфейс не поддерживается.

Этот метод вызывается косвенно при вызове CoGetMarshalSizeMax любым кодом в серверном процессе, отвечающим за маршалинг указателя на интерфейс в объекте . Этот код маршалинга обычно представляет собой заглушку, созданную COM для одного из нескольких интерфейсов, которые могут маршалировать указатель на интерфейс, реализованный в совершенно другом объекте. Примерами являются интерфейсы IClassFactory и IOleItemContainer . В целях обсуждения код, отвечающий за маршалинг указателя, называется заглушка маршалинга.

Для создания прокси-сервера для объекта COM требуются два фрагмента информации из исходного объекта: объем данных, записываемых в поток маршалинга, и CLSID прокси-сервера.

Маршалинговая заглушка получает эти два фрагмента информации с последовательными вызовами CoGetMarshalSizeMax и CoMarshalInterface.

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

Маршалинговая заглушка путем вызова CoGetMarshalSizeMax вызывает реализацию этого метода объекта для предварительного выделения буфера потока, который будет передан в MarshalInterface.

Этот метод не вызывается явным образом, если вы реализуете существующие COM-интерфейсы или используете язык определения интерфейса Майкрософт (MIDL) для определения собственных пользовательских интерфейсов. В любом случае заглушка, созданная MIDL, автоматически выполняет вызов.

Если вы не используете MIDL для определения собственного интерфейса (см. раздел Определение COM-интерфейсов), заглушка маршалинга не требует вызова GetMarshalSizeMax, хотя это настоятельно рекомендуется. Объект лучше, чем заглушка интерфейса, знает, какой максимальный размер пакета маршалинга данных, скорее всего, будет. Поэтому, если вы не предоставляете автоматически растущий поток, который настолько эффективен, что затраты на его расширение незначительны, следует вызывать этот метод даже при реализации собственных интерфейсов.

Значение, возвращаемое этим методом, гарантированно будет действительным только при условии, что внутреннее состояние маршалируемого объекта не изменится. Таким образом, фактическое маршалирование должно выполняться сразу после возвращения этой функции, иначе заглушка рискует, что объекту из-за некоторого изменения состояния может потребоваться больше памяти для маршалинга, чем было первоначально указано.

Примечания для разработчиков

Реализация MarshalInterface будет использовать предварительно выбранный буфер для записи данных маршалинга в поток. Если буфер слишком мал, операция маршалинга завершится ошибкой. Таким образом, значение, возвращаемое этим методом, должно представлять собой консервативную оценку объема данных, необходимых для маршалинга интерфейса. Нарушение этого требования следует рассматривать как катастрофическую ошибку.

При последующем вызове MarshalInterface реализация IMarshal не может полагаться на то, что вызывающий объект фактически вызвал GetMarshalSizeMax заранее. Он по-прежнему должен быть осторожным STG_E_MEDIUMFULL ошибок, возвращаемых потоком, и быть готовым к их корректной обработке.

Чтобы обеспечить правильную работу реализации GetMarshalSizeMax при поддержке новых контекстов назначения в будущем, делегируйте маршалинг в реализацию COM по умолчанию для всех значений dwDestContext , которые не понятны вашей реализации. Чтобы делегировать маршалинг реализации com по умолчанию, вызовите функцию CoGetStandardMarshal .

Требования

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

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

CoGetMarshalSizeMax

IMarshal

Поделиться через