функция обратного вызова PROTOCOL_CM_MAKE_CALL (ndis.h)

Статья
08/07/2023

Функция ProtocolCmMakeCall является обязательной функцией, которая настраивает параметры носителя для виртуального подключения (VC) и активирует виртуальное подключение.

Примечание Функцию необходимо объявить с помощью типа PROTOCOL_CM_MAKE_CALL . Дополнительные сведения см. в следующем разделе Примеры.

Синтаксис

PROTOCOL_CM_MAKE_CALL ProtocolCmMakeCall;

NDIS_STATUS ProtocolCmMakeCall(
  [in]            NDIS_HANDLE CallMgrVcContext,
  [in, out]       PCO_CALL_PARAMETERS CallParameters,
  [in, optional]  NDIS_HANDLE NdisPartyHandle,
  [out, optional] PNDIS_HANDLE CallMgrPartyContext
)
{...}

Параметры

[in] CallMgrVcContext

Указывает дескриптор области контекста, выделенной диспетчером вызовов, в которой диспетчеры вызовов сохраняют свое состояние по каждому VC. Диспетчер вызовов предоставил этот дескриптор NDIS из своей функции ProtocolCoCreateVc .

[in, out] CallParameters

Указатель на CO_CALL_PARAMETERS структуру, содержащую параметры, заданные клиентом, ориентированным на подключение, для этого исходящего вызова.

[in, optional] NdisPartyHandle

Указывает дескриптор, предоставляемый NDIS, который однозначно идентифицирует исходную сторону в виртуальном подключении с несколькими точками. Этот дескриптор непрозрачн для диспетчера вызовов и зарезервирован для использования библиотеки NDIS. Этот дескриптор имеет значение NULL , если клиент не настраивает исходящий многоточечный вызов.

[out, optional] CallMgrPartyContext

При возврате задает дескриптор для области контекста, предоставленной диспетчером вызовов, в которой диспетчер вызовов сохраняет состояние об исходной стороне в многоточеном вызове. Если NdisPartyHandle имеет значение NULL, этот дескриптор должен иметь значение NULL.

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

ProtocolCmMakeCall возвращает состояние своих операций в виде одного из следующих значений:

Код возврата	Описание
NDIS_STATUS_SUCCESS	Указывает, что диспетчер вызовов успешно выделил необходимые ресурсы для выполнения вызова и смог активировать виртуальное соединение с драйвером мини-порта.
NDIS_STATUS_PENDING	Указывает, что диспетчер вызовов выполнит запрос на асинхронный вызов. Когда диспетчер вызовов завершил все операции для выполнения вызова, он должен вызвать NdisCmMakeCallComplete , чтобы сообщить NDIS о том, что этот вызов завершен.
NDIS_STATUS_RESOURCES	Указывает, что диспетчеру вызовов не удалось выделить или инициализировать свои ресурсы для активации виртуального подключения по запросу клиента.
NDIS_STATUS_NOT_SUPPORTED	Указывает, что диспетчеру вызовов не удалось активировать виртуальное подключение, так как вызывающий объект запросил недопустимые или недоступные функции в параметрах вызова, указанных в CallParameters .

Если ProtocolCmMakeCall имеет явный NdisPartyHandle, этот VC был создан клиентом для многоточечных вызовов. Диспетчер вызовов должен выделить и инициализировать все необходимые ресурсы, необходимые для хранения сведений о состоянии и управления многоточечным вызовом. К таким ресурсам относятся, помимо прочего, буферы памяти, структуры данных, события и другие аналогичные ресурсы. Если диспетчер вызовов не может выделить или инициализировать необходимые ресурсы для своих областей состояния, он должен вернуть управление NDIS с NDIS_STATUS_RESOURCES.

ProtocolCmMakeCall при необходимости взаимодействует с устройствами управления сетью или другими субъектами мультимедиа, чтобы установить соединение между локальным узлом и удаленным узлом на основе параметров вызова, указанных в CallParameters . Такие действия могут включать, помимо прочего, обмен данными с коммутационным оборудованием, связь со станцией управления сетью или другие действия, соответствующие сетевой среде.

