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].

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].

Answer 2

Another difference is how this will show up in a PIA in .NET code.

[out, ret] will show up as a return value in .NET.

[out] will show up an argument on the method in .NET.