The transmit_as attribute associates a transmitted type that stubs pass over the network with a presented type that clients and servers manipulate. The specified transmitted type must be a named type defined previously in another type declaration.
There are two primary uses for this attribute:
· To pass complex data types for which the IDL compiler cannot generate marshalling and unmarshalling code.
· To pass data more efficiently. An application can provide routines to convert a data type between a sparse representation (presented to the client and server programs) and a compact one (transmitted over the network).
To build an application that uses presented and transmitted types, you must write routines to perform conversions between the types and to manage storage for the types, and you must link those routines with your application code. At runtime, the client and server stubs call these routines before sending and after receiving data of these types.
The following paragraphs specify C prototypes for generic binding and unbinding routines; in these prototypes, PRES is the name of the presented type and TRANS is the name of the transmitted type.
The PRES_to_xmit( ) routine allocates storage for the transmitted type and converts from the presented type to the transmitted type:
void PRES_to_xmit (PRES *presented, TRANS **transmitted)
The PRES_from_xmit( ) routine converts from the transmitted type to the presented type and allocates any storage referenced by pointers in the presented type:
void PRES_from_xmit (TRANS *transmitted, PRES *presented)
The PRES_free_inst( ) routine frees any storage referenced by pointers in the presented type by PRES_from_xmit( ):
void PRES_free_inst (PRES *presented)
Suppose that the transmit_as attribute appears either on the type of a parameter or on a component of a parameter and that the parameter has the out or in,out attribute. Then, the PRES_free_inst( ) routine will be called automatically for the data item that has the transmit_as attribute.
Suppose that the transmit_as attribute appears on the type of a parameter and that the parameter has only the in attribute. Then, the PRES_free_inst( ) routine will be called automatically.
Finally, suppose that the transmit_as attribute appears on a component of a parameter and that the parameter has only the in attribute. Then, the PRES_free_inst( ) routine will not be called automatically for the component; the manager application code must release any resources that the component uses, possibly by explicitly calling the PRES_free_inst( ) routine.
The PRES_free_xmit( ) routine frees any storage that has been allocated for the transmitted type by PRES_to_xmit( ):
void PRES_free_xmit (TRANS *transmitted)
A type with the transmit_as attribute cannot have other type attributes, specifically:
· A pipe type
· A pipe element type
· A type with the context_handle attribute
· A type of which any instance has the context_handle attribute
· A type that includes the handle attribute in its definition cannot be used, directly or indirectly, in the definition of a type with the transmit_as attribute. Nor can a type which includes the transmit_as attribute in its definition be used, directly or indirectly, in the definition of a type with the handle attribute.
· A conformant array type
· A varying array type
· A structure type containing a conformant array
· An array type of which any instance is varying
· A type with the represent_as attribute
The type name in a declaration for a transmit_as attribute is restricted to 21 characters.
A transmitted type specified by the transmit_as attribute must be either a base type, a predefined type, or a named type defined via typedef. A transmitted type cannot be a conformant array type or a conformant structure type if any instance of that type is an in parameter or an in, out parameter.
The following is an example of transmit_as. Assuming the following declarations:
typedef
struct tree_node_t {
data_t data;
struct tree_node_t * left;
struct tree_node_t * right;
} tree_node_t;
typedef
[transmit_as(tree_xmit_t)] tree_node_t *tree_t;
The application code must include routines that match the prototypes:
void tree_t_to_xmit ( tree_t *, (tree_xmit_t **) );
void tree_t_from_xmit ( (tree_xmit_t *), (tree_t *) );
void tree_t_free_inst ( tree_t *);
void tree_t_free_xmit ( (tree_xmit_t *) );