PROTOCOL_CL_MAKE_CALL_COMPLETE funzione di callback (ndis.h)

Articolo
02/29/2024

La funzione ProtocolClMakeCallComplete viene usata dai client NDIS orientati alla connessione che effettuano chiamate in uscita. Tali client devono avere funzioni ProtocolClMakeCallComplete per completare le operazioni asincrone avviate con NdisClMakeCall. In caso contrario, la funzione ProtocolClMakeCallComplete registrata di un driver di protocollo di questo tipo può semplicemente restituire il controllo.

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

Sintassi

PROTOCOL_CL_MAKE_CALL_COMPLETE ProtocolClMakeCallComplete;

void ProtocolClMakeCallComplete(
  [in]           NDIS_STATUS Status,
  [in]           NDIS_HANDLE ProtocolVcContext,
  [in, optional] NDIS_HANDLE NdisPartyHandle,
  [in]           PCO_CALL_PARAMETERS CallParameters
)
{...}

Parametri

[in] Status

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

NDIS_STATUS_SUCCESS

Il tentativo del client di configurare una connessione virtuale è riuscito. Di conseguenza, il client può procedere per effettuare trasferimenti nel vc attivo usando NdisVcHandle restituito da NdisCoCreateVc, che il client ha archiviato nell'area di contesto per VC in ProtocolVcContext .

NDIS_STATUS_RESOURCES

NDIS, gestione chiamate o driver sottostante non è riuscito ad allocare risorse sufficienti per configurare la connessione.

NDIS_STATUS_XXX

Il gestore chiamate o il driver miniport sottostante non è riuscito a stabilire una connessione attiva e NDIS ha propagato questo stato di errore determinato dal driver al client.

[in] ProtocolVcContext

Specifica l'handle per l'area di contesto per VC del client, che il client ha originariamente fornito a NDIS quando ha chiamato NdisCoCreateVc per configurare vc per la chiamata in uscita.

[in, optional] NdisPartyHandle

Se Status è NDIS_STATUS_SUCCESS e il client ha creato un vc multipoint passando un handle ProtocolPartyContext esplicito a NdisClMakeCall, si tratta di un NdisPartyHandle valido. In caso contrario, questo parametro è NULL.

ProtocolClMakeCallComplete deve salvare qualsiasi input valido NdisPartyHandle, in genere nell'area del contesto per parte del client. Il client deve usare questo handle se (o quando) effettua una chiamata successiva a NdisClDropParty o NdisClCloseCall che fa riferimento a questa parte.

[in] CallParameters

Puntatore a una struttura di CO_CALL_PARAMETERS memorizzata nel buffer. Il client ha allocato questo buffer e inizializzato questa struttura con i dati determinati dal client prima di passare questo puntatore a NdisClMakeCall. Durante l'elaborazione della richiesta del client, il gestore chiamate può modificare questi dati in modo da riflettere i risultati della negoziazione con la rete o con un peer di segnalazione.

Valore restituito

nessuno

Osservazioni

Una chiamata a ProtocolClMakeCallComplete indica che il gestore chiamate ha completato l'elaborazione della richiesta del client per stabilire una connessione virtuale con NdisClMakeCall.

Se il tentativo del client di stabilire una chiamata in uscita ha esito negativo (lo stato di input è qualcosa tranne NDIS_STATUS_SUCCESS), ProtocolClMakeCallComplete deve eseguire le operazioni seguenti:

Rilasciare o preparare il riutilizzo dell'area ProtocolPartyContext , se presente, e il buffer in CallParameters allocato dal client.
Rimuovere il vc creato dal client con una chiamata a NdisCoDeleteVc e rilasciare o prepararsi per riutilizzare l'area ProtocolVcContext allocata dal client.

In caso contrario, ProtocolClMakeCallComplete deve eseguire le operazioni seguenti:

Controllare il membro Flags della struttura in CallParameters per verificare se CALL_PARAMETERS_CHANGED è impostato, che indica che il gestore chiamate ha modificato i parametri di chiamata forniti dal client.
In tal caso, esaminare i dati in CallParameters per determinare se sono accettabili per questa connessione.
Ad esempio, il client potrebbe conservare i parametri di chiamata memorizzati nel buffer per il vc attivo, salvare NdisPartyHandle se si tratta di un vc multipunto e in genere rendere il client pronto per i trasferimenti successivi e altre operazioni sul vc attivo se rileva i parametri di chiamata specificati in modo soddisfacente.
In caso contrario, il protocollo di segnalazione determina se il client può tentare di rinegoziare i parametri di chiamata accettabili con il gestore chiamate.
Ad esempio, un gestore chiamate specifico potrebbe consentire ai client di chiamare NdisClModifyCallQoS una o più volte in queste circostanze.
Se i parametri di chiamata modificati da CM non sono accettabili e la rinegoziazione è impossibile, ProtocolClMakeCallComplete deve eliminare la chiamata con NdisClCloseCall.
In questo caso, ProtocolClMakeCallComplete non deve tentare di rilasciare risorse allocate dal client al ritorno da NdisClCloseCall, ma può semplicemente restituire il controllo. Al contrario, il client deve rilasciare le risorse allocate (o prepararle per il riutilizzo) all'interno della relativa funzione ProtocolClCloseCallComplete .

Esempi

Per definire una funzione ProtocolClMakeCallComplete , è 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 ProtocolClMakeCallComplete denominata "MyClMakeCallComplete", usare il tipo di PROTOCOL_CL_MAKE_CALL_COMPLETE come illustrato nell'esempio di codice seguente:

PROTOCOL_CL_MAKE_CALL_COMPLETE MyClMakeCallComplete;

Implementare quindi la funzione come segue:

_Use_decl_annotations_
VOID
 MyClMakeCallComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  NdisPartyHandle,
    PCO_CALL_PARAMETERS  CallParameters
    )
  {...}

Il tipo di funzione PROTOCOL_CL_MAKE_CALL_COMPLETE è 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_CL_MAKE_CALL_COMPLETE 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 ProtocolClMakeCallComplete (NDIS 5.1)) in Windows Vista. Supportato per i driver NDIS 5.1 (vedere ProtocolClMakeCallComplete (NDIS 5.1)) in Windows XP.
Piattaforma di destinazione	Windows
Intestazione	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL