PROTOCOL_CM_OPEN_AF fonction de rappel (ndis.h)

  • Article

La fonction ProtocolCmOpenAf est requise. Cette fonction alloue des ressources par ouverture pour qu’un gestionnaire d’appels interagisse avec un client NDIS orienté connexion qui ouvre la famille d’adresses.

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

Syntaxe

PROTOCOL_CM_OPEN_AF ProtocolCmOpenAf;

NDIS_STATUS ProtocolCmOpenAf(
  [in]  NDIS_HANDLE CallMgrBindingContext,
  [in]  PCO_ADDRESS_FAMILY AddressFamily,
  [in]  NDIS_HANDLE NdisAfHandle,
  [out] PNDIS_HANDLE CallMgrAfContext
)
{...}

Paramètres

[in] CallMgrBindingContext

Pour un gestionnaire d’appels non intégré, CallMgrBindingContext spécifie le handle à une zone de contexte allouée par le gestionnaire d’appels dans laquelle les gestionnaires d’appels conservent ses informations d’état par liaison. Le gestionnaire d’appels a fourni ce handle quand il a appelé NdisOpenAdapterEx.

Pour un gestionnaire d’appels intégré (MCM), CallMgrBindingContext spécifie le handle dans une zone de contexte allouée par miniport dans laquelle le miniport conserve ses informations d’état par adaptateur. Le miniport a fourni ce handle dans son appel NdisMSetAttributesEx (pour les pilotes 5.x) ou son appel NdisMSetMiniportAttributes (pour les pilotes 6.x).

[in] AddressFamily

Spécifie la famille d’adresses qu’un client ouvre. Cette famille d’adresses a été enregistrée par le gestionnaire d’appels lors de l’appel NdisCmRegisterAddressFamilyEx.

[in] NdisAfHandle

Spécifie un handle, fourni par NDIS, qui identifie de manière unique cette famille d’adresses instance. Ce handle est opaque pour le gestionnaire d’appels et réservé à l’utilisation du système.

[out] CallMgrAfContext

Spécifie le handle d’une zone de contexte fournie par le gestionnaire d’appels dans laquelle le gestionnaire d’appels conserve l’état de cet ouvert d’une famille d’adresses qu’il fournit.

Valeur retournée

ProtocolCmOpenAf retourne le status de ses opérations comme suit :

Code de retour Description
NDIS_STATUS_SUCCESS
 Indique que le gestionnaire d’appels a correctement alloué et initialisé toutes les ressources nécessaires pour accepter les demandes du client à cette famille d’adresses.
NDIS_STATUS_PENDING
 Indique que l’opération demandée est gérée de manière asynchrone. Le gestionnaire d’appels doit appeler NdisCmOpenAddressFamilyComplete lorsqu’il a terminé toutes ses opérations open-AF pour indiquer à NDIS (et au client) que les opérations ont été terminées.
NDIS_STATUS_RESOURCES
 Indique que le gestionnaire d’appels n’a pas pu effectuer ses opérations nécessaires en raison d’un manque de ressources système disponibles, telles que la mémoire.
NDIS_STATUS_XXX
 Indique que le gestionnaire d’appels n’a pas pu se définir dans un état où il peut accepter les demandes du client pour opérer sur cette famille d’adresses. Il peut s’agir d’une erreur status propagée à partir d’une autre fonction de bibliothèque NDIS ou d’une erreur status déterminée appropriée par l’enregistreur de pilotes.

Remarques

ProtocolCmOpenAf effectue toutes les allocations requises de ressources et de structures dynamiques que l’enregistreur du gestionnaire d’appels juge nécessaires pour effectuer des opérations au nom du client qui ouvre une instance de cette famille d’adresses. Ces ressources incluent, sans s’y limiter, les mémoires tampons, les structures de données, les événements et d’autres ressources similaires. Un gestionnaire d’appels doit également initialiser toutes les données pertinentes par ouverture avant de retourner le contrôle à NDIS.

Lorsqu’un gestionnaire d’appels a alloué sa zone d’état par ouverture, l’adresse de la zone d’état doit être définie dans le handle CallMgrAfContext avant de retourner le contrôle à NDIS. Pour ce faire, déréférencez CallMgrAfContext et stockez un pointeur vers la zone de données en tant que valeur du handle. Par exemple :

*CallMgrAfContext = SomeBuffer;

Si ProtocolCmOpenAf ne peut pas allouer les ressources par ouverture dont il a besoin pour effectuer les demandes suivantes au nom du client qui ouvre cette famille d’adresses, il doit libérer toutes les ressources qu’il a allouées pour le contrôle d’ouverture et de retour au NDIS avec NDIS_STATUS_RESOURCES.

Si ProtocolCmOpenAf a terminé ses opérations requises et que le cm est prêt à accepter les demandes du client, ProtocolCmOpenAf doit retourner le contrôle aussi rapidement que possible avec un status de NDIS_STATUS_SUCCESS.

Exemples

Pour définir une fonction ProtocolCmOpenAf , 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, au vérificateur de pilotes statiques (SDV) et à d’autres outils de vérification de trouver des erreurs. 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 ProtocolCmOpenAf nommée « MyCmOpenAf », utilisez le type PROTOCOL_CM_OPEN_AF comme indiqué dans cet exemple de code :

PROTOCOL_CM_OPEN_AF MyCmOpenAf;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
NDIS_STATUS
 MyCmOpenAf(
    NDIS_HANDLE  CallMgrBindingContext,
    PCO_ADDRESS_FAMILY  AddressFamily,
    NDIS_HANDLE  NdisAfHandle,
    PNDIS_HANDLE  CallMgrAfContext
    )
  {...}

Le type de fonction PROTOCOL_CM_OPEN_AF 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 PROTOCOL_CM_OPEN_AF 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 pour les pilotes NDIS 6.0 et NDIS 5.1 (voir ProtocolCmOpenAf (NDIS 5.1)) dans Windows Vista. Pris en charge pour les pilotes NDIS 5.1 (voir ProtocolCmOpenAf (NDIS 5.1)) dans Windows XP.
Plateforme cible Windows
En-tête ndis.h (inclure Ndis.h)
IRQL <= DISPATCH_LEVEL

Voir aussi

NdisClOpenAddressFamilyEx

NdisCmOpenAddressFamilyComplete NdisCmRegisterAddressFamilyEx

NdisOpenAdapterEx