ACF Attributes

The include Declaration

The include statement specifies one or more header files to be included in generated stub code via the C-preprocessor #include statement. The user must supply the C header file when compiling the stubs. The ACF include statement provides some flexibility in distributed application design. The include statement is necessary for certain types, such as implicit_handle types that are not defined in the IDL or its closure under #include and import directives.

Implicit Binding Handles

When an interface contains one or more functions whose first parameters are not an explicit handle and do not have an in or an in, out context handle bound to a remote address space, an implicit handle is needed. The implicit_handle and auto_handle attributes provide this capability.

The implicit_handle attribute specifies a global variable that is used as the RPC binding handle for all calls without a binding parameter.

The auto_handle attribute indicates that any function needing implicit handles is automatically bound. When no binding handle to a server exists just prior to calling the function for the first time, the stub automatically establishes a binding handle for the call.

Either auto_handle or implicit_handle can appear, but not both. When a function in the interface requires an implicit handle and no ACF is supplied, or the supplied ACF does not specify either implicit_handle or auto_handle, the MIDL compiler uses auto_handle and issues an informational message.

The code and nocode Attributes

If code appears in the interface attribute list, client stub code is generated for any function in the interface that does not appear in the ACF with a nocode in its function attribute list and which does not have a local attribute.

If nocode appears in the interface attribute list, stub code is generated only for functions in the interface that appear in the ACF with a code in their function attribute lists and which do not have a local attribute.

The nocode attribute is ignored when server stubs are generated. Applying nocode when generating server stubs in DCE-compatibility mode is an error. Either code or nocode can appear in an function attribute list, but not both.

The allocate Attribute

The allocate attribute allows you to customize the allocation and deallocation patterns used by the application and stubs. It can be applied to pointer types as a type attribute or as an interface attribute. When it occurs as an interface attribute, it affects all pointer parameters and types in the interface.

allocate attribute Description
allocate(single_node) Storage for each node on both the caller and callee side is allocated separately by calling midl_user_allocate.
allocate(all_nodes) The size of the total graph (or tree) is precomputed by the stub and midl_user_allocate is called once to allocate sufficient memory for all nodes in the graph upon return from a remote call. In this case, application code has to release this storage by making a single call to midl_user_free.
allocate(free) Storage allocated for nodes on the callee side is freed by stubs upon return from the manager code.
allocate(dont_free) Storage allocated for nodes on the server side is not deallocated by the server stub. This feature is useful for maintaining persistent pointer structures as part of the server application.

The byte_count Attribute

The byte_count ACF attribute associates a pointer parameter with another parameter that specifies the size in bytes of the memory area indicated by the pointer. Memory referenced by the pointer parameter is contiguous and is not allocated or freed by the client stubs. This feature of the byte_count attribute lets the developer create a persistent buffer area in client memory that can be reused across multiple calls.

The parameter providing the buffer must be an out pointer parameter and the parameter providing the length in bytes must be an in parameter of integral type. The byte_count attribute cannot be specified on a parameter that has the size attributes (size_is, max_is) applied to it.