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

  • Статья

Требуется функция ProtocolCmOpenAf . Эта функция выделяет открытые ресурсы для диспетчера вызовов для взаимодействия с клиентом NDIS, ориентированным на подключение, который открывает семейство адресов.

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

Синтаксис

PROTOCOL_CM_OPEN_AF ProtocolCmOpenAf;

NDIS_STATUS ProtocolCmOpenAf(
  [in]  NDIS_HANDLE CallMgrBindingContext,
  [in]  PCO_ADDRESS_FAMILY AddressFamily,
  [in]  NDIS_HANDLE NdisAfHandle,
  [out] PNDIS_HANDLE CallMgrAfContext
)
{...}

Параметры

[in] CallMgrBindingContext

Для неинтегрированного диспетчера вызовов CallMgrBindingContext задает дескриптор области контекста, выделенной диспетчером вызовов, в которой диспетчеры вызовов сохраняют сведения о состоянии привязки. Диспетчер вызовов предоставил этот дескриптор при вызове NdisOpenAdapterEx.

Для интегрированного диспетчера вызовов (MCM) CallMgrBindingContext указывает дескриптор области контекста, выделенной минипортом, в которой минипорт сохраняет сведения о состоянии каждого адаптера. Мини-порт предоставил этот дескриптор в вызове NdisMSetAttributesEx (для драйверов 5.x) или вызове NdisMSetMiniportAttributes (для драйверов 6.x).

[in] AddressFamily

Указывает семейство адресов, которое открывает клиент. Это семейство адресов было зарегистрировано диспетчером вызовов при вызове NdisCmRegisterAddressFamilyEx.

[in] NdisAfHandle

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

[out] CallMgrAfContext

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

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

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

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

Комментарии

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

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

*CallMgrAfContext = SomeBuffer;

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

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

Примеры

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

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

PROTOCOL_CM_OPEN_AF MyCmOpenAf;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCmOpenAf(
    NDIS_HANDLE  CallMgrBindingContext,
    PCO_ADDRESS_FAMILY  AddressFamily,
    NDIS_HANDLE  NdisAfHandle,
    PNDIS_HANDLE  CallMgrAfContext
    )
  {...}

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

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

Требования

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

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

NdisClOpenAddressFamilyEx

NdisCmOpenAddressFamilyComplete NdisCmRegisterAddressFamilyEx

NdisOpenAdapterEx