PROTOCOL_CL_REGISTER_SAP_COMPLETE fonction de rappel (ndis.h)

Article
08/07/2023

Un client NDIS orienté connexion qui accepte les appels entrants doit disposer d’une fonction ProtocolClRegisterSapComplete pour effectuer les opérations asynchrones qu’il lance avec NdisClRegisterSap. Sinon, la fonction ProtocolClRegisterSapComplete inscrite d’un tel pilote de protocole peut simplement retourner le contrôle.

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

Syntaxe

PROTOCOL_CL_REGISTER_SAP_COMPLETE ProtocolClRegisterSapComplete;

void ProtocolClRegisterSapComplete(
  [in] NDIS_STATUS Status,
  [in] NDIS_HANDLE ProtocolSapContext,
  [in] PCO_SAP Sap,
  [in] NDIS_HANDLE NdisSapHandle
)
{...}

Paramètres

[in] Status

Spécifie le status final de l’appel du client à NdisClRegisterSap, qui peut être l’un des éléments suivants :

NDIS_STATUS_SUCCESS

Le SAP a été enregistré auprès de NDIS et du gestionnaire d’appels, qui appellera par la suite NdisCmDispatchIncomingCall chaque fois qu’il reçoit une offre d’appel entrante dirigée vers le SAP donné, ce qui amène NDIS à appeler le client Fonction ProtocolClIncomingCall .

NDIS_STATUS_RESOURCES

NDIS ou le gestionnaire d’appels n’ont pas pu allouer et/ou initialiser les ressources nécessaires à l’inscription et à la maintenance du SAP.

NDIS_STATUS_INVALID_DATA

Le client a fourni une spécification non valide sur Sap à NDIS, qu’il a transmise à la fonction ProtocolCmRegisterSap du gestionnaire d’appels pour validation.

NDIS_STATUS_XXX

Le gestionnaire d’appels a rencontré une erreur lors de la tentative d’inscription du SAP donné et NDIS a propagé cette status d’échec déterminée par cm au client.

[in] ProtocolSapContext

Spécifie le handle de la zone de contexte par SAP du client, que le client a initialement fourni à NDIS lorsqu’il a appelé NdisClRegisterSap. Si l’inscription réussit, NDIS conserve ce handle de contexte et l’utilise par la suite dans les appels à la fonction ProtocolClIncomingCall du client relative à ce SAP.

[in] Sap

Pointeur vers la mémoire tampon allouée par le client contenant la spécification pour l’ouverture du SAP. À l’origine, le client a transmis ce pointeur à NdisClRegisterSap.

[in] NdisSapHandle

Si Status est NDIS_STATUS_SUCCESS, spécifie un handle valide fourni par NDIS à ce SAP inscrit, en fait une association établie avec NDIS entre le client et un gestionnaire d’appels particulier pour le SAP spécifié par le client. Sinon, ce paramètre a la valeur NULL. Le client doit enregistrer un handle valide, de préférence dans sa zone ProtocolSapContext , pour un appel éventuel à NdisClDeregisterSap.

Valeur de retour

None

Remarques

NDIS appelle ProtocolClRegisterSapComplete pour indiquer que l’appel précédent du client à NdisClRegisterSap a été traité par NDIS et, si NDIS n’a pas échoué à l’appel, par le gestionnaire d’appels avec lequel le client partage le NdisAfHandle qu’il a transmis à NdisClRegisterSap.

Pour recevoir des appels entrants via une carte réseau orientée connexion, un client ProtocolCoAfRegisterNotify ou La fonction ProtocolClOpenAfCompleteEx inscrit généralement une ou plusieurs sapps auprès du gestionnaire d’appels.

Pour inscrire chaque SAP, le client appelle NdisClRegisterSap, en passant le NdisAfHandle qui identifie le gestionnaire d’appels à partir duquel le client souhaite recevoir des notifications d’appels entrants, et NDIS retourne au client un NdisSapHandle au SAP inscrit si l’appel du client à NdisClRegisterSap réussit . ProtocolClRegisterSapComplete doit enregistrer chaque NdisSapHandle valide, généralement dans la zone per-SAP ProtocolSapContext du client afin qu’il puisse publier le SAP ultérieurement avec NdisClDeregisterSap.

Le format d’un SAP est spécifique au gestionnaire d’appels. Si le gestionnaire d’appels ne reconnaît pas le SAP que le client tente d’inscrire ou si le SAP spécifié est déjà utilisé, le gestionnaire d’appels peut échouer à l’inscription SAP. ProtocolClRegisterSapComplete doit case activée l’état d’entrée pour NDIS_STATUS_SUCCESS avant de poursuivre. Si la tentative d’inscription du SAP a échoué,
ProtocolClRegisterSapComplete peut libérer la zone de contexte et la mémoire tampon par SAP sur Sap que le client a allouées ou les préparer à la réutilisation dans un autre appel à NdisClRegisterSap.

Un client peut recevoir des appels entrants sur un SAP même si l’inscription SAP est toujours en attente, c’est-à-dire avant l’appel de sa fonction ProtocolClRegisterSapComplete .

Exemples

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

PROTOCOL_CL_REGISTER_SAP_COMPLETE MyClRegisterSapComplete;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
VOID
 MyClRegisterSapComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolSapContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle
    )
  {...}

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