External Interfaces

Creating References

You can pass most arguments to an external function by value, even when the prototype for that function declares the argument to be a reference. However, you may find times when it is useful to pass a MATLAB argument that is the equivalent of a C reference.

Using the libpointer Function

To construct a reference, use the function `libpointer` with this syntax:

• ```p = libpointer('type', 'value')
```

To give an example, create a pointer `pv` to an `int16` value. In the first argument to `libpointer`, enter the `type` of pointer you are creating. The type name is always the data type (`int16`, in this case) suffixed by the letters `Ptr`:

• ```v = int16(485);
pv = libpointer('int16Ptr', v);
```

The value returned, `pv`, is actually an instance of a MATLAB class called `lib.pointer`. The `lib.pointer` class has the properties `Value` and `DataType`. You can read and modify these properties with the MATLAB `get` and `set` functions:

• ```get(pv)
Value: 485
DataType: 'int16Ptr'
```

The `lib.pointer` class also has two methods, `setdatatype` and `reshape`, that are described in the next section, Obtaining the Function's Return Values:

• ```methods(pv)

Methods for class lib.pointer:
setdatatype  reshape
```

Creating a Reference to a Primitive Type

Here is a simple example that illustrates how to construct and pass a pointer to type `double`, and how to interpret the output data. The function `multDoubleRef` takes one input that is a reference to a `double` and returns the same.

Here is the C function:

• ```double *multDoubleRef(double *x)
{
*x *= 5;
return x;
}
```

Construct a reference, `xp`, to input data, `x`, and verify its contents:

• ```x = 15;
xp = libpointer('doublePtr', x);

get(xp)
Value: 15
DataType: 'doublePtr'
```

Now call the function and check the results:

• ```calllib('shrlibsample', 'multDoubleRef', xp);

get(xp, 'Value')
ans =
75
```

 Note    It is important to note that reference `xp` is not a true pointer as it would be in a language like C. That is, even though it was constructed as a reference to `x`, it does not contain the address of `x`. So, when the function executes, it modifies the `Value` property of `xp`, but it does not modify the value in `x`. If you now examine `x`, you find that its original value is unchanged:` x x = 15`

Obtaining the Function's Return Values.   In the last example, the result of the function called from MATLAB could be obtained by examining the modified input reference. But this function also returns data in its output arguments that may be useful.

The MATLAB prototype for this function (returned by `libfunctions` `-full`), indicates that MATLAB returns two outputs. The first is an object of class `lib.pointer`; the second is the `Value` property of the `doublePtr` input argument:

• ```libfunctions shrlibsample -full
[lib.pointer, doublePtr] multDoubleRef(doublePtr)
```

Run the example once more, but this time check the output values returned:

• ```x = 15;
xp = libpointer('doublePtr', x);

[xobj, xval] = calllib('shrlibsample', 'multDoubleRef', xp)
xobj =
lib.pointer
xval =
75
```

Like the input reference argument, the first output, `xobj`, is an object of class `lib.pointer`. You can examine this output, but first you need to initialize its data type and size as these factors are undefined when returned by the function. Use the `setdatatype` method defined by class `lib.pointer` to set the data type to `doublePtr` and the size to `1`-by-`1`.

Once initialized, you can examine the `xobj` output:

• ```setdatatype(xobj, 'doublePtr', 1, 1)

get(xobj)
ans =
Value: 75
DataType: 'doublePtr'
```

The second output, `xval`, is a `double` copied from the `Value` of input `xp`.

Creating a Structure Reference

Creating a reference argument to a structure is not much different than using a reference to a primitive type. The function shown here takes a reference to a structure of type `c_struct` as its only input. It returns an output argument that is the sum of all fields in the structure. It also modifies the fields of the input argument:

• ```double addStructByRef(struct c_struct *st)
{
double t = st->p1 + st->p2 + st->p3;
st->p1 = 5.5;
st->p2 = 1234;
st->p3 = 12345678;
return t;
}
```

Passing the Structure Itself.   Although this function expects to receive a structure reference input, it is easier to pass the structure itself and let MATLAB do the conversion to a reference. This example passes a MATLAB structure, `sm`, to the function `addStructByRef`. MATLAB returns the correct value in the output, `x`, but does not modify the contents of the input, `sm`, since `sm` is not a reference:

• ```sm.p1 = 476;   sm.p2 = -299;   sm.p3 = 1000;

x =
1177
```

Passing a Structure Reference.   The second part of this example passes the structure by reference. This time, the function receives a pointer to the structure and is then able to modify the structure fields.

• ```sp = libpointer('c_struct', sm);