Documentation

This is machine translation

Translated by Microsoft
Mouse over text to see original. Click the button below to return to the English verison of the page.

Pass Structures

addStructFields and addStructByRef Functions

The shrlibsample example library contains two functions with c_struct structure input parameters. c_struct is defined in the shrlibsample.h header file.

struct c_struct {
    double p1;
    short p2;
    long  p3;
};

Both functions sum the values of the fields in the structure. The input to addStructFields is c_struct. The input to addStructByRef is a pointer to c_struct. This function also modifies the fields after summing the values.

addStructFields Function

The addStructFields function sums the values of the fields in a c_struct structure.

EXPORTED_FUNCTION double addStructFields(struct c_struct st)
{
    double t = st.p1 + st.p2 + st.p3;
    return t;
}

The MATLAB® function signature is:

Return TypeNameArguments
doubleaddStructFields(struct c_struct)

addStructByRef Function

The addStructByRef function sums the values of the fields in a c_struct structure, then modifies the fields. The function returns the sum calculated before modifying the fields.

EXPORTED_FUNCTION 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;
}

Since the function modifies the input argument, MATLAB also returns the input as an output argument of type c_structPtr. The MATLAB function signature is:

Return TypeNameArguments
[double,
c_structPtr]
addStructByRef (c_structPtr)

You can pass a MATLAB structure to the function and let MATLAB autoconvert the argument. Or you can pass a pointer to a structure, which avoids creating a copy of the structure.

Add Values of Fields in Structure

This example shows how to pass a MATLAB structure to the function, addStructFields.

Create and initialize structure sm. Each field is of type double.

sm.p1 = 476;
sm.p2 = -299;
sm.p3 = 1000;

Load the library containing the addStructFields function.

if not(libisloaded('shrlibsample'))
    addpath(fullfile(matlabroot,'extern','examples','shrlib'))
    loadlibrary('shrlibsample')
end

Call the function. MATLAB automatically converts the fields of structure sm to the library definition for c_struct.

calllib('shrlibsample','addStructFields',sm)
ans =

        1177

Preconvert MATLAB Structure Before Adding Values

This example shows how to preconvert structure sm to c_struct before calling addStructFields. If you repeatedly pass sm to functions, preconverting eliminates the processing time required by MATLAB to autoconvert the structure for each function call.

Create and initialize a MATLAB structure.

sm.p1 = 476;
sm.p2 = -299;
sm.p3 = 1000;

Load the library containing the addStructFields function.

if not(libisloaded('shrlibsample'))
    addpath(fullfile(matlabroot,'extern','examples','shrlib'))
    loadlibrary('shrlibsample')
end

Convert the fields, which are of type double, to match the c_struct structure types, double, short, and long.

sc = libstruct('c_struct',sm);

Display the field names and values.

get(sc)
    p1: 476
    p2: -299
    p3: 1000

Add the field values.

calllib('shrlibsample','addStructFields',sc)
ans =

        1177

Autoconvert Structure Arguments

This example shows how to pass a MATLAB structure to a C library function, addStructByRef. When you pass the structure, MATLAB automatically converts the field types, but MATLAB also makes a copy of the fields.

Load the library.

if not(libisloaded('shrlibsample'))
    addpath(fullfile(matlabroot,'extern','examples','shrlib'))
    loadlibrary('shrlibsample')
end

Create a structure.

S.p1 = 476;
S.p2 = -299;
S.p3 = 1000;

Call addStructByRef.

res = calllib('shrlibsample','addStructByRef',S)
res =

        1177

MATLAB does not modify the contents of structure S, since it is not a pointer.

S
S = 

    p1: 476
    p2: -299
    p3: 1000

Pass Pointer to Structure

This example shows how calling the addStructByRef function with a pointer modifies the fields in the input argument.

if not(libisloaded('shrlibsample'))
    addpath(fullfile(matlabroot,'extern','examples','shrlib'))
    loadlibrary('shrlibsample')
end

Create a structure of type c_struct.

S.p1 = 20;
S.p2 = 99;
S.p3 = 3;

Create a pointer sp to the structure.

sp = libpointer('c_struct',S);
sp.Value
ans = 

    p1: 20
    p2: 99
    p3: 3

Pass the pointer to the function.

res = calllib('shrlibsample','addStructByRef',sp)
res =

   122

When you pass a pointer, the function modifies the fields in the structure it points to.

sp.Value
ans = 

    p1: 5.5000
    p2: 1234
    p3: 12345678

See Also

|

Related Examples

More About

Was this topic helpful?