External Interfaces Previous page   Next Page

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:

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:

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:

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

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:

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

Now call the function and check the results:

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:

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

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:

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:

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:

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.


Previous page  Structures Reference Pointers Next page

© 1994-2005 The MathWorks, Inc.