Edit

user_marshal attribute

  • Article

The user_marshal ACF attribute associates a named local type in the target language (userm-type) with a transfer type (wire-type) that is transferred between client and server.

typedef [user_marshal(userm_type)] wire-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

userm-type

Specifies the identifier of the user data type to be marshaled. The userm-type need not be transmittable and need not be a type known to the MIDL compiler.

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.

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 named local 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. For more information on these routines, see The user_marshal Attribute. Note that if there are embedded types in your data that are also defined with user_marshal or [ [wire_marshal], you need to manage the servicing of those embedded types also.

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 as these can be marshaled directly. If the user type is a full pointer, you must manage the aliasing yourself.

Examples

// Marshal a long as a structure containing two shorts.

typedef unsigned long FOUR_BYTE_DATA;
typedef struct _TWO_X_TWO_BYTE_DATA 
{ 
    unsigned short low; 
    unsigned short high; 
} TWO_X_TWO_BYTE_DATA;

// ACFL file

typedef [user_marshal(FOUR_BYTE_DATA)] TWO_X_TWO_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

Application Configuration File (ACF)

MIDL Base Types

long

represent_as

unsigned

The user_marshal Attribute

wire_marshal

NdrGetUserMarshalInfo