PROTOCOL_CO_CREATE_VC funzione di callback (ndis.h)
La funzione ProtocolCoCreateVc è una funzione obbligatoria che alloca le risorse necessarie per un gestore chiamate o un client per attivare e gestire una connessione virtuale (VC).
Sintassi
PROTOCOL_CO_CREATE_VC ProtocolCoCreateVc;
NDIS_STATUS ProtocolCoCreateVc(
[in] NDIS_HANDLE ProtocolAfContext,
[in] NDIS_HANDLE NdisVcHandle,
[out] PNDIS_HANDLE ProtocolVcContext
)
{...}
Parametri
[in] ProtocolAfContext
Specifica l'handle di un'area di contesto allocata dal protocollo in cui il gestore chiamate o il client mantiene lo stato per ogni apertura. Il gestore chiamate ha fornito questo handle dalla relativa funzione ProtocolCmOpenAf . Il client ha fornito questo handle quando ha chiamato NdisClOpenAddressFamilyEx dalla relativa funzione ProtocolCoAfRegisterNotify .
[in] NdisVcHandle
Specifica un handle, fornito da NDIS, che identifica in modo univoco questa connessione virtuale. Questo handle è opaco al driver del protocollo e riservato per l'uso della libreria NDIS. Tuttavia, il gestore chiamate e il client devono salvare questo handle per passare le chiamate successive alle funzioni NdisCo/Cl/Cm/MCmXxx che riguardano questo vc.
[out] ProtocolVcContext
Specifica l'handle di un'area di contesto fornita dal protocollo in cui il gestore chiamate o il client mantiene lo stato relativo a questa connessione virtuale.
Valore restituito
ProtocolCoCreateVc restituisce lo stato delle operazioni come uno dei valori seguenti:
| Codice restituito | Descrizione |
|---|---|
|
Indica che il gestore chiamate o il client ha allocato correttamente e/o inizializzato le risorse necessarie per stabilire e gestire una connessione virtuale. |
|
Indica che il gestore chiamate o il client non è riuscito ad allocare e/o inizializzare le risorse per stabilire e gestire una connessione virtuale. |
|
Indica che il gestore chiamate o il client non è riuscito a impostare se stesso in uno stato in cui è stato possibile stabilire una connessione virtuale. Può trattarsi di un valore restituito di errore propagato da un'altra routine della libreria NDIS.
Nota I responsabili chiamate o i client non possono restituire NDIS_STATUS_PENDING dalle funzioni ProtocolCoCreateVc . La restituzione in sospeso eseguirà il rendering di questa connessione virtuale inutilizzabile e la libreria NDIS chiamerà il client o il gestore chiamate per eliminarla.
|
Commenti
La funzione ProtocolCoCreateVc di un gestore chiamate o un client viene chiamata ogni volta che il client o il gestore chiamate corrispondente chiama rispettivamente NdisCoCreateVc. I client avviano la creazione di schede virtuali durante il processo di configurazione delle chiamate in uscita prima di chiamare NdisClMakeCall. Un gestore chiamate avvia la creazione di un vc nel processo di notifica al client che cm ha ricevuto un'offerta di chiamata in arrivo da un nodo remoto che viene indirizzato a un sap già registrato con cm da tale client prima delle chiamate CM NdisCmDispatchIncomingCall.
ProtocolCoCreateVc esegue tutte le allocazioni necessarie di risorse dinamiche e strutture richieste dal gestore chiamate o dal client per eseguire operazioni successive su un vc che verrà attivato. Tali risorse includono, ad esempio, buffer di memoria, strutture di dati, eventi e altre risorse simili. I responsabili delle chiamate e i client devono anche inizializzare tutte le strutture pertinenti per vc necessarie quando viene stabilita una chiamata.
I driver di protocollo orientati alla connessione devono archiviare l'handle per vc, specificato in NdisVcHandle, nell'area di stato per VC da usare nelle operazioni future su questa connessione virtuale. NdisVcHandle è il parametro obbligatorio per NdisCoXxx, NdisCmXxx e/o NdisClXxx che tale protocollo orientato alla connessione chiama successivamente.
Quando un gestore chiamate o un client ha allocato memoria per i propri dati per VC e ne ha inizializzato lo stato, l'indirizzo di questa struttura di dati deve essere impostato nell'handle prima di restituire il controllo a NDIS. A tale scopo, dereferenziare l'handle e archiviare un puntatore all'area dati allocata dal protocollo come valore dell'handle. Ad esempio:
*ProtocolVcContext = SomeBuffer;
Se ProtocolCoCreateVc non può allocare la risorsa necessaria per eseguire le operazioni di I/O di rete successive, deve liberare tutte le risorse allocate per questo vc e restituire il controllo con stato NDIS_STATUS_RESOURCES.
Se ProtocolCoCreateVc ha completato le operazioni necessarie e ha reso il gestore chiamate o il client pronto per eseguire l'inizializzazione delle chiamate per questa connessione virtuale, ProtocolCoCreateVc deve restituire il controllo il più rapidamente possibile con lo stato di NDIS_STATUS_SUCCESS.
Le chiamate a ProtocolCoCreateVc sono intrinsecamente sincrone. Ovvero ProtocolCoCreateVcnon può restituire NDIS_STATUS_PENDING.
Dopo che la funzione ProtocolCoCreateVc di un gestore chiamate restituisce il controllo, la funzione ProtocolCmMakeCall del gestore chiamate verrà chiamata per stabilire una connessione a un nodo remoto. I responsabili delle chiamate non devono eseguire alcuna azione in ProtocolCmMakeCall che stabilisce effettivamente una chiamata perché è possibile che il vc venga eliminato prima che venga stabilita una chiamata a causa di una condizione di errore in un altro componente dell'NDIS orientato alla connessione.
Dopo che la funzione ProtocolCoCreateVc di un client restituisce il controllo, la funzione ProtocolClIncomingCall del client riceverà una notifica quando una richiesta avviata da remoto per connettersi a un sap registrato in precedenza dal client entra in rete.
Esempi
Per definire una funzione ProtocolCoCreateVc , è 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 ProtocolCoCreateVc denominata "MyCoCreateVc", usare il tipo di PROTOCOL_CO_CREATE_VC come illustrato nell'esempio di codice seguente:
PROTOCOL_CO_CREATE_VC MyCoCreateVc;
Implementare quindi la funzione come segue:
_Use_decl_annotations_
NDIS_STATUS
MyCoCreateVc(
NDIS_HANDLE ProtocolAfContext,
NDIS_HANDLE NdisVcHandle,
PNDIS_HANDLE ProtocolVcContext
)
{...}
Il tipo di funzione PROTOCOL_CO_CREATE_VC è 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_CO_CREATE_VC 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 ProtocolCoCreateVc (NDIS 5.1)) in Windows Vista. Supportato per i driver NDIS 5.1 (vedere ProtocolCoCreateVc (NDIS 5.1)) in Windows XP. |
| Piattaforma di destinazione | Windows |
| Intestazione | ndis.h (include Ndis.h) |
| IRQL | <= DISPATCH_LEVEL |