Edit

transmit_as attribute

  • Article

The [transmit_as] attribute instructs the compiler to associate type-id*,* which is a presented type that client and server applications manipulate, with a transmitted type xmit-type.

typedef [transmit_as(xmit-type) [[ , type-attribute-list ]] ] type-specifier declarator-list; 

void __RPC_USER type-id_to_xmit (
  type-id __RPC_FAR *,
  xmit-type __RPC_FAR * __RPC_FAR *);
void __RPC_USER type-id_from_xmit (
  xmit-type __RPC_FAR *,
  type-id __RPC_FAR *);
void __RPC_USER type-id_free_inst (
  type-id __RPC_FAR *);
void __RPC_USER type-id_free_xmit (
  xmit-type__RPC_FAR *);

Parameters

xmit-type

Specifies the data type that is transmitted between client and server.

type-attribute-list

Specifies one or more attributes that apply to the type. Valid type attributes include [handle], [switch_type]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [string] and [ignore]. Separate multiple attributes with commas.

type-specifier

Specifies a base type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.

declarator-list

Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see Array and Sized-Pointer Attributes, arrays, and Arrays and Pointers. The declarator-list consists of one or more declarators separated by commas. The parameter declarator in the function declarator, such as the parameter name, is optional.

type-id

Specifies the name of the data type that is presented to the client and server applications.

Remarks

To use the [transmit_as] attribute, the user must supply routines that convert data between the presented and the transmitted types; these routines must also free memory used to hold the converted data. The [transmit_as] attribute instructs the stubs to call the user-supplied conversion routines.

The transmitted type xmit-type must resolve to a MIDL base type, predefined type, or a type identifier. For more information, see MIDL Base Types.

The user must supply the following routines.

Routine name Description
type-id**_to_xmit** Converts data from the presented type to the transmitted type. This routine allocates memory for the transmitted type and for any data referenced by pointers in the transmitted type.
type-id**_from_xmit** Converts data from the transmitted type to the presented type. This routine is responsible for allocating memory for data referenced by pointers in the presented type. RPC allocates memory for the type itself.
type-id**_free_inst** Frees memory allocated for data referenced by pointers in the presented type. RPC frees memory for the type itself.
type-id**_free_xmit** Frees storage used by the caller for the transmitted type and for data referenced by pointers in the transmitted type.

 

 

The client stub calls type-id**_to_xmit** to allocate space for the transmitted type and to translate the data into objects of type xmit-type. The server stub allocates space for the original data type and calls type-id**_from_xmit** to translate the data from its transmitted type to the presented type.

Upon return from the application code, the server stub calls type-id**_free_inst** to deallocate the storage for type-id on the server side. The client stub calls type-id**_free_xmit** to deallocate the xmit-type storage on the client side.

The following types cannot have a [transmit_as] attribute:

  • Context handles (types with the [context_handle] type attribute and types that are used as parameters with the [context_handle] attribute)
  • Types that are pipes or derived from pipes
  • Data types that are used as the base type of a pipe definition
  • Parameters that are pointers or resolve to pointers
  • Parameters that are conformant, varying, or open arrays
  • Structures that contain conformant arrays
  • The predefined type handle_t, void

Types that are transmitted must conform to the following restrictions:

  • They must not be pointers or contain pointers.
  • They must not be pipes or contain pipes.

Examples

typedef struct _TREE_NODE_TYPE 
{ 
    unsigned short data; 
    struct _TREE_NODE_TYPE * left; 
    struct _TREE_NODE_TYPE * right; 
} TREE_NODE_TYPE; 
 
typedef [transmit_as(TREE_XMIT_TYPE)] TREE_NODE_TYPE * TREE_TYPE; 
 
void __RPC_USER TREE_TYPE_to_xmit( 
    TREE_TYPE __RPC_FAR * , 
    TREE_XMIT_TYPE __RPC_FAR * __RPC_FAR *); 
 
void __RPC_USER TREE_TYPE_from_xmit ( 
    TREE_XMIT_TYPE __RPC_FAR *, 
    TREE_TYPE __RPC_FAR *); 
 
void __RPC_USER TREE_TYPE_free_inst( 
    TREE_TYPE __RPC_FAR *); 
 
void __RPC_USER TREE_TYPE_free_xmit( 
    TREE_XMIT_TYPE __RPC_FAR *);

See also

arrays

MIDL Base Types

context_handle

enum

handle

handle_t

Interface Definition (IDL) File

ignore

ptr

ref

string

struct

switch_type

typedef

union

unique

void