Attribut transmit_as

L’attribut [transmit_as] offre un moyen de contrôler le marshaling des données sans se soucier du marshaling des données à un niveau faible, c’est-à-dire sans se soucier de la taille des données ou de l’échange d’octets dans un environnement hétérogène. En vous permettant de réduire la quantité de données transmises sur le réseau, l’attribut [transmit_as] peut rendre votre application plus efficace.

Vous utilisez l’attribut [transmit_as] pour spécifier un type de données que les stubs RPC transmettront sur le réseau au lieu d’utiliser le type de données fourni par l’application. Vous fournissez des routines qui convertissent le type de données vers et à partir du type utilisé pour la transmission. Vous devez également fournir des routines pour libérer la mémoire utilisée pour le type de données et le type transmis. Par exemple, les éléments suivants définissent xmit_type comme type de données transmis pour toutes les données d’application spécifiées comme étant de type type_spec :

typedef [transmit_as (xmit_type)] type_spec type;

Le tableau suivant décrit les quatre noms de routine fournis par le programmeur. Type est le type de données connu de l’application, et xmit_type est le type de données utilisé pour la transmission.

Routine	Description
type_to_xmit	Alloue un objet du type transmis et convertit le type d’application en type transmis sur le réseau (appelant et objet appelé).
Type_from_xmit	Convertit le type transmis en type d’application (appelant et objet appelé).
Type_free_inst	Libère les ressources utilisées par le type d’application (objet appelé uniquement).
Type_free_xmit	Libère le stockage retourné par le type*_*to_xmit routine (appelant et objet appelé).

 

En dehors de ces quatre fonctions fournies par le programmeur, le type transmis n’est pas manipulé par l’application. Le type transmis est défini uniquement pour déplacer des données sur le réseau. Une fois les données converties en type utilisé par l’application, la mémoire utilisée par le type transmis est libérée.

Ces routines fournies par le programmeur sont fournies par le client ou l’application serveur en fonction des attributs directionnels. Si le paramètre est [in] uniquement, le client transmet au serveur. Le client a besoin des fonctions type_to_xmit et type_free_xmit . Le serveur a besoin des fonctions type_from_xmit et type_free_inst . Pour un paramètre [out]-only, le serveur transmet au client. L’application serveur doit implémenter les fonctions type_to_xmit et type_free_xmit , tandis que le programme client doit fournir la fonction type_from_xmit . Pour les objets xmit_type temporaires, le stub appelle le type*_*free_xmit pour libérer toute mémoire allouée par un appel à type_to_xmit.

Certaines instructions s’appliquent au type d’application instance. Si le type d’application est un pointeur ou contient un pointeur, la routine type_from_xmit doit allouer de la mémoire pour les données vers laquelle pointent les pointeurs (l’objet de type d’application lui-même est manipulé par le stub de la manière habituelle).

Pour les paramètres [out] et [in, out] out], ou l’un de leurs composants, d’un type qui contient l’attribut [transmit_as], la routine type_free_inst est automatiquement appelée pour les objets de données qui ont l’attribut . Pour les paramètres dans , la routine type_free_inst est appelée uniquement si l’attribut [transmit_as] a été appliqué au paramètre. Si l’attribut a été appliqué aux composants du paramètre, la routine type_free_inst n’est pas appelée. Il n’existe aucun appel de libération pour les données incorporées et au maximum un appel (lié à l’attribut de niveau supérieur) pour un paramètre in only.

À compter de MIDL 2.0, le client et le serveur doivent fournir les quatre fonctions. Par exemple, une liste liée peut être transmise sous la forme d’un tableau dimensionné. La routine type_to_xmit guide la liste liée et copie les données triées dans un tableau. Les éléments de tableau sont triés de sorte que les nombreux pointeurs associés à la structure de liste n’aient pas à être transmis. La routine type_from_xmit lit le tableau et place ses éléments dans une structure de liste liée.

La liste à double liaison (DOUBLE_LINK_LIST) inclut des données et des pointeurs vers les éléments de liste précédent et suivant :

typedef struct _DOUBLE_LINK_LIST 
{
    short sNumber;
    struct _DOUBLE_LINK_LIST * pNext;
    struct _DOUBLE_LINK_LIST * pPrevious;
} DOUBLE_LINK_LIST;

Au lieu d’expédier la structure complexe, l’attribut [transmit_as] peut être utilisé pour l’envoyer sur le réseau en tant que tableau. La séquence d’éléments dans le tableau conserve l’ordre des éléments de la liste à moindre coût :

typedef struct _DOUBLE_XMIT_TYPE 
{
    short sSize;
    [size_is(sSize)] short asNumber[];
} DOUBLE_XMIT_TYPE;

L’attribut [transmit_as] apparaît dans le fichier IDL :

typedef [transmit_as(DOUBLE_XMIT_TYPE)]  DOUBLE_LINK_LIST DOUBLE_LINK_TYPE;

Dans l’exemple suivant, ModifyListProc définit le paramètre de type DOUBLE_LINK_TYPE comme paramètre [in, out] :

void ModifyListProc([in, out] DOUBLE_LINK_TYPE * pHead)

Les quatre fonctions définies par le programmeur utilisent le nom du type dans les noms de fonction, et utilisent les types présentés et transmis comme types de paramètres, selon les besoins :

void __RPC_USER DOUBLE_LINK_TYPE_to_xmit ( 
    DOUBLE_LINK_TYPE __RPC_FAR * pList, 
    DOUBLE_XMIT_TYPE __RPC_FAR * __RPC_FAR * ppArray);

void __RPC_USER DOUBLE_LINK_TYPE_from_xmit ( 
    DOUBLE_XMIT_TYPE __RPC_FAR * pArray,
    DOUBLE_LINK_TYPE __RPC_FAR * pList);

void __RPC_USER DOUBLE_LINK_TYPE_free_inst ( 
    DOUBLE_LINK_TYPE __RPC_FAR * pList);

void __RPC_USER DOUBLE_LINK_TYPE_free_xmit ( 
    DOUBLE_XMIT_TYPE __RPC_FAR * pArray);