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

Статья
08/07/2023

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

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

Синтаксис

PROTOCOL_CL_ADD_PARTY_COMPLETE ProtocolClAddPartyComplete;

void ProtocolClAddPartyComplete(
  [in] NDIS_STATUS Status,
  [in] NDIS_HANDLE ProtocolPartyContext,
  [in] NDIS_HANDLE NdisPartyHandle,
  [in] PCO_CALL_PARAMETERS CallParameters
)
{...}

Параметры

[in] Status

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

NDIS_STATUS_SUCCESS

Указанная сторона была добавлена в активный клиентский многоточечный VC.

NDIS_STATUS_RESOURCES

NDIS не удалось выделить достаточные ресурсы для отслеживания новой стороны.

NDIS_STATUS_FAILURE

Клиент передал недопустимый объект NdisVcHandleв NdisClAddParty.

NDIS_STATUS_XXX

Функция ProtocolCmAddParty диспетчера вызовов вернула определяемое CM значение, чтобы указать, почему ей не удалось добавить сторону в VC.

[in] ProtocolPartyContext

Указывает предоставленный клиентом дескриптор, изначально переданный в NdisClAddParty.

[in] NdisPartyHandle

Если параметр Status имеет значение NDIS_STATUS_SUCCESS, этот дескриптор NDIS представляет связь между диспетчером вызовов и клиентом в отношении этой стороны. В противном случае попытка добавить сторону завершилась сбоем, и клиент должен считать этот параметр недопустимым дескриптором.

[in] CallParameters

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

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

None

Remarks

Вызов ProtocolClAddPartyComplete указывает на завершение асинхронной операции, инициированной клиентом NdisClAddParty. Если для параметра Input Status задано значение, отличное от NDIS_STATUS_SUCCESS, ProtocolClAddPartyComplete может освободить или повторно использовать буферы, выделенные клиентом, в ProtocolPartyContext и в CallParameters .

Если попытка добавить сторону завершилась успешно, ProtocolClAddPartyComplete должен сохранить входные данные NdisPartyHandle для последующих вызовов функций библиотеки NDIS, относящихся к этой стороне, в области ProtocolPartyContext клиента. Например, клиент должен передать этот дескриптор в последующем вызове NdisClDropParty в конечном итоге, если только эта удаленная сторона, которую он представляет, не закроет подключение первым.

Структура в CallParameters изначально была выделена и инициализирована клиентом, который передал этот указатель в
NdisClAddParty. Однако диспетчер вызовов мог изменить предоставленные клиентом значения, чтобы отразить результаты согласования cm с сетью или с сигнальным одноранговым элементом при обработке запроса стороннего клиента. Чтобы определить, внес ли диспетчер вызовов какие-либо изменения, ProtocolClAddPartyComplete может проверка элемент Flags этой структуры, чтобы определить, задано ли CALL_PARAMETERS_CHANGED. Если это так, ProtocolClAddPartyComplete должен обновить состояние стороны, которое клиент поддерживает для этого вызова в ProtocolPartyContext , если только изменения cm не будут неприемлемыми. Конкретный протокол сигнализации определяет, что клиент может сделать в этом случае. Как правило, клиент вызывает NdisClDropParty , если считает параметры вызова, измененные CM, неприемлемыми.

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

Примеры

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

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

PROTOCOL_CL_ADD_PARTY_COMPLETE MyClAddPartyComplete;

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

_Use_decl_annotations_
VOID
 MyClAddPartyComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolPartyContext,
    NDIS_HANDLE  NdisPartyHandle,
    PCO_CALL_PARAMETERS  CallParameters
    )
  {...}

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

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

Требования

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