estrutura RPC_CALL_ATTRIBUTES_V1_W (rpcasync.h)
A estrutura RPC_CALL_ATTRIBUTES_V1 fornece parâmetros para a função RpcServerInqCallAttributes . Implementado em versões ANSI e UNICODE para sistemas operacionais Windows XP e Windows Server 2003.
Sintaxe
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;
Membros
Version
Versão da função RpcServerInqCallAttributes que está sendo usada pelo aplicativo de chamada. Consulte Observações.
Flags
Bitmask especificando sinalizadores válidos para solicitar RPC_QUERY_SERVER_PRINCIPAL_NAME ou RPC_QUERY_CLIENT_PRINCIPAL_NAME. Consulte Observações.
ServerPrincipalNameBufferLength
Comprimento de ServerPrincipalName, em bytes. Se não for suficiente, ServerPrincipalName ficará inalterado e ServerPrincipalNameBufferLength indicará o comprimento do buffer necessário, incluindo o caractere NULL de terminação, e ERROR_MORE_DATA será retornado. Se ServerPrincipalNameBufferLength for maior do que o necessário, no retorno, ele será definido como o comprimento real usado, em bytes, incluindo o caractere NULL de terminação. Consulte Observações.
Se a sequência de protocolo não der suporte à recuperação de um nome de entidade de segurança do servidor, ServerPrincipalNameBufferLength será definido como zero no retorno e o buffer apontado por ServerPrincipalName não será modificado. Windows XP: Somente o grupo de ncacn_* de sequências de protocolo dá suporte à recuperação do nome da entidade de segurança do servidor.
Se o sinalizador RPC_QUERY_SERVER_PRINCIPAL_NAME não for especificado, ServerPrincipalNameBufferLength será ignorado. Se ServerPrincipalNameBufferLength não for zero e ServerPrincipalName for NULL, ERROR_INVALID_PARAMETER será retornado.
ServerPrincipalName
Ponteiro para o nome da entidade de segurança do servidor, se solicitado em Sinalizadores e com suporte pela sequência de protocolo. Após qualquer valor retornado diferente de RPC_S_OK ou ERROR_MORE_DATA, o conteúdo de ServerPrincipalName é indefinido e pode ter sido modificado pelo RPC.
ClientPrincipalNameBufferLength
Comprimento do buffer apontado por ClientPrincipalName, em bytes. Se insuficiente, ClientPrincipalName será inalterado e ClientPrincipalNameBufferLength indicará o comprimento do buffer necessário, incluindo o caractere NULL de terminação, e ERROR_MORE_DATA será retornado. Se ClientPrincipalNameBufferLength for maior do que o necessário, ao retornar, ele será definido como o comprimento real usado, em bytes, incluindo o caractere NULL de terminação.
Se a sequência de protocolo não der suporte à recuperação de um nome de entidade de segurança do cliente, ClientPrincipalNameBufferLength será definido como zero no retorno e o buffer apontado por ClientPrincipalName não será modificado. Windows XP: Somente a sequência de protocolo ncalrpc dá suporte à recuperação do nome da entidade de segurança do cliente.
Se o sinalizador RPC_QUERY_CLIENT_PRINCIPAL_NAME não for especificado, ClientPrincipalNameBufferLength será ignorado. Se ClientPrincipalNameBufferLength não for zero e ClientPrincipalName for NULL, ERROR_INVALID_PARAMETER será retornado.
ClientPrincipalName
Ponteiro para o nome da entidade de segurança do cliente, se solicitado no membro Flags e com suporte pela sequência de protocolo. Após qualquer valor retornado diferente de RPC_S_OK ou ERROR_MORE_DATA, o conteúdo de ClientPrincipalName é indefinido e pode ter sido modificado pelo RPC.
AuthenticationLevel
Nível de autenticação para a chamada. Consulte Constantes de nível de autenticação para obter níveis de autenticação compatíveis com RPC.
AuthenticationService
O serviço de autenticação, ou provedor de segurança, usado para fazer a chamada de procedimento remoto.
NullSession
Especifica se uma sessão Null é usada. Zero indica que a chamada não está chegando em uma sessão nula ; qualquer outro valor indica uma sessão nula .
Comentários
A estrutura RPC_CALL_ATTRIBUTES usa um esquema de controle de versão para habilitar a função RpcServerInqCallAttributes para incorporar novos recursos sem precisar introduzir novas funções com identificadores de sufixo. Por exemplo, uma segunda versão do RPC_CALL_ATTRIBUTES, identificada com uma #define simples no cabeçalho, pode adicionar novos membros para facilitar a nova funcionalidade incorporada a versões futuras da função RpcServerInqCallAttributes , sem precisar liberar uma função alternativa correspondente.
O membro Version indica a versão da estrutura de RPC_CALL_ATTRIBUTES (atualmente RPC_CALL_ATTRIBUTES_V1 ou RPC_CALL_ATTRIBUTES_V2) sendo usada pelo aplicativo de chamada. Essa identificação permite que o tempo de execução do RPC forneça compatibilidade com versões anteriores para aplicativos que não usam a versão mais atual da estrutura.
Especificar RPC_QUERY_SERVER_PRINCIPAL_NAME no membro Flags direciona RpcServerInqCallAttributes para retornar o nome da entidade de segurança do servidor em ServerPrincipalName. Se RPC_QUERY_SERVER_PRINCIPAL_NAME não for especificado, RpcServerInqCallAttributes não modificará o ponteiro passado em ServerPrincipalName e não armazenará nada nesse local de memória. Especificar RPC_QUERY_CLIENT_PRINCIPAL_NAME no membro Flags direciona RpcServerInqCallAttributes para retornar o nome da entidade de segurança do cliente em ClientPrincipalName. Se RPC_QUERY_CLIENT_PRINCIPAL_NAME não for especificado, RpcServerInqCallAttributes não modificará o ponteiro passado em ClientPrincipalName e não armazenará nada nesse local de memória.
O melhor mecanismo de processamento quando os nomes da entidade de segurança do cliente e do servidor estão sendo recuperados é armazenar o comprimento de ClientPrincipalNameBufferLength e ServerPrincipalNameBufferLength e, se ERROR_MORE_DATA for retornado, compare os comprimentos armazenados com os comprimentos retornados nesses membros. O membro com um valor armazenado menor ou igual ao valor retornado retornou com êxito, indicando que o outro membro tinha um buffer insuficiente. Na chamada subsequente, omita o sinalizador para o nome da entidade de segurança retornado com êxito; isso evita o processamento associado a outra recuperação e cópia do nome principal retornado com êxito.
A estrutura RPC_CALL_ATTRIBUTES_V1 geralmente é chamada de duas maneiras:
- Primeira abordagem: zero é especificado para o membro ServerPrincipalNameBufferLength ou ClientPrincipalNameBufferLength na primeira chamada de função RpcServerInqCallAttributes para recuperar o comprimento do buffer necessário ou para determinar se o protocolo dá suporte ao retorno do nome principal. Ao recuperar o comprimento do buffer necessário, um buffer é alocado do comprimento necessário e uma segunda chamada é feita para obter o comprimento real do buffer.
- Segunda abordagem: o chamador começa com um buffer razoável, geralmente alocado na pilha e, se ERROR_MORE_DATA for retornado, um buffer do comprimento necessário será alocado e a função RpcServerInqCallAttributes será chamada novamente.
Exemplos
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);
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Cabeçalho | rpcasync.h (inclua Rpc.h) |