PROTOCOL_CL_REGISTER_SAP_COMPLETE funzione di callback (ndis.h)

Articolo
08/07/2023

Un client NDIS orientato alla connessione che accetta chiamate in ingresso deve avere una funzione ProtocolClRegisterSapComplete per completare le operazioni asincrone avviate con NdisClRegisterSap. In caso contrario, tale funzione ProtocolClRegisterSapComplete del driver di protocollo può semplicemente restituire il controllo.

Nota È necessario dichiarare la funzione usando il tipo di PROTOCOL_CL_REGISTER_SAP_COMPLETE . Per altre informazioni, vedere la sezione Esempi seguenti.

Sintassi

PROTOCOL_CL_REGISTER_SAP_COMPLETE ProtocolClRegisterSapComplete;

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

Parametri

[in] Status

Specifica lo stato finale della chiamata del client a NdisClRegisterSap, che può essere uno dei seguenti:

NDIS_STATUS_SUCCESS

SAP è stato registrato sia con NDIS che con il gestore chiamate, che successivamente chiamerà NdisCmDispatchIncomingCall ogni volta che riceve un'offerta di chiamata in ingresso indirizzata a SAP specificato, causando così NDIS di chiamare il client Funzione ProtocolClIncomingCall .

NDIS_STATUS_RESOURCES

Non è stato possibile allocare e/o inizializzare le risorse necessarie per registrare e gestire SAP.

NDIS_STATUS_INVALID_DATA

Il client ha fornito una specifica non valida a Sap to NDIS, che ha inoltrato alla funzione ProtocolCmRegisterSap di ProtocolCmRegisterSap per la convalida.

NDIS_STATUS_XXX

Il gestore chiamate ha rilevato un errore durante il tentativo di registrare l'oggetto SAP e NDIS specificato ha propagato lo stato di errore determinato dal cm al client.

[in] ProtocolSapContext

Specifica l'handle nell'area di contesto per-SAP del client, che il client originariamente fornito a NDIS quando ha chiamato NdisClRegisterSap. Se la registrazione ha esito positivo, NDIS mantiene questo handle di contesto e lo usa successivamente nelle chiamate alla funzione ProtocolClIncomingCall del client relativa a questo SAP.

[in] Sap

Puntatore al buffer allocato dal client contenente la specifica per l'apertura di SAP. Il client ha originariamente passato questo puntatore a NdisClRegisterSap.

[in] NdisSapHandle

Se Status è NDIS_STATUS_SUCCESS, specifica un handle valido fornito da NDIS a questo SAP registrato, in modo efficace un'associazione stabilita con NDIS tra il client e un determinato gestore chiamate per il client specificato da SAP. In caso contrario, questo parametro è NULL. Il client deve salvare un handle valido, preferibilmente nell'area ProtocolSapContext , per una chiamata finale a NdisClDeregisterSap.

Valore restituito

nessuno

Osservazioni

NDIS chiama ProtocolClRegisterSapComplete per indicare che la chiamata precedente del client a NdisClRegisterSap è stata elaborata da NDIS e, se NDIS non ha superato la chiamata, dal chiamante con cui il client condivide NdisAfHandle passato a NdisClRegisterSap.

Per ricevere chiamate in ingresso tramite una scheda di interfaccia di rete orientata alla connessione, un client ProtocolCoAfRegisterNotify o La funzione ProtocolClOpenAfCompleteEx registra in genere uno o più PROVIDER di servizi di gestione chiamate.

Per registrare ogni SAP, il client chiama NdisClRegisterSap, passando in NdisAfHandle che identifica il gestore chiamate da cui il client vuole ricevere notifiche di chiamate in ingresso e NDIS restituisce il client un NdisSapHandle al sap registrato se la chiamata del client a NdisClRegisterSapSap ha esito positivo. ProtocolClRegisterSapComplete deve salvare ogni NdisSapHandle valido, in genere nell'area per-SAP ProtocolSapContext del client in modo che possa rilasciare il sap in un secondo momento con NdisClDeregisterSap.

Il formato di un SAP è specifico del gestore chiamate. Se il gestore chiamate non riconosce che il client sta tentando di registrare o se sap specificato è già in uso, il gestore chiamate può non riuscire la registrazione SAP. ProtocolClRegisterSapComplete deve controllare lo stato di input per NDIS_STATUS_SUCCESS prima di procedere ulteriormente. Se il tentativo di registrare sap non è riuscito,
ProtocolClRegisterSapComplete può rilasciare l'area di contesto per SAP e il buffer in Sap allocato dal client o prepararli per il riutilizzo in un'altra chiamata a NdisClRegisterSap.

Un client può ricevere chiamate in ingresso in un SAP anche quando la registrazione SAP è ancora in sospeso, ovvero prima che venga chiamata la funzione ProtocolClRegisterSapComplete .

Esempi

Per definire una funzione ProtocolClRegisterSapComplete , è prima necessario specificare una dichiarazione di funzione che identifica il tipo di funzione che si sta definendo. Windows fornisce un set di tipi di funzione per i driver. La dichiarazione di una funzione usando i tipi di funzione consente l'analisi del codice per i driver, il verifica driver statico (SDV) e altri strumenti di verifica trovano errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una funzione ProtocolClRegisterSapComplete denominata "MyClRegisterSapComplete ", usare il tipo di PROTOCOL_CL_REGISTER_SAP_COMPLETE come illustrato in questo esempio di codice:

PROTOCOL_CL_REGISTER_SAP_COMPLETE MyClRegisterSapComplete;

Implementare quindi la funzione come indicato di seguito:

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

Il tipo di funzione PROTOCOL_CL_REGISTER_SAP_COMPLETE è definito nel file di intestazione Ndis.h. Per identificare in modo più accurato gli errori durante l'esecuzione degli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations garantisce che vengano usate le annotazioni applicate al tipo di funzione PROTOCOL_CL_REGISTER_SAP_COMPLETE nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo per i driver NDIS.

Per informazioni su Use_decl_annotations, vedere Annotazione del comportamento della funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Supportato per i driver NDIS 6.0 e NDIS 5.1 (vedere ProtocolClRegisterSapComplete (NDIS 5.1) in Windows Vista. Supportato per i driver NDIS 5.1 (vedere ProtocolClRegisterSapComplete (NDIS 5.1) in Windows XP.
Piattaforma di destinazione	Windows
Intestazione	ndis.h (includere Ndis.h)
IRQL	<= DISPATCH_LEVEL