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

Статья
08/07/2023

NDIS вызывает функцию MiniportHaltEx драйвера минипорта для освобождения ресурсов при удалении адаптера мини-порта и остановки оборудования. Эта функция переводит мини-порт в состояние Остановлено, где другие обратные вызовы не могут выполняться (включая MiniportShutdownEx). Дополнительные сведения о состояниях драйвера мини-порта см. в разделе Состояния и операции адаптера минипорта.

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

Синтаксис

MINIPORT_HALT MiniportHalt;

void MiniportHalt(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] NDIS_HALT_ACTION HaltAction
)
{...}

Параметры

[in] MiniportAdapterContext

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

[in] HaltAction

Причина остановки адаптера мини-порта. Может иметь одно из следующих значений.

NdisHaltDeviceDisabled

NDIS останавливает адаптер мини-порта в ответ на сообщение об удалении Plug and Play (PnP).

NdisHaltDeviceInstanceDeInitialized

NDIS останавливает адаптер мини-порта в ответ на вызов промежуточного драйвераФункция NdisIMDeInitializeDeviceInstance.

NdisHaltDevicePoweredDown

NDIS останавливает адаптер мини-порта, так как система перейдет в спящее состояние.

NdisHaltDeviceSurpriseRemoved

Адаптер мини-порта был неожиданно удален, а оборудование отсутствует.

NdisHaltDeviceFailed

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

NdisHaltDeviceInitializationFailed

NDIS не удалось инициализировать адаптер мини-порта по неизвестной причине после успешного завершения функции MiniportInitializeEx .

NdisHaltDeviceStopped

NDIS останавливает адаптер мини-порта в ответ на сообщение об остановке устройства PnP.

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

None

Remarks

Драйвер указывает точку входа MiniportHaltEx при вызовеФункция NdisMRegisterMiniportDriver.

NDIS может вызвать MiniportHaltEx в любое время после успешного возврата функции MiniportInitializeEx драйвера. Если драйвер управляет физическим сетевым адаптером, MiniportHaltEx должен остановить сетевую карту. Если промежуточный драйвер NDIS вызываетФункция NdisIMDeInitializeDeviceInstance, NDIS вызывает функцию MiniportHaltEx для виртуального устройства драйвера.

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

Если сетевой адаптер создает прерывания, функция MiniportHaltEx драйвера miniportHaltEx может быть вытеснена функцией MiniportInterrupt драйвера, пока miniportHaltEx не вызоветФункция NdisMDeregisterInterruptEx возвращает. Функция MiniportHaltEx такого драйвера должна отключать прерывания и вызывать NdisMDeregisterInterruptEx как можно скорее. Обратите внимание, что драйвер может продолжать получать прерывания до тех пор, пока Возвращает NdisMDeregisterInterruptEx . NdisMDeregisterInterruptEx не возвращается, пока драйвер не завершит все запланированные DPC (дополнительные сведения см. в разделе Функция MiniportInterruptDPC ).

Если драйвер имеет функцию NetTimerCallback , связанную с объектом таймера, который может находиться в очереди системного таймера, MiniportHaltEx должен вызвать функцию NdisCancelTimerObject . Если NdisCancelTimerObject завершается сбоем, возможно, таймер уже сработал. В этом случае драйвер должен дождаться завершения функции таймера, прежде чем драйвер вернется из MiniportHaltEx.

NDIS не вызывает MiniportHaltEx при наличии невыполненных запросов OID или отправки запросов. NDIS не отправляет дальнейшие запросы для затронутого устройства после вызова NDIS MiniportHaltEx.

Если драйвер должен дождаться завершения какой-либо операции, MiniportHaltEx может использовать функцию NdisWaitEvent или функцию NdisMSleep .

NDIS вызывает MiniportHaltEx по irQL = PASSIVE_LEVEL.

Примеры

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

Например, чтобы определить функцию MiniportHaltEx с именем MyHaltEx, используйте тип MINIPORT_HALT , как показано в следующем примере кода:

MINIPORT_HALT MyHaltEx;

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

_Use_decl_annotations_
VOID
 MyHaltEx(
    NDIS_HANDLE  MiniportAdapterContext,
    NDIS_HALT_ACTION  HaltAction
    )
  {...}

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

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

Требования

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