Differences between [in, out] and [out, retval] in COM IDL definitions

Question

In some of the IDL I work with I have noticed that there are 2 conventions for marking return values in methods - [in, out] and [out, retval].

It appears that [in, out] is used when there are multiple return values, for example:

HRESULT MyMethod(
    [in] long InputParam, 
    [in, out] long* OutputParam1, 
    [in, out] long* OutputParam2
);

It appears that [out, retval] is used when there is only a single return value, for example:

HRESULT MyMethod2(
    [in] long InputParam, 
    [out, retval] long* OutputParam1
);

Is this a COM IDL convention or just a convention in the code I am working with?

Is there a functional difference in the code that will be generated from the 2 notations, or are they completely interchangeable?

Answer 1

[in, out] means that a valid value is passed when the method is called and a valid value is there (where the pointer points) when the method returns success. [out] means that the value pointed to can be whatever when the method is called but it will be valid when the method returns success. Both [out] and [in, out] parameters must be pointers - their values are unchanged and valid and the validity requirements only apply to the variables they point to.

[out, retval] is a syntactic sugar to indicate that when creating a Native COM Support wrapper this very parameter should be converted to a return value. For example

HRESULT MyMethod( [out] long* OutParam1, [out, retval] long* OutParam2 );

becomes

long IWrappedInterface::MyMethod( long* OutParam1 );

If you don't mark it [retval] the wrapper will contain a method with the original signature:

HRESULT IWrappedInterface::MyMethod( long* OutParam1, long* OutParam2 );

Only the last one [out] parameter can be marked as [out, retval]. [in, out] parameters can't be marked as [retval].