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

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

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

Синтаксис

PROTOCOL_CM_REG_SAP ProtocolCmRegSap;

NDIS_STATUS ProtocolCmRegSap(
  [in]  NDIS_HANDLE CallMgrAfContext,
  [in]  PCO_SAP Sap,
  [in]  NDIS_HANDLE NdisSapHandle,
  [out] PNDIS_HANDLE CallMgrSapContext
)
{...}

Параметры

[in] CallMgrAfContext

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

[in] Sap

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

[in] NdisSapHandle

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

[out] CallMgrSapContext

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

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

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

Код возврата Описание
NDIS_STATUS_SUCCESS
Указывает, что диспетчер вызовов успешно выделил и /или инициализировал все необходимые ресурсы для регистрации и обслуживания SAP. Кроме того, он также указывает, что SAP успешно зарегистрирован в соответствии с требованиями сетевого носителя, поддерживаемым диспетчером вызовов.
NDIS_STATUS_PENDING
Указывает, что диспетчер вызовов завершит обработку этого запроса асинхронно. Диспетчеры вызовов должны вызывать NdisCmRegisterSapComplete , когда все обработка завершена, чтобы сообщить NDIS о завершении регистрации.
NDIS_STATUS_RESOURCES
Указывает, что диспетчеру вызовов не удалось выделить и (или) инициализировать свои ресурсы, необходимые для регистрации SAP от имени клиента, ориентированного на подключение.
NDIS_STATUS_INVALID_DATA
Указывает, что указанная в Sap спецификация недопустимая или не поддерживается.
NDIS_STATUS_XXXX
Указывает, что диспетчер вызовов столкнулся с ошибкой при попытке зарегистрировать SAP для клиента, ориентированного на подключение. Код возврата подходит для ошибки и может быть возвращаемым кодом, распространяемым из другой функции библиотеки NDIS.

Примечания

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

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

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

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

*CallMgrSapContext = SomeBuffer ;

Если указанный SAP, который уже зарегистрирован другим клиентом, ориентированным на подключение, диспетчер вызовов должен завершить запрос и вернуть NDIS_STATUS_INVALID_DATA.

После того как диспетчер вызовов зарегистрировал SAP от имени клиента, ориентированного на подключение, он уведомляет клиента о входящем предложении вызова, направленном в SAP путем вызова. NdisCmDispatchIncomingCall.

Примеры

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

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

PROTOCOL_CM_REG_SAP MyCmRegisterSap;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCmRegisterSap(
    NDIS_HANDLE  CallMgrAfContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle,
    PNDIS_HANDLE  CallMgrSapContext
    )
  {...}

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

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

Требования

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

См. также

NdisCmDispatchIncomingCall

NdisCmRegisterSapComplete

NdisCoSendNetBufferLists

ProtocolCmDeregisterSap

ProtocolCmOpenAf