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

Статья
08/07/2023

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

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

Синтаксис

PROTOCOL_CO_CREATE_VC ProtocolCoCreateVc;

NDIS_STATUS ProtocolCoCreateVc(
  [in]  NDIS_HANDLE ProtocolAfContext,
  [in]  NDIS_HANDLE NdisVcHandle,
  [out] PNDIS_HANDLE ProtocolVcContext
)
{...}

Параметры

[in] ProtocolAfContext

Указывает дескриптор для области контекста, выделенной протоколом, в которой диспетчер вызовов или клиент сохраняет свое состояние открытия. Диспетчер вызовов предоставил этот дескриптор из функции ProtocolCmOpenAf . Клиент предоставил этот дескриптор при вызове NdisClOpenAddressFamilyEx из функции ProtocolCoAfRegisterNotify .

[in] NdisVcHandle

Указывает дескриптор, предоставляемый NDIS, который однозначно идентифицирует это виртуальное подключение. Этот дескриптор непрозрачн для драйвера протокола и зарезервирован для использования библиотеки NDIS. Однако диспетчер вызовов и клиент должны сохранить этот дескриптор для передачи последующих вызовов функциям NdisCo/Cl/Cm/MCmXxx , которые относятся к этому VC.

[out] ProtocolVcContext

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

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

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

Код возврата	Описание
NDIS_STATUS_SUCCESS	Указывает, что диспетчер вызовов или клиент успешно выделил и (или) инициализировал все необходимые ресурсы, необходимые для установления и поддержания виртуального подключения.
NDIS_STATUS_RESOURCES	Указывает, что диспетчеру вызовов или клиенту не удалось выделить и (или) инициализировать свои ресурсы для установления и обслуживания виртуального подключения.
NDIS_STATUS_XXX	Указывает, что диспетчер вызовов или клиент не могут перейти в состояние, в котором он может установить виртуальное подключение. Это может быть возвращаемое значение ошибки, распространяемое из другой подпрограммы библиотеки NDIS. Примечание Диспетчеры вызовов или клиенты не могут возвращать NDIS_STATUS_PENDING из своих функций ProtocolCoCreateVc . Если вернуть ожидание, это виртуальное подключение станет непригодным для использования, а библиотека NDIS вызовет клиент или диспетчер вызовов, чтобы удалить его.

Функция ProtocolCoCreateVc диспетчера вызовов или клиента вызывается всякий раз, когда соответствующий клиент или диспетчер вызовов соответственно вызывает NdisCoCreateVc. Клиенты инициируют создание виртуальных компьютеров в процессе настройки исходящих вызовов до вызова NdisClMakeCall. Диспетчер вызовов инициирует создание виртуальной машины в процессе уведомления клиента о том, что cm получил предложение о входящем вызове с удаленного узла, который направляется в SAP, уже зарегистрированный в CM этим клиентом, до вызова CM NdisCmDispatchIncomingCall.

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

Драйверы протоколов, ориентированных на подключение, должны хранить дескриптор для виртуального удостоверения, указанный в NdisVcHandle, в области состояния каждого VC для использования в будущих операциях с этим виртуальным подключением. NdisVcHandle является обязательным параметром для NdisCoXxx, NdisCmXxx и (или) NdisClXxx, которые впоследствии вызывает такой протокол, ориентированный на подключение.

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

*ProtocolVcContext = SomeBuffer;

Если ProtocolCoCreateVc не может выделить ресурс, необходимый для выполнения последующих операций сетевого ввода-вывода, он должен освободить все ресурсы, выделенные для этого виртуального удостоверения, и вернуть управление с состоянием NDIS_STATUS_RESOURCES.

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

Вызовы ProtocolCoCreateVc по своей природе являются синхронными. То есть ProtocolCoCreateVcне может вернуть NDIS_STATUS_PENDING.

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

После того как функция ProtocolCoCreateVc клиента возвращает управление, функция ProtocolClIncomingCall клиента будет уведомлена о том, что удаленный запрос на подключение к SAP, ранее зарегистрированный клиентом, поступает по сети.

Примеры

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

Например, чтобы определить функцию ProtocolCoCreateVc с именем MyCoCreateVc, используйте тип PROTOCOL_CO_CREATE_VC , как показано в следующем примере кода:

PROTOCOL_CO_CREATE_VC MyCoCreateVc;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCoCreateVc(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  NdisVcHandle,
    PNDIS_HANDLE  ProtocolVcContext
    )
  {...}

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

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

Требования


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