Main Content

本页翻译不是最新的。点击此处可查看最新英文版本。

C++ MEX API

注意

C++ MEX API 与 编写可从 MATLAB（MEX 文件）调用的 C 函数中所述的 C MEX API 不兼容。您不能在 MEX 文件中混用这些 API。

通过 C++ MEX API，您可以创建利用 C++11 功能（例如移动语义、异常处理和内存管理）的应用程序。

matlab::mex::FunctionC++ MEX 函数的基类
matlab::mex::ArgumentListC++ MEX 函数的输入和输出的容器
matlab::engine::MATLABEngine定义引擎 API 的类

matlab::mex::Function

所有 MEX 文件实现均是从 matlab::mex::Function 派生的类。

std::shared_ptr<matlab::engine::MatlabEngine> getEngine()获取指向 MATLABEngine 对象的指针
void mexLock()防止从内存中清除 MEX 文件
void mexUnLock()允许从内存中清除 MEX 文件
std::u16string getFunctionName()获取当前 MEX 函数的名称

matlab::mex::ArgumentList

通过 MexFunction 类的 operator() 传递的 MEX 函数参数是 matlab::mex::ArgumentList 容器。ArgumentList 完全涵盖数组的基本集合。ArgumentList 对象支持以下函数。

operator[]支持对 ArgumentList 的元素进行 [] 索引。
begin()启动迭代器。
end()结束迭代器。
size()返回参数列表中的元素数。使用此函数检查在调用位置指定的输入和输出的数目。
empty()返回逻辑值，指示参数列表是否为空 (size() == 0)。

C++ 引擎 API

使用以下各节介绍的 matlab::engine::MATLABEngine API 访问 MATLAB® 函数、变量和对象。要调用 matlab::engine::MATLABEngine 函数，请获取由 matlab::mex::Function::getEngine 函数返回的共享指针。例如：

std::shared_ptr<matlab::engine::MATLABEngine> matlabPtr = getEngine();

使用此指针调用引擎函数。例如：

matlabPtr->feval(...);

仅可在 MexFunction 类所在相同线程上调用引擎函数。

matlab::engine::MATLABEngine::feval带参数调用 MATLAB 函数
matlab::engine::MATLABEngine::fevalAsync以异步方式带参数和返回值调用 MATLAB 函数。
matlab::engine::MATLABEngine::eval对基础工作区中的 MATLAB 语句进行求值。
matlab::engine::MATLABEngine::evalAsync以异步方式对基础工作区中的 MATLAB 语句求值。
matlab::engine::MATLABEngine::getVariable从 MATLAB 基础工作区或全局工作区获取变量
matlab::engine::MATLABEngine::getVariableAsync以异步方式从 MATLAB 基础工作区或全局工作区获取变量
matlab::engine::MATLABEngine::setVariable将变量放在 MATLAB 基础工作区或全局工作区中
matlab::engine::MATLABEngine::setVariableAsync以异步方式将变量放在 MATLAB 基础工作区或全局工作区中
matlab::engine::MATLABEngine::getProperty获取对象属性
matlab::engine::MATLABEngine::getPropertyAsync异步获取对象属性
matlab::engine::MATLABEngine::setProperty设置对象属性
matlab::engine::MATLABEngine::setPropertyAsync异步设置对象属性

matlab::engine::MATLABEngine::feval

std::vector<matlab::data::Array> feval(const std::u16string &function,
   const size_t numReturned,
   const std::vector<matlab::data::Array> &args,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = 
       std::shared_ptr<matlab::engine::StreamBuffer>,
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = 
       std::shared_ptr<matlab::engine::StreamBuffer>())
matlab::data::Array feval(const std::u16string &function, 
   const std::vector<matlab::data::Array> &args, 
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = 
       std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = 
       std::shared_ptr<matlab::engine::StreamBuffer>())
matlab::data::Array feval(const std::u16string &function,
   const matlab::data::Array &arg,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = 
       std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = 
       std::shared_ptr<matlab::engine::StreamBuffer>())
ResultType feval(const std::u16string &function,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output,
   const std::shared_ptr<matlab::engine::StreamBuffer> &error,
   RhsArgs&&... rhsArgs )
ResultType feval(const std::u16string &function,
   RhsArgs&&... rhsArgs)

说明

从 MEX 函数调用 MATLAB 函数。使用 feval 带从 MEX 函数传递的参数调用 MATLAB 函数，并将来自 MATLAB 的结果返回给 MEX 函数。

