6.8. ICE Data Delivery C API¶
Data Delivery C APIは、ICE Coreとデバイスやエッジアプリケーションの間の通信機能を提供します。APIはデバイスアダプタ向けAPI、エッジアプリケーション向けAPI、共通APIの3つに分類されます。
6.8.1. デバイスアダプタ向け提供機能¶
Data Delivery C APIでは、デバイスアダプタ向けに以下の機能を提供します。
6.8.1.1. 初期化(ddca_devadpt_init API)¶
デバイスアダプタの初期化処理を行い、ICE Coreに接続します。また、デバイスアダプタプロファイルのデータをICE Coreに送信し、バックエンドのデータベースに登録します。
6.8.1.2. 終了(ddca_devadpt_destroy API)¶
デバイスアダプタの終了処理を行い、ICE Coreから切断します。この機能は、デバイスアダプタをICE Coreからのシグナル受信ではなく、自発的に終了する場合に使用します。
6.8.1.3. デバイスの登録(ddca_devapdt_register_device, ddca_devadpt_register_multi_devices API)¶
- デバイスごとにデバイスプロファイルを用意し、順番に1つずつ登録を行なっていくパターン
- 複数のデバイスで共通のデバイスプロファイルを用意し、1度にまとめて登録するパターン
これらのパターンはデバイスの数が単体か複数かやデバイスプロファイルの内容がデバイス固有か共通かどうかで使い分けます。
6.8.1.3.1. デバイスの登録制限¶
1つのデバイスアダプタプロセスで登録できるデバイス数の最大値は255です。この上限は環境変数ICE_DEVICE_MAXを定義することで、その値から1を引いた値に変更できます。また、デバイスの登録処理はデバイスアダプタのプロセス内でデバイスアダプタプロファイル、デバイスプロファイルの組み合わせ単位で1回となります。
6.8.1.4. データの送信(ddca_devadpt_emit, ddca_devadpt_emit_with_data_type API)¶
センサーデータをICE Coreに送信します。送信データにデバイスIDを紐付けることで、デバイス登録時のデバイスプロファイルの情報からdata_typeを引用し、送信データに付与します。これにより、データを受信した他のアプリケーションやバックエンドの処理でdata_typeごとに処理を分けることができます。また、任意のdata_typeを指定して送信することもできます。
6.8.1.4.1. 送信データサイズの制限¶
ICE Coreに送信するデータの最大サイズは999.5KBです。これより大きなサイズのデータを送信する場合は、送信データを分割して送信してください。
6.8.1.5. メッセージ受信処理の登録(ddca_devadpt_register_operation_cb API)¶
6.8.1.6. メッセージの受信応答(ddca_devadpt_respond API)¶
6.8.1.7. コールバック受け入れの開始(ddca_devadpt_start)¶
ICE Coreからの処理要求の受け入れを開始します。この処理を呼び出してから停止を呼び出すまでの間は、上記のコールバック処理が呼び出されるようになります。それ以外の間はICE Coreからの呼び出しを無視します。
6.8.1.8. コールバック受け入れの停止(ddca_devadpt_stop)¶
ICE Coreからの処理要求の受け入れを停止します。
6.8.1.9. コールバック受け入れ動作の終了待ち合わせ(ddca_devadpt_join)¶
現在のスレッドをICE Coreからの処理要求の受け入れ動作の終了まで待ち合わせます。この処理を呼び出してから受け入れ動作の終了まで、このスレッドは処理がブロックされます(スレッドのjoin動作)。
6.8.1.10. プロファイルの更新(ddca_devadpt_get_profile, ddca_devadpt_update_profile API)¶
- ddca_devadpt_get_profile APIの引数に空文字を渡すと初期化処理でバックエンドへ通知したデバイスアダプタプロファイル、デバイスIDを渡すとデバイス登録時にバックエンドへ通知したデバイスプロファイルのインスタンスが取得できます。
- 得られたプロファイルインスタンスに対してevent APIで要素の追加、削除、変更を行います。
- ddca_devadpt_update_profile APIで再通知を行います。引数に更新したプロファイルインスタンスと対応するデバイスIDを指定します。デバイスIDに空文字を指定するとデバイスアダプタの指定を意味します。
6.8.1.10.1. プロファイルサイズの制限¶
デバイスアダプタでは、更新するプロファイルの合計サイズに999.5KB未満の制限があります。
6.8.2. エッジアプリケーション¶
6.8.2.1. 概要¶
エッジアプリケーションは、エッジゲートウェイ上で動作しC APIを使って固有の処理を行い、ICE Coreとメッセージのやりとりを行うアプリケーションです。エッジアプリケーションにより、他システムとの連携やメッセージの中間処理を行うことができます。
6.8.2.2. プロセス起動/停止¶
エッジアプリケーションはICE Coreの起動時に自動で起動し、ICE Coreの停止時にシグナルを受け取って停止します。
6.8.2.3. エッジアプリケーションの処理の流れ¶
エッジアプリケーションは以下のいずれかの動作モデルを取ります。主にmainスレッドでICE Coreへデータの送信を行い、C APIが管理する受信スレッドでバックエンドやICE Coreからのメッセージを受信して対応するコールバック関数を呼び出します。
6.8.2.3.1. データをバックエンドに送信するモデル¶
- mainスレッド
- エッジアプリケーションの初期化
- データの準備(エッジアプリケーション固有の処理)
- ICE Coreへデータの送信
- 2, 3を繰り返す
- (シグナル受信ではなく自発的に終了する場合)エッジアプリケーションの終了
6.8.2.3.2. バックエンドからメッセージを受けて動作するモデル¶
- mainスレッド
- エッジアプリケーションの初期化
- メッセージ、イベント受信処理の登録
- メッセージ、イベント受信の開始
- メッセージ、イベント受信動作の終了待ち合わせ
- C API管理の受信スレッド
- メッセージ、イベントの受信(随時)
- メッセージ、イベントに対応する処理の実行
- メッセージ、イベントの受信応答の送信
- 追加のデータ送信
- メッセージ、イベントの受信(随時)
6.8.2.3.3. データをバックエンドに送信し、バックエンドからメッセージを受ける動作モデル¶
- mainスレッド
- エッジアプリケーションの初期化
- メッセージ、イベント受信処理の登録
- メッセージ、イベント受信の開始
- データの準備(エッジアプリケーション固有の処理)
- ICE Coreへデータの送信
- 4, 5を繰り返す
- (シグナル受信ではなく自発的に終了する場合)エッジアプリケーションの終了
- C API管理の受信スレッド
- メッセージ、イベントの受信(随時)
- メッセージ、イベントに対応する処理の実行
- メッセージ、イベントの受信応答の送信
- 追加のデータ送信
- メッセージ、イベントの受信(随時)
6.8.2.4. 提供機能¶
Data Delivery C APIでは、エッジアプリケーション向けに以下の機能を提供します。
6.8.2.4.1. 初期化(ddca_edgeap_init API)¶
エッジアプリケーションの初期化処理を行なって、エッジアプリケーションをICE Coreに接続します。また、エッジAPプロファイルのデータをICE Coreへ送信し、バックエンドのデータベースに登録します。
6.8.2.4.2. 終了(ddca_edgeap_destroy API)¶
エッジアプリケーションをICE Coreから切断します。この機能は、エッジアプリケーションをICE Coreからのシグナル受信ではなく、自発的に終了する場合に使用します。
6.8.2.4.3. データ送信(ddca_edgeap_emit, ddca_edgeap_emit_with_data_type API)¶
データをICE Coreに送信します。送信データにエッジAPプロファイルの情報からdata_typeを引用し、送信データに付与します。これにより、データを受信した他のアプリケーションやバックエンドの処理でdata_typeごとに処理を分けることができます。また、任意のdata_typeを指定して送信することもできます。
6.8.2.4.3.1. 送信データサイズの制限¶
ICE Coreに送信するデータの最大サイズは999.5KBです。これより大きなサイズのデータを送信する場合は、送信データを分割して送信してください。
6.8.2.4.4. イベント受信処理の登録(ddca_edgeap_register_event_cb API)¶
6.8.2.4.4.1. 他のAPから受け取ったデータの加工結果の送信¶
イベントの受信処理から送信するデータには、処理結果のデータのほかに受信処理の引数で受け取ったデータの以下の情報を含むことができます。要件に応じて送信データに再設定を行います。
- op_id
- source(device_id)
- data_type
6.8.2.4.4.2. イベント受信処理の登録の動作¶
4つのコールバック関数(process, filter, transform, event)のうち、1つのエッジアプリケーションに登録できるコールバック関数は1つだけに制限されます。すでにコールバック関数が登録されている状態で他のコールバック関数の登録処理が呼ばれると、エラーになります。
6.8.2.4.5. メッセージ受信処理の登録(ddca_edegap_register_operation_cb API)¶
6.8.2.4.6. メッセージの受信応答(ddca_edgeap_respond API)¶
6.8.2.4.7. コールバック受け入れの開始(ddca_edgeap_start API)¶
ICE Coreからの処理要求の受け入れを開始します。この処理を呼び出してから停止を呼び出すまでの間は、上記のコールバック処理が呼び出されるようになります。それ以外の間はICE Coreからの呼び出しを無視します。
6.8.2.4.8. コールバック受け入れの停止(ddca_edgeap_stop API)¶
ICE Coreからの処理要求の受け入れを停止します。
6.8.2.4.9. コールバック受け入れ動作の終了待ち合わせ(ddca_edgeap_join API)¶
現在のスレッドをICE Coreからの処理要求の受け入れ動作の終了まで待ち合わせます。この処理を呼び出してから受け入れ動作の終了まで、このスレッドは処理がブロックされます(スレッドのjoin動作)。
6.8.2.4.10. プロファイルの更新(ddca_edgeap_get_profile, ddca_edgeap_update_profile API)¶
- ddca_edgeap_get_profile APIで初期化処理でバックエンドへ通知したエッジAPプロファイルが取得できます。
- 得られたプロファイルインスタンスに対してevent APIで要素の追加、削除、変更を行います。
- ddca_edgeap_update_profile APIで再通知を行います。
6.8.2.4.10.1. プロファイルサイズの制限¶
エッジアプリケーションでは、更新するプロファイルの合計サイズに999.5KB未満の制限があります。
6.8.2.5. 設定ファイル¶
6.8.2.5.1. エッジAPプロファイル¶
例)エッジAPプロファイルの例
{
"Vendor": "エッジアプリケーションプログラム開発会社",
"Product": "エッジアプリケーションプログラム名",
"Version": "エッジアプリケーションプログラムバージョン",
"data_type": "エッジアプリケーションが送信するデータのタイプ"
}
6.8.2.5.1.1. エッジAPプロファイルの制限¶
エッジAPプロファイルの最大サイズ(空白、改行を除く)は999.5KBです。
6.8.3. 共通機能¶
6.8.3.1. 提供機能¶
Data Delivery C APIでは、デバイスダプタ、エッジアプリケーション向けの機能のほか、以下の共通機能を提供します。これらの機能はデバイスアダプタ、エッジアプリケーションのAPIと共に使用します。
6.8.3.1.1. イベントと操作API¶
6.8.3.1.1.1. メモリ解放対象のイベント¶
プログラム中にddca_event_createしたイベント変数は必ずddca_event_destroyで解放してください。ただしコールバック関数で渡されるevent変数など、プログラム中でcreateしていないevent変数は解放する必要はありません。
6.8.3.1.2. プロファイルと操作API¶
プロファイルとは、デバイスアダプタ、エッジアプリケーションの設定データです。各設定データは、ファイルからロードされると、このプロファイルとして表されます。プロファイル操作のAPIでは、値の取得や追加、削除が行えます。
6.8.3.1.2.1. プロファイルの生存期間¶
ロードされたプロファイルはアプリケーションプロセスの終了までメモリ上に存在します。そのためアプリケーションプロセスでプロファイルをロードする回数は必要最小限の有限回数にしてください。
6.8.3.1.3. 階層構造、配列と操作API¶
イベントとプロファイルでは、数値や文字列といった値のほか、階層構造と配列を扱うことができます。階層構造はその中に更に数値、文字列、階層構造を含むことができ、これにより複雑な構成のデータを表現できます。配列はその中に複数の値を非整列で格納できます。階層構造と配列操作のAPIでは、階層の取得や追加、削除が行えます。
6.8.3.2. 共通仕様¶
Data Delivery C APIでは、デバイスダプタ、エッジアプリケーションおよび共通機能について、以下の共通仕様があります。
6.8.3.2.1. デバッグメッセージ出力機能¶
環境変数にDDCA_DEBUG(値は不問)を設定すると、C APIが標準出力へ内部処理メッセージを出力するようになります。この機能により、エッジゲートウェイで障害発生時に動作情報を記録し、障害原因の切り分けに活用します。主にテストでC APIの内部動作を確認するために使用します。標準出力に大量のメッセージを出力するので、ファイル保存時にはディスクの圧迫にご注意ください。
6.8.3.2.2. コールバック関数の処理制限¶
デバイスアダプタまたはエッジアプリケーションのコールバック関数内で時間のかかる処理を行うと、その間次の受信処理が行われません。コールバック関数内で長時間の処理を行う場合は、新たにスレッドを作成してそちらで処理を行うようにしてください。このときスレッドには、処理に使うデータ以外に以下の情報を渡してください。
- 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でデータ送信を行います。
6.8.3.2.3. アプリケーションの配置¶
デバイスアダプタやエッジアプリケーションなどC APIを使用するアプリケーションは、ICE Coreのインストールディレクトリを<ICE_HOME>として、以下のディレクトリにアプリケーションごとにディレクトリ(アプリケーション名)を作成して配置します。
<ICE_HOME>/native/user/配下
6.8.3.2.3.1. エッジアプリケーションのアプリケーション名の最大長¶
エッジアプリケーションでは、アプリケーション名(アプリケーションディレクトリ名)の最大長は70文字です。ICE Coreを既定値と異なる場所にインストールした場合は、coreディレクトリ(<ICE_CORE>)までの絶対パスの長さとアプリケーション名の長さの合計が95文字以下である必要があります。
6.8.3.2.3.2. プロファイルの使用可能文字¶
デバイスアダプタプロファイル、デバイスプロファイル、エッジAPプロファイルで使用できる文字は英数字(a-zA-Z0-9)、アンダーバー(_)、ドット(.)です。