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

Статья
08/07/2023

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

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

Синтаксис

PROTOCOL_CL_MAKE_CALL_COMPLETE ProtocolClMakeCallComplete;

void ProtocolClMakeCallComplete(
  [in]           NDIS_STATUS Status,
  [in]           NDIS_HANDLE ProtocolVcContext,
  [in, optional] NDIS_HANDLE NdisPartyHandle,
  [in]           PCO_CALL_PARAMETERS CallParameters
)
{...}

Параметры

[in] Status

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

NDIS_STATUS_SUCCESS

Попытка клиента настроить виртуальное подключение завершилась успешно. Следовательно, клиент может выполнить передачу в активном VC с помощью NdisVcHandle , возвращенного NdisCoCreateVc, который клиент сохранил в своей области контекста для каждого VC в ProtocolVcContext .

NDIS_STATUS_RESOURCES

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

NDIS_STATUS_XXX

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

[in] ProtocolVcContext

Указывает дескриптор для области контекста клиента по каждому VC, который клиент изначально предоставлял NDIS при вызове NdisCoCreateVc для настройки VC для исходящего вызова.

[in, optional] NdisPartyHandle

Если параметр Status имеет значение NDIS_STATUS_SUCCESS и клиент создал многоточечный VC путем передачи явного дескриптора ProtocolPartyContextв NdisClMakeCall, это допустимый объект NdisPartyHandle . В противном случае этот параметр имеет значение NULL.

ProtocolClMakeCallComplete должен сохранять все допустимые входные данные NdisPartyHandle, обычно в области контекста стороннего клиента. Клиент должен использовать этот дескриптор, если (или когда) выполняет последующий вызов NdisClDropParty или NdisClCloseCall , который ссылается на эту сторону.

[in] CallParameters

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

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

None

Remarks

Вызов ProtocolClMakeCallComplete указывает, что диспетчер вызовов завершил обработку запроса клиента на установление виртуального подключения к NdisClMakeCall.

Если попытка клиента установить исходящий вызов не увенчалась успехом ( входное состояние — все, кроме NDIS_STATUS_SUCCESS), ProtocolClMakeCallComplete должен выполнить следующие действия:

Отпустите или подготовьтесь к повторному использованию области ProtocolPartyContext (если она есть) и буфера в CallParameters , выделенном клиентом.
Разорвите созданный клиентом VC с помощью вызова NdisCoDeleteVc и отпустите или подготовьтесь к повторному использованию области ProtocolVcContext , выделенной клиентом.

В противном случае ProtocolClMakeCallComplete должен выполнить следующие действия:

Проверьте элемент Flags структуры в CallParameters , чтобы узнать, задано ли CALL_PARAMETERS_CHANGED. Это означает, что диспетчер вызовов изменил предоставленные клиентом параметры вызова.
Если да, изучите данные в CallParameters , чтобы определить, являются ли они приемлемыми для этого подключения.
Например, клиент может сохранить параметры буферизованного вызова для активного виртуального сервера, сохранить NdisPartyHandle , если это многоточечный VC, и, как правило, подготовить клиента к последующим передачам и другим операциям в активном виртуальном сервере, если он считает заданные параметры вызова удовлетворительными.
В противном случае протокол сигнализации определяет, может ли клиент попытаться пересмотреть допустимые параметры вызова с помощью диспетчера вызовов.
Например, конкретный диспетчер вызовов может позволить своим клиентам вызывать NdisClModifyCallQoS один или несколько раз в этих обстоятельствах.
Если параметры вызова, измененные в CM, неприемлемы и дальнейшее согласование невозможно, ProtocolClMakeCallComplete должен отменить вызов с помощью NdisClCloseCall.
В этом случае ProtocolClMakeCallCompleteне должен пытаться освободить ресурсы, выделенные клиентом, при возвращении из NdisClCloseCall , но может просто вернуть управление. Вместо этого клиент должен освободить выделенные ресурсы (или подготовить их к повторному использованию) в рамках функции ProtocolClCloseCallComplete .

Примеры

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

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

PROTOCOL_CL_MAKE_CALL_COMPLETE MyClMakeCallComplete;

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

_Use_decl_annotations_
VOID
 MyClMakeCallComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  NdisPartyHandle,
    PCO_CALL_PARAMETERS  CallParameters
    )
  {...}

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

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

Требования

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