Data Delivery C API

Data Delivery C APIは、ICE Coreとデバイスやエッジアプリケーションの間の通信機能を提供します。APIはデバイスアダプタ向けAPI、エッジアプリケーション向けAPI、共通APIの3つに分類されます。

デバイスアダプタ向け提供機能

Data Delivery C APIでは、デバイスアダプタ向けに以下の機能を提供します。

初期化(ddca_devadpt_init API)

デバイスアダプタの初期化処理を行い、ICE Coreに接続します。また、デバイスアダプタプロファイルのデータをICE Coreに送信し、バックエンドのデータベースに登録します。

終了(ddca_devadpt_destroy API)

デバイスアダプタの終了処理を行い、ICE Coreから切断します。この機能は、デバイスアダプタをICE Coreからのシグナル受信ではなく、自発的に終了する場合に使用します。

デバイスの登録(ddca_devapdt_register_device, ddca_devadpt_register_multi_devices API)

デバイスに対応するデバイスプロファイルの情報をICE Coreに送信し、デバイスを登録します。デバイスの登録が完了するとデバイスIDが払い出されます。このデバイスIDは以降のデータ送信で 使用します。
デバイスの登録は以下のパターンがあります。
デバイスごとにデバイスプロファイルを用意し、順番に1つずつ登録を行なっていくパターン
 複数のデバイスで共通のデバイスプロファイルを用意し、1度にまとめて登録するパターン

これらのパターンはデバイスの数が単体か複数かやデバイスプロファイルの内容がデバイス固有か共通かどうかで使い分けます。

デバイスの登録制限

1つのデバイスアダプタプロセスで登録できるデバイス数の最大値は255です。この上限は環境変数ICE_DEVICE_MAXを定義することで、その値から1を引いた値に変更できます。また、デバイスの登録処理はデバイスアダプタのプロセス内でデバイスアダプタプロファイル、デバイスプロファイルの組み合わせ単位で1回となります。

データの送信(ddca_devadpt_emit, ddca_devadpt_emit_with_data_type API)

センサーデータをICE Coreに送信します。送信データにデバイスIDを紐付けることで、デバイス登録時のデバイスプロファイルの情報からdata_typeを引用し、送信データに付与します。これにより、データを受信した他のアプリケーションやバックエンドの処理でdata_typeごとに処理を分けることができます。また、任意のdata_typeを指定して送信することもできます。

送信データサイズの制限

ICE Coreに送信するデータの最大サイズは999.5KBです。これより大きなサイズのデータを送信する場合は、送信データを分割して送信してください。

メッセージ受信処理の登録(ddca_devadpt_register_operation_cb API)

Backend APIからメッセージが送信されたときに呼び出す処理(関数)を登録します。この機能を有効にするには、メッセージの待受開始機能(ddca_devadpt_start API)を呼び出す必要があります。ここで登録した処理はトポロジ定義によらず呼び出されます。
メッセージ受信処理にはバックエンドからのメッセージが後述のイベント形式で渡されるので、その内容に従ってデバイスの読み込み、書き込み、動作といった対応する処理を行います。そのほかop_idにはオペレーションごとに一意のidが, sinkには送信先のデバイスIDが(デバイスアダプタ宛の場合は空文字)、op_typeにはBackend APIで設定したオペレーションタイプが設定されています。これらの変数にはevent API(ddca_event_gte_op_id, ddca_event_get_sink, ddca_event_get_op_type)を通じてアクセス可能です。また、メッセージ受信処理ではトポロジ定義に従って処理結果を送信でき、送信時にはevent API(ddca_event_set_op_id)で送信データにop_idを紐付けることができます。これにより、データ受信側でオペレーションに紐付いたデータかどうかを判別できます。
メッセージの受信処理はC APIが管理するスレッド上で行われます。mainスレッドでそれ以上処理を行わない動作モデルの場合は、コールバック受け入れ動作の待ち合わせ機能(ddca_devadpt_join API)を呼び出してmainスレッドでの処理を停止します。

メッセージの受信応答(ddca_devadpt_respond API)

メッセージ受信処理でバックエンドにメッセージの受信をtrue/falseで応答することができます。この応答はメッセージに割り当てられたオペレーションIDに紐付いてバックエンドのデータベースに格納されます。処理結果を返さないコールバック処理での受信応答や、完了まで時間がかかるコールバック処理の一次応答として利用できます。
この応答は1メッセージにつき一度だけ行えます。

コールバック受け入れの開始(ddca_devadpt_start)

ICE Coreからの処理要求の受け入れを開始します。この処理を呼び出してから停止を呼び出すまでの間は、上記のコールバック処理が呼び出されるようになります。それ以外の間はICE Coreからの呼び出しを無視します。

コールバック受け入れの停止(ddca_devadpt_stop)

ICE Coreからの処理要求の受け入れを停止します。

コールバック受け入れ動作の終了待ち合わせ(ddca_devadpt_join)

現在のスレッドをICE Coreからの処理要求の受け入れ動作の終了まで待ち合わせます。この処理を呼び出してから受け入れ動作の終了まで、このスレッドは処理がブロックされます(スレッドのjoin動作)。

プロファイルの更新(ddca_devadpt_get_profile, ddca_devadpt_update_profile API)

デバイスアダプタの初期化、またはデバイス登録でバックエンドに通知したプロファイルのインスタンスを更新し、バックエンドへ再通知することができます。この機能により、デバイスアダプタの起動後に動的に決まる情報や状況により変動するような情報をバックエンドへタイムリーに通知することができます。
プロファイルの更新はプロファイルインスタンスの取得、取得したプロファイルインスタンスの更新、プロファイルインスタンスの再通知の3ステップで構成されます。 1. ddca_devadpt_get_profile APIの引数に空文字を渡すと初期化処理でバックエンドへ通知したデバイスアダプタプロファイル、デバイスIDを渡すとデバイス登録時にバックエンドへ通知したデバイスプロファイルのインスタンスが取得できます。 1. 得られたプロファイルインスタンスに対してevent APIで要素の追加、削除、変更を行います。 1. ddca_devadpt_update_profile APIで再通知を行います。引数に更新したプロファイルインスタンスと対応するデバイスIDを指定します。デバイスIDに空文字を指定するとデバイスアダプタの指定を意味します。

プロファイルサイズの制限

デバイスアダプタでは、更新するプロファイルの合計サイズに999.5KB未満の制限があります。

エッジアプリケーション

概要

エッジアプリケーションは、エッジゲートウェイ上で動作しC APIを使って固有の処理を行い、ICE Coreとメッセージのやりとりを行うアプリケーションです。エッジアプリケーションにより、他システムとの連携やメッセージの中間処理を行うことができます。

エッジアプリケーションの概要

プロセス起動/停止

エッジアプリケーションはICE Coreの起動時に自動で起動し、ICE Coreの停止時にシグナルを受け取って停止します。

エッジアプリケーションの処理の流れ

エッジアプリケーションは以下のいずれかの動作モデルを取ります。主にmainスレッドでICE Coreへデータの送信を行い、C APIが管理する受信スレッドでバックエンドやICE Coreからのメッセージを受信して対応するコールバック関数を呼び出します。

データをバックエンドに送信するモデル

  • mainスレッド
    1. エッジアプリケーションの初期化
    2. データの準備(エッジアプリケーション固有の処理)
    3. ICE Coreへデータの送信
    4. 2, 3を繰り返す
    5. (シグナル受信ではなく自発的に終了する場合)エッジアプリケーションの終了

バックエンドからメッセージを受けて動作するモデル

  • mainスレッド

    1. エッジアプリケーションの初期化
    2. メッセージ、イベント受信処理の登録
    3. メッセージ、イベント受信の開始
    4. メッセージ、イベント受信動作の終了待ち合わせ

  • C API管理の受信スレッド

    1. メッセージ、イベントの受信(随時)
      1. メッセージ、イベントに対応する処理の実行
      2. メッセージ、イベントの受信応答の送信
      3. 追加のデータ送信

データをバックエンドに送信し、バックエンドからメッセージを受ける動作モデル

  • mainスレッド

    1. エッジアプリケーションの初期化
    2. メッセージ、イベント受信処理の登録
    3. メッセージ、イベント受信の開始
    4. データの準備(エッジアプリケーション固有の処理)
    5. ICE Coreへデータの送信
    6. 4, 5を繰り返す
    7. (シグナル受信ではなく自発的に終了する場合)エッジアプリケーションの終了

  • C API管理の受信スレッド

    1. メッセージ、イベントの受信(随時)
      1. メッセージ、イベントに対応する処理の実行
      2. メッセージ、イベントの受信応答の送信
      3. 追加のデータ送信

提供機能

