RPC_CALL_ATTRIBUTES_V1_W structure (rpcasync.h)
La structure RPC_CALL_ATTRIBUTES_V1 fournit des paramètres à la fonction RpcServerInqCallAttributes . Implémenté dans les versions ANSI et UNICODE pour les systèmes d’exploitation Windows XP et Windows Server 2003.
Syntaxe
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;
Membres
Version
Version de la fonction RpcServerInqCallAttributes utilisée par l’application appelante. Consultez la section Notes.
Flags
Masque de bits spécifiant des indicateurs valides pour demander RPC_QUERY_SERVER_PRINCIPAL_NAME ou RPC_QUERY_CLIENT_PRINCIPAL_NAME. Consultez la section Notes.
ServerPrincipalNameBufferLength
Longueur de ServerPrincipalName, en octets. En cas d’insuffisance, ServerPrincipalName est inchangé, et ServerPrincipalNameBufferLength indique la longueur de mémoire tampon requise, y compris le caractère NULL de fin, et ERROR_MORE_DATA est retourné. Si ServerPrincipalNameBufferLength est plus long que nécessaire, lors du retour, il est défini sur la longueur réelle utilisée, en octets, y compris le caractère NULL de fin. Consultez la section Notes.
Si la séquence de protocole ne prend pas en charge la récupération d’un nom de principal de serveur, ServerPrincipalNameBufferLength est défini sur zéro au retour, et la mémoire tampon pointée par ServerPrincipalName n’est pas modifiée. Windows XP : Seul le groupe ncacn_* de séquences de protocole prend en charge la récupération du nom du principal du serveur.
Si l’indicateur RPC_QUERY_SERVER_PRINCIPAL_NAME n’est pas spécifié, ServerPrincipalNameBufferLength est ignoré. Si ServerPrincipalNameBufferLength est différent de zéro et Que ServerPrincipalName a la valeur NULL, ERROR_INVALID_PARAMETER est retourné.
ServerPrincipalName
Pointeur vers le nom du principal du serveur, si demandé dans Indicateurs et pris en charge par la séquence de protocole. Sur toute valeur de retour autre que RPC_S_OK ou ERROR_MORE_DATA, le contenu de ServerPrincipalName n’est pas défini et peut avoir été modifié par RPC.
ClientPrincipalNameBufferLength
Longueur de la mémoire tampon pointée par ClientPrincipalName, en octets. En cas d’insuffisance, ClientPrincipalName est inchangé, et ClientPrincipalNameBufferLength indique la longueur de mémoire tampon requise, y compris le caractère NULL de fin, et ERROR_MORE_DATA est retourné. Si ClientPrincipalNameBufferLength est plus long que nécessaire, lors du retour, il est défini sur la longueur réelle utilisée, en octets, y compris le caractère NULL de fin.
Si la séquence de protocole ne prend pas en charge la récupération d’un nom de principal client, ClientPrincipalNameBufferLength a la valeur zéro au retour, et la mémoire tampon pointée par ClientPrincipalName n’est pas modifiée. Windows XP : Seule la séquence de protocole ncalrpc prend en charge la récupération du nom du principal client.
Si l’indicateur RPC_QUERY_CLIENT_PRINCIPAL_NAME n’est pas spécifié, ClientPrincipalNameBufferLength est ignoré. Si ClientPrincipalNameBufferLength est différent de zéro et Que ClientPrincipalName a la valeur NULL, ERROR_INVALID_PARAMETER est retourné.
ClientPrincipalName
Pointeur vers le nom du principal client, si demandé dans le membre Flags et pris en charge par la séquence de protocole. Sur toute valeur de retour autre que RPC_S_OK ou ERROR_MORE_DATA, le contenu de ClientPrincipalName n’est pas défini et peut avoir été modifié par RPC.
AuthenticationLevel
Niveau d’authentification pour l’appel. Consultez Constantes de niveau d’authentification pour les niveaux d’authentification pris en charge par RPC.
AuthenticationService
Service d’authentification, ou fournisseur de sécurité, utilisé pour effectuer l’appel de procédure distante.
NullSession
Spécifie si une session Null est utilisée. Zéro indique que l’appel n’arrive pas sur une session Null ; toute autre valeur indique une session Null .
Remarques
La structure RPC_CALL_ATTRIBUTES utilise un schéma de contrôle de version pour permettre à la fonction RpcServerInqCallAttributes d’incorporer de nouvelles fonctionnalités sans avoir à introduire de nouvelles fonctions avec des identificateurs de suffixe. Par exemple, une deuxième version de l’RPC_CALL_ATTRIBUTES, identifiée avec une simple #define dans l’en-tête, peut ajouter de nouveaux membres pour faciliter les nouvelles fonctionnalités intégrées aux futures versions de la fonction RpcServerInqCallAttributes , sans avoir à libérer une autre fonction correspondante.
Le membre Version indique la version de la structure RPC_CALL_ATTRIBUTES (actuellement RPC_CALL_ATTRIBUTES_V1 ou RPC_CALL_ATTRIBUTES_V2) utilisée par l’application appelante. Cette identification permet au moment de l’exécution rpc de fournir une compatibilité descendante pour les applications qui n’utilisent pas la version la plus récente de la structure.
Si vous spécifiez RPC_QUERY_SERVER_PRINCIPAL_NAME dans le membre Flags , RpcServerInqCallAttributes retourne le nom du principal du serveur dans ServerPrincipalName. Si RPC_QUERY_SERVER_PRINCIPAL_NAME n’est pas spécifié, RpcServerInqCallAttributes ne modifie pas le pointeur passé dans ServerPrincipalName et ne stocke rien dans cet emplacement de mémoire. Si vous spécifiez RPC_QUERY_CLIENT_PRINCIPAL_NAME dans le membre Flags , RpcServerInqCallAttributes retourne le nom du principal client dans ClientPrincipalName. Si RPC_QUERY_CLIENT_PRINCIPAL_NAME n’est pas spécifié, RpcServerInqCallAttributes ne modifie pas le pointeur passé dans ClientPrincipalName et ne stocke rien dans cet emplacement de mémoire.
Le meilleur mécanisme de traitement lorsque les noms de principal du client et du serveur sont récupérés consiste à stocker la longueur de ClientPrincipalNameBufferLength et ServerPrincipalNameBufferLength, et si ERROR_MORE_DATA est retourné, comparez les longueurs stockées avec les longueurs retournées dans ces membres. Le membre dont la valeur stockée est inférieure ou égale à la valeur retournée a été correctement retourné, ce qui indique que la mémoire tampon de l’autre membre était insuffisante. Dans l’appel suivant, omettez l’indicateur pour le nom principal retourné avec succès ; cela évite le traitement associé à une autre récupération et copie du nom principal retourné avec succès.
La structure RPC_CALL_ATTRIBUTES_V1 est généralement appelée de deux façons :
- Première approche : zéro est spécifié pour le membre ServerPrincipalNameBufferLength ou ClientPrincipalNameBufferLength lors du premier appel de fonction RpcServerInqCallAttributes pour récupérer la longueur de mémoire tampon requise, ou pour déterminer si le protocole prend en charge le retour du nom principal. Lors de la récupération de la longueur de mémoire tampon requise, une mémoire tampon est allouée de la longueur requise et un deuxième appel est effectué pour obtenir la longueur réelle de la mémoire tampon.
- Deuxième approche : l’appelant commence par une mémoire tampon raisonnable, souvent allouée sur la pile, et si ERROR_MORE_DATA est retourné, une mémoire tampon de la longueur requise est allouée et la fonction RpcServerInqCallAttributes est appelée à nouveau.
Exemples
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);
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| En-tête | rpcasync.h (inclure Rpc.h) |