allocate attribute

The [allocate] ACF attribute lets you customize memory allocation and deallocation for a type defined in the IDL file.

typedef [allocate (allocate-option-list) [, type-attribute-list] ] type-name;

Parameters

allocate-option-list

Specifies one or more memory-allocation options. Select one of either single_node or all_nodes, or one of either free or dont_free, or one from each pair. When you specify more than one option, separate the options with commas.

type-attribute-list

Specifies other optional ACF-type attributes. When you specify more than one type attribute, separate the options with commas.

type-name

Specifies a type defined in the IDL file.

Remarks

The [allocate] attribute has the following valid options.

By default, the stubs may allocate storage for data referenced by a unique or full pointer by calling midl_user_allocate and midl_user_free individually for each pointer.

You can optimize the speed of your application by specifying the option all_nodes. This option directs the stub to compute the size of all memory referenced through the pointer of the specified type and to make a single call to midl_user_allocate. The stub releases the memory by making one call to midl_user_free.

The dont_free option directs the MIDL compiler to generate a server stub that does not call midl_user_free for the specified type. The dont_free option allows the pointer structures to remain accessible to the server application after the remote procedure call has completed and returned to the client.

The [allocate] attribute will cause any [in, out] parameter that is a pointer to a type qualified with the all_nodes option to reallocate memory when the data is unmarshaled. It is the responsibility of the application to free the memory allocated previously for this parameter. For example:

typedef struct thistype 
{ 
    [string] char * PTHISTYPE;  
} * PTHISTYPE
HRESULT proc1 ( [in,out] PTHISTYPE * ppthistype);

The data type PTHISTYPE will be reallocated in the [out] direction by the stub before unmarshaling. Therefore, the application must free the memory it previously allocated for this parameter's data, or a memory leak will occur.

Examples

/* ACF file */ 
typedef [allocate(all_nodes, dont_free)] PTYPE1; 
typedef [allocate(all_nodes)] PTYPE2; 
typedef [allocate(dont_free)] PTYPE3;

See also

Application Configuration File (ACF)

in

midl_user_allocate

midl_user_free

out

typedef