PROTOCOL_CM_REG_SAP funzione di callback (ndis.h)

Articolo
08/07/2023

La funzione ProtocolCmRegisterSap è una funzione obbligatoria chiamata da NDIS per richiedere a un gestore chiamate di registrare un punto di accesso SAP (servizio) per conto di un client orientato alla connessione.

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

Sintassi

PROTOCOL_CM_REG_SAP ProtocolCmRegSap;

NDIS_STATUS ProtocolCmRegSap(
  [in]  NDIS_HANDLE CallMgrAfContext,
  [in]  PCO_SAP Sap,
  [in]  NDIS_HANDLE NdisSapHandle,
  [out] PNDIS_HANDLE CallMgrSapContext
)
{...}

Parametri

[in] CallMgrAfContext

Specifica l'handle per un'area di contesto allocata dal gestore chiamate in cui il gestore chiamate mantiene lo stato af per apertura. Il gestore chiamate ha fornito questo handle a NDIS dalla relativa funzione ProtocolCmOpenAf .

[in] Sap

Puntatore a una struttura di CO_SAP specifica del supporto che contiene lo specifico SAP registrato da un client orientato alla connessione.

[in] NdisSapHandle

Specifica un handle, fornito da NDIS, che identifica in modo univoco questo SAP. Questo handle è opaco al gestore chiamate e riservato per l'uso della libreria NDIS.

[out] CallMgrSapContext

In caso di restituzione, specifica l'handle di un'area di contesto fornita dal gestore chiamate in cui il gestore chiamate mantiene lo stato relativo a questo SAP.

Valore restituito

ProtocolCmRegisterSap restituisce lo stato delle operazioni seguenti:

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	Indica che il gestore chiamate ha allocato correttamente e/o inizializzato tutte le risorse necessarie per registrare e gestire SAP. Inoltre, indica anche che SAP è stato registrato correttamente come richiesto dal supporto di rete supportato dal gestore chiamate.
NDIS_STATUS_PENDING	Indica che il gestore chiamate completerà l'elaborazione della richiesta in modo asincrono. I responsabili delle chiamate devono chiamare NdisCmRegisterSapComplete quando tutta l'elaborazione è stata completata per segnalare a NDIS che la registrazione è stata completata.
NDIS_STATUS_RESOURCES	Indica che il gestore chiamate non è riuscito ad allocare e/o inizializzare le risorse necessarie per registrare SAP per conto del client orientato alla connessione.
NDIS_STATUS_INVALID_DATA	Indica che la specifica fornita in Sap non è valida o non può essere supportata.
NDIS_STATUS_XXX	Indica che il gestore chiamate ha rilevato un errore durante il tentativo di registrare SAP per il client orientato alla connessione. Il codice restituito è appropriato per l'errore e potrebbe essere un codice restituito propagato da un'altra funzione della libreria NDIS.

Commenti

ProtocolCmMakeCall comunica con i dispositivi di controllo di rete o altri agenti specifici del supporto, se necessario, per registrare SAP, come specificato in Sap, nella rete per un client orientato alla connessione. Tali azioni possono includere, ad esempio, la comunicazione con l'hardware switching, la comunicazione con una stazione di controllo di rete o altre azioni appropriate per il supporto di rete.

Se un gestore chiamate è necessario per comunicare con gli agenti di controllo di rete (in altre parole, un commutatore di rete) deve usare una connessione virtuale all'agente di controllo di rete stabilito nella relativa funzione ProtocolBindAdapterEx . I gestori chiamate autonomi comunicano tramite il driver miniport sottostante chiamando NdisCoSendNetBufferLists. I driver Miniport con supporto integrato per la gestione delle chiamate non chiamano mai NdisCoSendNetBufferLists. Invece, trasmettono i dati direttamente attraverso la rete.

Inoltre, ProtocolCmRegisterSap deve eseguire le allocazioni necessarie di risorse dinamiche e strutture necessarie al gestore chiamate per mantenere le informazioni sullo stato relative a SAP per conto del client orientato alla connessione. Tali risorse includono, ad esempio, buffer di memoria, strutture di dati, eventi e altre risorse simili. Un gestore chiamate deve anche inizializzare tutte le risorse allocate prima di restituire il controllo a NDIS. I responsabili delle chiamate devono archiviare l'handle fornito da NDIS che identifica sap, fornito in NdisSapHandle, nell'area di contesto per un uso futuro.

Se ProtocolCmRegisterSap restituirà NDIS_STATUS_SUCCESS, deve, dopo aver allocato l'area di stato per SAP, impostare l'indirizzo di questa area di stato in CallMgrSapContext prima di restituire il controllo a NDIS. A tale scopo, dereferenziare CallMgrSapContext e archiviare un puntatore all'area dati come valore dell'handle. Ad esempio:

*CallMgrSapContext = SomeBuffer ;

Se il sap specificato già registrato da un altro client orientato alla connessione, il gestore chiamate deve non riuscire la richiesta e restituire NDIS_STATUS_INVALID_DATA.

Dopo che un gestore chiamate ha registrato un SAP per conto di un client orientato alla connessione, notifica che il client di un'offerta di chiamata in ingresso indirizzata a tale SAP chiamando NdisCmDispatchIncomingCall.

Esempi

Per definire una funzione ProtocolCmRegisterSap , è innanzitutto necessario fornire 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 con i tipi di funzione consente di eseguire l'analisi del codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica rilevano gli errori ed è un requisito per la scrittura dei driver per il sistema operativo Windows.

Ad esempio, per definire una funzione ProtocolCmRegisterSap denominata "MyCmRegisterSap", usare il tipo di PROTOCOL_CM_REG_SAP come illustrato in questo esempio di codice:

PROTOCOL_CM_REG_SAP MyCmRegisterSap;

Implementare quindi la funzione come segue:

_Use_decl_annotations_
NDIS_STATUS
 MyCmRegisterSap(
    NDIS_HANDLE  CallMgrAfContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle,
    PNDIS_HANDLE  CallMgrSapContext
    )
  {...}

Il tipo di funzione PROTOCOL_CM_REG_SAP è definito nel file di intestazione Ndis.h. Per identificare in modo più accurato gli errori quando si eseguono gli 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 utilizzate le annotazioni applicate al tipo di funzione PROTOCOL_CM_REG_SAP nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo di funzione per i driver NDIS.

Per informazioni sulle 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 ProtocolCmRegisterSap (NDIS 5.1)) in Windows Vista. Supportato per i driver NDIS 5.1 (vedere ProtocolCmRegisterSap (NDIS 5.1)) in Windows XP.
Piattaforma di destinazione	Windows
Intestazione	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL