The following table summarizes key rules regarding memory allocation:
| MIDL element | Description |
|---|---|
| Top-level ref pointers | Must be non-null pointers. |
| Function return value | New memory is always allocated for pointer return values. |
| unique, out or ptr, out pointer | Not allowed by MIDL. |
| Non-top-level unique, in, out or ptr, in, out pointer that changes from null to non-null | Client stubs allocate new memory on client on return. |
| Non-top-level unique, in, out pointer that changes from non-null to null | Memory is orphaned on client; client application is responsible for freeing memory and preventing leaks. |
| Non-top-level ptr, in, out pointer that changes from non-null to null | Memory will be orphaned on client if not aliased; client application is responsible for freeing and preventing memory leaks in this case. |
| ref pointers | Client-application layer usually allocates. |
| Non-null in, out pointer | Stubs attempt to write into existing storage on client. If string and size increases beyond size allocated on the client, it will cause a GP-fault on return. |
The following table summarizes the effects of key IDL and ACF attributes on memory management:
| MIDL feature | Client issues | Server issues |
|---|---|---|
| allocate(single_node), allocate(all_nodes) | Determines whether one or many calls are made to the memory functions. | Same as client, except private memory can often be used for allocate (single_node) [in] and [in,out] data. |
| allocate(free) or allocate(dont_free) | (None; affects server) | Determines whether memory on the server is freed after each remote procedure call. |
| array attributes max_is and size_is | (None; affects server) | Determines size of memory to be allocated. |
| byte_count | Client must allocate buffer; not allocated or freed by client stubs. | ACF parameter attribute determines size of buffer allocated on server. |
| enable_allocate | Usually, none. However, the client may be using a different memory management environment. | Server uses a different memory management environment. RpcSmAllocate should be used for allocations. |
| in attribute | Client application responsible for allocating memory for data. | Allocated on server by stubs. |
| out attribute | Allocated on client by stubs. | out-only pointer must be ref pointer; allocated on server by stubs. |
| ref attribute | Memory referenced by pointer must be allocated by client application. | Top-level and first-level reference pointers managed by stubs. |
| unique attribute | Non-null to null can result in orphaned memory; null to non-null causes client stub to call midl_user_allocate. | (Affects client) |
| ptr attribute | (See unique) | (See unique) |