NDIS_OID_REQUEST structure (ndis/oidrequest.h)

Article
08/07/2023

Pour interroger ou définir des informations OID, NDIS envoie NDIS_OID_REQUEST structures pour filtrer les pilotes et les pilotes miniport.

Syntaxe

typedef struct _NDIS_OID_REQUEST {
  NDIS_OBJECT_HEADER       Header;
  NDIS_REQUEST_TYPE        RequestType;
  NDIS_PORT_NUMBER         PortNumber;
  UINT                     Timeout;
  PVOID                    RequestId;
  NDIS_HANDLE              RequestHandle;
  union {
    NDIS_OID Oid;
    struct {
      NDIS_OID Oid;
      PVOID    InformationBuffer;
      UINT     InformationBufferLength;
      UINT     BytesWritten;
      UINT     BytesNeeded;
    } QUERY_INFORMATION;
    struct {
      NDIS_OID Oid;
      PVOID    InformationBuffer;
      UINT     InformationBufferLength;
      UINT     BytesRead;
      UINT     BytesNeeded;
    } SET_INFORMATION;
    struct {
      NDIS_OID Oid;
      PVOID    InformationBuffer;
      ULONG    InputBufferLength;
      ULONG    OutputBufferLength;
      ULONG    MethodId;
      UINT     BytesWritten;
      UINT     BytesRead;
      UINT     BytesNeeded;
    } METHOD_INFORMATION;
  } DATA;
  _REQUEST_DATA            _REQUEST_DATA;
  UCHAR                    *NdisReserved[NDIS_OID_REQUEST_NDIS_RESERVED_SIZE  sizeof(PVOID)];
  UCHAR                    *MiniportReserved[2  sizeof(PVOID)];
  UCHAR                    *SourceReserved[2  sizeof(PVOID)];
  UCHAR                    SupportedRevision;
  UCHAR                    Reserved1;
  USHORT                   Reserved2;
  NDIS_NIC_SWITCH_ID       SwitchId;
  NDIS_NIC_SWITCH_VPORT_ID VPortId;
  ULONG                    Flags;
} NDIS_OID_REQUEST, *PNDIS_OID_REQUEST;

Membres

Header

Structure NDIS_OBJECT_HEADER de la structure NDIS_OID_REQUEST. Définissez le membre Type sur NDIS_OBJECT_TYPE_OID_REQUEST. Pour indiquer la version de la structure NDIS_OID_REQUEST, définissez le membre Revision sur l’une des valeurs suivantes :

NDIS_OID_REQUEST_REVISION_2

Ajout des membres SwitchId, VPortId et Flags pour NDIS 6.50.

Définissez le membre Taille de l’en-tête sur NDIS_SIZEOF_OID_REQUEST_REVISION_2.

NDIS_OID_REQUEST_REVISION_1

Version d’origine de NDIS 6.0.

Définissez le membre Taille de l’en-tête sur NDIS_SIZEOF_OID_REQUEST_REVISION_1.

RequestType

Type de requête comme l’une des valeurs d’énumération NDIS_REQUEST_TYPE .

PortNumber

Port auquel la demande est envoyée. Si le port est inconnu ou par défaut, ce membre est égal à zéro.

Timeout

Délai d’attente, en secondes, pour la demande. NDIS peut réinitialiser le pilote ou annuler la demande si le délai d’expiration expire avant que le pilote termine la demande.

RequestId

Identificateur de la demande. Si un pilote miniport doit effectuer une requête immédiatement et qu’il termine la demande avec une status de NDIS_STATUS_INDICATION_REQUIRED, le pilote miniport utilise cette valeur RequestId pour définir le membre RequestId de la structure de NDIS_STATUS_INDICATION associée.

Les pilotes NDIS ou overlying peuvent également utiliser RequestId pour annuler une demande. Lorsqu’un pilote miniport reçoit une demande d’annulation, le pilote miniport annule toutes les demandes en attente avec un RequestId correspondant. Si RequestId est égal à zéro, le pilote miniport peut ignorer ce membre. Pour plus d’informations sur les indications status, consultez la section Remarques suivante.

