メインコンテンツ

<library>Initialize[WithHandlers]

library に関連付けられている MATLAB Runtime インスタンスを初期化

説明

bool libraryInitialize() は、生成された C/C++ 共有ライブラリ library に関連付けられている MATLAB® Runtime インスタンスを既定の出力ハンドラーとエラー ハンドラーを使用して作成します。

この関数は、mclInitializeApplication を呼び出した後、ライブラリによってエクスポートされるコンパイル済み関数を呼び出す前に C/C++ アプリケーションで呼び出します。

bool libraryInitializeWithHandlers(mclOutputHandlerFcn error_handler, mclOutputHandlerFcn print_handler) は、library に関連付けられている MATLAB Runtime インスタンスを作成します。エラー メッセージと出力テキストを処理する関数を指定できます。libraryInitializeWithHandlers に渡した関数が MATLAB Runtime インスタンスでインストールされ、エラー テキストや通常のテキストの出力のたびに呼び出されます。

bool libraryInitializeWithKey(const char* session_key) は、library に関連付けられている MATLAB Runtime インスタンスを作成します。16 進数でエンコードされた 64 バイトの AES 復号化キーを指定できます。この構文を使用すると、実行時にユーザーが MEX ローダーの代わりに C++ API を使用して復号化キーを提供できます。詳細については、mcc -k を参照してください。

bool libraryInitializeWithHandlersAndKey(mclOutputHandlerFcn error_handler, mclOutputHandlerFcn print_handler, const char* session_key) は、library に関連付けられている MATLAB Runtime インスタンスを作成します。エラー ハンドラー、出力ハンドラー、および 16 進数でエンコードされた AES 復号化キーを指定できます。

すべて折りたたむ

libtriangle という名前の C/C++ ライブラリに関連付けられている MATLAB Runtime インスタンスを初期化します。

C アプリケーション コードの main 関数で C ライブラリ libtriangle の初期化関数を呼び出します。

if (!libtriangleInitialize())
{
    fprintf(stderr, 
            "An error occurred while initializing: \n %s ",
            mclGetLastErrorMessage());
    return -2;
}

初期化に失敗すると、エラー メッセージが標準エラーに出力されます。

既定では、MATLAB Compiler SDK™ を使用して生成されたアプリケーションおよび共有ライブラリは、出力内容を標準出力に送信し、エラー メッセージを標準エラーに送信します。この動作を変更するには、独自のエラー ハンドラーと出力ハンドラーを記述し、それらを libraryInitializeWithHandlers に渡します。既定のハンドラーを使用するには、mclDefaultPrintHandler または mclDefaultPrintHandler を渡します。

詳細な例については、matlabroot\extern\examples\compilersdk\c_cpp\catcherror にあるファイルを参照してください。

C/C++ アプリケーションでカスタムの出力ハンドラー関数を記述します。このコード例は C で記述したものです。2 つの補助関数 StartMatlabOutputEndMatlabOutput を使用して出力内容をバナーでラップしています。

static int PrintHandler(const char *s)
{
    /* Declare and initialize all variables */
    int len = 0;
    const char * prefix = "* ";
    int written = 0;

    if (s == NULL)
    {
        return 0;
    }

    len = strlen(s);

    /* DISP adds two carriage returns. Suppress the last one. */
    if (len >= 2 && s[len-1] == '\n' && s[len-2] == '\n')
    {
        len = len-1;
    }
    
    if (emitPrefix)
    {
        fwrite(prefix, sizeof(char), strlen(prefix), stdout);
    }
    
    written = fwrite(s, sizeof(char), len, stdout);

    if (s[len-1] == '\n')
    {
        emitPrefix = true;
    }
    else
    {
        emitPrefix = false;
    }

    return written;
}

static void StartMatlabOutput()
{
    const char *startBanner = "******** Start MATLAB output *******\n";
    emitPrefix = false;
    PrintHandler(startBanner);
}

