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?

Accepted Answer

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

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

Solution

Problem