カスタムコンポーネントC-APIリファレンス
カスタムコンポーネントをC言語で開発する際のAPI仕様です。 カスタムコンポーネントの開発手順については下記を参照してください。
出力ポート関数#
hive_outport_create_column() … 新規カラム作成#
コンポーネントが収集したデータをSpeeDBee Synapseに登録するためのカラムのハンドルを取得する関数
定義
HIVE_OUTCOLUMN hive_outport_create_column(HIVE_COMPONENT component, int out_port_no, const char *name, HIVE_DATA_TYPE type, HIVE_COLUMN_OPTIONS opt)
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_COMPONENT component |
コンポーネントのインスタンス premain/main/postmainの関数引数に渡されたコンポーネントインスタンスをそのまま渡してください。 |
| 2 | int out_port_no |
カラムを作成するポート番号 OUTPORT1, OUTPORT2などのマクロ定数を指定します。通常はOUTPORT1だけを使用すればOKです。 |
| 3 | const char *name |
カラム名 作成するカラムの名前を指定します |
| 4 | HIVE_DATA_TYPE type |
データ型 作成するカラムの型を指定します |
| 5 | HIVE_COLUMN_OPTIONS opt |
カラムオプション 作成するカラムのオプションを指定します。詳細はHIVE_COLUMN_OPTIONSを参照してください。 |
戻り値
- カラムハンドル
HIVE_OUTCOLUMN: カラムを扱うハンドル。のちにカラムにデータを登録したり、カラム設定を変更する際に使用します - NULL: カラムの作成に失敗
説明
コンポーネントが収集したデータをSpeeDBee Synapseに登録するためのカラムのハンドルを取得する関数です。
カラムにデータを登録する際にはこの関数が返したカラムハンドルを使用します。
カラム名には"/"は使用できません。その他の文字は使用可能ですが、ASCII以外の文字を使用する場合はUTF-8エンコードされている必要があります。また、カラム名は127バイトまでとしてください。
１つのコンポーネント内で同一のカラム名のカラムを取得した場合、最後に取得したカラムハンドルのみが有効となります。 そのため、本関数で同じカラム名のカラムハンドルを取得すれば、カラムの設定を変更できます。ただし事前に取得していたカラムハンドルは無効になりますので使用しないでください。
カラムのオプション指定についての詳細はHIVE_COLUMN_OPTIONSを参照してください。
hive_outport_register_confirmed_time() … ステータス情報へのカラムデータ確定時刻の登録#
出力ポートにカラムデータの確定時刻を登録する関数
定義
void hive_outport_register_confirmed_time(HIVE_COMPONENT component, int out_port_no, hive_time_t ts);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_COMPONENT component |
コンポーネントのインスタンス premain/main/postmainの関数引数に渡されたコンポーネントインスタンスをそのまま渡してください。 |
| 2 | int out_port_no |
登録対象の出力ポート番号 |
| 3 | hive_time_t ts |
登録する時刻 |
戻り値
なし
説明
出力ポートにカラムデータの確定時刻を登録します。
この情報が登録されることにより、このコンポーネントは、登録した時刻より前のデータはすべて登録が完了したことをフレームワークに伝えることができます。
これによりデータを受け取る側のコンポーネントの処理が最適化され、より少ない遅延でデータを扱うことができるようになります。
データを登録するコンポーネントでは、何らかのタイムスタンプのデータを登録した後で、今後それより前のタイムスタンプのデータを登録することがないことが確定したタイミングでその時刻を登録してください。
このAPIを使わずとも各種コンポーネントは動作可能ですが、データを受けとる側のコンポーネントでデータを受け取る際に多少の遅延が発生します。
逆に、このAPIであるタイムスタンプを登録した場合、そのタイムスタンプより前のタイムスタンプのデータを登録しないように注意が必要です。 登録してしまうと、そのデータを受け取るコンポーネントでデータを取りこぼす可能性があります。
出力カラム関数#
hive_outcolumn_insert() … データ登録#
カラムにデータを登録する関数
定義
bool hive_outcolumn_insert(HIVE_OUTCOLUMN column, const void *data);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_OUTCOLUMN column |
カラムハンドル hive_outport_create_column()で取得したカラムハンドルを指定します |
| 2 | void *data |
登録するデータへのポインタ |
戻り値
- true: 登録成功
- false: 登録失敗
説明
第一引数に指定したカラムに単一のデータを登録します。
第二引数dataには、登録するカラムのデータ型に合わせたメモリアドレスを指定する必要があります。
例
- uint16型のスカラの場合、2バイトのメモリ領域の先頭アドレス
- float型の5要素配列の場合、20バイトのメモリ領域の先頭アドレス
本関数で登録したデータのタイムスタンプは、本関数呼び出し時の現在時刻となります。時刻を指定する必要がある場合はhive_outcolumn_insert_ts()を使用してください。
hive_outcolumn_insert_ts() … タイムスタンプ指定データ登録#
カラムにタイムスタンプ指定のデータを登録する関数
定義
bool hive_outcolumn_insert_ts(HIVE_OUTCOLUMN column, const void *data, hive_time_t ts);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_OUTCOLUMN column |
カラムハンドル hive_outport_create_column()で取得したカラムハンドルを指定します |
| 2 | const void *data |
登録するデータへのポインタ |
| 3 | hive_time_t ts |
登録するデータのタイムスタンプ |
戻り値
- true: 登録成功
- false: 登録失敗
説明
第一引数、第二引数はhive_outcolumn_insert()と同様です。
第三引数tsにはタイムスタンプを指定してください。現在時刻のタイムスタンプはhive_timestamp()で取得できます。
本関数は、複数のカラムに対して同一のタイムスタンプでデータを登録するような場面での利用を想定しています。
使用例：同じタイムスタンプで複数カラムにデータを登録する
:
hive_time_t ts0 = hive_timestamp();
hive_outcolumn_insert_ts(clmA, dataA, ts0);
hive_outcolumn_insert_ts(clmB, dataB, ts0);
hive_outcolumn_insert_ts(clmC, dataC, ts0);
:
hive_outcolumn_insert()を使用した場合、clmA, clmB, clmCそれぞれで異なるタイムスタンプになってしまいます。
本システムでは、同一のカラムに登録するデータのタイムスタンプは、基本的に時系列順に登録する必要があります。
そのため、あるカラムに時刻T0のデータを登録したあとでT0より前のタイムスタンプのデータを同じカラムに登録することはできません。
hive_outcolumn_insert_binary() … バイナリ型データ登録#
BINARY型カラムに可変長バイナリデータを登録する関数
定義
bool hive_outcolumn_insert_binary(HIVE_OUTCOLUMN column, const void *data, size_t n);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_OUTCOLUMN column |
カラムハンドル hive_outport_create_column()で取得したカラムハンドルを指定します |
| 2 | const void *data |
登録するデータへのポインタ |
| 3 | size_t n |
登録するデータのバイト数 |
戻り値
- true: 登録成功
- false: 登録失敗
説明
BINARY型として作成されたカラムに対して任意長のデータを登録する関数です。
第一引数、第二引数はhive_outcolumn_insert()と同様です。第三引数nには、登録するデータのバイト数を指定してください。
本関数で登録したデータのタイムスタンプは、本関数呼び出し時の現在時刻となります。 時刻を指定する必要がある場合はhive_outcolumn_insert_binary_ts()を使用してください。
hive_outcolumn_insert_binary_ts() … タイムスタンプ指定バイナリ型データ登録#
BINARY型カラムに可変長バイナリデータをタイムスタンプ指定で登録する関数
定義
bool hive_outcolumn_insert_binary_ts(HIVE_OUTCOLUMN column, const void *data, size_t n, hive_time_t ts);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_OUTCOLUMN column |
カラムハンドル hive_outport_create_column()で取得したカラムハンドルを指定します |
| 2 | const void *data |
登録するデータへのポインタ |
| 3 | size_t n |
登録するデータのバイト数 |
| 4 | hive_time_t ts |
登録するデータのタイムスタンプ |
戻り値
- true: 登録成功
- false: 登録失敗
説明
第一引数、第二引数、第三引数はhive_outcolumn_insert_binary()と同様です。
第三引数tsにはタイムスタンプを指定してください。タイムスタンプについての注意事事項はhive_outcolumn_insert_ts()を参照してください。
hive_outcolumn_insert_multisamples() … 複数サンプルデータ登録#
１つのカラムに複数のタイムスタンプのデータを一括で登録する関数
定義
bool hive_outcolumn_insert_multisamples(HIVE_OUTCOLUMN column, const void *data, hive_time_t ts, int sample_count);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_OUTCOLUMN column |
カラムハンドル hive_outport_create_column()が返したカラムハンドルを指定します |
| 2 | const void *data |
登録するデータへのポインタ |
| 3 | hive_time_t ts |
登録するデータのタイムスタンプ |
| 4 | int sample_count |
登録するデータのサンプル数 |
戻り値
- true: 登録成功
- false: 登録失敗
説明
本関数はカラムオプションにてカラムタイプMIDDLEでサンプリングレートを指定した場合のみ使用できます。
第一、第二、第三引数はhive_outcolumn_insert_ts()と同様です。
第四引数sample_countには、登録するデータのサンプル数を指定してください。登録する複数のデータは、第二引数のdataが指すメモリ上に連続して配置されている必要があります。
使用例：連続する複数サンプルのデータを登録する
HIVE_COLUMN_OPTIONS opt = {
.type = column_type_middle,
.sampling_rate = 10;
};
HIVE_OUTCOLUMN clmA = hive_outport_create_column(compo, "clmA", HIVE_DATA_SCALAR(HIVE_TYPE_UINT16), opt)
uint16_t data[10] = {.}
:
get_data(data, 10);
hive_time_t ts0 = hive_timestamp();
hive_outcolumn_insert_multisamples(clmA, data, ts0, 10);
:
上記の例の場合、data[0]は指定したタイムスタンプts0で登録され、続くdata[1]は ts0 + 0.1秒, data[2]はts0 + 0.2秒として登録されます。
各タイムスタンプの間隔はopt.sampling_rateから算出されます。
hive_outcolumn_open_file() … ファイル作成#
ファイル型カラム用のファイルを作成する関数
定義
HIVE_FILE *hive_outcolumn_open_file(HIVE_OUTCOLUMN column);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_OUTCOLUMN column |
カラムハンドル hive_outport_create_column()が返したカラムハンドルを指定します |
戻り値
- HIVE_FILEポインタ
HIVE_FILE: 作成されたファイルポインタを持つHIVE_FILEのポインタ。 - NULL: ファイルの作成に失敗
説明
本関数はファイル型カラムへのデータ登録のためのファイルを作成し、そのファイルポインタを持つHIVE_FILEポインタを返します。
返されたHIVE_FILE内のファイルポインタを使用してファイルへ書き込みを行ってください。その後、hive_outcolumn_insert_file()を使用してカラムにファイルを登録できます。
使用例：ファイル作成とデータの書き込み
HIVE_OUTCOLUMN clmfile = hive_outport_create_column(comp, OUTPORT1, "clmfile", HIVE_DATA_SCALAR(HIVE_TYPE_FILE), HIVE_COLUMN_OPTION_NONE);
:
HIVE_FILE *hf = hive_outcolumn_open_file(clmfile);
if (hf == NULL) {
HIVE_API_ERROR error = hive_get_api_error();
HIVE_LOG_ERROR("hive_outcolumn_open_file error(0x%x,%d,%d)", error.code, error.system_errno, error.db_errno);
}
:
for (int i = 0; i < 10; i++) {
fprintf(hf->fp, "data: %d\n");
}
:
HIVE_FILE_METAINFO meta = {
.filename = "a",
.media_type = "text/plain",
.begin_timestamp = 1,
.end_timestamp = 2,
};
if (!hive_outcolumn_insert_file(hf, 0, &meta)) {
HIVE_API_ERROR error = hive_get_api_error();
HIVE_LOG_ERROR("hive_outcolumn_insert_file error(0x%x,%d,%d)", error.code, error.system_errno, error.db_errno);
}
本関数が返したHIVE_FILEポインタは、必ず hive_outcolumn_insert_file()かhive_outcolumn_dispose_file()を使用してリソースを解放してください。そうしない
場合、リソースが解放されずにメモリリークの原因となります。
hive_outcolumn_insert_file() … ファイル型データの登録#
ファイル型カラムにデータを登録する関数
定義
bool hive_outcolumn_insert_file(HIVE_FILE *hf, hive_time_t ts, const HIVE_FILE_METAINFO *meta);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_FILE *hf |
HIVE_FILEのポインタ hive_outcolumn_open_file()が返したHIVE_FILEポインタを指定します |
| 2 | hive_time_t ts |
登録するデータのタイムスタンプ |
| 3 | HIVE_FILE_METAINFO *meta |
登録するファイルのメタ情報 |
戻り値
- true: 登録成功
- false: 登録失敗
説明
本関数はファイル型カラムにデータを登録します。
第一引数hfにはhive_outcolumn_open_file()で作成したHIVE_FILEポインタを指定します。
第二引数tsにはタイムスタンプを指定してください。0が指定されると現在時刻で登録されます。
第三引数metaにはHIVE_FILE_METAINFOに登録するファイルのメタ情報を入れ、指定してください。
メタ情報は、このファイル型カラムのデータを受け取る側で参照されますが、不要ならNULL指定も可能です。
使用例はhive_outcolumn_open_file()を参照してください。
hive_outcolumn_dispose_file() … ファイル破棄#
ファイルを破棄する関数
定義
void hive_outcolumn_dispose_file(HIVE_FILE *hf);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_FILE *hf |
HIVE_FILEのポインタ hive_outcolumn_open_file()が返したHIVE_FILEポインタを指定します |
戻り値
なし
説明
本関数はhive_outcolumn_open_file()で作成したファイル型カラム用のファイルとHIVE_FILEを破棄します。
hive_outcolumn_open_file()でファイルをオープンしたものの、途中で不要となった場合には本関数を呼び出してファイルを破棄してください。
入力カラム関数#
hive_inport_get_column_list() … 入力カラム情報取得#
入力ポートのカラム情報を取得する
定義
const HIVE_INCOLUMN_LIST *hive_inport_get_column_list(HIVE_COMPONENT component, int inPortNo);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_COMPONENT component |
コンポーネントのインスタンス premain/main/postmainの関数引数に渡されたコンポーネントインスタンスをそのまま渡してください。 |
| 2 | int in_port_no |
入力ポート番号 |
戻り値
- HIVE_INCOLUMN_LIST: カラム情報のリスト
- NULL: メモリ不足等によりカラム情報が取得できない場合
説明
本関数は、指定した入力ポートに接続された、他のコンポーネントのカラム情報（コンポーネント名、カラム名、型など）を取得します。
戻り値として受け取った構造体のメモリはシステムが内部で管理しているため、変更、解放等行わないでください。また、他のhive_inport_xxxxAPIをコールすると内容が変化することがありますので、保存しておく必要がある場合は別のメモリ領域にコピーするなどの操作を行ってください。
hive_inport_continuous_reader() … カラムデータ継続検索用のReader取得#
入力ポートのカラムから継続的にデータを取得するためのReaderを取得する
定義
HIVE_CONTINUOUS_READER *hive_inport_continuous_reader(HIVE_COMPONENT component, int in_port_no, hive_time_t search_begin);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_COMPONENT component |
コンポーネントのインスタンス premain/main/postmainの関数引数に渡されたコンポーネントインスタンスをそのまま渡してください。 |
| 2 | int in_port_no |
入力ポート番号 |
| 3 | hive_time_t search_begin |
検索範囲開始時刻 |
戻り値
- HIVE_CONTINUOUS_READER: カラムデータ継続検索用のReader
説明
本関数は、指定した入力ポートに接続された、他のコンポーネントのカラムデータを継続して検索するためのReaderを取得します。
取得したReaderをhive_continuous_reader_read()で使用することでカラムデータを検索、取得することができます、戻り値として受け取った構造体のメモリはシステムが内部で管理しているため、変更、解放等行わないでください。
使用例：
HIVE_CONTINUOUS_READER *creader;
creader = hive_inport_continuous_reader(comp, INPORT1, hive_timestamp());
while (hive_component_runnable(comp)) {
const HIVE_COLUMN_READ_RESULT *read_result = hive_continuous_reader_read(creader);
if (!read_result) { continue; }
HIVE_RECORD_ITERATOR iter = HIVE_GET_RECORD_ITERATOR(read_result);
const HIVE_RECORD *record;
while ((record = HIVE_RECORD_ITERATOR_GET_NEXT(&iter)) != NULL)
{
for (int i=0; i < record->data_count; i++) {
const HIVE_RECORD_DATA *rd = HIVE_RECORD_GET_DATA(record, i);
if (!rd) { continue; }
const char *sourcename = read_result->incolumn_list->incolumns[i].source_component;
const char *dataname = read_result->incolumn_list->incolumns[i].data_name;
HIVE_DATA_TYPE type = read_result->incolumn_list->incolumns[i].data_type;
hive_aggregation_stat_type_t stat = read_result->incolumn_list->incolumns[i].stat_type;
const char *dptr = rd->data;
size_t size = rd->data_size;
process_record_data(sourcename, dataanme, type, stat_type, dptr, size);
}
}
}
hive_continuous_reader_release(creader);
hive_continuous_reader_read() … カラムデータ継続検索#
Readerで指定された入力ポートに接続されているカラムのデータを継続して検索、取得する
定義
const HIVE_COLUMN_READ_RESULT *hive_continuous_reader_read(HIVE_CONTINUOUS_READER *contReader);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_CONTINUOUS_READER *contReader |
hive_inport_continuous_reader()で取得したReader |
戻り値
- HIVE_COLUMN_READ_RESULT: カラムデータ検索結果
説明
本関数は、hive_inport_continuous_reader()で取得したReaderからカラムデータを取得します。
呼び出しを行うごとに検索時間が更新され、継続的にカラムデータを取得することができます。
戻り値として受け取った構造体のメモリはシステムが内部で管理しているため、変更、解放等行わないでください。
hive_continuous_reader_release() … カラムデータ継続検索用のReaderの解放#
hive_inport_continuous_reader()で取得したReaderを解放する
定義
const void hive_continuous_reader_release(HIVE_CONTINUOUS_READER *contReader);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_CONTINUOUS_READER *contReader |
hive_inport_continuous_reader()で取得したReader |
戻り値
なし
説明
本関数は、hive_inport_continuous_reader()で取得したReaderを解放します。
コンポーネントの処理中にReaderが不要となるなどの場合に呼び出してください。
hive_inport_timerange_reader() … カラムデータ時間範囲検索用のReader取得#
入力ポートのカラムから時間範囲を指定してデータを取得するためのReaderを取得する
定義
HIVE_TIMERANGE_READER *hive_inport_timerange_reader(HIVE_COMPONENT component, const HIVE_INCOLUMN *incolumn, hive_time_t searchBegin, hive_time_t searchEnd);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_COMPONENT component |
コンポーネントのインスタンス premain/main/postmainの関数引数に渡されたコンポーネントインスタンスをそのまま渡してください。 |
| 2 | HIVE_INCOLUMN *incolumn |
データ取得するカラム |
| 3 | hive_time_t search_begin |
検索範囲開始時刻 |
| 3 | hive_time_t search_end |
検索範囲終了時刻 |
戻り値
- HIVE_TIMERANGE_READER: カラムデータ時間範囲検索用のReader
説明
本関数は、指定したカラムのデータを時間範囲を指定して検索するためのReaderを取得します。
カラムを指定しない場合には入力ポートに接続された、他のコンポーネントのカラムすべてを検索対象とします。取得したReaderをhive_timerange_reader_read()で使用することでカラムデータを検索、取得することができます。
戻り値として受け取った構造体のメモリはシステムが内部で管理しているため、変更、解放等行わないでください。
使用例：
hive_time_t search_bigin_ts = hive_timestamp() - 2*HIVE_TIME_1S;
while (hive_component_runnable(comp)) {
HIVE_TIMERANGE_READER *reader = hive_inport_timerange_reader(comp, incolumn, search_bigin_ts, search_bigin_ts + 1*HIVE_TIME_1S);
const HIVE_COLUMN_READ_RESULT *read_result;
while ((read_result = hive_timerange_reader_read(reader)) != NULL) {
if (!hive_component_runnable(comp)) { break; }
HIVE_LOG_INFO("time range: %lu ~ %lu", begin, end);
HIVE_RECORD_ITERATOR iter = HIVE_GET_RECORD_ITERATOR(read_result);
const HIVE_RECORD *record;
while ((record = HIVE_RECORD_ITERATOR_GET_NEXT(&iter)) != NULL)
{
Logbuff logb;
logbuff_reset(&logb);
logbuff_write(&logb, " %c %19lu", (record->record_type==0)?'D':'S', record->timestamp);
for (int i=0; i < record->data_count; i++) {
const HIVE_RECORD_DATA *rd = HIVE_RECORD_GET_DATA(record, i);
if (!rd) {
logbuff_write(&logb, "%10s", "(no data)");
continue;
}
const char *sourcename = read_result->incolumn_list->incolumns[i].source_component;
const char *dataname = read_result->incolumn_list->incolumns[i].data_name;
HIVE_DATA_TYPE type = read_result->incolumn_list->incolumns[i].data_type;
hive_aggregation_stat_type_t stat = read_result->incolumn_list->incolumns[i].stat_type;
const char *dptr = rd->data;
size_t size = rd->data_size;
process_record_data(sourcename, dataanme, type, stat_type, dptr, size);
}
}
}
hive_timerange_reader_release(reader);
usleep(1*1000*1000);
search_next_ts += 1*HIVE_TIME_1S;
}
hive_timerange_reader_read() … カラムデータ時間範検索#
Readerで指定されたカラム、または入力ポートに接続されている全カラムのデータを指定された時間範囲で検索、取得する
定義
const HIVE_COLUMN_READ_RESULT *hive_timerange_reader_read(HIVE_TIMERANGE_READER *rangeReader);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_TIMERANGE_READER *rangeReader |
hive_inport_timerange_reader()で取得したReader |
戻り値
- HIVE_COLUMN_READ_RESULT: カラムデータ検索結果
説明
本関数は、hive_inport_timerange_reader()で取得したReaderからカラムデータを取得します。
Readerの取得の際に指定した時間範囲のカラムデータを取得することができます。
戻り値として受け取った構造体のメモリはシステムが内部で管理しているため、変更、解放等行わないでください。
hive_timerange_reader_release() … カラムデータ時間範囲検索用のReaderの解放#
hive_inport_timerange_reader()で取得したReaderを解放する
定義
const void hive_timerange_reader_release(HIVE_TIMERANGE_READER *reader);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_TIMERANGE_READER *reader |
hive_inport_timerange_reader()で取得したReader |
戻り値
なし
説明
本関数は、hive_inport_timerange_reader()で取得したReaderを解放します。
コンポーネントの処理中にReaderが不要となるなどの場合に呼び出してください。
HIVE_GET_RECORD_ITERATOR() … レコードイテレータ取得#
ウィンドウデータからレコードのイテレータを取得
定義
HIVE_RECORD_ITERATOR HIVE_GET_RECORD_ITERATOR(const HIVE_COLUMN_READ_RESULT *data);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | const HIVE_COLUMN_READ_RESULT *data |
hive_continuous_reader_read()で取得したウィンドウデータ |
戻り値
- HIVE_RECORD_ITERATOR: レコードイテレータ
説明
本関数は、hive_continuous_reader_read()で取得したウィンドウデータが持つ、レコードのイテレータを取得します。
取得したイテレータに対してHIVE_RECORD_ITERATOR_GET_NEXT()を呼び出すことで、ウィンドウに含まれるレコードを順次取得することができます。
使用例：
while (hive_component_runnable(component)) {
const HIVE_RECORD *record;
const HIVE_COLUMN_READ_RESULT *read_result;
read_result = hive_continuous_reader_read(creader);
if (!read_result) { continue; }
HIVE_RECORD_ITERATOR iter = HIVE_GET_RECORD_ITERATOR(read_result);
while ((record = HIVE_RECORD_ITERATOR_GET_NEXT(&iter)) != NULL)
{
for (int i=0; i < record->data_count; i++) {
const HIVE_RECORD_DATA *rd = HIVE_RECORD_GET_DATA(record, i);
}
}
}
HIVE_RECORD_ITERATOR_GET_NEXT() … レコードイテレータ取得#
レコード取得
定義
const HIVE_RECORD *HIVE_RECORD_ITERATOR_GET_NEXT(HIVE_RECORD_ITERATOR *iter);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_RECORD_ITERATOR *iter |
HIVE_GET_RECORD_ITERATOR()で取得したイテレータへのポインタ |
戻り値
HIVE_RECORD*: レコードポインタNULL: すべてのレコードを取得済み
説明
本関数は、ウィンドウデータに含まれるレコードを順次取得するために、HIVE_GET_RECORD_ITERATOR()と組み合わせて使用します。
使用例はHIVE_GET_RECORD_ITERATOR()を参考にしてください。
HIVE_RECORD_GET_DATA() … レコードイテレータ取得#
レコードデータ取得
定義
const HIVE_RECORD_DATA *HIVE_RECORD_GET_DATA(const HIVE_RECORD *record, size_t index);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_RECORD *record |
HIVE_RECORD_ITERATOR_GET_NEXT()で取得したレコードへのポインタ |
| 2 | size_t index |
取得するレコードデータのインデックス。record->data_count未満の値にすること |
戻り値
HIVE_RECORD_DATA*: レコードデータポインタ
説明
本関数は、レコードに含まれる個々のデータを取得します。
使用例はHIVE_GET_RECORD_ITERATOR()を参考にしてください。
hive_incolumn_get_latest_value() … カラムデータ最新値の取得#
入力ポートのカラムから最新のデータを取得する
定義
bool hive_incolumn_get_latest_value(const HIVE_INCOLUMN *incolumn, hive_time_t *rts, char **dataPointer, size_t *dataSize);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_INCOLUMN *incolumn |
データ取得するカラム |
| 2 | hive_time_t *rst |
取得したデータのタイムスタンプを入れるポインタ |
| 3 | char **dataPointer |
取得したデータの先頭アドレスを格納するポインタ |
| 4 | size_t *dataSize |
取得したデータのサイズを格納するポインタ |
戻り値
- true: 最新値取得成功
- false: 最新値取得失敗
説明
本関数は、指定したカラムの最新データを取得します。
取得に失敗した場合には、戻り値はfalseに、最新データが無いなど取得ができない場合には、取得データのタイムスタンプは0、データサイズも0となります。読み込んだデータ領域はHIVE_INCOLUMN内に保持しています。そのため複数スレッドから同じHIVE_INCOLUMNに対してこの関数を呼ぶ場合、排他制御が必要です。
コンポーネントステータス関数#
hive_status_clear() … ステータス情報クリア#
ステータス情報をクリアし、エラーがない状態にする
定義
void hive_status_clear(HIVE_STATUS status);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_STATUS status |
ステータス構造体へのポインタ |
戻り値
なし
説明
ステータス構造体に登録されたエラー情報等を消去して、何もエラーが無い、正常状態に戻します。
この状態のステータス構造体がhive_component_register_status()で登録されると、本コンポーネントは正常に動作していると判断されます。
hive_status_add_error() … ステータス情報へのエラー登録#
ステータス情報にエラーを登録する
定義
void hive_status_add_error(HIVE_STATUS status, HIVE_ERROR_INFO error);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_STATUS status |
ステータス構造体へのポインタ |
| 2 | HIVE_ERROR_INFO error |
登録するエラーの番号 事前に定義済みのエラー番号を指定できます |
戻り値
なし
説明
ステータス構造体にエラーを登録します。
errorには、HIVE_ERROR()マクロ関数で生成した値を指定してください。
使用例：
const static HIVE_ERROR_TYPE error_types[] = {
{ .name="CONNECTION REFUSED", .parameter_names={"b","c"}},
{ .name="REGISTER READ ERROR", .parameter_names={"f","g"}},
{ .name=NULL },
};
const int ERROR_CONNECTION_REFUSED = 0;
const int ERROR_REGISTER_READ_ERROR = 1;
int proc(COMPONENT *comp, HIVE_STATUS status) {
:
hvie_status_clear(status);
if (detect_error1())
hive_status_add_error(status, HIVE_ERROR(ERROR_CONNECTION_REFUSED, STR("hostname:port")));
if (detect_error2())
hive_status_add_error(status, HIVE_ERROR(ERROR_REGISTER_READ_ERROR, STR("REGDATA_A"), STR("DT0001")));
:
hive_component_register_status(comp, status);
}
hive_status_set_total_xxx_xxx() … ステータス情報への実行時補助情報の登録#
ステータス情報に実行時補助情報を登録する
定義
void hive_status_set_total_emission_count(HIVE_STATUS status, uint64_t value);
void hive_status_set_total_emission_bytes(HIVE_STATUS status, uint64_t value);
void hive_status_set_total_received_count(HIVE_STATUS status, uint64_t value);
void hive_status_set_total_received_bytes(HIVE_STATUS status, uint64_t value);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_STATUS status |
ステータス構造体へのポインタ |
| 2 | uint64_t value |
登録値 |
戻り値
なし
説明
ステータス構造体にコンポーネント実行時補助情報を登録します。 現時点で定義済みの補助情報は下記のとおりです。
- 累計送信数(
hive_status_set_total_emission_count)
コンポーネントが外部に送信したデータの累計数 - 累計送信バイト数(
hive_status_set_total_emission_bytes)
コンポーネントが外部に送信したデータの累計バイト数 - 累計受信数(
hive_status_set_total_received_count)
コンポーネントが外部から受信したデータの累計数 - 累計受信バイト数(
hive_status_set_total_received_bytes)
コンポーネントが外部から受信したデータの累計バイト数
この情報はUIにて補助的に表示する目的で使用されます。 そのためAPIを呼び出さずともコンポーネントの動作に影響はありません。
hive_component_register_status() … コンポーネントへのステータス登録#
コンポーネントにステータス情報を登録する
定義
void hive_component_register_status(HIVE_COMPONENT component, const HIVE_STATUS status);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_COMPONENT component |
コンポーネントのインスタンス premain/main/postmainの関数引数に渡されたコンポーネントインスタンスをそのまま渡してください。 |
| 2 | HIVE_STATUS status |
ステータス構造体へのポインタ |
戻り値
なし
説明
コンポーネントにステータス情報を登録します。
このときのステータス情報にエラーが何も登録されていない場合、コンポーネントは正常に稼働しているとシステムが判断します。ステータス情報にエラーが登録されていると、コンポーネントにエラーが有ることがシステムに報告されます。
システムは最後に登録したステータス情報から、コンポーネントの状態を判定します。コンポーネントは、エラーが解消した場合にはエラーがクリアされたステータス情報をこの関数で登録し直さなければなりません。
HIVE_ERROR() … エラー情報の生成#
エラー情報構造体を生成するマクロ関数
定義
HIVE_ERROR_INFO HIVE_ERROR(int error_no, ...);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | int error_no |
コンポーネントが定義しているエラー種別情報のインデックスを指定してください。。 |
| 2 | ... | 発生したエラーの付属情報を指定してください。整数、浮動小数点数、文字列のいずれかを指定できますが、下記の説明の通り利用方法が特殊です。 |
戻り値
- エラー情報構造体
HIVE_ERROR_INFO
説明
発生したエラーの情報を持つ構造体を生成します。 （ヒープ領域ではなくスタック領域確保するため明示的に解放する必要はありません）
第一引数にはコンポーネントで定義しているエラー種別情報のインデックスを指定します。この情報からエラー種別が判別されます。 発生したエラーの詳細をシステムに知らせるために付属情報を引数で指定できます。その場合付属情報の型に応じて以下のようにマクロを利用して引数指定してください。
HIVE_ERROR_INFO error = HIVE_ERROR(ERROR_CONNECTION_REFUSED, STR(hostname), I64(portno));
付属情報には型に応じて以下のマクロを指定できます。
I64(x): 64bit符号付き整数U64(x): 64bit符号無し整数DBL(x): 倍精度浮動小数点数STR(x): 文字列ポインタ
付属情報に文字列を使う場合は、生成したHIVE_ERROR_INFOをhive_component_register_status()で登録するまではメモリを解放しないようにしてください。
hive_status_alloc() … ステータス情報構造体の確保#
ステータス情報構造体を確保する
定義
HIVE_STATUS hive_status_alloc(HIVE_COMPONENT component);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_COMPONENT component |
コンポーネントのインスタンス premain/main/postmainの関数引数に渡されたコンポーネントインスタンスをそのまま渡してください。 |
戻り値
- ステータス情報構造体
HIVE_STATUSのポインタ - NULL: メモリ不足
説明
ステータス情報を記録する構造体を確保します。
通常のコンポーネント開発ではこの関数を利用する必要はありません。コンポーネントの開始前に自動でステータス情報HIVE_STATUSが確保され、mainloopの引数として渡されます。
hive_status_free() … ステータス情報構造体の解放#
ステータス情報構造体を解放する
定義
void hive_status_free(HIVE_STATUS status);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_STATUS status |
解放するステータス情報構造体のポインタ |
戻り値
なし
説明
hive_status_alloc()で確保したステータス情報構造体を解放します。
通常のコンポーネント開発ではこの関数を利用する必要はありません。コンポーネントの開始前に自動で確保されたステータス情報HIVE_STATUSは、コンポーネント停止時に自動で解放されます。
ログ関連関数#
HIVE_LOG_XXXX() … ログ出力マクロ#
コンポーネント用のログ出力マクロ関数
定義
void HIVE_LOG_ERROR(const char *format, ...);
void HIVE_LOG_WARNING(const char *format, ...);
void HIVE_LOG_INFO(const char *format, ...);
void HIVE_LOG_DEBUG(const char *format, ...);
void HIVE_LOG_TRACE(const char *format, ...);
引数
| No | 引数 | 説明 |
|---|---|---|
| 1 | const char *format |
ログ出力書式指定文字列 ログに出力する書式指定文字列を指定します。標準Cライブラリのprintfと同じ形式です。 |
| 2 | - | 書式指定文字列の変換指示子により変換されるパラメータ |
戻り値
なし
説明
SpeeDBee Synapse本体のログ出力に文字列を出力するためのマクロ関数です。
引数format、および、それに続く可変長引数は、標準Cライブラリのprintf()と同様に使用できます。
マクロは５種類用意されており、それぞれログレベルに対応しています。
hive_current_loglevel() … ログレベル取得#
システムの現在のログレベルを取得する
定義
HIVE_FW_API HIVE_LOG_LEVEL hive_get_loglevel();
引数 なし
戻り値
- HIVE_LOG_LEVEL_ERROR(0): エラーログのみをログ出力する状態
- HIVE_LOG_LEVEL_WARNING(1): エラーおよび警告ログをログ出力する状態
- HIVE_LOG_LEVEL_INFO(2): 通常レベルのログを出力する状態
- HIVE_LOG_LEVEL_DEBUG(3): デバッグ用のログを出力する状態
- HIVE_LOG_LEVEL_TRACE(4): 詳細なトレースログを出力する状態
説明
システムの現在のログレベルを取得します。 ERRORが最低値、TRACEが最高値となっており、戻り値の値より小さい値のログはログファイルに出力されます。
その他の関数#
hive_component_interval_call() … 定期処理関数#
一定の周期で指定した関数を継続的に実行する関数
定義
bool hive_component_interval_call(HIVE_COMPONENT component, hive_interval_proc_t proc, void *data, hive_time_t base_time, uint64_t interval_usec);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_COMPONENT component |
コンポーネントのインスタンス premain/main/postmainの関数引数に渡されたコンポーネントインスタンスをそのまま渡してください。 |
| 2 | hive_interval_proc_t proc |
定期処理関数 定期的に実行する処理を定義した関数のポインタを指定します。 |
| 3 | void *data |
ユーザーデータ 任意のデータポインタを指定できます。procがコールされる際に引数に渡されます。 |
| 4 | hive_time_t base_time |
定期処理関数の実行開始時刻 proc関数を実行開始する基準時刻 0を指定すると現在時刻となる |
| 5 | uint64_t interval_usec |
定期処理関数実行の周期 proc関数をコールする周期をusec単位で指定します。 |
戻り値
- true: proc関数が一度もエラーとならずに、正常にコンポーネントが停止した場合
- false: proc関数内でエラーが発生した場合
説明
一定の周期で何らかの処理を実行する場合に、この関数を使用してください。
hive_component_save_running_info() … 実行時の情報を保存#
コンポーネントの実行時の情報を保存する関数
定義
bool hive_component_save_running_info(HIVE_COMPONENT component, const char *key, const void *data, size_t size);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_COMPONENT component |
コンポーネントのインスタンス premain/main/postmainの関数引数に渡されたコンポーネントインスタンスをそのまま渡してください。 |
| 2 | const char *key |
保存するデータを特定するための情報 異なる keyを指定することでそれぞれ別の情報を保持できます。 |
| 3 | const void *data |
保存するデータ |
| 4 | size_t size |
保存するデータのサイズ |
戻り値
- true: 保存成功
- false: 保存失敗
説明
コンポーネント実行時の任意の情報を保存します。
エミッタなどで一度停止した後で、続きから処理したい場合のためにデータを保持しておくことが可能です。
hive_component_load_running_info() … 保存した実行時の情報を読み込む#
hive_component_save_running_info()で保存したデータを読み込む関数
定義
const void *hive_component_load_running_info(HIVE_COMPONENT component, const char *key, size_t *size);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_COMPONENT component |
コンポーネントのインスタンス premain/main/postmainの関数引数に渡されたコンポーネントインスタンスをそのまま渡してください。 |
| 2 | const char *key |
保存したデータを特定するための情報 |
| 3 | size_t *size |
読み込んだデータのサイズが返る 出力引数 |
戻り値
読み込んだデータの先頭アドレス。データが存在しない場合にはnullが返されます。
このメモリはフレームワーク側で管理しているため、ユーザーが解放する必要はありません。ただし、同じAPIを再度コールすると以前のメモリ領域が上書きされますので、必要な場合はユーザー側でコピーして持つようにしてください。
説明
hive_component_save_running_info()で保存したデータを読み出します。 実行中のコンポーネントを停止した後、再度続きから処理したい場合に保存したデータを読み込むことで、データの途中から処理を再開することが出来ます。
hive_component_runnable() … コンポーネント継続可否#
コンポーネントの継続可否を判定する
定義
bool hive_component_runnable(HIVE_COMPONENT component);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_COMPONENT component |
コンポーネントのインスタンス premain/main/postmainの関数引数に渡されたコンポーネントインスタンスをそのまま渡してください。 |
戻り値
- true: コンポーネントのメイン処理を継続可能
- false: コンポーネントの停止要求が出ている
説明
本関数は、コンポーネントのメイン処理を継続可能かを判定するために使用します。
コンポーネントのメイン処理は、この関数がtrueを返す間、処理を継続し、falseを返した場合には速やかに終了する必要があります。そのためメイン処理内では定期的に（最長でも５秒間隔程度）この関数を呼び出して戻り値を確認してください。
この関数がfalseを返す状態にも関わらず、コンポーネントが所定の時間停止しない場合、コンポーネントのスレッドはシステムにより強制停止されることがあります。
hive_timestamp() … 現在時刻取得#
システムの現在時刻を取得する
定義
hive_time_t hive_timestamp();
引数
なし
戻り値
- システムの現在時刻
説明
システムの現在時刻を取得します。
タイムスタンプの単位についてはhive_time_tを参照してください。
hive_get_api_error() … 発生したエラーの情報を取得#
コンポーネントの実行時に発生したエラーの情報を取得する関数
定義
HIVE_API_ERROR hive_get_api_error();
引数 なし
戻り値
- HIVE_API_ERROR: エラー情報
説明
本関数はコンポーネントの実行時に発生したエラーの情報を取得します。
エラー情報の内容はHIVE_API_ERROR構造体を参照してください。
使用例：エラー情報の取得
:
HIVE_OUTCOLUMN clm = hive_outport_create_column(comp, OUTPORT1, "clm", HIVE_DATA_SCALAR(HIVE_TYPE_INT8), HIVE_COLUMN_OPTION_NONE);
if (clm == nullptr) {
HIVE_API_ERROR error = hive_get_api_error();
HIVE_LOG_ERROR("hive_outport_create_column error(0x%x,%d,%d)", error.code, error.system_errno, error.db_errno);
}
:
HIVE_DATA_TYPE_NAME() … データ型の名前(文字列)を取得#
SpeeDBee Synapseのデータ型の名前(文字列)を取得する関数
定義
const char *HIVE_DATA_TYPE_NAME(hive_primitive_type_t primitive_type);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | hive_primitive_type_t primitive_type |
データ型 |
戻り値
- 渡されたデータ型の名前が文字列として返される
説明
本関数はSpeeDBee Synapseのデータ型(hive_primitive_type_t)の名前を文字列として取得します。
使用例：データ型の名前(文字列)を取得
HIVE_LOG_INFO("HIVE_DATA_TYPE_NAME: %s", HIVE_DATA_TYPE_NAME(HIVE_TYPE_INT16));
:
HIVE_AGGREGATION_STAT_TYPE_NAME() … 統計種別の名前(文字列)を取得#
SpeeDBee Synapseの統計種別の名前(文字列)を取得する関数
定義
const char *HIVE_AGGREGATION_STAT_TYPE_NAME(hive_aggregation_stat_type_t stat_type);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | hive_aggregation_stat_type_t stat_type |
統計種別 |
戻り値
- 渡された統計種別の名前が文字列として返される
説明
本関数はSpeeDBee Synapseの統計種別の名前を文字列として取得します。
使用例：統計種別の名前(文字列)を取得
HIVE_LOG_INFO("HIVE_AGGREGATION_STAT_TYPE_NAME: %s", HIVE_AGGREGATION_STAT_TYPE_NAME(HIVE_AGGREGATION_STAT_TYPE_BASICSUM));
:
HIVE_DATA_TYPE_FROM_NAME() … データ名(文字列)からデータ型と配列数を取得#
データ名(文字列)からSpeeDBee Synapseのデータ型と配列数を取得する関数
定義
HIVE_DATA_TYPE HIVE_DATA_TYPE_FROM_NAME(const char *typeName);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | char *typeName |
データ名 |
戻り値
- HIVE_DATA_TYPE: SpeeDBee Synapseのデータ型と配列数の情報
説明
本関数はデータ名(文字列)からSpeeDBee Synapseのデータ型と配列数を取得します。
使用例：データ型と配列数を取得
HIVE_DATA_TYPE data_type = HIVE_DATA_TYPE_FROM_NAME("int16[3]");
HIVE_LOG_INFO("HIVE_DATA_TYPE: type: %d array: %d", data_type.type, data_type.array);
:
型・構造体・関数#
hive_time_t … HIVE時刻型#
システムの時刻を表す整数型
定義
typedef uint64_t hive_time_t;
説明
時刻を表す整数値です。
符号なしの64bit整数値となっており、 UNIXエポック(1970年1月1日0時0分0秒(UTC))を0としたときの経過ナノ秒数で表現されています。
| 時刻 | 値 |
|---|---|
| 1970年1月1日0時0分0秒.0(UTC) | 0 |
| 1970年1月1日9時0分0秒.0(JST) | 0 |
| 1970年1月1日9時0分1 秒.0(JST) | 1000000000 |
| 1970年1月1日9時1分0 秒.0(JST) | 60000000000 |
| 1970年1月1日10時0分0秒.0(JST) | 3600000000000 |
| 2022年1月31日13時0分0秒.0(JST) | 1643688000000000000 |
| 2022年1月31日13時0分1秒.0(JST) | 1643688001000000000 |
| 2022年1月31日13時1分0秒.0(JST) | 1643688060000000000 |
| 2022年1月31日14時0分0秒.0(JST) | 1643691600000000000 |
hive_primitive_type_t … HIVEカタムプリミティブ型#
カラムのプリミティブ型の列挙型定義
定義
typedef enum {
HIVE_TYPE_NONE = 0,
HIVE_TYPE_BOOLEAN,
HIVE_TYPE_INT8,
HIVE_TYPE_INT16,
HIVE_TYPE_INT32,
HIVE_TYPE_INT64,
HIVE_TYPE_UINT8,
HIVE_TYPE_UINT16,
HIVE_TYPE_UINT32,
HIVE_TYPE_UINT64,
HIVE_TYPE_FLOAT,
HIVE_TYPE_DOUBLE,
HIVE_TYPE_TIMESTAMP, // unsupported
HIVE_TYPE_STRING,
HIVE_TYPE_BINARY,
HIVE_TYPE_COMPLEX, // unsupported
HIVE_TYPE_FILE,
HIVE_TYPE_JSON, // unsupported
HIVE_TYPE_BSON, // unsupported
HIVE_TYPE_MESSAGEPACK, // unsupported
HIVE_TYPE_COMPONENT_STATUS, // unsupported
HIVE_TYPE_USERDEFINED = 100,// unsupported
} hive_primitive_type_t;
メンバ
| No | 項目 | 値 | 説明 |
|---|---|---|---|
| 1 | HIVE_TYPE_NONE |
0 | 不正な型 |
| 2 | HIVE_TYPE_BOOLEAN |
1 | 真偽値型 |
| 3 | HIVE_TYPE_INT8 |
2 | 8bit符号あり整数 |
| 4 | HIVE_TYPE_INT16 |
3 | 16bit符号あり整数 |
| 5 | HIVE_TYPE_INT32 |
4 | 32bit符号あり整数 |
| 6 | HIVE_TYPE_INT64 |
5 | 64bit符号あり整数 |
| 7 | HIVE_TYPE_UINT8 |
6 | 8bit符号なし整数 |
| 8 | HIVE_TYPE_UINT16 |
7 | 16bit符号なし整数 |
| 9 | HIVE_TYPE_UINT32 |
8 | 32bit符号なし整数 |
| 10 | HIVE_TYPE_UINT64 |
9 | 64bit符号なし整数 |
| 11 | HIVE_TYPE_FLOAT |
10 | 32bit浮動小数点数 |
| 12 | HIVE_TYPE_DOUBLE |
11 | 64bit浮動小数点数 |
| 13 | HIVE_TYPE_STRING |
13 | 文字列 |
| 14 | HIVE_TYPE_BINARY |
14 | バイナリデータ |
| 15 | HIVE_TYPE_FILE |
16 | ファイルデータ |
説明
出力ポートにカラムを作成するときや、入力ポートからカラム情報を取得するときに、そのカラムの基本型を表します。
HIVE_DATA_TYPE … HIVEカラムデータ型#
カラムのデータ型を識別する構造体
定義
typedef struct _tag_HIVE_DATA_TYPE {
uint8_t type;
uint8_t array;
} HIVE_DATA_TYPE;
メンバ
| No | 項目 | 説明 |
|---|---|---|
| 1 | uint8_t type |
プリミティブ型 |
| 2 | uint8_t array |
配列要素数 |
説明
出力ポートにカラムを作成するときや、入力ポートからカラム情報を取得するときに、そのカラムのデータ型を示す構造体です。
カラムのデータ型には、スカラの他に配列も指定可能なので、配列を指定する場合はその要素数がarrayとなります。ただし、array=0はスカラ型であることを示します。
以下のプリミティブ型はスカラのみに対応しています。配列にはできないためarrayは常に0としてください。
HIVE_TYPE_TIMESTAMPHIVE_TYPE_STRINGHIVE_TYPE_BINARYHIVE_TYPE_FILE
HIVE_COMPONENT … コンポーネントインスタンス#
コンポーネントのインスタンス情報
定義
typedef struct {
void *user_data;
} *HIVE_COMPONENT;
メンバ
| No | 項目 | 説明 |
|---|---|---|
| 1 | void *user_data |
コンポーネント側で自由に参照・編集できる専用メンバ |
説明
コンポーネントの実行情報を保持する構造体へのポインタです。
上記定義の他、コンポーネントを制御するシステム側が個々のコンポーネントを参照/識別するためのものも別メンバとして定義されています。
各種API呼び出し時に必要となりますのでその引数として使用してください。
user_dataはユーザーが任意に参照・編集できます。
コンポーネントのコールバック関数を超えて保持したいデータがある場合はこちらを使用してください。
hive_interval_proc_t … 定期処理関数シグネチャ#
API hive_component_interval_callを使用する際に指定する関数インタフェースのtypedefです。
定義
typedef bool (*hive_interval_proc_t)(HIVE_COMPONENT component, void *data, hive_time_t now, int skipped, HIVE_STATUS status);
引数
| No | 項目 | 説明 |
|---|---|---|
| 1 | HIVE_COMPONENT component |
コンポーネントのインスタンスhive_component_interval_callの呼び出し時に渡したcomponentです。 |
| 2 | void *data |
ユーザーデータhive_component_interval_callで指定した任意のポインタです。 |
| 3 | hive_time_t now |
各定期処理実行時に、この関数が呼ばれた時刻のタイムスタンプ |
| 4 | int skipped |
定期処理が間に合わずにスキップされた場合のスキップ数 |
| 5 | HIVE_STATUS status |
エラー情報等の登録に使用するstatus |
戻り値
- true: 定期処理をこのあとも継続する場合
- false: 定期処理を停止する場合
説明
API hive_component_interval_callを使用する際に指定する関数インタフェースのtypedefです。
定期処理を行う関数はこの宣言と一致するように定義してください。
この関数の戻り値により、このあとの定期処理が継続されるか、停止するかが決まります。エラーでこのあとの処理が継続できないような場合以外はtrueを返すようにしてください。
HIVE_COLUMN_READ_RESULT … カラム情報読み込み結果（ウィンドウデータ）#
入力ポートからカラムの値を読み込んだ結果を格納する構造体
定義
typedef struct hive_HIVE_COLUMN_READ_RESULT {
hive_time_t timerange_begin;
hive_time_t timerange_end;
const HIVE_INCOLUMN_LIST *incolumn_list;
uint64_t window_id;
uint64_t event_id;
const struct hive_HIVE_RECORD *statistics_record;
bool is_continued;
const char *buffer;
size_t buffer_size;
} HIVE_COLUMN_READ_RESULT;
メンバ
| No | 項目 | 説明 |
|---|---|---|
| 1 | hive_time_t timerange_begin |
この構造体に含まれるデータの時刻範囲の先頭時刻 |
| 2 | hive_time_t timerange_end |
この構造体に含まれるデータの時刻範囲の終端時刻 |
| 3 | const HIVE_INCOLUMN_LIST *incolumn_list |
入力ポートに接続されたカラムの一覧 |
| 6 | uint64_t window_id |
このデータのウィンドウID |
| 6 | uint64_t event_id |
このデータのイベントID |
| 6 | HIVE_RECORD *statistics_record |
集約レコード |
| 6 | bool is_continued |
ウィンドウが次のREAD_RESULTに継続するか否か |
| 4 | const char *buffer |
システムが内部で使用する領域。アクセスしないこと |
| 5 | size_t buffer_size |
システムが内部で使用する領域。アクセスしないこと |
説明
API hive_continuous_reader_read()を使用した際に戻り値として受け取るデータ型です。
この１つの構造体で１ウィンドウ分のデータを保持しています。ウィンドウ範囲は入力ポートの設定により変動します。
この構造体からデータを取得する場合、HIVE_GET_RECORD_ITERATOR()やHIVE_RECORD_ITERATOR_GET_NEXT()を使用してください。
HIVE_RECORD … カラムデータレコード#
ウィンドウデータに含まれる同一タイムスタンプの各カラムのデータをまとめた構造体
定義
typedef struct hive_HIVE_RECORD {
uint8_t record_type;
uint8_t unused;
uint16_t data_count;
uint32_t data_size;
uint64_t timestamp;
uint32_t offset[0];
} HIVE_RECORD;
メンバ
| No | 項目 | 説明 |
|---|---|---|
| 1 | uint8_t record_type |
レコード種別 |
| 2 | uint8_t unused |
未使用領域 |
| 3 | uint16_t data_count |
レコード内のデータ数 |
| 4 | uint32_t data_size |
レコード内の全データのバイト数 |
| 5 | uint64_t timestamp |
レコードのタイムスタンプ |
| 6 | uint32_t offset[0] |
システムが内部で使用する領域。アクセスしないこと |
説明
入力ポートから取得したウィンドウデータ内の同一タイムスタンプのデータセットです。
HIVE_RECORD_ITERATOR_GET_NEXT()を使用して取得できます。
このレコードに含まれるデータ数はdata_countにて取得できますが、ウィンドウデータのincolumn_listのカラム数と同じになります。
レコード内の各データにはHIVE_RECORD_GET_DATA(record, i)でアクセスできます。
HIVE_RECORD_DATA … レコードデータ#
レコードに含まれる個々のデータを持つ構造体
定義
typedef struct hive_HIVE_RECORD_DATA {
uint16_t index;
uint16_t stat_type;
uint32_t data_size;
uint64_t timestamp;
char data[0];
} HIVE_RECORD_DATA;
メンバ
| No | 項目 | 説明 |
|---|---|---|
| 1 | uint16_t index |
未使用領域 |
| 2 | uint16_t stat_type |
本データの集約種別 |
| 3 | uint32_t data_size |
データサイズ |
| 4 | uint64_t timestamp |
タイムスタンプ |
| 5 | char data[0] |
データ |
説明
レコード内の個々のデータを保持する構造体です。
メンバdataは、0要素のchar配列で定義されていますが、実際にはdata_size分のメモリ領域が確保されています。
ただし、data_sizeが0の場合、このタイムスタンプのデータがないことを示します。その場合もdataのポインタはNULLにはならないことに注意してください。
HIVE_COLUMN_OPTIONS … カラムオプション#
カラム作成時のオプション情報を格納する構造体
定義
typedef struct _tag_HIVE_COLUMN_OPTIONS {
hive_column_type_t type;
double sampling_rate;
int compression_unit;
int fixed_size_binary;
int max_binary_size;
} HIVE_COLUMN_OPTIONS;
#define HIVE_COLUMN_OPTION_NONE ((HIVE_COLUMN_OPTIONS){column_type_low,0,0,0,0})
#define HIVE_COLUMN_OPTION_MIDDLE(r) ((HIVE_COLUMN_OPTIONS){column_type_middle,r,0,0,0})
メンバ
| No | 項目 | 説明 |
|---|---|---|
| 1 | hive_column_type_t type |
カラム種別（column_type_low orcolumn_type_middle） |
| 2 | double sampling_rate |
サンプリングレート |
| 3 | int compression_unit |
圧縮単位 |
| 4 | int fixed_size_binary |
バイナリ型固定サイズ |
| 5 | int max_binary_size |
バイナリ型最大サイズ |
説明
hive_outport_create_column()でカラムを作成する際に、第５引数に指定するオプション情報です。必須ではありません。
マクロ
マクロHIVE_COLUMN_OPTION_NONEはデフォルトのオプション定義です。通常はこれを使用してください。
マクロHIVE_COLUMN_OPTION_MIDDLE(r)はミドル種別のカラムを定義するためのオプション情報です。ミドルカラムの場合、サンプリングレートの指定が必須となります。
HIVE_API_ERROR … APIエラー#
APIエラー情報構造体
定義
typedef struct hive_HIVE_API_ERROR {
uint32_t code;
int system_errno;
int db_errno;
} HIVE_API_ERROR;
メンバ
| No | 項目 | 説明 |
|---|---|---|
| 1 | uint32_t code |
エラーの種別を表す数値 |
| 2 | int system_errno |
システムのエラー番号 |
| 3 | int db_errno |
データベースのエラー番号 |
説明
APIエラー発生時に、そのエラーの種別や詳細情報を保持する構造体です。
エラーが発生した場合、hive_get_api_error()関数によりこの情報を取得できます。
codeには、発生したエラーを識別する数値が記録されています。
APIエラーがシステムエラーの場合、そのエラー番号がsystem_errnoに格納されます。システムエラーではない場合はsystem_errnoは0です。
データベースシステムのエラーが起因となっていた場合、そのエラー番号がdb_errnoに格納されます。データベースシステム起因でない場合はdb_errnoは0です。