static void EndMatlabOutput()
{
    const char *endBanner = "********* End MATLAB output ********\n";
    emitPrefix = false;
    PrintHandler(endBanner);
}

カスタムのエラー ハンドラー関数を記述します。

static char LastError[2048];

static int ErrorHandler(const char *s)
{
    int len = 0;
    len = strlen(s);
    LastError[0] = '\0';
    strcpy(LastError, s);
    return len+1;
}

main 関数で、変数を初期化した後、関数 libraryInitializeWithHandlers に出力ハンドラーとエラー ハンドラーを渡します。

if (!libcatcherrorInitializeWithHandlers(ErrorHandler, PrintHandler))
{
    fprintf(stderr,"Could not initialize the library.\n");
    return -2;
}
else
{
    /* Call the library function. */
    if (mlfRealacos(1, &out, in1))
    {
        /* Display the return value of the library function */
        printf("realacos(%6.4f) = \n", in1val);
        StartMatlabOutput();
        mlfReveal(out);
        EndMatlabOutput();
    }
    else
    {
        printf("Disaster! An unexpected error occurred.\n");
        printf("Error:\n%s\n", LastError);
    }

    /* Call the library termination routine */
    libcatcherrorTerminate();
        
    /* Free the memory allocated for the input variables. */
    mxDestroyArray(in1); 
    in1 = 0;
    mxDestroyArray(in2); 
    in2 = 0;
}

コンパイル時に MEX ローダー ファイルを提供する代わりに、関数 libraryInitializeWithKey を使用して C++ アプリケーションで復号化キーを指定できます。

AES 暗号化キーを取得します。たとえば、コマンド ラインで openssl を使用してキーを生成できます。

openssl rand -hex 64 -out appkey.key

mcc を使用して C++ 共有ライブラリを作成します。生成した復号化キーを -k オプションを使用して指定します。詳細については、mcc -k を参照してください。

 mcc -W cpplib:libappwithkey appwithkey.m -k 'file=appkey.key'

C++ アプリケーションの main 関数で、復号化キーを取得します。たとえば、AWS® CloudHSM クラスターからキーを取得できます。16 進数でエンコードされたキーを初期化関数 libappwithkeyInitializeWithKey の引数として渡します。

if (!mclInitializeApplication(NULL, 0))
    {
        printf("Failed to initialize application.\n");
        return -1;
    }

    /* Retrieve the decryption key. */
    ...
    
    if (!libappwithkeyInitializeWithKey(“<key_value>”)) 
    {
        printf("Failed to initialize libappwithkey.\n");
        return -2;
    }
else
{
    /* Call the library function. */
    ...
}

初期化に失敗すると、エラー メッセージが標準エラーに出力されます。

入力引数

すべて折りたたむ

ライブラリ名。関数名の一部として指定します。ライブラリは、MATLAB Compiler SDK で生成された C/C++ 共有ライブラリでなければなりません。

例: libmatrix

エラー ハンドラー関数。カスタムのユーザー記述関数または mclDefaultErrorHandler として指定します。関数は文字列を受け取り、出力される文字数を返さなければなりません。詳細については、Print and Error Handling Functionsを参照してください。

例: myErrorHandler

出力ハンドラー関数。カスタムのユーザー記述関数または mclDefaultPrintHandler として指定します。関数は文字列を受け取り、出力される文字数を返さなければなりません。標準エラー出力ストリームに送信される文字列の最後にキャリッジ リターンがない場合、関数で追加する必要があります。詳細については、Print and Error Handling Functionsを参照してください。

例: myPrintHandler

AES 復号化キー。64 文字のファイル サイズの 16 進数でエンコードされた AES キーとして指定します。

詳細については、mcc -k を参照してください。

例: mykey.txt

出力引数

すべて折りたたむ

初期化結果。ブール値として返されます。結果は mcli の初期化が正常に行われたかどうかを示します。関数が false を返す場合、コンパイルされた関数を呼び出すと、予期しない動作が発生することがあります。

バージョン履歴

R2009a で導入