1.7.1.3 In-out parameters

In-out
parameters are always of type pointer in COM and are handled as a mixture of
in
and
out
. In particular, they have both a positional parameter and a keyword parameter, which can be used to control the value passed and conversion of the value returned respectively. Each
in-out
parameter generates a return value, which will be
eq
to the value of the keyword argument if it was passed and otherwise depends on the type of the parameter as below.

As for
out
parameters, if the value of the keyword argument is a foreign pointer then it is passed directly to the method and is expected to be of the appropriate size to contain the returned data. If the value of the keyword argument is
nil
then a null pointer is passed to the COM call. The positional argument should be
nil
is these cases. If the keyword argument not passed, a foreign object with dynamic extent is created to contain the value, initialized with data from the positional argument before calling the method and possibly converted back to a Lisp value on return.

For a parameter with the
string attribute, the positional argument is handled as for the
in
argument
string
case and the keyword argument is handled as for the
out
argument
string
case. The functions co-task-mem-alloc and co-task-mem-free should be used to manage the memory for the string itself.

For a parameter whose type is a non-aggregate array type or a pointer to a non-aggregate type that has the
size_is attribute, the positional argument is handled as for the
in
argument array case and the keyword argument is handled as for the
out
argument array case. To update an existing array, pass it as both the positional and keyword argument values.

For a parameter whose type is a foreign aggregate type, the keyword argument must be passed and its value must be a foreign pointer. This pointer is passed directly to the method and the positional argument should be
nil
.

Otherwise, a foreign object with dynamic extent is created, set to contain the value of positional argument before calling the method and dereferenced on return to obtain the Lisp return value, as if by calling
fli:dereference
.

For example, given the IDL

import "unknwn.idl";

[ object,

uuid(E37A70A0-EFC9-11D5-BF02-000347024BE1)

]

interface IArgumentExamples : IUnknown

{

typedef [string] char *argString;

HRESULT inoutMethod([in, out] int *inoutInt,

[in, out] argString *inoutString,

[in] int inoutArraySize,

[in, out, size_is(inoutArraySize)]

int *inoutArray);

}

the method
inout-method
can receive and return Lisp objects like this: