estructura de RPC_CALL_ATTRIBUTES_V1_A (rpcasync.h)
La estructura RPC_CALL_ATTRIBUTES_V1 proporciona parámetros a la función RpcServerInqCallAttributes . Se implementa en versiones ANSI y UNICODE para sistemas operativos Windows XP y Windows Server 2003.
Sintaxis
typedef struct tagRPC_CALL_ATTRIBUTES_V1_A {
unsigned int Version;
unsigned long Flags;
unsigned long ServerPrincipalNameBufferLength;
unsigned char *ServerPrincipalName;
unsigned long ClientPrincipalNameBufferLength;
unsigned char *ClientPrincipalName;
unsigned long AuthenticationLevel;
unsigned long AuthenticationService;
BOOL NullSession;
} RPC_CALL_ATTRIBUTES_V1_A;
Miembros
Version
Versión de la función RpcServerInqCallAttributes que usa la aplicación que realiza la llamada. Vea la sección Comentarios.
Flags
Máscara de bits que especifica marcas válidas para solicitar RPC_QUERY_SERVER_PRINCIPAL_NAME o RPC_QUERY_CLIENT_PRINCIPAL_NAME. Vea la sección Comentarios.
ServerPrincipalNameBufferLength
Longitud de ServerPrincipalName, en bytes. Si no es suficiente, ServerPrincipalName no cambia y ServerPrincipalNameBufferLength indica la longitud del búfer necesaria, incluido el carácter NULL de terminación, y se devuelve ERROR_MORE_DATA. Si ServerPrincipalNameBufferLength es más largo de lo necesario, al devolverlo se establece en la longitud real utilizada, en bytes, incluido el carácter NULL de terminación. Vea la sección Comentarios.
Si la secuencia de protocolos no admite la recuperación de un nombre principal del servidor, ServerPrincipalNameBufferLength se establece en cero a cambio y el búfer señalado por ServerPrincipalName no está modificado. Windows XP: Solo el grupo de secuencias de protocolos ncacn_* admite la recuperación del nombre principal del servidor.
Si no se especifica la marca RPC_QUERY_SERVER_PRINCIPAL_NAME, serverPrincipalNameBufferLength se omite. Si ServerPrincipalNameBufferLength es distinto de cero y ServerPrincipalName es NULL, se devuelve ERROR_INVALID_PARAMETER.
ServerPrincipalName
Puntero al nombre principal del servidor, si se solicita en Marcas y es compatible con la secuencia de protocolo. Tras cualquier valor devuelto distinto de RPC_S_OK o ERROR_MORE_DATA, el contenido de ServerPrincipalName no está definido y puede haber sido modificado por RPC.
ClientPrincipalNameBufferLength
Longitud del búfer al que apunta ClientPrincipalName, en bytes. Si no es suficiente, ClientPrincipalName no cambia y ClientPrincipalNameBufferLength indica la longitud del búfer necesaria, incluido el carácter NULL de terminación, y se devuelve ERROR_MORE_DATA. Si ClientPrincipalNameBufferLength es más largo de lo necesario, al devolverlo se establece en la longitud real utilizada, en bytes, incluido el carácter NULL de terminación.
Si la secuencia de protocolos no admite la recuperación de un nombre principal de cliente, ClientPrincipalNameBufferLength se establece en cero al devolver y el búfer señalado por ClientPrincipalName no está modificado. Windows XP: Solo la secuencia de protocolo ncalrpc admite la recuperación del nombre principal del cliente.
Si no se especifica la marca RPC_QUERY_CLIENT_PRINCIPAL_NAME, se omite ClientPrincipalNameBufferLength . Si ClientPrincipalNameBufferLength es distinto de cero y ClientPrincipalName es NULL, se devuelve ERROR_INVALID_PARAMETER.
ClientPrincipalName
Puntero al nombre principal del cliente, si se solicita en el miembro Flags y es compatible con la secuencia de protocolo. Tras cualquier valor devuelto distinto de RPC_S_OK o ERROR_MORE_DATA, el contenido de ClientPrincipalName no está definido y puede haber sido modificado por RPC.
AuthenticationLevel
Nivel de autenticación de la llamada. Consulte Constantes de nivel de autenticación para conocer los niveles de autenticación admitidos por RPC.
AuthenticationService
Servicio de autenticación, o proveedor de seguridad, que se usa para realizar la llamada a procedimiento remoto.
NullSession
Especifica si se usa una sesión Null . Cero indica que la llamada no llega a través de una sesión Null ; cualquier otro valor indica una sesión Null .
Comentarios
La estructura de RPC_CALL_ATTRIBUTES usa un esquema de control de versiones para habilitar la función RpcServerInqCallAttributes para incorporar nuevas funcionalidades sin tener que introducir nuevas funciones con identificadores de sufijo. Por ejemplo, una segunda versión del RPC_CALL_ATTRIBUTES, identificada con un #define simple en el encabezado, puede agregar nuevos miembros para facilitar la nueva funcionalidad integrada en versiones futuras de la función RpcServerInqCallAttributes , sin tener que liberar una función alternativa correspondiente.
El miembro Version indica la versión de la estructura de RPC_CALL_ATTRIBUTES (actualmente RPC_CALL_ATTRIBUTES_V1 o RPC_CALL_ATTRIBUTES_V2) que usa la aplicación que realiza la llamada. Esta identificación permite que el tiempo de ejecución de RPC proporcione compatibilidad con versiones anteriores para las aplicaciones que no usan la versión más actual de la estructura.
Al especificar RPC_QUERY_SERVER_PRINCIPAL_NAME en el miembro Flags , RpcServerInqCallAttributes se devuelve el nombre principal del servidor en ServerPrincipalName. Si no se especifica RPC_QUERY_SERVER_PRINCIPAL_NAME, RpcServerInqCallAttributes no modifica el puntero pasado en ServerPrincipalName y no almacena nada en esa ubicación de memoria. Al especificar RPC_QUERY_CLIENT_PRINCIPAL_NAME en el miembro Flags se dirige RpcServerInqCallAttributes para devolver el nombre principal del cliente en ClientPrincipalName. Si no se especifica RPC_QUERY_CLIENT_PRINCIPAL_NAME, RpcServerInqCallAttributes no modifica el puntero pasado en ClientPrincipalName y no almacena nada en esa ubicación de memoria.
El mejor mecanismo de procesamiento cuando se recuperan los nombres principales de cliente y servidor es almacenar la longitud de ClientPrincipalNameBufferLength y ServerPrincipalNameBufferLength y, si se devuelve ERROR_MORE_DATA, compare las longitudes almacenadas con las longitudes devueltas en esos miembros. El miembro con un valor almacenado menor o igual que el valor devuelto se ha devuelto correctamente, lo que indica que el otro miembro tenía un búfer insuficiente. En la llamada posterior, omita la marca para el nombre principal devuelto correctamente; Esto evita el procesamiento asociado a otra recuperación y copia del nombre principal devuelto correctamente.
La estructura de RPC_CALL_ATTRIBUTES_V1 se suele llamar de dos maneras:
- Primer enfoque: cero se especifica para el miembro ServerPrincipalNameBufferLength o ClientPrincipalNameBufferLength en la primera llamada de función RpcServerInqCallAttributes para recuperar la longitud del búfer necesaria o para determinar si el protocolo admite la devolución del nombre principal. Al recuperar la longitud del búfer necesaria, se asigna un búfer de la longitud necesaria y se realiza una segunda llamada para obtener la longitud real del búfer.
- Segundo enfoque: el llamador comienza con un búfer razonable, a menudo asignado en la pila y, si se devuelve ERROR_MORE_DATA, se asigna un búfer de la longitud necesaria y se vuelve a llamar a la función RpcServerInqCallAttributes .
Ejemplos
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 | Value |
|---|---|
| Cliente mínimo compatible | Windows XP [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2003 [solo aplicaciones de escritorio] |
| Encabezado | rpcasync.h (include Rpc.h) |