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

Статья
05/23/2024

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

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

Синтаксис

MINIPORT_PAUSE MiniportPause;

NDIS_STATUS MiniportPause(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] PNDIS_MINIPORT_PAUSE_PARAMETERS PauseParameters
)
{...}

Параметры

[in] MiniportAdapterContext

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

[in] PauseParameters

Указатель на NDIS_MINIPORT_PAUSE_PARAMETERS структуры, определяющей параметры приостановки для адаптера мини-порта.

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

MiniportPause возвращает одно из следующих значений состояния:

Код возврата	Описание
NDIS_STATUS_SUCCESS	MiniportPause успешно остановил поток сетевых данных через адаптер miniport.
NDIS_STATUS_PENDING	MiniportPause не выполнил операцию приостановки, и операция будет завершена асинхронно. Драйвер мини-порта должен вызвать функцию NdisMPauseComplete после завершения операции.

NDIS приостанавливает адаптер минипорта, чтобы остановить поток данных, который может мешать операциям PnP, таким как добавление или удаление драйвера фильтра, привязка или отмена привязки драйвера протокола.

NDIS вызывает функцию MiniportPause драйвера минипорта, чтобы инициировать запрос приостановки для адаптера минипорта, указанного в MiniportAdapterContext. Адаптер мини-порта остается в состоянии приостановки до завершения операции приостановки.

Для адаптера мини-порта в состоянии Приостановка драйвер мини-порта:

Ожидает всех вызовов к Возвращаемая функция NdisMIndicateReceiveNetBufferLists .
Ожидает, пока NDIS возвратит право собственности на все NET_BUFFER_LIST структуры от невыполненных показаний получения до водителя минипорта Функция MiniportReturnNetBufferLists .
Завершает все незавершенные запросы на отправку и вызывает Функция NdisMSendNetBufferListsComplete для всех невыполненных запросов на отправку.
Отклоняет все новые запросы на отправку, выполненные в его Функция MiniportSendNetBufferLists немедленно путем вызова NdisMSendNetBufferListsComplete. В каждом NET_BUFFER_LIST должно быть задано полное состояние NDIS_STATUS_PAUSED.
Может предоставлять сведения о состоянии с помощью Функция NdisMIndicateStatusEx .
Должен обрабатывать запросы OID в функции MiniportOidRequest .
Не следует полностью останавливать адаптер минипорта, если остановка адаптера минипорта не позволяет драйверу обрабатывать запросы или предоставлять сведения о состоянии.
Не должен освобождать ресурсы, выделенные драйвером во время инициализации.

NDIS не инициирует другие операции PnP для адаптера минипорта, такие как остановка, инициализация, изменение питания, приостановка или перезапуск, пока адаптер минипорта находится в состоянии приостановки . NDIS может инициировать эти операции PnP после того, как адаптер минипорта находится в состоянии Приостановлено .

После того как драйвер мини-порта завершает все невыполненные запросы на отправку и NDIS возвращает все полученные структуры сетевых данных (из незавершенных указаний на получение), драйвер должен завершить операцию приостановки. Если драйвер возвращает NDIS_STATUS_SUCCESS из MiniportPause, операция приостановки завершается. Если драйвер возвращает NDIS_STATUS_PENDING, адаптер минипорта может оставаться в состоянии Приостановка , а операция приостановки будет завершена после того, как драйвер вызовет функцию NdisMPauseComplete . После завершения операции приостановки адаптер мини-порта находится в состоянии Приостановлено .

Для адаптера минипорта в состоянии Приостановлено драйвер мини-порта:

Необходимо немедленно отклонить все запросы на отправку в MiniportSendNetBufferLists , вызвав NdisMSendNetBufferListsComplete. Он должен задать для элемента Status в каждом NET_BUFFER_LIST значение NDIS_STATUS_PAUSED.
Может обрабатывать прерывания приема (см. функцию MiniportInterrupt ) и прерывания DPC (см. функцию MiniportInterruptDPC ), но не должен указывать полученные сетевые данные.
Может предоставлять указания состояния с помощью функции NdisMIndicateStatusEx .
Должен обрабатывать запросы OID в функции MiniportOidRequest .
Должен обрабатывать запросы на изменение состояния питания устройства в Функция MiniportDevicePnPEventNotify .
Может обрабатывать вызовы функций NetTimerCallback .
Может обрабатывать запросы на сброс оборудования в функции MiniportResetEx .

Драйверы мини-порта не могут завершить запрос на приостановку. Таким образом, если драйверу мини-порта требуются какие-либо ресурсы для обработки запроса на приостановку, он должен предварительно выделить ресурсы во время инициализации.

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

NDIS вызывает MiniportPause в IRQL = PASSIVE_LEVEL.

Примеры

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

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

MINIPORT_PAUSE MyPause;

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

_Use_decl_annotations_
NDIS_STATUS
 MyPause(
    NDIS_HANDLE  MiniportAdapterContext,
    PNDIS_MINIPORT_PAUSE_PARAMETERS  MiniportPauseParameters
    )
  {...}

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

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

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается в NDIS 6.0 и более поздних версиях.
Целевая платформа	Windows
Header	ndis.h (включая Ndis.h)
IRQL	PASSIVE_LEVEL