Edit

force_allocate attribute

  • Article

The ACF attribute [force_allocate] forces a pointer parameter to be allocated using midl_user_allocate instead of optimizing away the allocation.

[ [function-attribute-list <>] ] type-specifier <> [pointer- <>declarator <>] function-name <>( [ force_allocate [ , parameter-attribute-list <> ] ] type-specifier <> [declarator <>] , ...);

Parameters

This attribute has no parameters.

Remarks

RPC attempts to minimize memory allocations on the server by supplying pointers to internal memory buffers. This approach can cause problems for applications that attempt to directly call midl_user_free on RPC-supplied pointers, because a pointer that has been optimized cannot be freed. Marking a parameter with [force_allocate] will prevent this optimization for all pointers deriving it.

Another common use for [force_allocate] is to guarantee the alignment of the memory being pointed to if an application requires an alignment greater than that of the memory pointed to. For example, applications often pass data in a generic array of bytes rather than using the actual type, but a byte is only guaranteed to be aligned at 1, which may cause problems for applications that assume a larger alignment. By marking the parameter with [force_allocate], the application can guarantee all memory pointed to will have an alignment equal to that guaranteed by midl_user_allocate.

Examples

/* IDL file */
void Func1([in, out, string] char **ppstr);
void Func2([in] long s, [in, size_is(s)] byte *pData);

/* ACF file */

/* e.g. The application wishes to call midl_user_free on *ppstr and supply a new pointer */
Func1([force_allocate] pstr);

/* e.g. pData really points to a structure that needs an alignment greater than 1 */
Func2([force_allocate] pData);

See also

Avoiding Information Hiding

Designing 64-bit-Compatible Interfaces

midl_user_allocate

midl_user_free

allocate