RequestHandle

Handle qui identifie la source qui a émis la requête OID. Si un pilote miniport doit terminer la demande immédiatement et termine la requête avec une status de NDIS_STATUS_INDICATION_REQUIRED, le pilote miniport utilise cette valeur RequestHandle pour définir le membre DestinationHandle de la structure de NDIS_STATUS_INDICATION associée. Dans ce cas, NDIS envoie uniquement l’indication de status suivante à la source qui a émis la requête OID.

Pour plus d’informations sur les indications status, consultez la section Remarques suivante.

DATA

Union qui définit les données de requête. Les informations contenues dans les données varient en fonction du type de requête spécifié par le membre RequestType . Les structures membres suivantes sont spécifiées :

DATA.Oid

DATA.QUERY_INFORMATION

Cette structure contient les paramètres d’un type de requête NdisRequestQueryInformation ou NdisRequestQueryStatistics . Cette structure est spécifiée comme suit :


struct _QUERY
  {
    NDIS_OID    Oid;
    PVOID       InformationBuffer;
    UINT        InformationBufferLength;
    UINT        BytesWritten;
    UINT        BytesNeeded;
  } QUERY_INFORMATION;

DATA.QUERY_INFORMATION.Oid

Identificateur d’objet de l’opération demandée. La valeur est un code OID_ XXX .

DATA.QUERY_INFORMATION.InformationBuffer

Pointeur vers une mémoire tampon dans laquelle le pilote sous-jacent ou NDIS retourne les informations demandées pour les demandes d’informations de requête.

DATA.QUERY_INFORMATION.InformationBufferLength

Taille, en octets, de la mémoire tampon dans InformationBuffer. La valeur sur Oid détermine la valeur appropriée pour ce membre.

DATA.QUERY_INFORMATION.BytesWritten

Nombre d’octets que le pilote ou NDIS sous-jacent transfère dans la mémoire tampon sur InformationBuffer pour les demandes d’informations de requête. Si la fonction NdisOidRequest retourne NDIS_STATUS_INVALID_LENGTH, la valeur de ce membre n’a aucun sens.

DATA.QUERY_INFORMATION.BytesNeeded

Nombre d’octets requis pour retourner les informations de requête demandées par le code XXX OID_ donné.

Si NdisOidRequest retourne NDIS_STATUS_SUCCESS, la valeur de ce membre n’a aucun sens. Si informationBufferLength est trop petit pour la OID_ XXX donnée sur une requête, ce membre indique la taille d’une mémoire tampon nécessaire pour satisfaire la demande.

DATA.SET_INFORMATION

Cette structure contient les paramètres d’un type de requête NdisRequestSetInformation . Cette structure est spécifiée comme suit :


struct _SET
  {
    NDIS_OID    Oid;
    PVOID       InformationBuffer;
    UINT        InformationBufferLength;
    UINT        BytesRead;
    UINT        BytesNeeded;
  } SET_INFORMATION;

DATA.SET_INFORMATION.Oid

Identificateur d’objet de l’opération demandée. La valeur est un code OID_ XXX .

DATA.SET_INFORMATION.InformationBuffer

Pointeur vers une mémoire tampon à partir de laquelle le pilote sous-jacent lit les informations fournies par l’appelant pour les demandes set-information.

DATA.SET_INFORMATION.InformationBufferLength

Taille, en octets, de la mémoire tampon dans InformationBuffer. La valeur sur Oid détermine la valeur appropriée pour ce membre.

DATA.SET_INFORMATION.BytesRead

Nombre d’octets que le pilote sous-jacent lit à partir de la mémoire tampon dans InformationBuffer pour les demandes d’informations de définition.

DATA.SET_INFORMATION.BytesNeeded

Nombre d’octets requis pour effectuer l’opération set demandée par le code XXX OID_ donné.

Si NdisOidRequest retourne NDIS_STATUS_SUCCESS, la valeur de ce membre n’a aucun sens. Si la mémoire tampon dans InformationBuffer ne contient pas suffisamment de données pour le OID_ XXX donné sur une demande de jeu, ce membre indique la quantité de données requises.

