`void*` 引数および `void**` 引数の定義

MATLAB^® は、void* 入力をもつ、または void* 出力を返す C++ シグネチャをサポートします。void* の戻り値の型と void** パラメーターの型は、不透明なオブジェクトです。

void* 型と void** 型は MATLAB では作成できません。代わりに、これらの型をもつ C++ ライブラリ関数を使用できます。

void* が typedef (または using) キーワードを使用して定義されている場合、MATLAB は typedef 名を MLTYPE として割り当てます。
パブリッシャーは、ライブラリ定義ファイルで MLTYPE を指定して、MATLAB 型を void* 型に割り当てることができます。
MATLAB ユーザーは、void* の戻り引数を、適切な void* 入力を取る関数に入力として渡すことができます。

MATLAB は、void** パラメーターに対して void* の戻り値の型を返します。詳細については、void** 入力引数型を参照してください。

MATLAB は、MATLAB データ型への void* の型キャストをサポートしません。

`void*` の戻り値の型

MATLAB は、引数 MLTYPE を次のいずれかとして指定して、void* 出力をライブラリ定義ファイルで定義します。

ライブラリからの typedef。スカラー出力の場合のみ使用します。
void* にライブラリで定義された typedef がある場合、MATLAB は、typedef ステートメントで MLTYPE を新しい型名として指定します。
typedef がない場合は、clib.InterfaceName.TypeName 形式の MATLAB 型を選択します。ここで、TypeName には名前空間を含めることができます。
ライブラリに適切な typedef ステートメントがない場合は、MATLAB 型を使用して void* を定義できます。

このサンプルのヘッダーファイルには、void* 型の関数が含まれています。これらの型を定義するには、この例で生成されたライブラリ定義ファイルのステートメントを使用します。引数の型に関する仮定は、ライブラリドキュメンテーションに基づいています。

typedef void* handle; 
handle getHandle();   

using ghandle = void*;
ghandle getGHandle(); 

void* getImagData(const int* pa);

typedef void* data; 
void* getData();

ライブラリからの `typedef` を使用した出力引数の定義

handle は typedef で定義されます。MATLAB は、opaque 型の typedef void* handle を作成します。

addOpaqueType(libnameDef, ...
    "typedef void* handle", "MATLABName", ...
    "clib.libname.handle", ... 
    "Description", "clib.libname.handle Representation of C++ type void*.")

MATLAB では、この型を自動的に使用して、戻り引数で MLTYPE を clib.libname.handle として定義します。

defineOutput(getHandleDefinition, "RetVal", "clib.lib.handle");

`using` ステートメントからの出力引数の定義

ghandle は、using ステートメントを使用して定義されます。前の例の handle と同様に、MATLAB では、typedef void* ghandle 型を自動的に作成し、それを使用して戻り引数で MLTYPE を clib.libname.ghandle として定義します。

addOpaqueType(libnameDef, ...
    "typedef void* ghandle", "MATLABName", ...
    "clib.libname.ghandle", ... 
    "Description", "clib.libname.ghandle Representation of C++ type void*.")
defineOutput(getGHandleDefinition, "RetVal", "clib.libname.ghandle");

新しい型名からの出力引数の定義

getImagData の出力には定義が必要です。

%defineOutput(getImagDataDefinition, "RetVal", <MLTYPE>, <SHAPE>); ...
%'<MLTYPE>' can be an existing typedef name for void* or a new typedef name to void*.

clib.libname.ImagData などの新しい型を指定し、それを使用して RetVal をこの型のスカラー値として定義します。

defineOutput(getImagDataDefinition, "RetVal", "clib.libname.ImagData", 1);

既存の `typedef` からの出力引数の定義

getData の出力には定義が必要です。

%defineOutput(getDataDefinition, "RetVal", <MLTYPE>, <SHAPE>); 
%'<MLTYPE>' can be an existing typedef name for void* or a new typedef name to void*.

data という名前の void* の typedef があるため、これを使用して、RetVal を clib.libname.data 型のスカラー値として定義できます。

defineOutput(getDataDefinition, "RetVal", "clib.libname.data", 1);

`void*` 入力引数型

MATLAB は、void* 引数の基となる C++ データを対応する C++ の型に変換しようとします。C++ から MATLAB データ型へのマッピングについては、void* 引数型を参照してください。

基本型
clib.array 型
ライブラリの C++ クラスの型
void* typedef

以下のサンプルヘッダーファイルのステートメントには、void* 入力引数をもつ関数が含まれています。引数の型に関する仮定は、ライブラリドキュメンテーションに基づいています。生成されたライブラリ定義ファイル definelibname.m 内の defineArgument ステートメントは、各ケースの処理方法を示しています。

基本型としての入力引数の定義

getAttribute に関するドキュメンテーションには、void *value が uint64_t 基本型の C++ データをポイントすること、およびこの値が戻り引数として渡されることが示されています。

class TaskHandle; 
int32 getAttribute(TaskHandle tHandle, int32 attribute, void *value);

