Sviluppo di interfacce tramite handle di contesto

In genere, si crea un handle di contesto specificando l'attributo [context_handle] in una definizione di tipo nel file IDL. La definizione del tipo specifica anche in modo implicito una routine di esecuzione del contesto, che è necessario specificare. Se la comunicazione tra il client e il server si interrompe, il tempo di esecuzione del server richiama questa routine per eseguire la pulizia necessaria. Per altre informazioni sulle routine di esecuzione del contesto, vedere Routine di esecuzione del contesto del server.

Un'interfaccia che usa un handle di contesto deve avere un handle di associazione per l'associazione iniziale, che deve essere eseguita prima che il server possa restituire un handle di contesto. È possibile usare un handle di associazione automatico, implicito o esplicito per creare l'associazione e stabilire il contesto.

Un handle di contesto deve essere di tipo void * o di un tipo che si risolve in void *. Il programma server lo esegue il cast al tipo richiesto.

Nota

L'uso di [in, out] per i parametri di handle di contesto è sconsigliato, ad eccezione delle routine che chiudono gli handle di contesto. Se vengono usati i parametri contrassegnati come [in, out], non passare un handle di contesto NULL o non inizializzato dal client al server. È invece necessario passare un puntatore NULL a un handle di contesto. Si noti che i parametri di handle di contesto contrassegnati come [in] non accettano puntatori NULL .

 

Il frammento seguente di una definizione di interfaccia di esempio mostra come un'applicazione distribuita può usare un handle di contesto per avere un server aperto e aggiornare un file di dati per ogni client.

L'interfaccia deve contenere una chiamata di routine remota per inizializzare l'handle e impostarla su un valore non Null . In questo esempio la funzione RemoteOpen esegue questa operazione. Specifica l'handle di contesto con un attributo direzionale [out]. In alternativa, è possibile restituire l'handle di contesto come valore restituito della routine. In questo esempio, tuttavia, il contesto verrà passato attraverso l'elenco di parametri.

In questo esempio, le informazioni sul contesto sono un handle di file. Tiene traccia del percorso corrente nel file. L'interfaccia crea un pacchetto dell'handle di file come handle di contesto e lo passa come parametro alle chiamate di routine remote. Una struttura contiene il nome del file e l'handle di file.

/* file: cxhndl.idl (fragment of interface definition file) */
typedef [context_handle] void * PCONTEXT_HANDLE_TYPE;
typedef [ref] PCONTEXT_HANDLE_TYPE * PPCONTEXT_HANDLE_TYPE;
 
short RemoteOpen([out] PPCONTEXT_HANDLE_TYPE pphContext,
    [in, string] unsigned char * pszFile);
 
void RemoteRead(
    [in] PCONTEXT_HANDLE_TYPE phContext,
    [out, size_is(cbBuf)] unsigned char achBuf[],
    [in, out] short *pcbBuf);
 
short RemoteClose([in, out] PPCONTEXT_HANDLE_TYPE pphContext);

La funzione RemoteOpen crea un handle di contesto non Null valido. Passa l'handle di contesto al client. Le successive chiamate di procedura remota, ad esempio RemoteRead, usano l'handle di contesto come puntatore.

Oltre alla procedura remota che inizializza l'handle di contesto, l'interfaccia deve contenere una routine che libera il contesto del server e imposta l'handle di contesto su NULL. Nell'esempio precedente la funzione RemoteClose esegue questa operazione.