DATA.METHOD_INFORMATION

Cette structure contient les paramètres d’un type de requête NdisRequestMethod . Cette structure est spécifiée comme suit :


struct _METHOD
  {
    NDIS_OID            Oid;
    PVOID               InformationBuffer;
    ULONG               InputBufferLength;
    ULONG               OutputBufferLength;
    ULONG               MethodId;
    UINT                BytesWritten;
    UINT                BytesRead;
    UINT                BytesNeeded;
  } METHOD_INFORMATION;

DATA.METHOD_INFORMATION.Oid

Identificateur d’objet de l’opération demandée. La valeur est un code OID_ XXX .

DATA.METHOD_INFORMATION.InformationBuffer

Pointeur vers une mémoire tampon dans laquelle le pilote sous-jacent ou NDIS retourne les informations demandées pour les opérations de requête ou à partir de laquelle le pilote sous-jacent lit les informations fournies par l’appelant pour les opérations de définition. Ces opérations sont spécifiques au type de demande NdisRequestMethod en cours d’exécution.

Note Cette mémoire tampon est utilisée pour les demandes set-information et query-information. Par conséquent, les données de la mémoire tampon pour la demande set-information sont remplacées par les données retournées pour la requête d’informations sur la requête. L’utilisation exacte dépend de l’opération demandée, comme spécifié par le membre Oid .

DATA.METHOD_INFORMATION.InputBufferLength

Taille, en octets, des données lisibles dans la mémoire tampon sur InformationBuffer. La valeur sur Oid détermine la valeur appropriée pour ce membre.

DATA.METHOD_INFORMATION.OutputBufferLength

Nombre d’octets dans la mémoire tampon dans InformationBuffer que le pilote peut écrire.

DATA.METHOD_INFORMATION.MethodId

Méthode à exécuter pour un OID de méthode. Une requête OID de méthode peut prendre en charge plusieurs opérations, comme défini par MethodId. Il peut s’agir de n’importe quelle valeur supérieure ou égale à zéro. Zéro indique la méthode par défaut. NDIS peut définir des OID de méthode publique avec certaines méthodes prédéfinies. Les pilotes Miniport peuvent définir des OID de méthode personnalisée. Pour plus d’informations sur les OID personnalisés, consultez OID_GEN_SUPPORTED_GUIDS.

DATA.METHOD_INFORMATION.BytesWritten

Pour les OID de méthode, BytesWritten doit être inférieur ou égal à la valeur dans le membre OutputBufferLength .

DATA.METHOD_INFORMATION.BytesRead

Nombre d’octets que le pilote sous-jacent lit à partir de la mémoire tampon dans InformationBuffer pour les demandes d’informations de définition.

Pour les OID de méthode, BytesRead doit être inférieur ou égal à la valeur dans le membre InputBufferLength .

DATA.METHOD_INFORMATION.BytesNeeded

Nombre d’octets requis pour retourner des informations de requête ou pour effectuer l’opération set demandée par le code XXX OID_ donné.

Si NdisOidRequest retourne NDIS_STATUS_SUCCESS, la valeur de ce membre n’a aucun sens. Si informationBufferLength est trop petit pour le OID_ XXX donné sur une requête, ce membre indique la taille d’une mémoire tampon nécessaire pour satisfaire la demande. Si la mémoire tampon sur InformationBuffer ne contient pas suffisamment de données pour le OID_ XXX donné sur un jeu, ce membre indique la quantité de données requises.

_REQUEST_DATA

NdisReserved[NDIS_OID_REQUEST_NDIS_RESERVED_SIZE * sizeof(PVOID)]

Zone réservée à NDIS.

MiniportReserved[2 * sizeof(PVOID)]

Zone réservée au pilote miniport.

SourceReserved[2 * sizeof(PVOID)]

Zone réservée au pilote d’origine. Réservé à l’allocateur de la structure NDIS_OID_REQUEST. Il s’agit généralement d’un pilote de protocole NDIS ou d’un pilote de filtre NDIS.

