функция обратного вызова PROTOCOL_CO_CREATE_VC (ndis.h)
Функция ProtocolCoCreateVc — это обязательная функция, которая выделяет ресурсы, необходимые диспетчеру вызовов или клиенту для активации и поддержки виртуального подключения (VC).
Синтаксис
PROTOCOL_CO_CREATE_VC ProtocolCoCreateVc;
NDIS_STATUS ProtocolCoCreateVc(
[in] NDIS_HANDLE ProtocolAfContext,
[in] NDIS_HANDLE NdisVcHandle,
[out] PNDIS_HANDLE ProtocolVcContext
)
{...}
Параметры
[in] ProtocolAfContext
Указывает дескриптор области контекста, выделенной протоколом, в которой диспетчер вызовов или клиент сохраняет свое состояние для каждого открытого. Диспетчер вызовов предоставил этот дескриптор из функции ProtocolCmOpenAf . Клиент предоставил этот дескриптор при вызове NdisClOpenAddressFamilyEx из функции ProtocolCoAfRegisterNotify .
[in] NdisVcHandle
Указывает дескриптор, предоставляемый NDIS, который однозначно идентифицирует это виртуальное подключение. Этот дескриптор непрозрачн для драйвера протокола и зарезервирован для использования библиотеки NDIS. Однако диспетчер вызовов и клиент должны сохранить этот дескриптор для передачи последующих вызовов функций NdisCo/Cl/Cm/MCmXxx , которые относятся к этому VC.
[out] ProtocolVcContext
Указывает дескриптор области контекста, предоставленной протоколом, в которой диспетчер вызовов или клиент сохраняет состояние этого виртуального подключения.
Возвращаемое значение
ProtocolCoCreateVc возвращает состояние своих операций в виде одного из следующих значений:
| Код возврата | Описание |
|---|---|
|
Указывает, что диспетчер вызовов или клиент успешно выделил и /или инициализировал все необходимые ресурсы, необходимые для установки и обслуживания виртуального подключения. |
|
Указывает, что диспетчер вызовов или клиент не смогли выделить и (или) инициализировать свои ресурсы для установки и обслуживания виртуального подключения. |
|
Указывает, что диспетчеру вызовов или клиенту не удалось установить виртуальное подключение. Это может быть возвращаемое значение ошибки, распространяемое из другой подпрограммы библиотеки NDIS.
Примечание Диспетчеры вызовов или клиенты не могут возвращать NDIS_STATUS_PENDING из функций ProtocolCoCreateVc . Возврат ожидающего выполнения приведет к тому, что это виртуальное подключение станет непригодным для использования, а библиотека NDIS вызовет клиента или диспетчера вызовов, чтобы удалить его.
|
Комментарии
Функция ProtocolCoCreateVc диспетчера вызовов или клиента вызывается всякий раз, когда соответствующий клиент или диспетчер вызовов соответственно вызывает NdisCoCreateVc. Клиенты инициируют создание виртуальных машин в процессе настройки исходящих вызовов до вызова NdisClMakeCall. Диспетчер вызовов инициирует создание VC в процессе уведомления клиента о том, что cm получил предложение о входящем вызове от удаленного узла, который направляется в SAP, уже зарегистрированный в CM этим клиентом, до вызова CM NdisCmDispatchIncomingCall.
ProtocolCoCreateVc выполняет все необходимые выделения динамических ресурсов и структур, необходимых диспетчеру вызовов или клиенту для выполнения последующих операций с активируемым VC. К таким ресурсам относятся, помимо прочего, буферы памяти, структуры данных, события и другие подобные ресурсы. Диспетчеры звонков и клиенты также должны инициализировать все соответствующие структуры для VC, которые им понадобятся при установлении вызова.
Драйверы протокола, ориентированные на подключение, должны хранить дескриптор для VC, указанный в NdisVcHandle, в области состояния каждого VC, чтобы использовать его в будущих операциях с этим виртуальным подключением. NdisVcHandle является обязательным параметром для NdisCoXxx, NdisCmXxx и /или NdisClXxx, который впоследствии вызывает такой протокол, ориентированный на подключение.
Когда диспетчер вызовов или клиент выделил память для своих собственных данных по VC и инициализировал свое состояние, адрес этой структуры данных должен быть задан в дескрипторе перед возвратом управления в NDIS. Для этого разыменуйте дескриптор и сохраните указатель на область данных, выделенную протоколом, в качестве значения дескриптора. Пример:
*ProtocolVcContext = SomeBuffer;
Если ProtocolCoCreateVc не может выделить ресурс, необходимый для выполнения последующих сетевых операций ввода-вывода, он должен освободить все ресурсы, выделенные для этого VC, и вернуть управление с состоянием NDIS_STATUS_RESOURCES.
Если ProtocolCoCreateVc выполнил необходимые операции и приготовил диспетчера вызовов или клиента к выполнению инициализации вызовов для этого виртуального подключения, ProtocolCoCreateVc должен как можно быстрее вернуть управление с состоянием NDIS_STATUS_SUCCESS.
Вызовы ProtocolCoCreateVc по своей природе являются синхронными. То есть ProtocolCoCreateVcне может вернуть NDIS_STATUS_PENDING.
После того как функция ProtocolCoCreateVc диспетчера вызовов вернет управление, будет вызвана функция ProtocolCmMakeCall диспетчера вызовов, чтобы установить подключение к удаленному узлу. Диспетчеры вызовов не должны предпринимать никаких действий в ProtocolCmMakeCall , который фактически устанавливает вызов, поскольку возможно, что VC будет уничтожен до того, как вызов будет установлен из-за ошибки в другом компоненте NDIS, ориентированном на подключение.
После того как функция ProtocolCoCreateVc клиента вернет управление, функция ProtocolClIncomingCall будет уведомлена о том, что инициированный удаленно запрос на подключение к SAP, ранее зарегистрированный клиентом, поступает по сети.
Примеры
Чтобы определить функцию ProtocolCoCreateVc , необходимо сначала предоставить объявление функции, определяющее тип определяемой функции. Windows предоставляет набор типов функций для драйверов. Объявление функции с помощью типов функций помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.Например, чтобы определить функцию ProtocolCoCreateVc с именем MyCoCreateVc, используйте тип PROTOCOL_CO_CREATE_VC , как показано в этом примере кода:
PROTOCOL_CO_CREATE_VC MyCoCreateVc;
Затем реализуйте функцию следующим образом:
_Use_decl_annotations_
NDIS_STATUS
MyCoCreateVc(
NDIS_HANDLE ProtocolAfContext,
NDIS_HANDLE NdisVcHandle,
PNDIS_HANDLE ProtocolVcContext
)
{...}
Тип функции PROTOCOL_CO_CREATE_VC определен в файле заголовка Ndis.h. Чтобы более точно определить ошибки при запуске средств анализа кода, обязательно добавьте заметку Use_decl_annotations в определение функции. Заметка Use_decl_annotations гарантирует использование заметок, которые применяются к типу функции PROTOCOL_CO_CREATE_VC в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в разделе Объявление функций с помощью типов ролей функций для драйверов NDIS.
Сведения о Use_decl_annotations см. в статье О поведении функции.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Поддерживается для драйверов NDIS 6.0 и NDIS 5.1 (см. ProtocolCoCreateVc (NDIS 5.1)) в Windows Vista. Поддерживается для драйверов NDIS 5.1 (см. ProtocolCoCreateVc (NDIS 5.1)) в Windows XP. |
| Целевая платформа | Windows |
| Header | ndis.h (включая Ndis.h) |
| IRQL | <= DISPATCH_LEVEL |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по