структура RPC_CALL_ATTRIBUTES_V1_W (rpcasync.h)
Структура RPC_CALL_ATTRIBUTES_V1 предоставляет параметры функции RpcServerInqCallAttributes . Реализовано в версиях ANSI и UNICODE для операционных систем Windows XP и Windows Server 2003.
Синтаксис
typedef struct tagRPC_CALL_ATTRIBUTES_V1_W {
unsigned int Version;
unsigned long Flags;
unsigned long ServerPrincipalNameBufferLength;
unsigned short *ServerPrincipalName;
unsigned long ClientPrincipalNameBufferLength;
unsigned short *ClientPrincipalName;
unsigned long AuthenticationLevel;
unsigned long AuthenticationService;
BOOL NullSession;
} RPC_CALL_ATTRIBUTES_V1_W;
Члены
Version
Версия функции RpcServerInqCallAttributes , используемой вызывающим приложением. См. заметки.
Flags
Битовая маска, указывающая допустимые флаги для запроса RPC_QUERY_SERVER_PRINCIPAL_NAME или RPC_QUERY_CLIENT_PRINCIPAL_NAME. См. заметки.
ServerPrincipalNameBufferLength
Длина serverPrincipalName в байтах. Если значение недостаточно, Значение ServerPrincipalName не изменяется, а ServerPrincipalNameBufferLength указывает необходимую длину буфера, включая завершающий символ NULL , и возвращается ERROR_MORE_DATA. Если serverPrincipalNameBufferLength длиннее, чем необходимо, при возврате ему присваивается фактическая используемая длина в байтах, включая завершающий символ NULL . См. заметки.
Если последовательность протоколов не поддерживает получение имени участника-сервера, значение ServerPrincipalNameBufferLength при возврате равно нулю, а буфер, на который указывает ServerPrincipalName , не изменяется. Windows XP: Только группа последовательностей протоколов ncacn_* поддерживает получение имени участника-сервера.
Если флаг RPC_QUERY_SERVER_PRINCIPAL_NAME не указан, параметр ServerPrincipalNameBufferLength игнорируется. Если serverPrincipalNameBufferLength не равно нулю, а ServerPrincipalName имеет значение NULL, возвращается ERROR_INVALID_PARAMETER.
ServerPrincipalName
Указатель на имя участника-сервера, если он запрашивается в разделе Флаги и поддерживается последовательностью протокола. При любом возвращаемом значении, отличном от RPC_S_OK или ERROR_MORE_DATA, содержимое ServerPrincipalName не определено и может быть изменено RPC.
ClientPrincipalNameBufferLength
Длина буфера, на который указывает ClientPrincipalName, в байтах. Если значение недостаточно, clientPrincipalName не изменяется, а ClientPrincipalNameBufferLength указывает необходимую длину буфера, включая завершающий символ NULL , и возвращается ERROR_MORE_DATA. Если clientPrincipalNameBufferLength длиннее, чем необходимо, при возврате ему присваивается используемая фактическая длина в байтах, включая завершающий символ NULL .
Если последовательность протоколов не поддерживает получение имени участника клиента, clientPrincipalNameBufferLength при возврате задается равным нулю, а буфер, на который указывает ClientPrincipalName , не изменяется. Windows XP: Только последовательность протокола ncalrpc поддерживает получение имени участника клиента.
Если флаг RPC_QUERY_CLIENT_PRINCIPAL_NAME не указан, clientPrincipalNameBufferLength игнорируется. Если свойство ClientPrincipalNameBufferLength не равно нулю, а ClientPrincipalName имеет значение NULL, возвращается ERROR_INVALID_PARAMETER.
ClientPrincipalName
Указатель на имя субъекта клиента, если он запрашивается в элементе Flags и поддерживается последовательностью протокола. При любом возвращаемом значении, отличном от RPC_S_OK или ERROR_MORE_DATA, содержимое ClientPrincipalName не определено и может быть изменено RPC.
AuthenticationLevel
Уровень проверки подлинности для вызова. Уровни проверки подлинности, поддерживаемые RPC, см. в разделе Authentication-Level Constants (Константы уровня проверки подлинности).
AuthenticationService
Служба проверки подлинности или поставщик безопасности, используемая для удаленного вызова процедуры.
NullSession
Указывает, используется ли сеанс NULL . Ноль означает, что вызов не выполняется через сеанс NULL ; любое другое значение указывает на сеанс null .
Комментарии
Структура RPC_CALL_ATTRIBUTES использует схему управления версиями, чтобы включить функцию RpcServerInqCallAttributes для включения новых возможностей без необходимости вводить новые функции с идентификаторами суффикса. Например, вторая версия RPC_CALL_ATTRIBUTES, определяемая простым #define в заголовке, может добавлять новые члены, чтобы упростить новые функции, встроенные в будущие версии функции RpcServerInqCallAttributes , без необходимости выпускать соответствующую альтернативную функцию.
Элемент Version указывает версию структуры RPC_CALL_ATTRIBUTES (в настоящее время RPC_CALL_ATTRIBUTES_V1 или RPC_CALL_ATTRIBUTES_V2), используемой вызывающим приложением. Эта идентификация позволяет среде выполнения RPC обеспечить обратную совместимость приложений, не использующих самую последнюю версию структуры.
Если указать RPC_QUERY_SERVER_PRINCIPAL_NAME в элементе Flags , RpcServerInqCallAttributes возвращает имя участника-сервера в поле ServerPrincipalName. Если RPC_QUERY_SERVER_PRINCIPAL_NAME не указан, RpcServerInqCallAttributes не изменяет указатель, переданный в ServerPrincipalName , и не сохраняет ничего в этом расположении памяти. Если указать RPC_QUERY_CLIENT_PRINCIPAL_NAME в элементе Flags , RpcServerInqCallAttributes возвращает имя субъекта клиента в ClientPrincipalName. Если RPC_QUERY_CLIENT_PRINCIPAL_NAME не указан, RpcServerInqCallAttributes не изменяет указатель, переданный в ClientPrincipalName , и не сохраняет ничего в этом расположении памяти.
Лучший механизм обработки при извлечении имен клиента и субъекта-сервера — хранить длину ClientPrincipalNameBufferLength и ServerPrincipalNameBufferLength. Если возвращается ERROR_MORE_DATA, сравните хранимую длину с длиной, возвращаемой в этих элементах. Элемент с сохраненным значением, меньшим или равным возвращаемого значения, успешно вернулся, что указывает на то, что у другого элемента недостаточно буфера. В последующем вызове опустите флаг для успешно возвращенного имени участника; это позволяет избежать обработки, связанной с другим извлечением и копией успешно возвращенного имени участника.
Структура RPC_CALL_ATTRIBUTES_V1 обычно называется двумя способами:
- Первый подход: нуль указывается для элемента ServerPrincipalNameBufferLength или ClientPrincipalNameBufferLength в первом вызове функции RpcServerInqCallAttributes , чтобы получить необходимую длину буфера или определить, поддерживает ли протокол возврат имени участника. После получения требуемой длины буфера буфер выделяется требуемой длины и выполняется второй вызов, чтобы получить реальную длину буфера.
- Второй подход: вызывающий объект начинается с разумного буфера, который часто выделяется в стеке, и если возвращается ERROR_MORE_DATA, выделяется буфер требуемой длины и снова вызывается функция RpcServerInqCallAttributes .
Примеры
RPC_CALL_ATTRIBUTES CallAttributes; // this maps to RPC_CALL_ATTRIBUTES_V1
memset(&CallAttributes, 0, sizeof(CallAttributes));
CallAttributes.Version = RPC_CALL_ATTRIBUTES_VERSION; // maps to 1
CallAttributes.Flags = ;//....
Status = RpcServerInqCallAttributes(0, &CallAttributes);
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Верхняя часть | rpcasync.h (включая Rpc.h) |