输入和输出是由 用于 C++ 的 MATLAB 数据 API 定义的类型。还有一种语法支持原生 C++ 类型。

参数

const std::u16string &function

要计算的 MATLAB 函数或脚本的名称。将名称指定为 std::u16string。此外，您可以将此参数指定为 std::string。

const size_t nlhs

返回值的数目。

const std::vector<matlab::data::Array> &args

要以 std::vector 形式传递给 MATLAB 函数的多个输入参数。该向量转换为 MATLAB 中的列数组。

const matlab::data::Array &arg

要传递给 MATLAB 函数的单一输入参数。

const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>()

用于存储来自 MATLAB 函数的标准输出的流缓冲区。

const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>()

用于存储来自 MATLAB 函数的错误消息的流缓冲区。

RhsArgs&&... rhsArgs

用于函数输入的原生 C++ 数据类型。feval 接受以下 C++ 数据类型的标量输入：bool、int8_t、int16_t、int32_t、int64_t、uint8_t、uint16_t、uint32_t、uint64_t、float、double。

返回值

std::vector<matlab::data::Array>

从 MATLAB 函数返回的输出。

matlab::data::Array

从 MATLAB 函数返回的单个输出。

ResultType

从 MATLAB 返回的作为用户指定的类型的输出。如果返回多个参数，可以是 std::tuple。

异常

matlab::engine::MATLABException

函数中存在 MATLAB 运行时错误。

matlab::engine::TypeConversionException

MATLAB 函数的结果无法转换为指定的类型。

matlab::engine::MATLABSyntaxException

MATLAB 函数中存在语法错误。

有关详细信息，请参阅Call MATLAB Functions from MEX Functions

matlab::engine::MATLABEngine::fevalAsync

FutureResult<std::vector<matlab::data::Array>> fevalAsync(const std::u16string &function,
   const size_t numReturned,
   const std::vector<matlab::data::Array> &args,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())
FutureResult<matlab::data::Array> fevalAsync(const std::u16string &function,
   const std::vector<matlab::data::Array> &args,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())
FutureResult<matlab::data::Array> fevalAsync(const std::u16string &function,
   const matlab::data::Array &arg,
   const std::shared_ptr<matlab::engine::StreamBuffer> & output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> & error = std::shared_ptr<matlab::engine::StreamBuffer>())
FutureResult<ResultType> fevalAsync(const std::u16string &function,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output,
   const std::shared_ptr<matlab::engine::StreamBuffer> &error,
   RhsArgs&&... rhsArgs)
FutureResult<ResultType> fevalAsync(const std::u16string &function,
   RhsArgs&&... rhsArgs)

说明

以异步方式带参数和返回值调用 MATLAB 函数。有关详细信息，请参阅Making async Requests Using mexCallMATLAB。

参数

const std::u16string &function

要计算的 MATLAB 函数或脚本的名称。将名称指定为 std::u16string。此外，您可以将此参数指定为 std::string。

const size_t numReturned

返回值的数目

const std::vector<matlab::data::Array> &args

要以 std::vector 形式传递给 MATLAB 函数的多个输入参数。该向量转换为 MATLAB 中的列数组。

const matlab::data::Array arg

要传递给 MATLAB 函数的单一输入参数。

const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>()

用于存储来自 MATLAB 函数的标准输出的流缓冲区。

const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>()

用于存储来自 MATLAB 函数的错误消息的流缓冲区。

RhsArgs&&... rhsArgs

用于函数输入的原生 C++ 数据类型。feval 接受以下 C++ 数据类型的标量输入：bool、int8_t、int16_t、int32_t、int64_t、uint8_t、uint16_t、uint32_t、uint64_t、float、double。

返回值

FutureResult

FutureResult 对象，用于获取调用 MATLAB 函数的结果。

异常

无

matlab::engine::MATLABEngine::eval

void eval(const std::u16string &statement,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = 
       std::shared_ptr<matlab::engine::StreamBuffer> (),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = 
       std::shared_ptr<matlab::engine::StreamBuffer> ())

说明

在调用函数工作区中，将 MATLAB 语句作为文本字符串进行计算。

参数

const std::u16string &statement

要计算的 MATLAB 语句

const std::shared_ptr<matlab::engine::StreamBuffer> &output

用于存储来自 MATLAB 语句的标准输出的流缓冲区

const std::shared_ptr<matlab::engine::StreamBuffer> &error

