Represent Structure Arguments in C Shared Library Functions

Structure Argument Requirements

When you pass a MATLAB^® structure to an external library function:

• Every MATLAB field name must match a field name in the library structure definition. Field names are case-sensitive.

• MATLAB structures cannot contain fields that are not in the library structure definition.

• If a MATLAB structure contains fewer fields than defined in the library structure, MATLAB sets undefined fields to zero.

You do not need to match the data types of numeric fields. The calllib function converts to the correct numeric type.

Find Structure Field Names

To determine the name and data type of structure fields, you can:

• Consult the library documentation.

• Look at the structure definition in the library header file.

• Use the libstruct function.

Strategies for Passing Structures

MATLAB automatically converts a structure to the library definition for that structure type. For most cases, such as working with small structures, this works fine.

However, when working with repeated calls that pass large structures, convert the structure manually before making any calls to external functions. You save processing time by converting the structure data only once at the start rather than at each function call. You can also save memory if the fields of the converted structure take up less space than the original MATLAB structure.

To convert manually, call the libstruct function to create a libstruct object. Although it is an object, it behaves like a MATLAB structure. The fields of the object are derived from an externally specified structure type.