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 = calllib('shrlibsample', 'addStructByRef', sm)
  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);
  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.