Если диспетчер вызовов требуется для взаимодействия с сетевым оборудованием (например, сетевым коммутатором), он должен использовать виртуальное подключение к устройству управления сетью, установленное в функции ProtocolBindAdapterEx . Диспетчеры звонков взаимодействуют со своим сетевым оборудованием через драйвер мини-порта, вызывая NdisCoSendNetBufferLists. Драйверы минипорта с встроенной поддержкой управления звонками не будут вызывать NdisCoSendNetBufferLists, а будут передавать данные самостоятельно.

После того как диспетчер вызовов выполнил все необходимое взаимодействие с сетевым оборудованием в соответствии с требованиями среды, диспетчеры вызовов должны вызвать NdisCmActivateVc.

Если этот вызов был многоточечным, после того как диспетчер вызовов обменялся данными с сетевым оборудованием, проверил параметры вызова, а также выделил и инициализировал свои данные о состоянии для каждой стороны, адрес блока состояний должен быть задан в дескрипторе CallMgrPartyContext перед возвратом управления в NDIS. Дескриптор задается путем разыменовки дескриптора и сохранения указателя на блок состояний в качестве значения дескриптора. Пример:

*CallMgrPartyContext = SomeBuffer ;

Если protocolCmMakeCall выполнил необходимые операции для своей сети и VC успешно активирован через NdisCmActivateVc, ProtocolCmMakeCall должен как можно быстрее вернуть управление с состоянием STATUS_SUCCESS.

После того как ProtocolCmMakeCall вернет управление NDIS, диспетчер вызовов не будет предпринимать никаких дальнейших действий по его настройке. ProtocolCmMakeCall отвечает за установку подключения, чтобы клиент смог осуществлять передачу данных по сети в этом VC. Однако впоследствии можно вызвать диспетчера вызовов, чтобы изменить качество обслуживания звонка, добавить или удалить стороны, если это многоточественный VC, и в конечном итоге завершить этот вызов.

Примеры

Чтобы определить функцию ProtocolCmMakeCall , необходимо сначала предоставить объявление функции, определяющее тип определяемой функции. Windows предоставляет набор типов функций для драйверов. Объявление функции с помощью типов функций помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить функцию ProtocolCmMakeCall с именем MyCmMakeCall, используйте тип PROTOCOL_CM_MAKE_CALL , как показано в этом примере кода:

PROTOCOL_CM_MAKE_CALL MyCmMakeCall;

Затем реализуйте функцию следующим образом:

_Use_decl_annotations_
NDIS_STATUS
 MyCmMakeCall(
    NDIS_HANDLE  CallMgrVcContext,
    PCO_CALL_PARAMETERS  CallParameters,
    NDIS_HANDLE  NdisPartyHandle,
    PNDIS_HANDLE  CallMgrPartyContext
    )
  {...}

Тип функции PROTOCOL_CM_MAKE_CALL определяется в файле заголовка Ndis.h. Чтобы более точно определить ошибки при запуске средств анализа кода, обязательно добавьте заметку Use_decl_annotations в определение функции. Заметка Use_decl_annotations гарантирует использование заметок, применяемых к типу функции PROTOCOL_CM_MAKE_CALL в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в разделе Объявление функций с помощью типов ролей функций для драйверов NDIS.

Сведения о Use_decl_annotations см. в статье О поведении функции.

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается для драйверов NDIS 6.0 и NDIS 5.1 (см. ProtocolCmMakeCall (NDIS 5.1)) в Windows Vista. Поддерживается для драйверов NDIS 5.1 (см. ProtocolCmMakeCall (NDIS 5.1)) в Windows XP.
Целевая платформа	Windows
Header	ndis.h (включая Ndis.h)
IRQL	<= DISPATCH_LEVEL

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

NdisClMakeCall

NdisCmActivateVc

NdisCmMakeCallComplete

ProtocolCoCreateVc

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