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

Статья
08/07/2023

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

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

Синтаксис

PROTOCOL_CL_REGISTER_SAP_COMPLETE ProtocolClRegisterSapComplete;

void ProtocolClRegisterSapComplete(
  [in] NDIS_STATUS Status,
  [in] NDIS_HANDLE ProtocolSapContext,
  [in] PCO_SAP Sap,
  [in] NDIS_HANDLE NdisSapHandle
)
{...}

Параметры

[in] Status

Указывает окончательное состояние вызова клиента к NdisClRegisterSap, которое может быть одним из следующих:

NDIS_STATUS_SUCCESS

SAP зарегистрирован как в NDIS, так и в диспетчере вызовов, который впоследствии вызывает NdisCmDispatchIncomingCall всякий раз, когда он получает предложение о входящем вызове, направленном на данный SAP, тем самым вызывая NDIS для вызова клиента Функция ProtocolClIncomingCall .

NDIS_STATUS_RESOURCES

NDIS или диспетчеру вызовов не удалось выделить и (или) инициализировать необходимые ресурсы для регистрации и обслуживания SAP.

NDIS_STATUS_INVALID_DATA

Клиент предоставил недопустимую спецификацию в Sap в NDIS, которую он перенаправлял в функцию ProtocolCmRegisterSap диспетчера вызовов для проверки.

NDIS_STATUS_XXX

Диспетчер вызовов обнаружил ошибку при попытке зарегистрировать заданный SAP, и NDIS распространила это состояние сбоя, определяемое CM, на клиент.

[in] ProtocolSapContext

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

[in] Sap

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

[in] NdisSapHandle

Если состояние имеет значение NDIS_STATUS_SUCCESS, указывает предоставленный NDIS допустимый дескриптор для этой зарегистрированной SAP, фактически связь, установленную с NDIS между клиентом и конкретным диспетчером вызовов для указанной клиентом SAP. В противном случае этот параметр имеет значение NULL. Клиент должен сохранить допустимый дескриптор, предпочтительно в области ProtocolSapContext , для конечного вызова NdisClDeregisterSap.

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

None

Remarks

NDIS вызывает ProtocolClRegisterSapComplete , чтобы указать, что предыдущий вызов клиента к NdisClRegisterSap был обработан NDIS и, если NDIS не завершил вызов, диспетчером вызовов, с которым клиент совместно использует NdisAfHandle , переданный NdisClRegisterSap.

Для получения входящих вызовов через сетевой адаптер, ориентированный на подключение, клиент ProtocolCoAfRegisterNotify илиФункция ProtocolClOpenAfCompleteEx обычно регистрирует один или несколько файлов SAP в диспетчере вызовов.

Чтобы зарегистрировать каждый SAP, клиент вызывает NdisClRegisterSap, передав NdisAfHandle , который идентифицирует диспетчер вызовов, от которого клиент хочет получать уведомления о входящих вызовах, и NDIS возвращает клиенту NdisSapHandle зарегистрированной SAP в случае успешного вызова клиента NdisClRegisterSap . ProtocolClRegisterSapComplete должен сохранять все допустимые NdisSapHandle, как правило, в клиентской области ProtocolSapContext для каждого SAP, чтобы можно было освободить SAP позже с помощью NdisClDeregisterSap.

Формат SAP зависит от диспетчера вызовов. Если диспетчер вызовов не распознает SAP, который клиент пытается зарегистрировать, или если указанный SAP уже используется, диспетчер вызовов может завершиться ошибкой регистрации SAP. ProtocolClRegisterSapComplete должен проверка входное состояние для NDIS_STATUS_SUCCESS перед дальнейшим выполнением. Если попытка регистрации SAP завершилась сбоем,
ProtocolClRegisterSapComplete может освободить область контекста sap и буфер sap, выделенные клиентом, или подготовить их для повторного использования в другом вызове NdisClRegisterSap.

Клиент может принимать входящие вызовы в SAP даже в то время, когда регистрация SAP все еще находится в состоянии ожидания, т. е. до вызова функции ProtocolClRegisterSapComplete .

Примеры

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

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

PROTOCOL_CL_REGISTER_SAP_COMPLETE MyClRegisterSapComplete;

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

_Use_decl_annotations_
VOID
 MyClRegisterSapComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolSapContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle
    )
  {...}

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

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

Требования

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