共有 C ライブラリ関数への引数の受け渡し

C の型と対応する MATLAB の型

共有ライブラリインターフェイスはすべての標準スカラーの C の型をサポートしています。次の表は、C の型とそれに対応する MATLAB^® の型の一覧です。MATLAB は、左の列に示された C の型をもつ引数について、右の列の型を使用します。

メモ

MATLAB によって返されるスカラー値はすべて、double 型です。

MATLAB プリミティブ型

C の型	対応する MATLAB の型
`char`, `byte`	`int8`
`unsigned char`, `byte`	`uint8`
`short`	`int16`
`unsigned short`	`uint16`
`int`	`int32`
`long` (Windows^®)	`int32`, `long`
`long` (Linux^®)	`int64`, `long`
`unsigned int`	`uint32`
`unsigned long` (Windows)	`uint32`, `long`
`unsigned long` (Linux)	`uint64`, `long`
`float`	`single`
`double`	`double`
`char *`	`char` 配列 (1 行 n 列)
`*char[]`	文字ベクトルの cell 配列

次の表は、MATLAB が C ポインター (1 列目) を対応する MATLAB 関数シグネチャ (2 列目) にマッピングする方法を示しています。通常、変数は「等価な MATLAB 型」列から、対応する「引数データ型」をもつ関数に渡すことができます。lib.pointer オブジェクトを代わりに使用する場合の詳細については、C 関数内でのポインター引数を参照してください。

MATLAB の拡張型

C ポインターの型	引数データ型	等価な MATLAB 型	共有ライブラリ shrlibsample における関数の例
`double *`	`doublePtr`	`double`	`addDoubleRef`
`float *`	`singlePtr`	`single`
`intsize *` (整数ポインターの型)	`(u)int(size)Ptr` たとえば、`int64 *` は `int64Ptr` になります。	`(u)int(size)`	`multiplyShort`
`byte[]`	`int8Ptr`	`int8`
`char[]` (値渡しの null 終端文字列)	`cstring`	`char` 配列 (1 行 n 列)	`stringToUpper`
`char **` (文字列を指すポインターの配列)	`stringPtrPtr`	文字ベクトルの cell 配列
`enum`	`enumPtr`
`type **`	`type``PtrPtr` たとえば、`double **` は `doublePtrPtr` になります。	`lib.pointer` オブジェクト	`allocateStruct`
`void *`	`voidPtr`		`deallocateStruct`
`void **`	`voidPtrPtr`	`lib.pointer` オブジェクト
`struct` (C スタイルの構造体)	`structure`	MATLAB `struct`	`addStructFields`
`mxArray *`	`MATLAB array`	MATLAB 配列
`mxArray **`	`MATLAB arrayPtr`	`lib.pointer` オブジェクト

MATLAB による関数シグネチャの表示方法

MATLAB の関数シグネチャに示された入出力引数について、いくつかの注意事項を以下に示します。

多くの引数 (int32 や double のような) は、C のそれと似ています。こうした場合は、その引数に対して示される MATLAB 型のみを渡します。
一部の C 引数 (たとえば、**double や定義済みの構造体) は、標準の MATLAB の型とは異なります。こうした場合は、標準の MATLAB 型を渡して MATLAB に変換させるか、あるいは MATLAB 関数 libstruct および libpointer を使用してデータを自分で変換します。詳細については、関数に渡されるデータの手動変換を参照してください。
C 関数はしばしば、参照渡しの入力引数のデータを返します。MATLAB では、これらの値を返すための追加の出力引数が作成されます。Ptr または PtrPtr で終わる入力引数は、出力引数としてもリストされています。

MATLAB 関数シグネチャの例は、共有ライブラリ shrlibsampleを参照してください。

引数受け渡しのガイドライン

ライブラリ関数では、非スカラー引数は参照渡しとして宣言しなければなりません。
ライブラリ関数が単一の添字インデックスを使用して 2 次元行列を参照する場合、C プログラムは行列を行ごとに処理することに注意してください。MATLAB は行列を列ごとに処理します。関数から C の動作を取得するには、関数を呼び出す前に入力行列を転置し、その後関数出力を転置します。
空の配列 [] を使用して、オプションの入力引数をサポートしているライブラリ関数に NULL パラメーターを渡します。この表記は、libfunctions や libfunctionsview によって示されるように、Ptr または PtrPtr として引数が宣言される場合にのみ有効です。

NULL ポインター

ライブラリ関数に渡す NULL ポインターは以下の方法により作成できます。

引数として空配列 [] を渡します。

関数 libpointer を使用します。

p = libpointer; % no arguments

p = libpointer('string') % string argument

p = libpointer('cstring') % pointer to a string argument

関数 libstruct を使用します。

p = libstruct('structtype'); % structure type

空の `libstruct` オブジェクト

空の libstruct オブジェクトを作成するには、libstruct を structtype 引数のみで呼び出します。以下に例を示します。

sci = libstruct('c_struct')
get(sci)

    p1: 0
    p2: 0
    p3: 0

MATLAB に初期化された値が表示されます。

関数に渡されるデータの手動変換

ほとんどの場合、MATLAB ソフトウェアは、外部ライブラリ関数との間で受け渡しされるデータを、外部関数で想定されるデータ型に自動的に変換します。しかし、引数データの手動による変換も選択できます。以下に例を示します。

同じデータを一連のライブラリ関数に渡す場合、呼び出しのたびに MATLAB でデータを自動変換する代わりに、最初の関数の呼び出し前に手動で一度変換します。この手法より、不要なコピーおよび変換操作の数が削減されます。
大規模な構造体を渡す場合、汎用の MATLAB 構造体を使用する代わりに関数で使用される C 構造体の形状と一致する MATLAB 構造体を作成することで、メモリを節約します。関数 libstruct は、ライブラリから取得した C 構造体をモデルとした MATLAB 構造体を作成します。
外部関数に対する引数で複数のレベルの参照が使用される場合 (double ** など)、MATLAB による型の自動変換に頼らず、関数 libpointer を使用して作成したポインターを渡します。

参考

libstruct | libpointer | libfunctions | libfunctionsview