External Interfaces

Passing Arguments

To determine which MATLAB data types to use when passing arguments to library functions, see the output of libfunctionsview or libfunctions -full. These functions list all of the functions found in a particular library along with a specification of the data types required for each argument.

A sample external library called shrlibsample is supplied with MATLAB. The .dll file for the shrlibsample library resides in the directory, extern\examples\shrlib. To use the shrlibsample library, you first need to either add this directory to your MATLAB path with the command,

• addpath([matlabroot '\extern\examples\shrlib'])
  

or make this your current working directory with the command,

• cd([matlabroot '\extern\examples\shrlib'])
  

The following example loads the shrlibsample library and displays some of the functions that come with the library:

• loadlibrary shrlibsample shrlibsample.h
  libfunctions shrlibsample -full
  
  doublePtr multDoubleArray(doublePtr, int32)
  double addMixedTypes(int16, int32, double)
  [double, doublePtr] addDoubleRef(double, doublePtr, double)
  [string, string] stringToUpper(string)
  string readEnum(Enum1)
  double addStructFields(c_struct)
  [lib.pointer, doublePtr] multDoubleRef(doublePtr)
  [double, c_structPtr] addStructByRef(c_structPtr)
  c_structPtrPtr allocateStruct(c_structPtrPtr)
  voidPtr deallocateStruct(voidPtr)
  int16Ptr multiplyShort(int16Ptr, int32)
  

These functions are all written in C. What you see here is the MATLAB syntax for calling the C functions.

Some General Rules

There are a few interesting things to note about the input and output arguments shown in the function listing above:

• Many of the arguments (like int32, double) are very similar to their C counterparts. In these cases, you only need to pass in the MATLAB data types shown for these arguments.
• Some arguments in C (like **double, or predefined structures), are quite different from standard MATLAB data types. In these cases, you usually have the option of either passing a standard MATLAB type and letting MATLAB convert it for you, or converting the data yourself using MATLAB functions like libstruct and libpointer. See the next section on Data Conversion.
• C input arguments are often passed by reference. Although MATLAB does not support passing by reference, you can create MATLAB arguments that are compatible with C references. In the listing shown above, these are the arguments with names ending in Ptr and PtrPtr. See Creating References.
• C functions often return data in input arguments passed by reference. MATLAB creates additional output arguments to return these values. Note in the listing shown above that all input arguments ending in Ptr or PtrPtr are also listed as outputs.

A few general guidelines on passing arguments:

• Nonscalar arguments must be declared as passed by reference in the library functions.
• If the library function uses single subscript indexing to reference a two- dimensional matrix, keep in mind that C programs process matrices row by row while MATLAB processes matrices by column. To get C behavior from the function, transpose the input matrix before calling the function, and then transpose the function output.
• When passing an array having more than two dimensions, the shape of the array may be altered by MATLAB. To ensure that the array retains its shape, store the size of the array before making the call, and then use this same size to reshape the output array to the correct dimensions:

• vs = size(vin)                 % Store the original dimensions
  vs =
       2     5     2
  
  vout = calllib('shrlibsample','multDoubleArray', vin, 20);
  
  size(vout)                     % Dimensions have been altered
  ans =
       2    10
  
  vout = reshape(vout, vs);      % Restore the array to 2-by-5-by-2
  
  size(vout)
  ans =
       2     5     2
  

• Use an empty array, [], to pass a NULL parameter to a library function that supports optional input arguments. This is valid only when the argument is declared as a Ptr or PtrPtr as shown by libfunctions or libfunctionsview.

Invoking Library Functions

Passing References

© 1994-2005 The MathWorks, Inc.