Data Delivery C APIでは、エッジアプリケーション向けに以下の機能を提供します。

初期化(ddca_edgeap_init API)

エッジアプリケーションの初期化処理を行なって、エッジアプリケーションをICE Coreに接続します。また、エッジAPプロファイルのデータをICE Coreへ送信し、バックエンドのデータベースに登録します。

終了(ddca_edgeap_destroy API)

エッジアプリケーションをICE Coreから切断します。この機能は、エッジアプリケーションをICE Coreからのシグナル受信ではなく、自発的に終了する場合に使用します。

データ送信(ddca_edgeap_emit, ddca_edgeap_emit_with_data_type API)

データをICE Coreに送信します。送信データにエッジAPプロファイルの情報からdata_typeを引用し、送信データに付与します。これにより、データを受信した他のアプリケーションやバックエンドの処理でdata_typeごとに処理を分けることができます。また、任意のdata_typeを指定して送信することもできます。

送信データサイズの制限

ICE Coreに送信するデータの最大サイズは999.5KBです。これより大きなサイズのデータを送信する場合は、送信データを分割して送信してください。

イベント受信処理の登録(ddca_edgeap_register_event_cb API)

ICE Coreからの要求で呼び出すエッジアプリケーションの処理(関数)を登録します。この機能を有効にするには、メッセージの待受開始機能(ddca_devadpt_start API)を呼び出す必要があります。この処理はICE Coreのトポロジ定義に従って、中間処理(flow)や終端処理(sink)で呼び出されます。引数には後述するイベント形式で呼び出し元からデータが渡されます。
コールバック処理のタイプには特化処理、フィルタ、変形処理、汎用をそれぞれ表すprocess, filter, transform, eventがあり、エッジアプリケーションの処理内容に応じて1つのタイプを選択してコールバック関数を登録します。
processコールバックは引数に2つのevent変数をとり、それぞれが入力と出力に相当します。processコールバックがDDCA_SUCCESSで終了すると、C APIは自動で出力に相当するevent変数をICE Coreに送信します。
filterコールバックは引数に1つのevent変数をとり、フィルタした結果をDDCA_TRUEかそれ以外の値を返却することで伝えます。C APIはfilterコールバックがDDCA_TRUEを返却すると、そのevent変数をICE Coreに自動で送信します。
transformコールバックは引数に1つのevent変数をとり、それが入力と出力を兼ねます。transformコールバックがDDCA_SUCCESSで終了すると、C APIは自動で引数で渡したevent変数をICE Coreに送信します。
eventコールバックは他のコールバックの汎用型で、引数に1つのevent変数をとり、それが入力となります。eventコールバックは他のコールバックと異なりevent変数をICE Coreに自動送信しないので、データを送信する場合は必要に応じてコールバック処理内で行います。
イベントの受信処理はC APIが管理するスレッド上で行われます。mainスレッドでそれ以上処理を行わない動作モデルの場合は、コールバック受け入れ動作の待ち合わせ機能(ddca_edgeap_join API)を呼び出してmainスレッドでの処理を停止します。

他のAPから受け取ったデータの加工結果の送信

イベントの受信処理から送信するデータには、処理結果のデータのほかに受信処理の引数で受け取ったデータの以下の情報を含むことができます。要件に応じて送信データに再設定を行います。 * op_id * source(device_id) * data_type

イベント受信処理の登録の動作

4つのコールバック関数(process, filter, transform, event)のうち、1つのエッジアプリケーションに登録できるコールバック関数は1つだけに制限されます。すでにコールバック関数が登録されている状態で他のコールバック関数の登録処理が呼ばれると、エラーになります。

メッセージ受信処理の登録(ddca_edegap_register_operation_cb API)

Backend APIからメッセージが送信されたときに呼び出す処理(関数)を登録します。この機能を有効にするには、メッセージの待受開始機能(ddca_devadpt_start API)を呼び出す必要があります。ここで登録した処理はトポロジ定義によらず呼び出されます。
メッセージ受信処理にはバックエンドからのメッセージが後述のイベント形式で渡されるので、その内容に従ってエッジアプリケーション固有の処理を行います。そのほかop_idにはオペレーションごとに一意のidが, op_typeにはBackend APIで設定したオペレーションタイプが設定されています。これらの変数にはevent API(ddca_event_gte_op_id, ddca_event_get_op_type)を通じてアクセス可能です。また、メッセージ受信処理ではトポロジ定義に従って処理結果を送信でき、送信時にはevent API(ddca_event_set_op_id)で送信データにop_idを紐付けることができます。これにより、データ受信側でオペレーションに紐付いたデータかどうかを判別できます。
メッセージの受信処理はC APIが管理するスレッド上で行われます。mainスレッドでそれ以上処理を行わない動作モデルの場合は、メッセージの待受機能(ddca_edgeap_join API)を呼び出してmainスレッドでの処理を停止します。