用于存储来自 MATLAB 命令的错误消息的流缓冲区

异常

matlab::engine::MATLABExecutionException

MATLAB 语句中存在运行时错误。

matlab::engine::MATLABSyntaxException

MATLAB 语句中存在语法错误。

有关详细信息，请参阅Execute MATLAB Statements from MEX Function

matlab::engine::MATLABEngine::evalAsync

FutureResult<void> evalAsync(const std::u16string &str,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer> (),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer> ())

说明

以异步方式计算 MATLAB 语句字符串。有关详细信息，请参阅Making async Requests Using mexCallMATLAB。

参数

const std::u16string &str

要计算的 MATLAB 语句

const std::shared_ptr<matlab::engine::StreamBuffer> & output

用于存储来自 MATLAB 语句的标准输出的流缓冲区。

const std::shared_ptr<matlab::engine::StreamBuffer> & error

用于存储来自 MATLAB 命令的错误消息的流缓冲区。

返回值

matlab::engine::FutureResult

FutureResult 对象，用于等待 MATLAB 语句的完成。

异常

无

matlab::engine::MATLABEngine::getVariable

matlab::data::Array getVariable(const std::u16string &varName,
    WorkspaceType workspaceType = WorkspaceType::BASE)

说明

从 MATLAB 基础工作区或全局工作区获取变量。

参数

const std::u16string& varName

MATLAB 工作区中变量的名称。将名称指定为 std::u16string。此外，您可以将此参数指定为 std::string。

matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE

要从中获取变量的 MATLAB 工作区（BASE 或 GLOBAL）。有关详细信息，请参阅 global 和 matlab::engine::WorkspaceType。

返回值

matlab::data::Array

从 MATLAB 基础工作区或全局工作区获得的变量

异常

matlab::engine::MATLABExecutionException

指定的 MATLAB 基础工作区或全局工作区中不存在请求的变量。

有关详细信息，请参阅Set and Get MATLAB Variables from MEX

matlab::engine::MATLABEngine::getVariableAsync

FutureResult<matlab::data::Array> getVariableAsync(const std::u16string &varName,
    WorkspaceType workspaceType = WorkspaceType::BASE)

说明

以异步方式从 MATLAB 基础工作区或全局工作区获取变量。

参数

const std::u16string& varName

MATLAB 工作区中变量的名称。将名称指定为 std::u16string。此外，您可以将此参数指定为 std::string。

WorkspaceType workspaceType = WorkspaceType::BASE

要从中获取变量的 MATLAB 工作区（BASE 或 GLOBAL）。有关详细信息，请参阅 global。

返回值

matlab::engine::FutureResult

FutureResult 对象，您可以使用该对象从 MATLAB 工作区以 matlab.data.Array 形式获取变量。

异常

无

matlab::engine::MATLABEngine::setVariable

void setVariable(const std::u16string &varName,
   const matlab::data::Array &var,
   WorkspaceType workspaceType = WorkspaceType::BASE)

说明

将变量放入 MATLAB 基础工作区或全局工作区中。如果 MATLAB 工作区中存在同名变量，setVariable 会覆盖它。

参数

const std::u16string& varName

要在 MATLAB 工作区中创建的变量的名称。将名称指定为 std::u16string。此外，您可以将此参数指定为 std::string。

const matlab::data::Array var

要在 MATLAB 工作区中创建的变量的值。

matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE

在其中放入变量的 MATLAB 工作区（BASE 或 GLOBAL）。有关详细信息，请参阅 global 和 matlab::engine::WorkspaceType。

有关详细信息，请参阅Set and Get MATLAB Variables from MEX

matlab::engine::MATLABEngine::setVariableAsync

FutureResult<void> setVariableAsync(const std::u16string &varName,
   const matlab::data::Array var,
   WorkspaceType workspaceType = WorkspaceType::BASE)

说明

以异步方式将变量放入 MATLAB 基础工作区或全局工作区中。如果 MATLAB 基础工作区中存在同名变量，setVariableAsync 会覆盖它。

参数

const std::u16string& varName

要在 MATLAB 工作区中创建的变量的名称。将名称指定为 std::u16string。此外，您可以将此参数指定为 std::string。

const matlab::data::Array var

要在 MATLAB 工作区中创建的变量的值

WorkspaceType workspaceType = WorkspaceType::BASE

将变量放入 MATLAB BASE 或 GLOBAL 工作区。有关详细信息，请参阅 global。

异常

无

