libpointer - Create pointer object for use with shared libraries

Syntax

Description

p = libpointer returns an empty (void) pointer.

p = libpointer('type') returns an empty pointer that contains a reference to the specified type. This type can be any MATLAB numeric type, or a structure or enumerated type defined in an external library that has been loaded into MATLAB with the loadlibrary function. For valid types, see the table under C and MATLAB Equivalent Types.

Note   Using this syntax, p is a NULL pointer. You, therefore, must ensure that any library function to which you pass p must be able to accept a NULL pointer as an argument.

p = libpointer('type',value) returns a pointer to the specified data type and initialized to the value supplied.

Tips

MATLAB automatically converts data passed to and from external library functions to the data type expected by the external function. The libpointer function enables you to convert your argument data manually, using the setdatatype method. This is an advanced feature available to experienced C programmers. For more information about using pointer objects, see Working with Pointers. Additional examples for using libpointer can be found in Multilevel Pointers.

Examples

This example passes an int16 pointer to a function that multiplies each value in a matrix by its index. The function multiplyShort is defined in the MATLAB sample shared library, shrlibsample.

Here is the C function:

void multiplyShort(short *x, int size)
{
    int i;
    for (i = 0; i < size; i++)
    *x++ *= i;
}

Load the shrlibsample library. Create the matrix, v, and also a pointer to it, pv:

addpath([matlabroot '\extern\examples\shrlib'])
loadlibrary shrlibsample shrlibsample.h

v = [4 6 8; 7 5 3];

pv = libpointer('int16Ptr',v);
get(pv,'Value')
ans =
     4     6     8
     7     5     3

Now call the C function in the library, passing the pointer to v. If you were to pass a copy of v, the results would be lost once the function terminates. Passing a pointer to v enables you to get back the results:

calllib('shrlibsample','multiplyShort',pv,numel(v));
get(pv,'Value')
ans =
     0    12    32
     7    15    15

unloadlibrary shrlibsample

See Also

libstruct | loadlibrary

How To

• Reading a libpointer Object

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS