OID_RECEIVE_FILTER_ALLOCATE_QUEUE

Article
03/13/2025

Le surlysage des pilotes émet des demandes de méthode d’identificateur d’objet (OID) de OID_RECEIVE_FILTER_ALLOCATE_QUEUE pour allouer une file d’attente qui a un ensemble initial de paramètres de configuration.

Le membre InformationBuffer de la structure NDIS_OID_REQUEST contient un pointeur vers une structure NDIS_RECEIVE_QUEUE_PARAMETERS. Après un retour réussi de la requête de méthode OID, le InformationBuffer membre de la structure NDIS_OID_REQUEST contient un pointeur vers une structure NDIS_RECEIVE_QUEUE_PARAMETERS qui a un nouvel identificateur de file d’attente.

Remarques

La demande de méthode OID de OID_RECEIVE_FILTER_ALLOCATE_QUEUE est facultative pour les pilotes miniport NDIS 6.20 et ultérieurs. Il est obligatoire pour les pilotes miniport qui prennent en charge l’interface de file d’attente de machines virtuelles (VMQ).

Le pilote overlying initialise la structure NDIS_RECEIVE_QUEUE_PARAMETERS avec sa configuration de file d’attente demandée. NDIS affecte un identificateur de file d’attente dans le QueueId membre de la structure NDIS_RECEIVE_QUEUE_PARAMETERS et transmet la demande de méthode au pilote miniport.

Remarque Le pilote surlysant peut définir les indicateurs de NDIS_RECEIVE_QUEUE_PARAMETERS_PER_QUEUE_RECEIVE_INDICATION et de NDIS_RECEIVE_QUEUE_PARAMETERS_LOOKAHEAD_SPLIT_REQUIRED dans les indicateurs membre de la structure NDIS_RECEIVE_QUEUE_PARAMETERS. Les autres indicateurs ne sont pas utilisés pour l’allocation de file d’attente.

Une fois qu’un pilote miniport a émis une requête OID de OID_RECEIVE_FILTER_ALLOCATE_QUEUE et le gère correctement, la file d’attente est dans l’état suspendu.

Le pilote surlysant doit utiliser l’identificateur de file d’attente fourni par NDIS dans les requêtes OID suivantes, par exemple pour modifier les paramètres de file d’attente ou libérer la file d’attente. L’identificateur de file d’attente est également inclus dans les données OOB (out-of-band) sur toutes les structures NET_BUFFER_LIST associées à la file d’attente. Les pilotes utilisent la macro NET_BUFFER_LIST_RECEIVE_QUEUE_ID pour récupérer l’identificateur de file d’attente dans une structure NET_BUFFER_LIST.

Lorsque NDIS reçoit une demande OID pour allouer une file d’attente de réception, il vérifie les paramètres de la file d’attente. Une fois que NDIS alloue les ressources nécessaires et l’identificateur de file d’attente, il envoie la requête OID au pilote miniport sous-jacent. L’identificateur de file d’attente est unique à la carte réseau associée.

Si le pilote miniport peut allouer correctement les ressources logicielles et matérielles nécessaires pour la file d’attente de réception, il termine la requête OID en retournant NDIS_STATUS_SUCCESS.

Le pilote miniport doit conserver les identificateurs de file d’attente pour les files d’attente de réception allouées. NDIS utilise l’identificateur de file d’attente d’une file d’attente pour les appels suivants au pilote miniport afin de définir un filtre de réception sur la file d’attente de réception, de modifier les paramètres de la file d’attente de réception ou de libérer la file d’attente de réception.

Une fois qu’un pilote surlysé alloue une ou plusieurs files d’attente de réception et définit éventuellement les filtres initiaux, il doit émettre OID_RECEIVE_FILTER_QUEUE_ALLOCATION_COMPLETE définir des demandes OID pour avertir le pilote miniport que l’allocation est terminée pour le lot actuel de files d’attente de réception.

Le pilote miniport ne doit pas conserver de paquets dans une file d’attente de réception s’il n’existe aucun filtre défini sur cette file d’attente. Si une file d’attente n’a jamais eu de filtres définis ou si tous les filtres ont été effacés, la file d’attente doit être vide et tous les paquets doivent être ignorés. Autrement dit, les paquets ne sont pas indiqués dans la pile des pilotes ou conservés dans la file d’attente.

Les pilotes overlying utilisent des requêtes OID de OID_RECEIVE_FILTER_FREE_QUEUE pour libérer des files d’attente qu’ils allouent.

Codes d’état de retour

NDIS ou le pilote miniport retourne l’un des codes d’état suivants pour la demande de méthode OID de OID_RECEIVE_FILTER_ALLOCATE_QUEUE.

Code d’état	Description
NDIS_STATUS_SUCCESS	La file d’attente a été allouée avec succès. La mémoire tampon d’informations contient la structure de NDIS_RECEIVE_QUEUE_PARAMETERS mise à jour.
NDIS_STATUS_PENDING	La requête est en attente d’achèvement. Le code d’état final et les résultats sont transmis à un gestionnaire d’achèvement de requête OID de l’appelant.
NDIS_STATUS_INVALID_PARAMETER	Un ou plusieurs paramètres que le pilote surlysant fourni n’étaient pas valides.
NDIS_STATUS_INVALID_LENGTH	La mémoire tampon d’informations était trop courte. NDIS définit le DATA.METHOD_INFORMATION.membre BytesNeededed dans la structure NDIS_OID_REQUEST à la taille minimale de mémoire tampon requise.
NDIS_STATUS_NOT_SUPPORTED	La version NDIS du pilote miniport est antérieure à la version 6.20.
NDIS_STATUS_FAILURE	La demande a échoué pour d’autres raisons.