External Interfaces |
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.
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:
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:
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:
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); calllib('shrlibsample', 'addStructByRef', sp) ans = 1177 get(sp, 'Value') ans = p1: 5.5000 p2: 1234 p3: 12345678
Structures | Reference Pointers |
© 1994-2005 The MathWorks, Inc.