| title | description | ms.assetid | keywords | ms.topic | ms.date | ||
|---|---|---|---|---|---|---|---|
The user_marshal Attribute |
The \ user\_marshal\ attribute is an ACF-type attribute similar in syntax to \ represent\_as\ . |
5a381b44-e271-4713-954f-a55840a92bb7 |
|
article |
05/31/2018 |
The [ user_marshal] attribute is an ACF-type attribute similar in syntax to [ represent_as]. As with the IDL attribute, [ wire_marshal], it offers a more efficient way to marshal data across a network. As an ACF attribute, [user_marshal] lets you marshal custom data types that are unknown to MIDL. Each application-specific type has a corresponding transmittable type that defines the wire representation.
Your application-specific type can be a simple, composite, or pointer type. The main restriction is that the type instance must have a fixed, well-defined memory size. If the size of your type instance needs to change, use a pointer field rather than a conformant array. Alternatively, you can define a pointer to the changeable type.
As with the [wire_marshal] attribute, you supply routines for the sizing, marshaling, unmarshaling, and freeing passes. The following table describes the four user-supplied routine names. The <type> is the userm-type specified in the [user_marshal] type definition.
| Routine | Description |
|---|---|
| <type>_UserSize | Sizes the RPC data buffer before marshaling on the client or server side. |
| <type>_UserMarshal | Marshals the data on the client or server side. |
| <type>_UserUnmarshal | Unmarshals the data on the client or server side. |
| <type>_UserFree | Frees the data on the server side. |
These user-supplied routines are provided by either the client or the server application, based on the directional attributes.
If the parameter is [ in] only, the client transmits to the server. The client needs the <type>_UserSize and <type>_UserMarshal functions. The server needs the <type>_UserUnmarshal and <type>_UserFree functions.
For an [ out]-only parameter, the server transmits to the client. The server needs the <type>_UserSize and <type>_UserMarshal functions, while the client needs the <type>_UserMarshal function.