функция обратного вызова 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

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

NDIS_STATUS_RESOURCES

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

NDIS_STATUS_XXX

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

[in] ProtocolVcContext

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

[in, optional] NdisPartyHandle

Если состояние 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