Definitions of Parameter Attributes
The standard COM parameter attributes [in], [out], [in/out], and [out, retval] not only identify the direction of the flow of information to and from a function, but also specify whether the caller or callee is responsible for allocating and freeing memory.
You allocate and free memory using standard COM memory functions, such as SysAllocString and SysFreeString.
Clients must call IUnknown::Release to release the IDispatch interface when finished. Failure to do so keeps the object in memory even though it is not used.
The parameter attributes are defined as follows:
- Input data for a function, allocated and freed by the caller using whatever memory management the caller wants. An [in] parameter is not modified by the called function. However, BSTRs must be allocated using SysAllocString.
- Output data from a function, allocated by the function and freed by the caller.
- Input data for the function, modified and returned to the caller as output data. Initially allocated by the caller, an [in/out] parameter may be freed and reallocated by the function if necessary. Ultimately, it is the caller's responsibility to free the memory.
- [out, retval]
- The [retval] attribute designates the parameter that receives the return value of the member function. This attribute is used on parameters of interface members that describe methods or get properties. The [retval] attribute applies only to the last parameter of a member function, and the parameter is a pointer type.