wire_marshal attribute
The [wire_marshal] attribute specifies a data type that will be used for transmission (the wire-type) instead of an application-specific data type (the userm-type).
typedef [wire_marshal(wire_type)] type-specifier userm-type;
unsigned long __RPC_USER < userm-type >_UserSize(
unsigned long __RPC_FAR *pFlags,
unsigned long StartingSize,
< userm-type > __RPC_FAR * pUser_typeObject );
unsigned char __RPC_FAR * __RPC_USER < userm-type >_UserMarshal(
unsigned long __RPC_FAR * pFlags,
unsigned char __RPC_FAR * Buffer,
< userm-type > __RPC_FAR * pUser_typeObject);
unsigned char __RPC_FAR * __RPC_USER < userm-type >_UserUnmarshal(
unsigned long __RPC_FAR * pFlags,
unsigned char __RPC_FAR * Buffer,
< userm-type > __RPC_FAR * pUser_typeObject);
void __RPC_USER < userm-type >_UserFree(
unsigned long __RPC_FAR * pFlags,
< userm-type > __RPC_FAR * pUser_typeObject);
Parameters
-
wire-type
-
Specifies the named transfer data type that is actually transferred between client and server. The wire-type must be a MIDL base type, predefined type, or a type identifier of a type that can be transmitted across the network.
-
type-specifier
-
The type for which userm-type will become an alias.
-
userm-type
-
Specifies the identifier of the user data type to be marshaled. It can be any type, as given by the type-specifier, as long as it has a well-defined size. The userm-type need not be transmittable but must be a type known to the MIDL compiler.
-
pFlags
-
Specifies a pointer to a flag field ( unsigned long). The high-order word specifies NDR data representation flags as defined by DCE for floating point, big- or little-endian, and character representation. The low-order word specifies a marshaling context flag. The exact layout of the flags is described in The type_UserSize Function.
-
StartingSize
-
Specifies the current buffer size (offset) before sizing the object.
-
pUser_typeObject
-
Specifies a pointer to an object of userm_type.
-
Buffer
-
Specifies the current buffer pointer.
Remarks
Each application-specific data type, userm-type, has a one-to-one correspondence with a wire-type that defines the wire representation of the type. You must supply routines to size the data for marshaling, to marshal and unmarshal the data, and to free memory. Note that if there are embedded types in your data that are also defined with [wire_marshal] or [user_marshal], you need to manage the servicing of those embedded types also. For more information on these routines, see The wire_marshal Attribute.
Your implementation must follow the marshalling rules according to the OSF-DCE specification. Details about NDR transfer syntax can be found at https://www.opengroup.org/onlinepubs/9629399/chap14.htm. It is not recommended to use [wire_marshal] if you are not familiar with the wire protocol.
The wire-type cannot be an interface pointer or a full pointer. The wire-type must have a well-defined memory size. See Marshaling Rules for user_marshal and wire_marshal for details on how to marshal a given wire-type.
The userm-type should not be an interface pointer because these can be marshaled directly. If the user type is a full pointer, you must manage the aliasing yourself.
You cannot use the [wire_marshal] attribute with the [allocate] attribute, either directly or indirectly, because the NDR engine does not control memory allocation for the transmitted type.
Examples
typedef unsigned long _FOUR_BYTE_DATA;
typedef struct _TWO_X_TWO_BYTE_DATA
{
unsigned short low;
unsigned short high;
} TWO_X_TWO_BYTE_DATA;
typedef [wire_marshal(TWO_X_TWO_BYTE_DATA)]
_FOUR_BYTE_DATA FOUR_BYTE_DATA;
//Marshaling functions:
// Calculate size that converted data will
// require in the buffer
unsigned long __RPC_USER FOUR_BYTE_DATA_UserSize(
ULONG __RPC_FAR * pulFlags,
ULONG __RPC_FAR ulStartingSize,
FOUR_BYTE_DATA __RPC_FAR * pul);
// Copy FOUR_BYTE_DATA into buffer as
// TWO_X_TWO_BYTE_DATA
unsigned long __RPC_USER FOUR_BYTE_DATA_UserMarshal(
ULONG __RPC_FAR *pulFlags,
char __RPC_FAR * pBufferStart,
FOUR_BYTE_DATA __RPC_FAR * pul);
// Recreate FOUR_BYTE_DATA from TWO_X_TWO_BYTE_DATA in buffer
unsigned long __RPC_USER FOUR_BYTE_DATA_UserUnmarshal(
ULONG __RPC_FAR * pulFlags,
char __RPC_FAR * pBufferStart,
FOUR_BYTE_DATA __RPC_FAR * pul);
// Nothing to do here as the engine frees the top
// node and FOUR_BYTE_DATA is a flat data type.
void __RPC_USER FOUR_BYTE_DATA_UserFree(
ULONG __RPC_FAR * pulFlags,
FOUR_BYTE_DATA __RPC_FAR * pul
);
See also