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

Статья
08/25/2023

Функция RpcSsContextLockExclusive позволяет приложению начать использовать дескриптор контекста в монопольном режиме. Функция RpcSsContextLockExclusive позволяет динамически изменять методы, объявленные как несериализованные (общие) в IDL-файле или ACF, для доступа к дескриптору контекста в сериализованном (монопольном) режиме.

Синтаксис

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

Параметры

[in] ServerBindingHandle

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

[in] UserContext

Указатель, передаваемый в подпрограмму диспетчера или сервера с помощью RPC. См. заметки.

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

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

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

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

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

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

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

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

Методы не должны изменять дескриптор контекста в режиме общего доступа. Вызов функции RpcSsContextLockExclusive не устраняет блокировку чтения для указанного дескриптора контекста; это гарантирует неизменность дескриптора контекста для приложений, которые не изменяют дескрипторы контекста в общем режиме. Если два потока пытаются получить монопольную блокировку одного и того же дескриптора контекста путем одновременного вызова функции RpcSsContextLockExclusive , один произвольно выбранный поток возвращается RPC_S_OK, а другой возвращается ERROR_MORE_WRITES. Поток, который возвращается ERROR_MORE_WRITES, получает монопольную блокировку, но его блокировка чтения для дескриптора контекста теряется при возврате. Вызывающий объект, получающий ERROR_MORE_WRITES, не должен ничего предполагать о дескрипторе контекста при возвращении функции RpcSsContextLockExclusive , так как он мог быть уничтожен.

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

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

Требования

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

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

RpcSsContextLockShared

context_handle

context_handle_noserialize

context_handle_serialize

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