transmit_as attribute
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