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

Статья
02/26/2024

Функция 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-open. Диспетчер вызовов предоставил этот дескриптор 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_XXX	Указывает, что диспетчер вызовов обнаружил ошибку при попытке зарегистрировать 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