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 run-down 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 del tipo void * oppure un tipo che si risolve in void *. Il programma server lo 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 il contesto gestisce i parametri contrassegnati [in, out] vengono usati, non passare un handle di contesto NULL o non inizializzato dal client al server. Deve essere passato un puntatore NULL a un handle di contesto. Si noti che i parametri handle di contesto indicati con [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 aprire un server e aggiornare un file di dati per ogni client.

L'interfaccia deve contenere una chiamata di procedura remota per inizializzare l'handle e impostarlo 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 procedura. Tuttavia, in questo esempio, il handle del contesto verrà passato attraverso l'elenco di parametri.

In questo esempio, le informazioni sul contesto sono un handle di file. Tiene traccia della posizione attuale nel file. L'interfaccia impacchetta l'handle di file come handle di contesto e lo passa come parametro alle chiamate di procedura 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 nullvalido e diverso da. Passa l'handle di contesto al client. Le chiamate di procedura remota successive, come RemoteRead, utilizzano l'handle di contesto come parametro di input.

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.