Funzione RpcSsContextLockExclusive (rpcasync.h)

Articolo
03/15/2023

La funzione RpcSsContextLockExclusive consente a un'applicazione di iniziare a usare un handle di contesto in modalità esclusiva. La funzione RpcSsContextLockExclusive consente ai metodi dichiarati come non condivisi (condivisi) nel file IDL o ACF di essere modificati dinamicamente per accedere a un handle di contesto in modalità serializzata (esclusiva).

Sintassi

RPC_STATUS RpcSsContextLockExclusive(
  [in] RPC_BINDING_HANDLE ServerBindingHandle,
  [in] PVOID              UserContext
);

Parametri

[in] ServerBindingHandle

Handle di associazione nel server che rappresenta un'associazione a un client. Il server rappresenta il client indicato da questo handle. Se viene specificato un valore pari a zero, il server rappresenta il client gestito da questo thread del server.

[in] UserContext

Puntatore passato alla routine di gestione o server tramite RPC. Vedere la sezione Osservazioni.

Per gli handle di contesto out-only, la funzione RpcSsContextLockExclusive non esegue alcuna operazione.

Valore restituito

Restituisce RPC_S_OK al termine dell'esecuzione, a indicare che il thread ha ora accesso all'handle di contesto in modalità esclusiva. Restituisce ERROR_MORE_WRITES quando più thread tentano un blocco esclusivo sull'handle di contesto. Vedere la sezione Osservazioni.

Nota Per un elenco di codici di errore validi, vedere Valori restituiti RPC.

Commenti

Modificare se un handle di contesto viene serializzato o non serializzato può essere utile per le applicazioni che determinano se chiudere un handle di contesto in base alle condizioni rilevate durante l'esecuzione. Per modificare un handle di contesto da serializzato (esclusivo) a nonserializzato (condiviso), usare la funzione RpcSsContextLockShared .

Per il parametro UserContext , se la routine manager riceve un puntatore a un handle di contesto, deve passare la funzione RpcSsContextLockExclusive lo stesso puntatore ricevuto da RPC. Se la routine di gestione riceve l'handle di contesto stesso, che è tipico solo per gli handle di contesto [in], deve passare l'handle di contesto stesso alla funzione RpcSsContextLockExclusive . Nell'esempio di codice seguente viene illustrato quanto segue:

void _UseShared(
    /* [in] */ handle_t Binding,
    //...
    /* [in] */ TestContextHandleShared *Ctx,
    //...
    )
{
    //...
    RpcStatus = RpcSsContextLockExclusive(Binding, Ctx);
    //...
}

Se una routine di gestione accetta più handle di contesto [in, out] come argomento, RPC assegna al gestore un puntatore all'handle di contesto, non all'handle di contesto stesso. Il puntatore è garantito che sia univoco e quindi lo passi alla funzione RpcSsContextLockExclusive non ambiguo. Tuttavia, se una funzione accetta più handle di contesto [in], RPC fornisce alla routine di gestione l'handle di contesto stesso. Pertanto, l'handle di contesto potrebbe non essere univoco. In questo caso, RPC esegue questa funzione nel primo handle di contesto con il valore specificato.

I metodi non devono modificare un handle di contesto quando è in modalità condivisa. La chiamata alla funzione RpcSsContextLockExclusive non elimina un blocco lettore sull'handle di contesto specificato; in questo modo si garantisce un handle di contesto invariato per le applicazioni che non modificano gli handle di contesto in modalità condivisa. Se due thread tentano di ottenere un blocco esclusivo sullo stesso handle di contesto chiamando la funzione RpcSsContextLockExclusive contemporaneamente, viene restituito un thread scelto arbitrariamente RPC_S_OK e l'altro viene restituito ERROR_MORE_WRITES. Il thread restituito ERROR_MORE_WRITES riceve un blocco esclusivo, ma il blocco del lettore sull'handle di contesto viene perso al momento della restituzione. Un chiamante che riceve ERROR_MORE_WRITES deve presupporre nulla sull'handle di contesto al momento della restituzione della funzione RpcSsContextLockExclusive , perché potrebbe essere stata eliminata definitivamente.

Le chiamate asincrone non devono usare la funzione RpcSsContextLockExclusive sullo stesso oggetto di chiamata da più thread alla volta.

La funzione RpcSsContextLockExclusive può non riuscire a causa di condizioni di memoria insufficiente e i server RPC devono quindi essere pronti a gestire tali errori.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	rpcasync.h (include Rpc.h)
Libreria	Rpcrt4.lib
DLL	Rpcrt4.dll

Vedi anche

RpcSsContextLockShared

context_handle

context_handle_noserialize

context_handle_serialize

Condividi tramite