MATLAB は、入力引数 value を定義するために、以下のステートメントを生成します。

%defineArgument(getAttributeDefinition, "value", <MLTYPE>, <DIRECTION>, <SHAPE>); 
%'<MLTYPE>' can be primitive type, user-defined type, clib.array type, or 
%a list of existing typedef names for void*.

value を uint64 型のスカラー型の戻り値として定義します。

defineArgument(getAttributeDefinition, "value", "uint64", "output", 1);

`clib.array` 型としての入力引数の定義

この関数 readRaw の readArray 引数を clib.array 型として定義できます。

class TaskHandle; 
int32 readRaw (TaskHandle tHandle, void *readArray, uInt32 arraySizeInBytes);

引数 void *readArray を、サイズが arraySizeInBytes である clib.array.libname.Int 型の入力として定義します。

defineArgument(readRawDefinition, "readArray", "clib.array.libname.Int", ...
    "input", "arraySizeInBytes");

ライブラリの C++ クラスとしての入力引数の定義

この関数 setDrawCallback の userdata 引数をライブラリのクラスとして定義できます。

void setDrawCallback(const String& winname, 
    OpenGlDrawCallback onOpenGlDraw, 
    void* userdata = 0) 
void on_opengl(void* param) { 
cv::ogl::Texture2D* backgroundTex = (cv::ogl::Texture2D*)param; 
.... 
}

引数 void *userdata を clib.lib.cv.ogl.Texture2D クラスの入力スカラーとして定義します。

defineArgument(setDrawCallbackDefinition, "userdata", "clib.lib.cv.ogl.Texture2D", ...
    "input", 1);

既存の `void*` `typedef` としての入力引数の定義

void* の既存の typedef を使用して、この関数 setRemoteTimeout の in 引数を定義できます。

typedef void* sessionHandle; 
void setRemoteTimeout(sessionHandle in);

引数 in を typedef sessionHandle の入力スカラーとして定義します。

defineArgument(setRemoteTimeoutDefinition, "in", "clib.libname.sessionHandle", "input", 1);

`void**` 入力引数型

MATLAB は、void** パラメーターに対して void* 引数を返します。void * が typedef または using ステートメントを使用して定義されている場合、MATLAB では、typedef または using の名前が MLTYPE として自動的に割り当てられます。それ以外の場合、ライブラリ定義ファイルで MLTYPE を指定して、MATLAB 型をライブラリの既存の void* 型に割り当てることができます。

このサンプルのヘッダーファイルには、void** パラメーターをもつ関数が含まれています。以下のトピックでは、この例で生成されたライブラリ定義ファイルのステートメントを使用して、これらの型を定義する方法を説明します。引数の型に関する仮定は、ライブラリドキュメンテーションに基づいています。

class HClass{};
typedef void* handle; 
void getHandle(handle* out){
    *out = new HClass();
}
using ghandle = void*;
void getGHandle(ghandle* out){
    *out = new HClass();
}

void getNewHandle(void** out){
    *out = new int(1);
}
typedef void* ptr; 
void getPointer(void** out){
    *out = new int(2);
}

ライブラリからの `void*` `typedef` または `using` ステートメントを使用した引数の定義

関数 getHandle の out 引数は、void* 型の handle へのポインターとして定義されます。インターフェイスライブラリ lib の場合、MATLAB は既存の typedef ステートメントを使用して、out を clib.lib.handle 型の出力スカラーとして定義します。

defineArgument(getHandleDefinition, "out", "clib.lib.handle", "output", 1);

関数 getGHandle の out 引数は、using ステートメントで定義された void* 変数 ghandle へのポインターとして定義されます。MATLAB は、既存の using ステートメントを使用して、out を clib.lib.ghandle 型の出力スカラーとして定義します。

defineArgument(getGHandleDefinition, "out", "clib.lib.ghandle", "output", 1);

`void*` の新しい型名からの引数の定義

getNewHandle の void** パラメーターには定義が必要です。

%defineArgument(getNewHandleDefinition, "out", <MLTYPE>, "output", 1);

clib.lib.NewHandle などの新しい型を指定できます。

defineArgument(getNewHandleDefinition, "out", "clib.lib.NewHandle", "output", 1);

既存の `void*` `typedef` からの引数の定義

getNewHandle の void** パラメーターには定義が必要です。

%defineArgument(getPointerDefinition, "out", <MLTYPE>, "output", 1);

ptr という名前の void* の typedef があるため、これを使用して、out パラメーターを clib.lib.ptr 型のスカラー値として定義できます。

defineArgument(getPointerDefinition, "out", "clib.lib.ptr", "output", 1);

クラスのオブジェクトとしての `MATLABType`

MATLAB には、そのクラスのオブジェクトを作成しないと使用できないオブジェクトに関するメッセージが表示され、MATLABType に対する他の値が提示されます。あるいは、クラスのスコープ外である MATLABType の使用を検討してください。

