Функция RpcSsContextLockShared (rpcasync.h)

Статья
08/25/2023

Функция RpcSsContextLockShared позволяет приложению начать использовать дескриптор контекста в общем режиме.

Синтаксис

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

Параметры

[in] ServerBindingHandle

Дескриптор привязки на сервере, представляющий привязку к клиенту. Сервер олицетворяет клиента, указанного этим дескриптором. Если указано нулевое значение, сервер олицетворяет клиент, обслуживаемый этим потоком сервера.

[in] UserContext

Указатель, передаваемый в подпрограмму диспетчера или сервера rpc. Дополнительные сведения см. в разделе "Примечания".

Для [out] только для дескрипторов контекста функция RpcSsContextLockShared не выполняет никаких операций.

Возвращаемое значение

Возвращает RPC_S_OK после успешного выполнения, указывая, что поток теперь имеет доступ к дескриптору контекста в общем режиме.

Примечание Список допустимых кодов ошибок см. в разделе Возвращаемые значения RPC.

Изменение сериализации или несериализации дескриптора контекста может быть полезно для приложений, которые определяют, следует ли закрывать дескриптор контекста на основе условий, обнаруженных при выполнении. Чтобы изменить дескриптор контекста с несериализованного (общего) на сериализованный (эксклюзивный), используйте функцию RpcSsContextLockExclusive .

Если для параметра UserContext подпрограмма диспетчера получает указатель на дескриптор контекста, она должна передать функции RpcSsContextLockShared тот же указатель, который она получила от RPC. Если подпрограмма руководителя получает сам дескриптор контекста, что типично для дескрипторов контекста [in] только для дескрипторов контекста, она должна передать сам дескриптор контекста в функцию RpcSsContextLockShared . Это демонстрируется в следующем примере кода:

UseExclusive (..., /* [in] */ TestContextHandleExclusive *Ctx, ...)
{
    ...
    // we decided that we're done changing the context handle exclusively
    // and that we have extensive processing ahead - downgrade the exclusive
    // lock to shared, and do the processing allowing other readers in
    RpcSsContextLockShared (NULL,    // use the explicit context
        Ctx
        );
    ...
}

Если подпрограмма руководителя принимает несколько дескрипторов контекста [in, out] в качестве аргумента, RPC дает подпрограмме руководителя указатель на дескриптор контекста, а не сам дескриптор контекста. Указатель гарантированно будет уникальным, поэтому передача его функции RpcSsContextLockShared является однозначной. Однако если функция принимает несколько дескрипторов контекста [in], RPC предоставляет подпрограмме диспетчера сам дескриптор контекста. Поэтому дескриптор контекста может быть не уникальным. В этом случае RPC выполняет эту функцию на первом дескрипторе контекста с заданным значением.

Методы не должны изменять дескриптор контекста в общем режиме. Вызов функции RpcSsContextLockShared не устраняет блокировку записи для указанного дескриптора контекста; это гарантирует, что дескриптор контекста не будет изменен другим потоком.

Асинхронные вызовы не должны использовать функцию RpcSsContextLockShared в одном объекте вызова из нескольких потоков одновременно.

Функция RpcSsContextLockShared может завершиться сбоем из-за нехватки памяти, поэтому серверы RPC должны быть готовы к обработке таких ошибок.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	rpcasync.h (включая Rpc.h)
Библиотека	Rpcrt4.lib
DLL	Rpcrt4.dll

См. также раздел

RpcSsContextLockExclusive

context_handle

context_handle_noserialize

context_handle_serialize

Поделиться через