External Interfaces |

For library functions that take structure arguments, you need to pass structures that have field names that are the same as those in the structure definitions in the library. To determine the names and also the data types of structure fields, you can do one of the following:

- Consult the documentation that was provided with the library.
- Look for the structure definition in the header file that you used to load the library into MATLAB.

You can also determine the field names of an externally defined structure from within MATLAB using the following procedure. When you create and initialize the structure, you don't necessarily have to match the data types of numeric fields. MATLAB converts to the correct numeric type for you when you make the call using the `calllib`

function. To get the structure field names:

- Use
`libfunctionsview`

to display the signatures for all functions in the library you are using.`libfunctionsview`

shows the names of the structures used by each function. For example, when you type

- MATLAB opens a new window displaying function signatures for the
`shrlibsample`

library. The line showing the`addStructFields`

function reads:

- If the function you are interested in takes a structure argument, get the structure type from the
`libfunctionsview`

display, and invoke the`libstruct`

function on that type.`libstruct`

returns an object that is modeled on the structure as defined in the library: - Get the names of the structure fields from the object returned by
`libstruct`

: - Initialize the fields to the values you want to pass to the library function and make the call using
`calllib`

:

**Specifying Structure Field Names**

Here are a few general guidelines that apply to structures passed to external library functions:

- These structures may contain fewer fields than defined in the library structure. MATLAB sets any undefined or uninitialized fields to zero.
- Any structure field name that you use must match a field name in the structure definition. Structure names are case sensitive.
- Structures cannot contain additional fields that are not in the library structure definition.

**Passing a MATLAB Structure**

As with other data types, when an external function takes a structure argument (such as a C structure), you can pass a MATLAB structure to the function in its place. Structure field names must match field names defined in the library, but data types for numeric fields do not have to match. MATLAB converts each numeric field of the MATLAB structure to the correct data type.

**Example of Passing a MATLAB Structure.** The sample shared library, `shrlibsample`

, defines the following C structure and function:

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

The following code passes a MATLAB structure, `sm`

, with three `double`

fields to `addStructFields`

. MATLAB converts the fields to the `double`

, `short`

, and `long`

data types defined in the C structure, `c_struct`

.

**Passing a libstruct Object**

When you pass a structure to an external function, MATLAB makes sure that the structure being passed matches the library's definition for that structure type. It must contain all the necessary fields defined for that type and each field must be of the expected data type. For any fields that are missing in the structure being passed, MATLAB creates an empty field of that name and initializes its value to zero. For any fields that have a data type that doesn't match the structure definition, MATLAB converts the field to the expected type.

When working with small structures, it is efficient enough to have MATLAB do this work for you. You can pass the original MATLAB structure with `calllib`

and let MATLAB handle the conversions automatically. However, when working with repeated calls that pass one or more large structures, it may be to your advantage to convert the structure manually before making any calls to external functions. In this way, 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.

**Using the libstruct Function.** You can convert a MATLAB structure to a C-like structure derived from a specific type definition in the library in one step. Call the `libstruct`

function, passing in the name of the structure type from the library, and the original structure from MATLAB. The syntax for `libstruct`

is

The value `s`

returned by this function is called a *libstruct object*. Although it is truly a MATLAB object, it handles much like a MATLAB structure. The fields of this new "structure" are derived from the external structure type specified by `structtype`

in the syntax above.

For example, to convert a MATLAB structure, `sm`

, to a libstruct object, `sc`

, that is derived from the `c_struct`

structure type, use

The original structure, `sm`

, has fields that are all of type `double`

. The object, `sc`

, returned from the `libstruct`

call has fields that match the `c_struct`

structure type. These fields are `double`

, `short`

, and `long`

.

**Creating an Empty libstruct Object.** You can also create an empty libstruct object by calling `libstruct`

with only the `structtype`

argument. This constructs an object with all the required fields and with each field initialized to zero.

**libstruct Requirements for Structures.** when converting a MATLAB structure to a libstruct object, the structure to be converted must adhere to the same guidelines that were documented for MATLAB structures passed directly to external functions. See Specifying Structure Field Names.

**Using the Structure as an Object**

The value returned by `libstruct`

is not a true MATLAB structure. It is actually an instance of a class called `lib.c_struct`

, as seen by examining the output of `whos`

:

The fields of this structure are implemented as properties of the `lib.c_struct`

class. You can read and modify any of these fields using the MATLAB object-oriented functions, `set`

and `get`

:

sc = libstruct('c_struct'); set(sc, 'p1', 100, 'p2', 150, 'p3', 200); get(sc) p1: 100 p2: 150 p3: 200

You can also read and modify the fields by simply treating them like any other MATLAB structure fields:

**Example of Passing a libstruct Object**

Repeat the `addStructFields`

example, this time converting the structure to one of type `c_struct`

before calling the function:

sm.p1 = 476; sm.p2 = -299; sm.p3 = 1000; sc = libstruct('c_struct', sm); get(sc) p1: 476 p2: -299 p3: 1000

Now call the function, passing the structure `sc`

:

Enumerated Types | Creating References |

© 1994-2005 The MathWorks, Inc.