Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
allocate
id
in
int
odl
out
ptr
ref
Collapse the table of content
Expand the table of content

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.

OptionDescription
all_nodesMakes one call to allocate and free memory for all nodes.
single_nodeMakes many individual calls to allocate and free each node of memory.
freeFrees memory on return from the server stub.
dont_freeDoes not free memory on return from the server stub.

 

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

 

 

Community Additions

ADD
Show:
© 2015 Microsoft