Функция RpcNsMgmtHandleSetExpAge (rpcnsi.h)

Статья
08/25/2023

Функция RpcNsMgmtHandleSetExpAge задает срок действия дескриптора службы имен для локальных копий данных службы имен.

Примечание Эта функция не поддерживается в операционных системах Windows Vista и более поздних версий.

Синтаксис

RPC_STATUS RpcNsMgmtHandleSetExpAge(
  RPC_NS_HANDLE NsHandle,
  unsigned long ExpirationAge
);

Параметры

NsHandle

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

ExpirationAge

Целочисленное значение в секундах, которое задает срок действия локальных данных службы имен, считанных всеми следующими подпрограммами с помощью указанного параметра NsHandle .

Срок действия 0 приводит к немедленному обновлению данных локальной службы имен.

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

Значение	Значение
RPC_S_OK	Вызов выполнен успешно.
RPC_S_NAME_SERVICE_UNAVAILABLE	Служба имен недоступна.

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

Функция RpcNsMgmtHandleSetExpAge задает срок действия дескриптора для указанного дескриптора службы имени (NsHandle). Срок действия — это период времени, в течение которых локальная копия данных из атрибута name-service может существовать до того, как запрос из приложения для атрибута потребует обновления локальной копии. При запуске приложения в библиотеке времени выполнения RPC указывается срок действия по умолчанию в два часа. Значение по умолчанию является глобальным для приложения. Срок действия дескриптора применяется только к определенному дескриптору службы имен и временно переопределяет текущий глобальный срок действия.

Срок действия дескриптора используется исключительно следующими операциями указателя (которые считывают данные из атрибутов службы имен). Следующая операция обычно начинается с поиска локальной копии данных атрибута, запрашиваемой приложением. При отсутствии локальной копии следующая операция создает экземпляр со свежими данными атрибутов из базы данных службы имен. Если локальная копия уже существует, операция сравнивает ее фактический возраст с сроком действия, используемым приложением (в данном случае это срок действия, заданный для дескриптора службы имен). Если фактический срок действия превышает срок действия дескриптора, операция автоматически пытается обновить локальную копию новыми данными атрибутов. Если обновление невозможно, старые локальные данные остаются на месте и следующая операция завершается сбоем, возвращая код состояния RPC_S_NAME_SERVICE_UNAVAILABLE.

Область срока действия дескриптора — это одна серия следующих операций. Функция RpcNsMgmtHandleSetExpAge работает в следующем контексте:

Операция begin создает дескриптор службы имен.
Вызов функции RpcNsMgmtHandleSetExpAge создает срок действия дескриптора.
Ряд следующих операций для дескриптора службы имен использует срок действия дескриптора.
Выполненная операция для дескриптора службы имен удаляет дескриптор и срок его действия.

Примечание Как правило, следует избегать использования RpcNsMgmtHandleSetExpAge. Вместо этого следует полагаться на глобальный срок действия приложения. Установка небольшого значения срока действия дескриптора приводит к тому, что следующие операции службы имен часто обновляют локальные данные для любого атрибута службы имен, запрошенного приложением. Например, если установить для срока действия значение 0, следующая операция будет обновлять локальные данные для атрибута name-service, запрошенного приложением. Таким образом, установка небольшого срока действия дескриптора может создать проблемы с производительностью приложения. Кроме того, если приложение использует удаленный сервер службы имен, небольшой срок действия может негативно повлиять на производительность сети для всех приложений.

Ограничьте использование RpcNsMgmtHandleSetExpAge следующими ситуациями:

Если необходимо всегда получать точные данные службы имен.
Например, во время операций управления для обновления профиля может потребоваться всегда просматривать текущее содержимое профиля. В этом случае перед началом запроса о профиле приложение должно вызвать функцию RpcNsMgmtHandleSetExpAge и указать 0 для параметра ExpirationAge .
Если запрос, использующий срок действия по умолчанию, завершился сбоем, и приложению необходимо повторить операцию.
Например, клиентское приложение, использующее операции импорта службы имен, должно сначала попытаться получить привязки, используя срок действия приложения по умолчанию. Однако иногда операция import-next возвращает либо отсутствие дескрипторов привязки, либо их недостаточное количество. В этом случае клиент может повторить операцию импорта и после вызова RpcNsBindingImportBegin включить вызов RpcNsMgmtHandleSetExpAge и указать 0 для параметра ExpirationAge . Когда клиент снова вызывает функцию import-next, небольшой срок действия дескриптора приводит к тому, что операция import-next обновляет данные локальных атрибутов.

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	rpcnsi.h (включая Rpc.h)
Библиотека	Rpcns4.lib
DLL	Rpcns4.dll

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

RpcNsBindingImportBegin

RpcNsMgmtInqExpAge

RpcNsMgmtSetExpAge

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