A close look at the preceding interface definitions will show you that all the interface functions are declared using __stdcall, the standard for 32-bit implementations. Frequently, however, you will see use of a STDMETHOD macro that expands to include the calling convention and the standard return type, HRESULT. When implementing an interface member function, you'll frequently see the use of the macro STDMETHODIMP(method), which expands to HRESULT __export __stdcall method, or STDMETHODIMP_(type, method), which expands to type __export __stdcall method. You must always export all interface member functions; using the IMP macros will eliminate any chances that you'll forget to do so.
You may also have noticed the use of [in] and [out] labels before various arguments in the interface member functions. These labels identify the direction of the flow of information through these arguments, such as whether the information is exclusively input data to a function, exclusively output data from the function (such as a structure that it fills), or both. The possible variations are defined as follows, using the word parameter interchangeably with argument:
Parameter Type | Description and Allocation Rules |
in-parameter | Input data for a function, allocated and freed by the caller using whatever memory management is wanted. |
out-parameter | Output data from a function, allocated by the function and freed by the caller using standard COM task memory. The called function must always fill this parameter even on failure; for example, an output pointer must be set to NULL on failure. |
in/out-parameter | Input data for the function, modified and returned as output data on return from the function. Initially allocated by the caller, freed and reallocated by the callee if necessary, and ultimately freed by the caller as with an out-parameter. |
What is referred to as standard COM task memory involves the use of OLE's standard memory allocation service. This is discussed later under "Memory Management." This memory service is used for all function arguments in which a transfer of memory ownership occurs between a client and an object, which means that there must be rules on how to allocate and free this memory. Because there's no transfer of ownership with in-parameters, they do not involve the use of this memory service.