4.2 Reference and Memory Management Conventions

Since the set of methods and semantics attached to a COM interface represented by a particular GUID only needs to be informally defined by the designer of the interface and understood by the programmers writing code that uses that interface, the exact semantics of the interface can be arbitrary - COM makes no explicit restrictions on the interface's methods and semantics as long as they are meaningful and well-defined. However, for convenience and consistency, and to make it more practical for COM interfaces to be defined in a form usable by automated tools such as IDL compilers, COM provides a set of method invocation conventions which interface designers are recommended to use when possible. These conventions mainly deal with the allocation and deallocation of memory across method calls, and similarly, the allocation and deallocation of COM object references.

As with typical interface definition languages (IDLs), COM defines three basic logical types of parameters, each with its own standard semantic rules for memory and object reference management. Although COM interfaces do not need to be defined in any IDL, this categorization makes COM's conventions consistent with common IDLs and makes COM interfaces easier to define in IDLs when necessary:

• in parameters are parameters through which the caller passes information to the callee. Memory is allocated and freed by the caller: if the callee wants to retain a copy of the data after returning from the call, it must allocate its own memory area and copy the data into it. The callee must not modify or deallocate the memory since it is merely ``on loan'' from the caller. Similarly, COM object references are allocated and freed by the caller: the callee merely ``borrows'' the object reference during the call, and if it wants to retain its own reference to the object after returning from the call, it must call the addref method on the interface pointer before returning.
• out parameters are parameters through which the callee passes information back to the caller. In this case, memory buffers and object references are allocated by the callee and freed by the caller: in other words, the method allocates the buffers or references itself and then hands the responsibility for their management to the caller on return.
• in-out parameters are parameters through which the caller passes information to the callee at call time, and the callee later passes information back to the caller at return time. In this case, the caller initially allocates the parameters and initializes them with their initial ``ingoing'' values; however, during the call, the callee may free and reallocate some or all of these parameters and reinitialize them with the final ``outgoing'' values to be passed back to the caller. After the call is complete, the caller is then responsible for deallocating these final memory buffers and object references.

By convention, the return value of a COM interface method is normally used to return a generic success/failure code to the caller (see Section 4.3, below). However, sometimes methods are instead defined to return something else as their return value; in this case, the return value can be thought of as an out parameter for purposes of memory and object reference management.