matlab::engine::MATLABEngine::getProperty

matlab::data::Array getProperty(const matlab::data::Array &objectArray,
    size_t index,
    const std::u16string &propertyName)
matlab::data::Array getProperty(const matlab::data::Array &object,
    const std::u16string &propertyName)

说明

获取对象属性的值。如果对象输入参数是对象数组，请指定对应于要获取其属性值的对象的数组元素的索引。

参数

const matlab::data::Array &objectArray

MATLAB 对象的数组

const matlab::data::Array &object

标量 MATLAB 对象

size_t index

对象数组中从 0 开始的索引，指定该数组中返回其属性值的对象

const std::u16string &propertyName

属性的名称。将名称指定为 std::u16string。此外，您可以将此参数指定为 std::string。

返回值

matlab::data::Array

指定属性的值

异常

matlab::engine::MATLABExecutionException

该属性不存在。

有关详细信息，请参阅 MATLAB Objects in MEX Functions

matlab::engine::MATLABEngine::getPropertyAsync

matlab::engine::FutureResult<matlab::data::Array> getPropertyAsync(const matlab::data::Array &objectArray,
    size_t index,
    const std::u16string &propertyName)
matlab::engine::FutureResult<matlab::data::Array> getPropertyAsync(const matlab::data::Array &object,
   const std::u16string &propertyName)

说明

以异步方式获取对象属性的值。如果对象输入参数是对象数组，请指定对应于要获取其属性值的对象的数组元素的索引。

参数

const matlab::data::Array &objectArray

MATLAB 对象的数组

const matlab::data::Array &object

标量 MATLAB 对象

size_t index

对象数组中从 0 开始的索引，指定该数组中返回其属性值的对象

const std::u16string &propertyName

属性的名称。将名称指定为 std::u16string。此外，您可以将此参数指定为 std::string。

返回值

matlab::engine::FutureResult

用于同步操作的 matlab::engine::FutureResult 对象。

异常

无

matlab::engine::MATLABEngine::setProperty

void setProperty(matlab::data::Array &objectArray,   
    size_t index,
    const std::u16string &propertyName,
    const matlab::data::Array &propertyValue)
void setProperty(matlab::data::Array &object, 
    const std::u16string &propertyName,
    const matlab::data::Array &propertyValue)

说明

设置对象属性的值。如果对象输入参数是对象数组，请指定对应于要设置其属性值的对象的数组元素的索引。

参数

matlab::data::Array &objectArray

MATLAB 对象的数组

matlab::data::Array &object

标量 MATLAB 对象

size_t index

对象数组中元素的索引（从 0 开始），指定该数组中设置了属性值的对象

const std::u16string &propertyName

要设置的属性的名称。将名称指定为 std::u16string。此外，您可以将此参数指定为 std::string。

const matlab::data::Array &propertyValue

赋给属性的值

异常

matlab::engine::MATLABExecutionException

该属性不存在。

有关详细信息，请参阅 MATLAB Objects in MEX Functions

matlab::engine::MATLABEngine::setPropertyAsync

FutureResult<void> setPropertyAsync(matlab::data::Array &objectArray,   
    size_t index,
    const std::u16string &propertyName,
    const matlab::data::Array &propertyValue)
FutureResult<void> setPropertyAsync(matlab::data::Array &object,
 const std::u16string &propertyName,
 const matlab::data::Array &propertyValue)

说明

以异步方式设置对象属性的值。如果对象输入参数是对象数组，请指定对应于要设置其属性值的对象的数组元素的索引。

参数

matlab::data::Array &objectArray

MATLAB 对象的数组

matlab::data::Array &object

标量 MATLAB 对象

size_t index

对象数组中元素的索引（从 0 开始），指定该数组中设置了属性值的对象

const std::u16string &propertyName

要设置的属性的名称。将名称指定为 std::u16string。此外，您可以将此参数指定为 std::string。

const matlab::data::Array &propertyValue

赋给属性的值。

异常

无

异常类

异常原因

matlab::engine::EngineException

函数中存在 MATLAB 运行时错误，或 MATLAB 无法启动。

matlab::engine::MATLABSyntaxException

MATLAB 函数中存在语法错误。

matlab::engine::MATLABExecutionException

MATLAB 函数或语句中存在 MATLAB 运行时错误。

matlab::engine::TypeConversionException

MATLAB 函数的结果无法转换为指定的类型

有关详细信息，请参阅Catch Exceptions in MEX Function

相关主题