SupportedRevision

Révision d’une structure NDIS prise en charge par un pilote NDIS 6.0 ou ultérieur lorsqu’il a géré une requête OID. Une structure révisée est toute structure NDIS 6.0 qui contient une structure NDIS_OBJECT_HEADER . Lorsque le pilote réussit à définir un OID, il doit définir SupportedRevision sur le numéro de révision de la structure qu’il a prise en charge. Pour plus d’informations sur les informations de version NDIS, consultez Spécification des informations de version NDIS.

Reserved1

Réservé à un usage ultérieur.

Reserved2

Réservé à un usage ultérieur.

SwitchId

Valeur NDIS_NIC_SWITCH_ID qui identifie le commutateur sur lequel le VPort cible, spécifié par VPortId, est en cours d’exécution.

Notes

Ce champ est pris en charge dans NDIS 6.50 et versions ultérieures.

VPortId

Valeur NDIS_NIC_SWITCH_VPORT_ID qui identifie le VPort ciblé par cette requête OID. Ce champ est considéré comme valide uniquement si l’indicateur NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID est défini.

Notes

Ce champ est pris en charge dans NDIS 6.50 et versions ultérieures.

Flags

Valeur ULONG qui contient un OR au niveau du bit d’indicateurs pour cette requête OID. Actuellement, ces indicateurs sont pris en charge :

Indicateur	Valeur	Description
NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID	0x0001	Lorsque cet indicateur est défini, le membre VportId est considéré comme valide et identifie le VPort vers lequel l’OID est ciblé. Si cet indicateur n’est pas défini, l’OID correspond à l’adaptateur miniport lui-même.

Notes

Ce champ est pris en charge dans NDIS 6.50 et versions ultérieures.

Remarques

Un pilote de protocole ou un pilote de filtre doit allouer de la mémoire non paginée pour la mémoire tampon sur InformationBuffer et pour la structure NDIS_OID_REQUEST. L’utilisation de données allouées à partir de la mémoire paginée peut entraîner des erreurs de page irrécupérables, car les pilotes sous-jacents s’exécutent à IRQL = DISPATCH_LEVEL d’effectuer l’opération demandée.

NDIS_OID_REQUEST contient une sous-structure DATA pour chaque type d’opération qu’un pilote de protocole peut demander à un pilote sous-jacent. Avant d’appeler NdisOidRequest, le pilote de protocole remplit les membres appropriés de la sous-structure qui représente l’opération de requête ou de jeu qu’il a spécifiée dans le membre Oid . NDIS ou le pilote sous-jacent remplit les membres restants avant qu’il ne retourne le contrôle à l’appelant.

Certaines demandes OID permettent à un pilote miniport de fournir une status d’achèvement OID avec une indication status. Dans ce cas, le pilote miniport retourne NDIS_STATUS_INDICATION_REQUIRED pour la status d’achèvement de la requête OID. Un pilote miniport ne peut pas retourner cette status sauf si l’OID particulier l’autorise. Pour déterminer si cette status est autorisée, consultez la page de référence OID.

Si une indication status est associée à une requête OID où le pilote miniport a renvoyé NDIS_STATUS_INDICATION_REQUIRED, le pilote qui effectue l’indication status doit définir les membres DestinationHandle et RequestId dans la structure NDIS_STATUS_INDICATION.

Dans ce cas, le pilote définit les membres DestinationHandle et RequestId sur les valeurs des membres RequestHandle et RequestId dans la structure NDIS_OID_REQUEST, respectivement.

Par exemple, en réseau sans fil, le traitement d’une demande OID peut prendre beaucoup de temps. Dans ce cas, le pilote miniport peut exécuter immédiatement la demande OID et fournir une indication status ultérieurement pour fournir le résultat final de la demande OID.

Les types NdisRequestGenericn(1-4) sont disponibles pour les pilotes miniport qui créent leurs propres requêtes internes. Pour implémenter une telle demande, un pilote miniport affecte une variable interne à l’un de ces types génériques.