PROTOCOL_CM_REG_SAP funzione di callback (ndis.h)
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.
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 |
|---|---|
|
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. |
|
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. |
|
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. |
|
Indica che la specifica fornita in Sap non è valida o non può essere supportata. |
|
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 |