FILTER_OID_REQUEST fonction de rappel (ndis.h)

Article
08/07/2023

NDIS appelle la fonction FilterOidRequest d’un pilote de filtre pour traiter une requête OID associée au module de filtre spécifié.

Note Vous devez déclarer la fonction à l’aide du type FILTER_OID_REQUEST . Pour plus d’informations, consultez la section Exemples suivante.

Syntaxe

FILTER_OID_REQUEST FilterOidRequest;

NDIS_STATUS FilterOidRequest(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_OID_REQUEST OidRequest
)
{...}

Paramètres

[in] FilterModuleContext

Handle de la zone de contexte pour le module de filtre qui est la cible de cette requête. Le pilote de filtre a créé et initialisé cette zone de contexte dans la fonction FilterAttach .

[in] OidRequest

Pointeur vers une structure de NDIS_OID_REQUEST qui spécifie l’opération demandée, y compris le code OID_XXX . La structure peut spécifier une requête OID ou une demande de jeu OID. Pour plus d’informations sur les OID, consultez OID NDIS.

Valeur retournée

FilterOidRequest retourne l’une des valeurs status suivantes :

Code de retour	Description
NDIS_STATUS_SUCCESS	FilterOidRequest a réussi l’opération de requête ou de définition du pilote de filtre pour ce module de filtre.
NDIS_STATUS_PENDING	Indique que le pilote de filtre effectue la requête de manière asynchrone. Une fois que le pilote a terminé la demande, il doit appeler le Fonction NdisFOidRequestComplete pour informer NDIS que la demande est terminée.
NDIS_STATUS_INVALID_OID	Indique que la requête, spécifiée dans OidRequest, n’est pas valide ou n’est pas reconnue.
NDIS_STATUS_NOT_SUPPORTED	FilterOidRequest ne prend pas en charge l’OID, l’OID est facultatif.
NDIS_STATUS_BUFFER_TOO_SHORT	Indique que la mémoire tampon, fournie dans OidRequest, est trop petite pour contenir les données demandées.
NDIS_STATUS_INVALID_LENGTH	Pour une opération de requête, le membre InformationBufferLength de la structure NDIS_OID_REQUEST ne correspond pas à la longueur requise par l’OID donné. FilterOidRequest a retourné la taille de mémoire tampon requise, en octets, dans le membre BytesNeededed de la structure NDIS_OID_REQUEST.
NDIS_STATUS_INVALID_DATA	Pour une opération de jeu, les données fournies dans le membre InformationBuffer de la structure NDIS_OID_REQUEST n’étaient pas valides pour l’OID donné.
NDIS_STATUS_NOT_ACCEPTED	FilterOidRequest a tenté de collecter les informations demandées, mais a échoué.
NDIS_STATUS_RESOURCES	FilterOidRequest a échoué en raison de ressources insuffisantes.
NDIS_STATUS_FAILURE	FilterOidRequest retourne NDIS_STATUS_FAILURE si aucune des valeurs précédentes ne s’applique. Le pilote de filtre doit appeler la fonction NdisWriteErrorLogEntry avec des paramètres qui spécifient la raison de l’échec.

Remarques

FilterOidRequest est une fonction facultative. Si un pilote de filtre n’utilise pas de requêtes OID, il peut définir le point d’entrée de cette fonction sur NULL lorsqu’il appelle la fonction NdisFRegisterFilterDriver . Si un pilote de filtre définit une fonction FilterOidRequestComplete , il doit fournir la fonction FilterOidRequest .

NDIS appelle la fonction FilterOidRequest du pilote de filtre pour traiter les requêtes OID provenant de pilotes trop longs. Les pilotes de filtre peuvent transférer ces requêtes aux pilotes sous-jacents en appelant la fonction NdisFOidRequest .

Avant que le pilote appelle NdisFOidRequest, le pilote doit allouer une structure de NDIS_OID_REQUEST et transférer les informations de requête vers la nouvelle structure en appelant NdisAllocateCloneOidRequest. En option, un pilote de filtre peut exécuter une requête immédiatement sans transférer la demande.

Pour effectuer une requête de manière synchrone, le pilote de filtre retourne NDIS_STATUS_SUCCESS ou une status d’échec. Si le pilote retourne NDIS_STATUS_PENDING, il doit appeler la fonction NdisFOidRequestComplete pour informer NDIS que la demande est terminée.

Pour une opération de requête, FilterOidRequest retourne les informations demandées dans le membre InformationBuffer et définit la variable dans le membre BytesWritten de la structure NDIS_OID_REQUEST sur la quantité d’informations qu’elle a retournées. Les pilotes sous-jacents effectuent cette opération si le pilote de filtre a transmis la requête avec NdisFOidRequest.

Pour une opération de jeu, FilterOidRequest peut utiliser les données du membre InformationBuffer de la structure NDIS_OID_REQUEST pour définir les informations requises par l’OID donné. Dans ce cas, FilterOidRequest définit la variable BytesRead sur la quantité de données fournies qu’elle a utilisées. Les pilotes sous-jacents effectuent cette opération si le pilote de filtre a transmis la requête avec NdisFOidRequest.

Comme les pilotes miniport, les pilotes de filtre ne peuvent recevoir qu’une seule requête à la fois. NDIS sérialise les demandes qu’il envoie à un pilote de filtre. NDIS ne peut pas appeler FilterOidRequest avant qu’un pilote de filtre termine la requête actuelle.

NDIS appelle FilterOidRequest à IRQL <= DISPATCH_LEVEL.

Exemples

Pour définir une fonction FilterOidRequest , vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction que vous définissez. Windows fournit un ensemble de types de fonctions pour les pilotes. La déclaration d’une fonction à l’aide des types de fonction permet à l’analyse du code pour les pilotes, le vérificateur de pilotes statique (SDV) et d’autres outils de vérification de trouver les erreurs, et il s’agit d’une exigence pour l’écriture de pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une fonction FilterOidRequest nommée « MyOidRequest », utilisez le type FILTER_OID_REQUEST comme indiqué dans cet exemple de code :

FILTER_OID_REQUEST MyOidRequest;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
NDIS_STATUS
 MyOidRequest(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

Le type de fonction FILTER_OID_REQUEST est défini dans le fichier d’en-tête Ndis.h. Pour identifier plus précisément les erreurs lors de l’exécution des outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction FILTER_OID_REQUEST dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes NDIS.

Pour plus d’informations sur Use_decl_annotations, consultez Annotating Function Behavior.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge dans NDIS 6.0 et versions ultérieures.
Plateforme cible	Windows
En-tête	ndis.h (inclure Ndis.h)
IRQL	<= DISPATCH_LEVEL