RpcSsContextLockExclusive-Funktion (rpcasync.h)

Die RpcSsContextLockExclusive-Funktion ermöglicht es einer Anwendung, ein Kontexthandle im exklusiven Modus zu verwenden. Die RpcSsContextLockExclusive-Funktion ermöglicht es Methoden, die in der IDL- oder ACF-Datei als nicht-ialisiert (freigegeben) deklariert wurden, dynamisch zu ändern, um im serialisierten (exklusiven) Modus auf ein Kontexthandle zuzugreifen.

Syntax

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

Parameter

[in] ServerBindingHandle

Bindungshandle auf dem Server, das eine Bindung an einen Client darstellt. Der Server gibt die Identität des Clients an, der durch dieses Handle angegeben wird. Wenn ein Wert von 0 angegeben wird, gibt der Server die Identität des Clients an, der von diesem Serverthread bedient wird.

[in] UserContext

Zeiger, der per RPC an den Manager oder die Serverroutine übergeben wird. Siehe Hinweise.

Bei reinen Kontexthandles führt die RpcSsContextLockExclusive-Funktion keinen Vorgang aus.

Rückgabewert

Gibt bei erfolgreicher Ausführung RPC_S_OK zurück, die angibt, dass der Thread jetzt zugriff auf das Kontexthandle im exklusiven Modus hat. Gibt ERROR_MORE_WRITES zurück, wenn mehrere Threads eine exklusive Sperre für das Kontexthandle versuchen. Siehe Hinweise.

Hinweis Eine Liste der gültigen Fehlercodes finden Sie unter RPC-Rückgabewerte.

 

Hinweise

Das Ändern, ob ein Kontexthandle serialisiert oder nicht serialisiert ist, kann für Anwendungen nützlich sein, die bestimmen, ob ein Kontexthandle basierend auf den bei der Ausführung erkannten Bedingungen geschlossen werden soll. Verwenden Sie die RpcSsContextLockShared-Funktion , um ein Kontexthandle von serialisiert (exklusiv) in nicht-serialisiert (freigegeben) zu ändern.

Wenn die Managerroutine für den UserContext-Parameter einen Zeiger auf ein Kontexthandle empfängt, muss sie der RpcSsContextLockExclusive-Funktion denselben Zeiger übergeben, den sie von RPC empfangen hat. Wenn die Managerroutine das Kontexthandle selbst empfängt, was typischerweise nur für [in]-Kontexthandles ist, muss sie das Kontexthandle selbst an die RpcSsContextLockExclusive-Funktion übergeben. Im folgenden Codebeispiel wird dies veranschaulicht:

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

Wenn eine Managerroutine mehrere [in,out]-Kontexthandles als Argument verwendet, gibt RPC der Managerroutine einen Zeiger auf das Kontexthandle, nicht auf das Kontexthandle selbst. Der Zeiger ist garantiert eindeutig, und daher ist die Übergabe an die RpcSsContextLockExclusive-Funktion eindeutig. Wenn eine Funktion jedoch nur mehrere [in]-Kontexthandles verwendet, gibt RPC dem Manager routine das Kontexthandle selbst. Daher ist das Kontexthandle möglicherweise nicht eindeutig. In diesem Fall führt RPC diese Funktion im ersten Kontexthandle mit dem angegebenen Wert aus.

Methoden sollten ein Kontexthandle nicht ändern, wenn sie sich im freigegebenen Modus befinden. Durch das Aufrufen der RpcSsContextLockExclusive-Funktion wird keine Lesersperre für das angegebene Kontexthandle beseitigt. Dadurch wird ein unverändertes Kontexthandle für Anwendungen sichergestellt, die Kontexthandles im freigegebenen Modus nicht ändern. Wenn zwei Threads versuchen, eine exklusive Sperre für dasselbe Kontexthandle zu erhalten, indem sie die RpcSsContextLockExclusive-Funktion gleichzeitig aufrufen, wird ein willkürlich ausgewählter Thread RPC_S_OK zurückgegeben, und der andere wird ERROR_MORE_WRITES zurückgegeben. Der Thread, der ERROR_MORE_WRITES zurückgegeben wird, erhält eine exklusive Sperre, aber seine Lesersperre für das Kontexthandle geht bei der Rückgabe verloren. Ein Aufrufer, der ERROR_MORE_WRITES empfängt, darf bei der Rückgabe der RpcSsContextLockExclusive-Funktion nichts über das Kontexthandle annehmen, da es möglicherweise zerstört wurde.

Asynchrone Aufrufe dürfen nicht die RpcSsContextLockExclusive-Funktion für dasselbe Aufrufobjekt aus mehreren Threads gleichzeitig verwenden.

Die RpcSsContextLockExclusive-Funktion kann aufgrund von Nicht-Arbeitsspeicher-Bedingungen fehlschlagen, und RPC-Server müssen daher bereit sein, solche Fehler zu behandeln.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	rpcasync.h (include Rpc.h)
Bibliothek	Rpcrt4.lib
DLL	Rpcrt4.dll

Weitere Informationen

RpcSsContextLockShared

context_handle

context_handle_noserialize

context_handle_serialize