たとえば、このクラス A からライブラリ定義ファイル definelib.m を作成するとします。

class A {
public:
	typedef void* handle;
	A(void* arg1, handle arg2) {}

	void* task1() {
		int* x = new int(10);
		return x;
	}

	handle task2() {
		int* x = new int(10);
		return x;
	}
};

MATLAB は、typedef void* handle の opaque 型を作成し、task2 を定義します。パブリッシャーは、void* task1 の opaque 型 clib.lib.A.NewHandle と A クラスのコンストラクター引数 void* arg1 を作成します。

addOpaqueType(libDef, "typedef void* A::handle", "MATLABName", "clib.lib.A.handle ", ...
"Description", "clib.lib.A.handle Representation of C++ opaque type.");

AConstructor1Definition = addConstructor(ADefinition, ...
"A::A(void * in)", ...
"Description", "clib.lib.A.A Constructor of C++ class A.");
defineArgument(AConstructor1Definition, "arg1", "clib.lib.A.NewHandle", "input", 1); 
% '<MLTYPE>' can be primitive type, user-defined type, clib.array type, or a list of existing typedef names for void*.
defineArgument(AConstructor1Definition, "arg2", "clib.lib.A.handle", "input", 1); 
% '<MLTYPE>' can be clib.lib.A.handle, primitive type, user-defined type, or a clib.array type.
validate(AConstructor1Definition);

task1Definition = addMethod(ADefinition, ...
"A::handle A::task1()", ...
"Description", "clib.lib.A.task1 Method of C++ class A.");
defineOutput(task1Definition, "RetVal", "clib.lib.A.NewHandle", 1); 
% '<MLTYPE>' can be an existing typedef name for void* or a new typedef name to void*.
validate(task1Definition);

task2Definition = addMethod(ADefinition, ...
"A::handle A::task2()", ...
"Description", "clib.lib.A.task2 Method of C++ class A.");
defineOutput(task2Definition, "RetVal", "clib.lib.A.handle", 1);
validate(task2Definition);

コンストラクター A には複数の void* 入力引数があるため、MATLAB には次のメッセージが表示されます。

clib.lib.A(clib.lib.A.Newhandle,clib.lib.A.handle)
      Note: This constructor cannot create object clib.lib.A, if object clib.lib.A.Newhandle/ 
      clib.lib.A.handle is not available without constructing object of clib.lib.A. 
      Consider using a MATLABType which is outside the scope of clib.lib.A.

このコンストラクターの clib.lib.A オブジェクトを作成するには、MATLABType を次のいずれかとして指定します。

arg1 はプリミティブ型、ユーザー定義型、または clib.array 型。
arg2 はプリミティブ型、ユーザー定義型、または clib.array 型。
MATLABType (clib.lib.A のスコープ外)。

`void*` 引数および `void**` 引数のメモリ管理

defineArgument (FunctionDefinition) または defineArgument (MethodDefinition) で名前と値の引数 ReleaseOnCall を使用して、void* 引数のメモリの所有権をライブラリに渡すことができます。

defineOutput (FunctionDefinition) または defineOutput (MethodDefinition) で名前と値の引数 DeleteFcn を使用して、void* 出力のメモリの所有権を MATLAB に渡すことができます。deleterは、ユーザー定義関数にするか、void* の戻り値の型の C++ 標準 delete 演算子にすることができます。

スカラーの void** 出力引数の場合は、defineArgument (FunctionDefinition) または defineArgument (MethodDefinition) で DeleteFcn 引数を使用します。例については、double 型のポインターの入力引数に使用するメモリの管理を参照してください。

複数の void* typedef ステートメントがある場合は、これらの typedef 引数のリストを void* 入力の MLTYPE として取る deleter 関数を定義できます。DeleteFcn を関数によって返された 1 つの void* typedef にのみ割り当てた場合、MATLAB ユーザーは、その引数を使用してこの deleter 関数を直接呼び出すことはできません。ユーザーが MATLAB の関数 delete を呼び出したときに、MATLAB がこの関数を呼び出します。ただし、ユーザーは、他の任意の void* typedef 引数を使用して deleter 関数を直接呼び出すことができます。

詳細については、MATLAB での C++ オブジェクトの有効期間の管理を参照してください。

void* 引数および void** 引数の定義

void* の戻り値の型

ライブラリからの typedef を使用した出力引数の定義

using ステートメントからの出力引数の定義

新しい型名からの出力引数の定義

既存の typedef からの出力引数の定義

void* 入力引数型

基本型としての入力引数の定義

clib.array 型としての入力引数の定義

ライブラリの C++ クラスとしての入力引数の定義

既存の void* typedef としての入力引数の定義

void** 入力引数型

ライブラリからの void* typedef または using ステートメントを使用した引数の定義

void* の新しい型名からの引数の定義

既存の void* typedef からの引数の定義

クラスのオブジェクトとしての MATLABType

void* 引数および void** 引数のメモリ管理

参考

トピック