メッセージの受信応答(ddca_edgeap_respond API)

メッセージ受信処理でバックエンドにメッセージの受信をtrue/falseで応答することができます。この応答はメッセージに割り当てられたオペレーションIDに紐付いてバックエンドのデータベースに格納されます。処理結果を返さないコールバック処理での受信応答や、完了まで時間がかかるコールバック処理の一次応答として利用できます。
この応答は1メッセージにつき一度だけ行えます。

コールバック受け入れの開始(ddca_edgeap_start API)

ICE Coreからの処理要求の受け入れを開始します。この処理を呼び出してから停止を呼び出すまでの間は、上記のコールバック処理が呼び出されるようになります。それ以外の間はICE Coreからの呼び出しを無視します。

コールバック受け入れの停止(ddca_edgeap_stop API)

ICE Coreからの処理要求の受け入れを停止します。

コールバック受け入れ動作の終了待ち合わせ(ddca_edgeap_join API)

現在のスレッドをICE Coreからの処理要求の受け入れ動作の終了まで待ち合わせます。この処理を呼び出してから受け入れ動作の終了まで、このスレッドは処理がブロックされます(スレッドのjoin動作)。

プロファイルの更新(ddca_edgeap_get_profile, ddca_edgeap_update_profile API)

エッジアプリケーションの初期化でバックエンドに通知したプロファイルのインスタンスを更新し、バックエンドへ再通知することができます。この機能により、エッジアプリケーションの起動後に動的に決まる情報や状況により変動するような情報をバックエンドへタイムリーに通知することができます。
プロファイルの更新はプロファイルインスタンスの取得、取得したプロファイルインスタンスの更新、プロファイルインスタンスの再通知の3ステップで構成されます。 1. ddca_edgeap_get_profile APIで初期化処理でバックエンドへ通知したエッジAPプロファイルが取得できます。 1. 得られたプロファイルインスタンスに対してevent APIで要素の追加、削除、変更を行います。 1. ddca_edgeap_update_profile APIで再通知を行います。

プロファイルサイズの制限

エッジアプリケーションでは、更新するプロファイルの合計サイズに999.5KB未満の制限があります。

設定ファイル

エッジAPプロファイル

エッジAPプロファイルは、エッジアプリケーションの設定ファイルです。エッジアプリケーションの名前や作成者、バージョン、ICE Coreに送信するデータの構成名(data_type)、のほか、エッジアプリケーションが参照する外部設定などの情報を記述します。
エッジAPプロファイルではVendor, Product, Version, data_typeは必須項目です。ICEではdata_type以外の項目の有無をチェックしませんが、エッジアプリケーションの区別のために定義されていることが望ましいです。

例)エッジAPプロファイルの例

    {
        "Vendor": "エッジアプリケーションプログラム開発会社",
        "Product": "エッジアプリケーションプログラム名",
        "Version": "エッジアプリケーションプログラムバージョン",
        "data_type": "エッジアプリケーションが送信するデータのタイプ"
    }
エッジAPプロファイルの制限

エッジAPプロファイルの最大サイズ(空白、改行を除く)は999.5KBです。

共通機能

提供機能

Data Delivery C APIでは、デバイスダプタ、エッジアプリケーション向けの機能のほか、以下の共通機能を提供します。これらの機能はデバイスアダプタ、エッジアプリケーションのAPIと共に使用します。

イベントと操作API

イベントとは、デバイスアダプタ、エッジアプリケーションとICE Coreの間を流れるデータのことを言い、デバイスから取得したセンサーデータやICE Coreからの指示など、すべてのメッセージがイベントとして表されます。
デバイスアダプタやエッジアプリケーションでは、ddca_event_createでイベント変数を作成し、event APIで値の追加・削除・参照を行なった後データ送信機能でICE Coreに送信し、その後ddca_event_destroyでメモリを解放します。

メモリ解放対象のイベント

