Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
L'attributo [context_handle] identifica un handle di associazione che gestisce il contesto o le informazioni sullo stato nel server tra chiamate di routine remote.
typedef [context_handle [ , type-attribute-list ] ] type-specifier declarator-list;
[context_handle [, function-attr-list ] ] type-specifier [ptr-decl] function-name(
[ [parameter-attribute-list] ] type-specifier [declarator], ...);
[ [ function-attr-list ] ] type-specifier [ ptr-decl ] function-name(
[context_handle [ , parameter-attribute-list ] ] type-specifier [declarator], ...);
[ void __RPC_USER context-handle-type_rundown (
context-handle-type); ]
Parametri
-
type-attribute-list
-
Specifica uno o più attributi che si applicano al tipo.
-
type-specifier
-
Specifica un tipo di puntatore o un identificatore di tipo. Una specifica di archiviazione facoltativa può precedere l'identificatore di tipo.
-
declarator e declarator-list
-
Specifica i dichiaratori C standard, ad esempio identificatori, dichiaratori di puntatore e dichiaratori di matrice. Il dichiaratore per un handle di contesto deve includere almeno un dichiaratore di puntatore. Per altre informazioni, vedere Matrice e Sized-Pointer attributi, matrici e matricie puntatori. L'elenco dichiaratore è costituito da uno o più dichiaratori, separati da virgole. L'identificatore del nome del parametro nel dichiaratore di funzione è facoltativo.
-
function-attr-list
-
Specifica zero o più attributi che si applicano alla funzione. Gli attributi di funzione validi sono [callback], [local]; attributo puntatore [ref], [unique], o [ptr]; e gli attributi di utilizzo [string], [ignore]e [context_handle].
-
ptr-decl
-
Specifica zero o più dichiaratori di puntatore. Un dichiaratore di puntatore è uguale al dichiaratore del puntatore usato in C; viene costruito dal * designatore, dai modificatori, come ad esempio, e dal qualificatore const.
-
function-name
-
Specifica il nome della routine remota.
-
parameter-attribute-list
-
Specifica zero o più attributi direzionali, attributi di campo, attributi di utilizzo e attributi del puntatore appropriati per il tipo di parametro specificato. Separare più attributi con virgole.
-
context-handle-type
-
Specifica l'identificatore che specifica il tipo di handle di contesto come definito in una dichiarazione typedef che accetta l'attributo [context_handle]. La routine di rundown è facoltativa.
Windows Server 2003 e Windows XP: Una singola interfaccia può contenere handle di contesto serializzati e non serializzati, consentendo a un metodo su un'interfaccia di accedere esclusivamente a un handle di contesto (serializzato), mentre altri metodi accedono a tale handle di contesto in modalità condivisa (nonrializzato). Queste funzionalità di accesso sono paragonabili ai meccanismi di blocco di lettura/scrittura; i metodi che usano un handle di contesto serializzato sono utenti esclusivi (writer), mentre i metodi che usano un handle di contesto nonrializzato sono utenti condivisi (lettori). I metodi che eliminano o modificano lo stato di un handle di contesto devono essere serializzati. I metodi che non modificano lo stato di un handle di contesto, ad esempio i metodi che semplicemente leggono da un handle di contesto, possono essere nonrializzati. Si noti che i metodi di creazione vengono serializzati in modo implicito.
Osservazioni:
L'attributo [context_handle] può essere visualizzato come attributo typedef IDL, come attributo di tipo restituito dalla funzione o come attributo di parametro. Quando si applica l'attributo [context_handle] a una definizione di tipo, è necessario specificare anche una routine di rundown del contesto. Per informazioni dettagliate, vedere Routine di esecuzione del contesto del server .
Quando si usa il compilatore MIDL in modalità predefinita (/ms_ext), un handle di contesto può essere qualsiasi tipo di puntatore selezionato dall'utente, purché sia conforme ai requisiti per gli handle di contesto descritti qui. I dati associati a un tipo di handle di contesto di questo tipo non vengono trasmessi nella rete e devono essere modificati solo dall'applicazione server. I compilatori IDL DCE limitano gli handle di contesto ai puntatori di tipo void*. Questa funzionalità non è pertanto disponibile quando si usa l'opzione /osf del compilatore MIDL.
Come con altri tipi di handle, l'handle di contesto è opaco per l'applicazione client e tutti i dati associati non vengono trasmessi. Nel server l'handle di contesto funge da handle nel contesto attivo e tutti i dati associati al tipo di handle di contesto sono accessibili.
Per creare un handle di contesto, il client passa al server un puntatore [out], [ref] a un handle di contesto. L'handle di contesto stesso può avere un valore NULL o non NULL , purché il relativo valore sia coerente con gli attributi del puntatore. Ad esempio, quando al tipo di handle di contesto è applicato l'attributo [ref] , non può avere un valore NULL . È necessario specificare un altro handle di associazione per eseguire l'associazione fino a quando non viene creato l'handle di contesto. Quando non viene specificato alcun handle esplicito, viene usata l'associazione implicita. Quando non è presente alcun attributo [implicit_handle] , viene usato un handle automatico.
La procedura remota nel server crea un handle di contesto attivo. Il client deve usare tale handle di contesto come parametro [in] o [in, out] nelle chiamate successive. Un handle di contesto [in]-only può essere usato come handle di associazione, pertanto deve avere un valore non NULL . Un handle di contesto [in]-only non riflette le modifiche di stato nel server.
Nel server la routine chiamata può interpretare l'handle di contesto in base alle esigenze. Ad esempio, la procedura chiamata può allocare l'archiviazione dell'heap e usare l'handle di contesto come puntatore a questa risorsa di archiviazione.
Per chiudere un handle di contesto, il client passa l'handle di contesto come argomento [in], [out]. Il server deve restituire un handle di contesto NULL quando non gestisce più il contesto per conto del chiamante. Ad esempio, se l'handle di contesto rappresenta un file aperto e la chiamata chiude il file, il server deve impostare l'handle di contesto su NULL e restituirlo al client. Un valore NULL non è valido come handle di associazione nelle chiamate successive.
Un handle di contesto è valido solo per un server. Quando una funzione ha due parametri di handle e l'handle di contesto non è NULL, gli handle di associazione devono fare riferimento allo stesso spazio indirizzi.
Quando una funzione ha un handle di contesto [in] o [in, out] , il relativo handle di contesto può essere usato come handle di associazione. In questo caso, l'associazione implicita non viene usata e l'attributo [implicit_handle] o [auto_handle] viene ignorato.
Le restrizioni seguenti si applicano agli handle di contesto:
- Gli handle di contesto non possono essere elementi di matrice, membri della struttura o membri di unione. Possono essere solo parametri.
- Gli handle di contesto non possono avere l'attributo [transmit_as] o [represent_as].
- I parametri che sono puntatori agli handle di contesto [out] devono essere puntatori [ref].
- Un handle di contesto [in] può essere usato come handle di associazione e non può essere NULL.
- Un handle di contesto [in, out può essere NULL all'input, ma solo se la routine ha un altro parametro handle esplicito. Se non sono presenti altri parametri di handle di contesto non NULL espliciti, l'handle di contesto [in, out] non può essere NULL.
- Non è possibile usare un handle di contesto con callback.
Examples
typedef [context_handle] void * PCONTEXT_HANDLE_TYPE;
short RemoteFunc1([out] PCONTEXT_HANDLE_TYPE * pCxHandle);
short RemoteFunc2([in, out] PCONTEXT_HANDLE_TYPE * pCxHandle);
void __RPC_USER PCONTEXT_HANDLE_TYPE_rundown (PCONTEXT_HANDLE_TYPE);
Vedere anche