PROTOCOL_CM_MAKE_CALL funzione di callback (ndis.h)
La funzione ProtocolCmMakeCall è una funzione obbligatoria che configura parametri specifici del supporto per una connessione virtuale e attiva la connessione virtuale.
Sintassi
PROTOCOL_CM_MAKE_CALL ProtocolCmMakeCall;
NDIS_STATUS ProtocolCmMakeCall(
[in] NDIS_HANDLE CallMgrVcContext,
[in, out] PCO_CALL_PARAMETERS CallParameters,
[in, optional] NDIS_HANDLE NdisPartyHandle,
[out, optional] PNDIS_HANDLE CallMgrPartyContext
)
{...}
Parametri
[in] CallMgrVcContext
Specifica l'handle di un'area di contesto allocata dal gestore chiamate in cui i responsabili delle chiamate mantengono lo stato per vc. Il gestore chiamate ha fornito questo handle a NDIS dalla relativa funzione ProtocolCoCreateVc .
[in, out] CallParameters
Puntatore a una struttura CO_CALL_PARAMETERS che contiene i parametri, specificati da un client orientato alla connessione, per questa chiamata in uscita.
[in, optional] NdisPartyHandle
Specifica un handle, fornito da NDIS, che identifica in modo univoco la parte iniziale nella connessione virtuale multipoint. Questo handle è opaco al gestore chiamate e riservato per l'uso della libreria NDIS. Questo handle è NULL se il client non configura una chiamata multipunto in uscita.
[out, optional] CallMgrPartyContext
In caso di restituzione, specifica un handle per un'area di contesto fornita dal gestore chiamate in cui il gestore chiamate mantiene lo stato circa la parte iniziale nella chiamata multipoint. Se NdisPartyHandle è NULL, questo handle deve essere impostato su NULL.
Valore restituito
ProtocolCmMakeCall restituisce lo stato delle operazioni come uno dei valori seguenti:
| Codice restituito | Descrizione |
|---|---|
|
Indica che il gestore chiamate ha allocato correttamente le risorse necessarie per effettuare la chiamata ed è stato in grado di attivare la connessione virtuale con il driver miniport. |
|
Indica che il gestore chiamate completerà la richiesta per effettuare una chiamata in modo asincrono. Quando il gestore chiamate ha completato tutte le operazioni per effettuare una chiamata, deve chiamare NdisCmMakeCallComplete per segnalare a NDIS che questa chiamata è stata completata. |
|
Indica che il gestore chiamate non è riuscito ad allocare e/o inizializzare le risorse per l'attivazione della connessione virtuale come richiesto dal client. |
|
Indica che il gestore chiamate non è riuscito ad attivare una connessione virtuale perché il chiamante ha richiesto funzionalità non valide o non disponibili nei parametri di chiamata specificati in CallParameters . |
Commenti
Se a ProtocolCmMakeCall viene assegnato un NdisPartyHandle esplicito, questo vc è stato creato dal client per una chiamata multipoint. Il gestore chiamate deve allocare e inizializzare le risorse necessarie per mantenere le informazioni sullo stato e controllare una chiamata multipunto. Tali risorse includono, ad esempio, buffer di memoria, strutture di dati, eventi e altre risorse simili. Se il gestore chiamate non può allocare o inizializzare le risorse necessarie per le aree di stato, deve restituire il controllo a NDIS con NDIS_STATUS_RESOURCES.
ProtocolCmMakeCall comunica con dispositivi di controllo di rete o altri attori specifici del supporto, se necessario, per stabilire una connessione tra il nodo locale e un nodo remoto in base ai parametri di chiamata specificati in CallParameters . Tali azioni possono includere, ma non solo, comunicazioni con hardware switching, comunicazioni con una stazione di controllo di rete o altre azioni appropriate per il supporto di rete.
Se un gestore chiamate è necessario per comunicare con l'hardware di rete (ad esempio un commutatore di rete), deve usare una connessione virtuale al dispositivo di controllo di rete stabilito nella relativa funzione ProtocolBindAdapterEx . I responsabili delle chiamate comunicano con l'hardware di rete tramite il driver miniport chiamando NdisCoSendNetBufferLists. I driver Miniport con supporto integrato per la gestione delle chiamate non chiameranno NdisCoSendNetBufferLists, ma trasmetteranno i dati stessi.
Dopo che un chiamante ha eseguito tutte le comunicazioni necessarie con l'hardware di rete richiesto dal supporto, i responsabili chiamate devono chiamare NdisCmActivateVc.
Se questa chiamata è stata chiamata multipunto, dopo che il gestore chiamate ha comunicato con l'hardware di rete, i parametri di chiamata verificati e ha allocato e inizializzato i dati sullo stato per parte, l'indirizzo del relativo blocco di stato deve essere impostato nell'handle CallMgrPartyContext prima di restituire il controllo a NDIS. L'handle viene impostato dereferenziando l'handle e archiviando un puntatore al blocco di stato come valore dell'handle. Ad esempio:
*CallMgrPartyContext = SomeBuffer ;
Se ProtocolCmMakeCall ha completato le operazioni necessarie per la rete e il vc è stato attivato correttamente tramite NdisCmActivateVc, ProtocolCmMakeCall dovrebbe restituire il controllo il più rapidamente possibile con lo stato di STATUS_SUCCESS.
Dopo che ProtocolCmMakeCall restituisce il controllo a NDIS, il gestore chiamate dovrebbe prevedere di non eseguire altre azioni su questa chiamata per configurarla. ProtocolCmMakeCall è responsabile della creazione della connessione in modo che il client possa effettuare trasferimenti di dati in rete in questo vc. Tuttavia, il gestore chiamate può essere chiamato successivamente per modificare la qualità del servizio della chiamata, per aggiungere o eliminare parti se si tratta di un vc multipunto e infine per terminare questa chiamata.
Esempi
Per definire una funzione ProtocolCmMakeCall , è 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 ProtocolCmMakeCall denominata "MyCmMakeCall", usare il tipo PROTOCOL_CM_MAKE_CALL come illustrato nell'esempio di codice seguente:
PROTOCOL_CM_MAKE_CALL MyCmMakeCall;
Implementare quindi la funzione come segue:
_Use_decl_annotations_
NDIS_STATUS
MyCmMakeCall(
NDIS_HANDLE CallMgrVcContext,
PCO_CALL_PARAMETERS CallParameters,
NDIS_HANDLE NdisPartyHandle,
PNDIS_HANDLE CallMgrPartyContext
)
{...}
Il tipo di funzione PROTOCOL_CM_MAKE_CALL è 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 assicura che vengano utilizzate le annotazioni applicate al tipo di funzione PROTOCOL_CM_MAKE_CALL 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 ProtocolCmMakeCall (NDIS 5.1)) in Windows Vista. Supportato per i driver NDIS 5.1 (vedere ProtocolCmMakeCall (NDIS 5.1)) in Windows XP. |
| Piattaforma di destinazione | Windows |
| Intestazione | ndis.h (include Ndis.h) |
| IRQL | <= DISPATCH_LEVEL |