FILTER_DIRECT_OID_REQUEST fonction de rappel (ndis.h)

Article
08/07/2023

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

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

Syntaxe

FILTER_DIRECT_OID_REQUEST FilterDirectOidRequest;

NDIS_STATUS FilterDirectOidRequest(
  [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_ Xx . La structure peut spécifier une requête de requête ou une demande d’ensemble

Valeur retournée

FilterDirectOidRequest retourne l’une des valeurs status suivantes :

Code de retour	Description
NDIS_STATUS_SUCCESS	FilterDirectOidRequest 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	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 NdisFDirectOidRequestComplete pour informer NDIS que la demande est terminée.
NDIS_STATUS_INVALID_OID	La demande spécifiée par OidRequest n’était pas valide ou n’était pas reconnue.
NDIS_STATUS_NOT_SUPPORTED	FilterDirectOidRequest ne prend pas en charge l’OID ; l’OID est facultatif.
NDIS_STATUS_BUFFER_TOO_SHORT	La mémoire tampon fournie par OidRequest était 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é. FilterDirectOidRequest 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	FilterDirectOidRequest a tenté de collecter les informations demandées, mais a échoué.
NDIS_STATUS_RESOURCES	FilterDirectOidRequest a échoué en raison de ressources insuffisantes.
NDIS_STATUS_FAILURE	N une des valeurs de retour précédentes s’applique. Le pilote de filtre doit appeler la fonction NdisWriteErrorLogEntry avec des paramètres qui spécifient la raison de l’échec.

Remarques

FilterDirectOidRequest est une fonction facultative. Si un pilote de filtre n’utilise pas de requêtes OID directes, 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 un Fonction FilterDirectOidRequestComplete , elle doit fournir la fonction FilterDirectOidRequest .

NDIS appelle la fonction FilterDirectOidRequest du pilote de filtre pour traiter les requêtes OID directes qui proviennent de pilotes trop longs. Les pilotes de filtre peuvent transférer ces demandes aux pilotes sous-jacents en appelant la fonction NdisFDirectOidRequest . En option, un pilote de filtre peut également effectuer une demande immédiatement sans transférer la demande.

Avant que le pilote n’appelle NdisFDirectOidRequest, le pilote doit allouer une structure NDIS_OID_REQUEST et transférer les informations de demande à la nouvelle structure en appelant le Fonction NdisAllocateCloneOidRequest .

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 le Fonction NdisFDirectOidRequestComplete pour informer NDIS que la demande est terminée.

Pour une opération de requête, FilterDirectOidRequest 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 NdisFDirectOidRequest.

Pour une opération de jeu , FilterDirectOidRequest 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, FilterDirectOidRequest définit la variable sur BytesRead sur la quantité de données fournies qu’elle a utilisées. Les pilotes sous-jacents définissent BytesRead de cette façon si le pilote de filtre a transmis la requête avec NdisFDirectOidRequest.

NDIS ne sérialise pas les requêtes qu’il envoie à FilterDirectOidRequest avec d’autres requêtes OID. Le pilote de filtre doit être en mesure de gérer plusieurs appels à FilterDirectOidRequest lorsque d’autres demandes envoyées à FilterOidRequest ou FilterDirectOidRequest sont en attente.

NDIS appelle FilterDirectOidRequest à IRQL <= DISPATCH_LEVEL.

Exemples

Pour définir une fonction FilterDirectOidRequest , 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 FilterDirectOidRequest nommée « MyDirectOidRequest », utilisez le type FILTER_DIRECT_OID_REQUEST comme indiqué dans cet exemple de code :

FILTER_DIRECT_OID_REQUEST MyDirectOidRequest;

Ensuite, implémentez votre fonction comme suit :

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

Le type de fonction FILTER_DIRECT_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_DIRECT_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.1 et versions ultérieures.
Plateforme cible	Windows
En-tête	ndis.h (inclure Ndis.h)
IRQL	<= DISPATCH_LEVEL