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

Статья
02/29/2024

Платформа PacketDirect (PD) вызывает функцию PDPostAndDrainBufferList драйвера минипорта с поддержкой PD для размещения PD_BUFFER структур в очереди передачи и получения PD и очистки всех ранее опубликованных PD_BUFFER структур, которые были завершены.

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

Синтаксис

NDIS_PD_POST_AND_DRAIN_BUFFER_LIST NdisPdPostAndDrainBufferList;

VOID() NdisPdPostAndDrainBufferList(
  [in, out] NDIS_PD_QUEUE *Queue,
  [in, out] PD_BUFFER **PostBufferListHead,
  [in, out] PD_BUFFER ***DrainBufferListTail,
  [in]      ULONG MaxDrainCount
)
{...}

Параметры

[in, out] Queue

Указатель на очередь передачи или получения, которая будет получать опубликованные буферы и удалять завершенные буферы.

[in, out] PostBufferListHead

Глава списка должностей. Поставщик удаляет буферы из этого списка и добавляет их в очередь.

[in, out] DrainBufferListTail

Хвост списка стоков. Поставщик удаляет все завершенные буферы из очереди и добавляет их в этот список.

[in] MaxDrainCount

Максимальное количество PD_BUFFER структур для стока. Поставщик должен гарантировать, что этот объем не превышается. Набор частичных PD_BUFFER структур, составляющих один пакет L2, равен 1.

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

Эта функция обратного вызова не возвращает значение.

Поставщик удаляет буферы из PostBufferList и помещает их в очередь, начиная с буфера головы в списке и переходя к следующему буферу до тех пор, пока PostBufferList не будет пуст или очередь не будет заполнена (или почти заполнена). Поставщик переместит на PostListHead и возвращает новую голову списка вызывающей. Поставщик также удаляет все завершенные буферы из очереди и вставляет их в хвостовый фрагмент DrainBufferList и возвращает клиенту новый хвост DrainBufferList.

Примечание Поставщик должен слить как можно больше буферов, чтобы открыть место для размещаемых буферов. PostBufferList и DrainBufferList гарантированно являются несвязанным списком буферов (клиент никогда не предоставляет заголовок буферного списка в качестве PostBufferListHead и заголовок того же списка, что и DrainBufferListTail).

Клиент также может передать пустой список буферов после простой очистки завершенных буферов без публикации каких-либо новых буферов. Клиент также может задать параметру MaxDrainCount значение 0, чтобы просто отправлять новые буферы без очистки готовых буферов. В редких случаях клиент может вызвать вызов с пустым списком буферов после и maxDrainCount со значением 0. Поставщик не должен предполагать обратное и правильно обрабатывать такой вызов, например отсутствие операции.

Примеры

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

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

NDIS_PD_POST_AND_DRAIN_BUFFER_LIST MyPDPostAndDrainBufferList;

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

_Use_decl_annotations_
VOID
 MyPDPostAndDrainBufferList(
    NDIS_PD_QUEUE*  Queue,
    PD_BUFFER**  PostBufferListHead,
    PD_BUFFER*** DrainBufferListTail,
    ULONG  MaxDrainCount
    )
  {...}

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

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

Ниже приведен пример фрагмента кода, иллюстрирующий косвенное использование указателя для этой функции.

PD_BUFFER* PostHead = NULL;
PD_BUFFER** PostTail = &PostHead;
PD_BUFFER* DrainHead = NULL;
PD_BUFFER** DrainTail = &DrainHead;

PD_BUFFER* bufX = <allocated PD_BUFFER>;

bufX->NextPDBuffer = NULL;
*PostTail = bufX;
PostTail = &bufX->NextPDBuffer;

// BEFORE:
//PostHead == bufX
//PostTail == &bufZ->NextPDBuffer
//DrainHead == NULL
//DrainTail == &DrainHead

NDIS_PD_POST_AND_DRAIN_BUFFER_LIST(
          Queue,
          &PostHead,
          &DrainTail,
          32);

// AFTER:
//PostHead == bufY
//PostTail == &bufZ->NextPDBuffer
//DrainHead == buf1
//DrainTail == &buf5->NextPDBuffer

Требования

Требование	Значение
Минимальная версия клиента	Windows 10
Минимальная версия сервера	Windows Server 2016
Целевая платформа	Windows
Header	ndis.h
IRQL	<= DISPATCH_LEVEL

Поделиться через