プログラム中にddca_event_createしたイベント変数は必ずddca_event_destroyで解放してください。ただしコールバック関数で渡されるevent変数など、プログラム中でcreateしていないevent変数は解放する必要はありません。

プロファイルと操作API

プロファイルとは、デバイスアダプタ、エッジアプリケーションの設定データです。各設定データは、ファイルからロードされると、このプロファイルとして表されます。プロファイル操作のAPIでは、値の取得や追加、削除が行えます。

プロファイルの生存期間

ロードされたプロファイルはアプリケーションプロセスの終了までメモリ上に存在します。そのためアプリケーションプロセスでプロファイルをロードする回数は必要最小限の有限回数にしてください。

階層構造、配列と操作API

イベントとプロファイルでは、数値や文字列といった値のほか、階層構造と配列を扱うことができます。階層構造はその中に更に数値、文字列、階層構造を含むことができ、これにより複雑な構成のデータを表現できます。配列はその中に複数の値を非整列で格納できます。階層構造と配列操作のAPIでは、階層の取得や追加、削除が行えます。

共通仕様

Data Delivery C APIでは、デバイスダプタ、エッジアプリケーションおよび共通機能について、以下の共通仕様があります。

デバッグメッセージ出力機能

環境変数にDDCA_DEBUG(値は不問)を設定すると、C APIが標準出力へ内部処理メッセージを出力するようになります。この機能により、エッジゲートウェイで障害発生時に動作情報を記録し、障害原因の切り分けに活用します。主にテストでC APIの内部動作を確認するために使用します。標準出力に大量のメッセージを出力するので、ファイル保存時にはディスクの圧迫にご注意ください。

コールバック関数の処理制限

デバイスアダプタまたはエッジアプリケーションのコールバック関数内で時間のかかる処理を行うと、その間次の受信処理が行われません。コールバック関数内で長時間の処理を行う場合は、新たにスレッドを作成してそちらで処理を行うようにしてください。このときスレッドには、処理に使うデータ以外に以下の情報を渡してください。

  • object_id
    デバイスアダプタのコールバック関数から作成したスレッド内でemitする場合に必要です。 エッジアプリケーションのコールバック関数から作成したスレッドでは不要です。
  • op_id
    コールバック関数で作成したスレッド内からバックエンドへ送信するデータが、バックエンドからのオペレーション指示に紐付いた情報であることを共通のop_idを使って示したい場合に使用します。そうでなければ不要です。
    コールバック関数の呼び出しで渡されたeventからddca_event_get_op_idで取得し、ddca_event_createで生成したeventにddca_event_set_op_idで使用します。
    コールバック関数の呼び出し経路がオペレーションに紐付かない場合はop_idがNULLとなる点に注意してください。
  • source
    デバイスアダプタからエッジアプリケーションにイベントを渡すトポロジ定義を使用しており、デバイスアダプタから受け取ったイベントのデバイスIDをエッジアプリケーションのコールバック関数で作成したスレッドから送信するデータに含めたい場合に使用します。そうでなければ不要です。
    コールバック関数の呼び出しで渡されたeventからddca_event_get_sourceで取得し、ddca_event_createの第一引数に設定します。
    その他の場合sourceの値はNULLになる点に注意してください。
  • data_type
    エッジアプリケーションプロファイルに記載したdata_typeではなく、コールバックで受け取ったeventのdata_typeを返信するeventに設定したい場合に使用します。そうでなければ不要です。
    コールバック関数の呼び出しで渡されたeventからddca_event_get_data_typeでdata_typeを取得し、ddca_event_createで生成したeventにddca_event_set_data_typeでdata_typeを設定します。その後ddca_edgeap_emit_with_data_typeでデータ送信を行います。

アプリケーションの配置

デバイスアダプタやエッジアプリケーションなどC APIを使用するアプリケーションは、以下のディレクトリにアプリケーションごとにディレクトリ(アプリケーション名)を作成して配置します。

{ICE_HOME}/native/user/配下

アプリケーション名の最大長

アプリケーション名(アプリケーションディレクトリ名)の最大長は70文字です。ICE Coreを既定値と異なる場所にインストールした場合は、coreディレクトリ({ICE_HOME)までの絶対パスの長さとアプリケーション名の長さの合計が95文字以下である必要があります。

プロファイルの使用可能文字

デバイスアダプタプロファイル、デバイスプロファイル、エッジAPプロファイルで使用できる文字は英数字(a-zA-Z0-9)、アンダーバー(_)、ドット(.)です。