Custom component C-API reference
This section provides the API specifications for custom component development in the C language. See below for the custom component development procedures.
Custom Component Creation in C Language
OUT Port Functions#
hive_outport_create_column() … Create new column#
Function to get the handle of the column used to register the data collected by the component with SpeeDBee Synapse
Definition
HIVE_OUTCOLUMN hive_outport_create_column(HIVE_COMPONENT component, int out_port_no, const char *name, HIVE_DATA_TYPE type, HIVE_COLUMN_OPTIONS opt)
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_COMPONENT component |
Component instance Pass the component instance exactly as it was passed to the premain/main/postmain function argument. |
| 2 | int out_port_no |
Port number to create the column Specify a macro constant, such as OUTPORT1 or OUTPORT2. Use of only OUTPORT1 is usually sufficient. |
| 3 | const char *name |
Column name Specify the name of the column to be created Note: For information about characters that cannot be used, please refer to "About Column Names That Cannot Be Used" below |
| 4 | HIVE_DATA_TYPE type |
Data type Specify the type of the column to be created |
| 5 | HIVE_COLUMN_OPTIONS opt |
Column options Specify the options of the column to be created. See HIVE_COLUMN_OPTIONS for more information. |
About Column Names That Cannot Be Used
The following characters cannot be used in column names
\- backslash/- slash*- asterisk?- question mark"- double quote< >- angle brackets|- pipe'- single quote- space
Return value
HIVE_OUTCOLUMNcolumn handle: Handle to the column. Used later to register data in the column or to change the column settings- NULL: Failed to create the column
Description
This function gets the handle of the column used to register the data collected by the component with SpeeDBee Synapse.
To register data in a column, the column handle returned by this function is used.
The column name cannot contain "/" (slash). Other characters are allowable, but non-ASCII characters must be UTF-8 encoded. The column name must not exceed 127 bytes.
If one component gets columns with the identical column names, only the handle of the last one is enabled. Therefore, it is possible to change the settings of a column by getting the column handle of the same column name with this function. However, this method should not be used because it disables any previously acquired column handles.
See HIVE_COLUMN_OPTIONS for more information about specifying column options.
hive_outport_register_confirmed_time() … Register column data confirmed time in status information#
Function to register column data confirmed time with the OUT Port
Definition
void hive_outport_register_confirmed_time(HIVE_COMPONENT component, int out_port_no, hive_time_t ts);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_COMPONENT component |
Component instance Pass the component instance exactly as it was passed to the premain/main/postmain function argument. |
| 2 | int out_port_no |
OUT Port number to be registered |
| 3 | hive_time_t ts |
Time to register |
Return value
None
Description
This function registers column data confirmed time with the OUT Port.
By registering this information, this component can tell the framework that all data before the time of registration has been registered.
This optimizes the processing of the component that receives data so that it can handle the data with less latency.
The component that registers data should register the time after registering data of some timestamp, when it is confirmed that data of a timestamp earlier than that time is not to be registered in the future.
Various components can operate without this API, but some delay occurs in data reception on the component that receives data.
Conversely, when registering a timestamp with this API, it is necessary to exercise caution not to register data with a timestamp earlier than that timestamp. If registered, the component that receives the data may drop the data.
Output Column Functions#
hive_outcolumn_insert() … Register data#
Function to register data in a column
Definition
bool hive_outcolumn_insert(HIVE_OUTCOLUMN column, const void *data);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_OUTCOLUMN column |
Column handle Specify a column handle acquired with hive_outport_create_column() |
| 2 | void *data |
Pointer to the data to register |
Return value
- true: Successfully registered
- false: Failed to register
Description
This function registers a single piece of data into the column specified in the first argument.
The second argument data must be a memory address that matches the data type of the column to be registered.
Examples
- Top address of a 2-byte memory area for a scalar of type uint16
- Top address of a 20-byte memory area for a 5 element array of float type
The data timestamp registered with this function will be the current time when this function is called. If it is necessary to specify the time, use hive_outcolumn_insert_ts().
hive_outcolumn_insert_ts() … Register timestamp specified data#
Function to register timestamp specified data in a column
Definition
bool hive_outcolumn_insert_ts(HIVE_OUTCOLUMN column, const void *data, hive_time_t ts);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_OUTCOLUMN column |
Column handle Specify a column handle acquired with hive_outport_create_column() |
| 2 | const void *data |
Pointer to the data to register |
| 3 | hive_time_t ts |
Data timestamp to register |
Return value
- true: Successfully registered
- false: Failed to register
Description
The first and second arguments are similar to those of hive_outcolumn_insert().
For the third argument ts, specify a timestamp. The current timestamp is acquirable with hive_timestamp().
This function is intended for use in situations where data is registered with the same timestamp for multiple columns.
Usage example: Registering data in multiple columns with the same 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);
:
Using hive_outcolumn_insert() will result in different timestamps for clmA, clmB, and clmC.
In this system, the data timestamps to be registered in the same column must be registered in chronological order.
Therefore, it is not possible to register data at time T0 in a column and then register data with a timestamp earlier than T0 in the same column.
hive_outcolumn_insert_binary() … Register binary data#
Function to register variable-length binary data in a BINARY column
Definition
bool hive_outcolumn_insert_binary(HIVE_OUTCOLUMN column, const void *data, size_t n);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_OUTCOLUMN column |
Column handle Specify a column handle acquired with hive_outport_create_column() |
| 2 | const void *data |
Pointer to the data to register |
| 3 | size_t n |
Number of bytes of data to be registered |
Return value
- true: Successfully registered
- false: Failed to register
Description
This function registers arbitrary length data for a column created as type BINARY.
The first and second arguments are similar to those of hive_outcolumn_insert(). For the third argument n, specify the number of bytes of data to be registered.
The data timestamp registered with this function will be the current time when this function is called. If it is necessary to specify the time, use hive_outcolumn_insert_binary_ts().
hive_outcolumn_insert_binary_ts() … Register timestamp specified binary type data#
Function to register variable-length binary data with a timestamp specification in a BINARY column
Definition
bool hive_outcolumn_insert_binary_ts(HIVE_OUTCOLUMN column, const void *data, size_t n, hive_time_t ts);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_OUTCOLUMN column |
Column handle Specify a column handle acquired with hive_outport_create_column() |
| 2 | const void *data |
Pointer to the data to register |
| 3 | size_t n |
Number of bytes of data to be registered |
| 4 | hive_time_t ts |
Data timestamp to register |
Return value
- true: Successfully registered
- false: Failed to register
Description
The first, second, and third arguments are similar to those of hive_outcolumn_insert_binary().
For the third argument ts, specify a timestamp. See hive_outcolumn_insert_ts() for notes on timestamps.
hive_outcolumn_insert_multisamples() … Register multi-sample data#
Function to register multiple timestamp data sets in a single column
Definition
bool hive_outcolumn_insert_multisamples(HIVE_OUTCOLUMN column, const void *data, hive_time_t ts, int sample_count);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_OUTCOLUMN column |
Column handle Specify a column handle returned by hive_outport_create_column() |
| 2 | const void *data |
Pointer to the data to register |
| 3 | hive_time_t ts |
Data timestamp to register |
| 4 | int sample_count |
Number of samples of data to be registered |
Return value
- true: Successfully registered
- false: Failed to register
Description
This function is usable only when a sampling rate of column type MIDDLE is specified in the column option.
The first, second, and third arguments are similar to those of hive_outcolumn_insert_ts().
For the fourth argument sample_count, specify the number of samples of the data to be registered. Multiple pieces of data to be registered must be located consecutively in the memory pointed to by the second argument data.
Usage example: Registering consecutive samples of 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);
:
In the above example, data [0] is registered with the specified timestamp ts0, followed by data [1] as ts0 + 0.1 seconds and data [2] as ts0 + 0.2 seconds.
The interval between each timestamp is derived from opt.sampling_rate.
hive_outcolumn_open_file() … Create file#
Function to create a file for a file-type column
Definition
HIVE_FILE *hive_outcolumn_open_file(HIVE_OUTCOLUMN column);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_OUTCOLUMN column |
Column handle Specify a column handle returned by hive_outport_create_column() |
Return value
- HIVE_FILE pointer
HIVE_FILE: Pointer to HIVE_FILE with a created file pointer. - NULL: Failed to create the file
Description
This function creates a file for registering data to a file-type column and returns the HIVE_FILE pointer with the file pointer.
Use the file pointer in the returned HIVE_FILE to write to the file. Subsequently, use hive_outcolumn_insert_file() to register the file with the column.
Usage example: Creating a file and writing data
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);
}
Ensure that the HIVE_FILE pointers returned by this function release the resources with hive_outcolumn_insert_file() or hive_outcolumn_dispose_file(). Otherwise, the resources will be kept unreleased, resulting in memory leaks.
hive_outcolumn_insert_file() … Register file type data#
Function to register data in a file type column
Definition
bool hive_outcolumn_insert_file(HIVE_FILE *hf, hive_time_t ts, const HIVE_FILE_METAINFO *meta);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_FILE *hf |
Pointer to HIVE_FILE Specify the HIVE_FILE pointer returned by hive_outcolumn_open_file() |
| 2 | hive_time_t ts |
Data timestamp to register |
| 3 | HIVE_FILE_METAINFO *meta |
Meta information of the file to be registered |
Return value
- true: Successfully registered
- false: Failed to register
Description
This function registers data in a file type column.
For the first argument hf, specify the HIVE_FILE pointer created by hive_outcolumn_open_file().
For the second argument ts, specify a timestamp. If 0 is specified, the current time is registered.
For the third argument meta, insert and specify the meta information of the file to be registered in HIVE_FILE_METAINFO.
The meta information is referenced by the receiver of the data in this file type column, but can be NULL if not required.
See hive_outcolumn_open_file() for a usage example.
hive_outcolumn_dispose_file() … Discard files#
Function to discard files
Definition
void hive_outcolumn_dispose_file(HIVE_FILE *hf);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_FILE *hf |
Pointer to HIVE_FILE Specify the HIVE_FILE pointer returned by hive_outcolumn_open_file() |
Return value
None
Description
This function discards the file for a file-type column created with hive_outcolumn_open_file() and HIVE_FILE.
When a file is opened with hive_outcolumn_open_file() but is no longer needed, call this function to discard the file.
Input Column Functions#
hive_inport_get_column_list() … Get input column information#
Get IN Port column information
Definition
const HIVE_INCOLUMN_LIST *hive_inport_get_column_list(HIVE_COMPONENT component, int inPortNo);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_COMPONENT component |
Component instance Pass the component instance exactly as it was passed to the premain/main/postmain function argument. |
| 2 | int in_port_no |
IN Port setting |
Return value
- HIVE_INCOLUMN_LIST: Column information list
- NULL: Column information not acquirable due to a cause such as insufficient memory
Description
This function gets the column information (e.g., component names, column names, types) of another component connected to the specified IN Port.
The memory of structure received as a return value is managed internally by the system and should not be modified, released, etc. Note also that calling another hive_inport_xxxx API may cause the contents to be changed. If it is necessary to save this information, copy it to a separate memory area.
hive_inport_continuous_reader() … Get Reader for continuous retrieval for column data#
Get a Reader to continuously get data from the IN Port columns
Definition
HIVE_CONTINUOUS_READER *hive_inport_continuous_reader(HIVE_COMPONENT component, int in_port_no, hive_time_t search_begin);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_COMPONENT component |
Component instance Pass the component instance exactly as it was passed to the premain/main/postmain function argument. |
| 2 | int in_port_no |
IN Port setting |
| 3 | hive_time_t search_begin |
Search range starting time |
Return value
- HIVE_CONTINUOUS_READER: Reader for continuous column data retrieval
Description
This function gets a Reader used to continuously retrieve the column data of other components connected to the specified IN Port.
This Reader can then be used in hive_continuous_reader_read() to search for and retrieve column data. The memory of the structure received as a return value is managed internally by the system and should not be modified, released, etc.
Usage example:
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() … Continuously retrieve column data#
Continuously search for and retrieve data from the columns connected to the IN Port specified for the Reader
Definition
const HIVE_COLUMN_READ_RESULT *hive_continuous_reader_read(HIVE_CONTINUOUS_READER *contReader);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_CONTINUOUS_READER *contReader |
Reader acquired with hive_inport_continuous_reader() |
Return value
- HIVE_COLUMN_READ_RESULT: Column data retrieval results
Description
This function gets column data from the Reader acquired with hive_inport_continuous_reader().
Each call updates the search time, allowing column data to be continuously acquired.
The memory of structure received as a return value is managed internally by the system and should not be modified, released, etc.
hive_continuous_reader_release() … Release Reader for continuous retrieval of column data#
Release the Reader acquired with hive_inport_continuous_reader()
Definition
const void hive_continuous_reader_release(HIVE_CONTINUOUS_READER *contReader);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_CONTINUOUS_READER *contReader |
Reader acquired with hive_inport_continuous_reader() |
Return value
None
Description
This function releases the Reader acquired with hive_inport_continuous_reader().
Call this function when the Reader is no longer needed during component processing.
hive_inport_timerange_reader() … Get Reader for time range retrieval of column data#
Get a Reader to get data from the IN Port columns specifying a time range
Definition
HIVE_TIMERANGE_READER *hive_inport_timerange_reader(HIVE_COMPONENT component, const HIVE_INCOLUMN *incolumn, hive_time_t searchBegin, hive_time_t searchEnd);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_COMPONENT component |
Component instance Pass the component instance exactly as it was passed to the premain/main/postmain function argument. |
| 2 | HIVE_INCOLUMN *incolumn |
Column to get data from |
| 3 | hive_time_t search_begin |
Search range starting time |
| 3 | hive_time_t search_end |
Search range ending time |
Return value
- HIVE_TIMERANGE_READER: Reader for time range retrieval of column data
Description
This function gets a Reader used to retrieve data in the specified column within a specified time range.
If no column is specified, all columns of other components connected to the IN Port will be subject to search. This Reader can then be used in hive_timerange_reader_read() to search for and retrieve column data.
The memory of structure received as a return value is managed internally by the system and should not be modified, released, etc.
Usage example:
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() … Search for column data in a time range#
Search for and retrieve data in the column specified for the Reader or in all columns connected to the IN Port over a specified time range
Definition
const HIVE_COLUMN_READ_RESULT *hive_timerange_reader_read(HIVE_TIMERANGE_READER *rangeReader);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_TIMERANGE_READER *rangeReader |
Reader acquired with hive_inport_timerange_reader() |
Return value
- HIVE_COLUMN_READ_RESULT: Column data retrieval results
Description
This function gets column data from the Reader acquired with hive_inport_timerange_reader().
It can get column data in the time range specified at the time of Reader acquisition.
The memory of structure received as a return value is managed internally by the system and should not be modified, released, etc.
hive_timerange_reader_release() … Release Reader for time range retrieval of column data#
Release the Reader acquired with hive_inport_timerange_reader()
Definition
const void hive_timerange_reader_release(HIVE_TIMERANGE_READER *reader);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_TIMERANGE_READER *reader |
Reader acquired with hive_inport_timerange_reader() |
Return value
None
Description
This function releases the Reader acquired with hive_inport_timerange_reader().
Call this function when the Reader is no longer needed during component processing.
HIVE_GET_RECORD_ITERATOR() … Get record iterator#
Get the record iterator from window data
Definition
HIVE_RECORD_ITERATOR HIVE_GET_RECORD_ITERATOR(const HIVE_COLUMN_READ_RESULT *data);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | const HIVE_COLUMN_READ_RESULT *data |
Window data acquired with hive_continuous_reader_read() |
Return value
- HIVE_RECORD_ITERATOR: Record iterator
Description
This function acquires the record iterator from the window data acquired with hive_continuous_reader_read().
Call HIVE_RECORD_ITERATOR_GET_NEXT() for the acquired iterator to sequentially get records contained in the window.
Usage example:
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() … Get record iterator#
Get records
Definition
const HIVE_RECORD *HIVE_RECORD_ITERATOR_GET_NEXT(HIVE_RECORD_ITERATOR *iter);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_RECORD_ITERATOR *iter |
Pointer to the iterator acquired with HIVE_GET_RECORD_ITERATOR() |
Return value
HIVE_RECORD*: Record pointerNULL: All records acquired
Description
This function is used in combination with HIVE_GET_RECORD_ITERATOR() to sequentially get records contained in window data.
See HIVE_GET_RECORD_ITERATOR() for a usage example.
HIVE_RECORD_GET_DATA() … Get record iterator#
Get record data
Definition
const HIVE_RECORD_DATA *HIVE_RECORD_GET_DATA(const HIVE_RECORD *record, size_t index);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_RECORD *record |
Pointer to the record acquired with HIVE_RECORD_ITERATOR_GET_NEXT() |
| 2 | size_t index |
Index of the record data to be acquired. To be a value less than record->data_count |
Return value
HIVE_RECORD_DATA*: Record data pointer
Description
This function gets individual data pieces contained in a record.
See HIVE_GET_RECORD_ITERATOR() for a usage example.
hive_incolumn_get_latest_value() … Get latest value of column data#
Get the latest data from the IN Port column
Definition
bool hive_incolumn_get_latest_value(const HIVE_INCOLUMN *incolumn, hive_time_t *rts, char **dataPointer, size_t *dataSize);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_INCOLUMN *incolumn |
Column to get data from |
| 2 | hive_time_t *rst |
Pointer to put in the acquired data timestamp |
| 3 | char **dataPointer |
Pointer to store the top address of the acquired data |
| 4 | size_t *dataSize |
Pointer to store the size of the acquired data |
Return value
- true: Successfully acquired the latest value
- false: Failed to acquire the latest value
Description
This function gets the latest data from a specified column.
If acquisition fails, the return value is false. If acquisition is unavailable due to a reason such as no latest data, the acquired data timestamp is 0 and the data size is 0. The loaded data area is kept in HIVE_INCOLUMN. Therefore, if multiple threads are to call this function for the same HIVE_INCOLUMN, exclusive control is required.
Component Status Functions#
hive_status_clear() … Clear status information#
Clear status information and make sure there are no errors
Definition
void hive_status_clear(HIVE_STATUS status);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_STATUS status |
Pointer to the status structure |
Return value
None
Description
This function erases the error and other information registered in the status structure and returns it to the normal state without any error.
When a status structure in this state is registered by hive_component_register_status(), the component is determined to be operating normally.
hive_status_add_error() … Register an error in status information#
Register an error in status information
Definition
void hive_status_add_error(HIVE_STATUS status, HIVE_ERROR_INFO error);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_STATUS status |
Pointer to the status structure |
| 2 | HIVE_ERROR_INFO error |
Number of the error to be registered Allowed to specify a predefined error number |
Return value
None
Description
This function registers an error in the status structure.
For error, specify a value generated by the HIVE_ERROR() macro function.
Usage example:
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() … Register run-time auxiliary information in status information#
Register run-time auxiliary information in status information
Definition
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);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_STATUS status |
Pointer to the status structure |
| 2 | uint64_t value |
Registered value |
Return value
None
Description
This function registers component run-time auxiliary information in the status structure. The auxiliary information currently defined is as follows.
- Cumulative number sent (
hive_status_set_total_emission_count)
Cumulative number of outbound data pieces sent by the component - Cumulative number of bytes sent (
hive_status_set_total_emission_bytes)
Cumulative number of bytes of outbound data sent by the component - Cumulative number received (
hive_status_set_total_received_count)
Cumulative number of inbound data pieces received by the component - Cumulative number of bytes received (
hive_status_set_total_received_bytes)
Cumulative number of bytes of inbound data received by the component
The UI uses this information for supplementary display purposes. Therefore, not calling the API will not affect the behavior of the component.
hive_component_register_status() … Register status with component#
Register status information with the component
Definition
void hive_component_register_status(HIVE_COMPONENT component, const HIVE_STATUS status);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_COMPONENT component |
Component instance Pass the component instance exactly as it was passed to the premain/main/postmain function argument. |
| 2 | HIVE_STATUS status |
Pointer to the status structure |
Return value
None
Description
This function registers status information with the component.
If no errors are registered in the status information, the system assumes that the component is operating normally. If an error is registered in the status information, the system receives a report that the component has an error.
The system determines the status of the component from the status information that was last registered. If the error is resolved, the component must use this function to re-register the status information that the error has been resolved.
HIVE_ERROR() … Generate error information#
Macro function to generate an error information structure
Definition
HIVE_ERROR_INFO HIVE_ERROR(int error_no, ...);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | int error_no |
Specify the index of the error type information defined for the component. |
| 2 | ... | Specify the additional information of the error that occurred. This can be an integer, a floating point number, or a string, but its usage is special as described below. |
Return value
- Error information structure
HIVE_ERROR_INFO
Description
This function generates a structure with information about the error that occurred. (It does not need to be explicitly released because it allocates stack space, not heap space.)
For the first argument, specify the index of the error type information defined for the component. The system determines the error type from this information. To inform the system of the details of the error that occurred, arguments are useful for specifying additional information. In that event, use a macro as shown below to specify arguments according to the type of additional information.
HIVE_ERROR_INFO error = HIVE_ERROR(ERROR_CONNECTION_REFUSED, STR(hostname), I64(portno));
The following macros are specifiable for the additional information, depending on the type.
I64(x): 64-bit signed integerU64(x): 64-bit unsigned integerDBL(x): Double-precision floating-point numberSTR(x): String pointer
When using a string for additional information, make sure that the memory is not released until the generated HIVE_ERROR_INFO is registered by hive_component_register_status().
hive_status_alloc() … Allocate status information structure#
Allocate a status information structure
Definition
HIVE_STATUS hive_status_alloc(HIVE_COMPONENT component);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_COMPONENT component |
Component instance Pass the component instance exactly as it was passed to the premain/main/postmain function argument. |
Return value
- Pointer to the status information structure
HIVE_STATUS - NULL: Low memory
Description
This function allocates a structure to record status information.
Normal component development does not require the use of this function. Status information HIVE_STATUS is automatically allocated and passed as an argument to mainloop before the component starts.
hive_status_free() … Release status information structure#
Release a status information structure
Definition
void hive_status_free(HIVE_STATUS status);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_STATUS status |
Pointer to the status information structure to be released |
Return value
None
Description
This function releases the status information structure allocated by hive_status_alloc().
Normal component development does not require the use of this function. The status information HIVE_STATUS that was automatically allocated before the component started is automatically released when the component stops.
Log Related Functions#
HIVE_LOG_XXXX() … Log output macros#
Log output macro function for components
Definition
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, ...);
Arguments
| No | Arguments | Description |
|---|---|---|
| 1 | const char *format |
Log output format string Specify the format string to be sent to the log output. This is the same format as printf in the standard C library. |
| 2 | - | Parameters converted based on format string conversion specifiers |
Return value
None
Description
This is a macro function to send character strings to the SpeeDBee Synapse main log output.
The format argument and the subsequent variadic arguments can be used as with printf() in the standard C library.
Available macros are of five types, each corresponding to a log level.
hive_current_loglevel() … Get log level#
Get the current log level of the system
Definition
HIVE_FW_API HIVE_LOG_LEVEL hive_get_loglevel();
Arguments None
Return value
- HIVE_LOG_LEVEL_ERROR(0): Status in which only error logs are sent to the log output
- HIVE_LOG_LEVEL_WARNING(1): Status in which error and warning logs are sent to the log output
- HIVE_LOG_LEVEL_INFO(2): Status in which logs at the normal level are subject to output
- HIVE_LOG_LEVEL_DEBUG(3): Status in which debugging logs are subject to output
- HIVE_LOG_LEVEL_TRACE(4): Status in which detailed trace logs are subject to output
Description
This function gets the current log level of the system. ERROR is the lowest value, TRACE is the highest, and a log with a value less than the return value is sent to the log file.
Other Functions#
hive_component_interval_call() … Periodic function#
Function to continuously run a specified function at regular intervals
Definition
bool hive_component_interval_call(HIVE_COMPONENT component, hive_interval_proc_t proc, void *data, hive_time_t base_time, uint64_t interval_usec);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_COMPONENT component |
Component instance Pass the component instance exactly as it was passed to the premain/main/postmain function argument. |
| 2 | hive_interval_proc_t proc |
Periodic function Specify a pointer to the function that defines the processing to be run periodically. |
| 3 | void *data |
User data Any data pointer is specifiable. Passed as an argument when proc is called. |
| 4 | hive_time_t base_time |
Time to start running the periodic function Base time for starting to run the proc function Current time if 0 is specified |
| 5 | uint64_t interval_usec |
Periodic function execution interval Specify the interval of calling the proc function in usec units. |
Return value
- true: The component stopped normally without any error in the proc function
- false: An error occurred in the proc function
Description
This function is useful for executing a certain process at regular intervals.
hive_component_save_running_info() … Save run-time information#
Function to save component run-time information
Definition
bool hive_component_save_running_info(HIVE_COMPONENT component, const char *key, const void *data, size_t size);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_COMPONENT component |
Component instance Pass the component instance exactly as it was passed to the premain/main/postmain function argument. |
| 2 | const char *key |
Information to identify the data to be saved Specify different keys to hold different information. |
| 3 | const void *data |
Data to be saved |
| 4 | size_t size |
Size of data to be saved |
Return value
- true: Successfully saved
- false: Failed to save
Description
This function saves arbitrary information during component execution.
It enables data to be held so that the processing can resume after stopping, for example, at an emitter.
hive_component_load_running_info() … Load saved run-time information#
Function to load data saved with hive_component_save_running_info()
Definition
const void *hive_component_load_running_info(HIVE_COMPONENT component, const char *key, size_t *size);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_COMPONENT component |
Component instance Pass the component instance exactly as it was passed to the premain/main/postmain function argument. |
| 2 | const char *key |
Information to identify the data saved |
| 3 | size_t *size |
Returns the size of the data loaded Output argument |
Return value
The top address of the data loaded. If no data exists, null is returned.
This memory is managed by the framework and does not require release by the user. However, if the same API is called again, the previous memory area will be overwritten. According to need, the user should copy the memory area.
Description
This function loads data saved with hive_component_save_running_info(). To restart the processing of data after stopping the running component, the component can resume the processing by loading the saved data.
hive_component_runnable() … Component sustainability#
Determine whether the component is continuable
Definition
bool hive_component_runnable(HIVE_COMPONENT component);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_COMPONENT component |
Component instance Pass the component instance exactly as it was passed to the premain/main/postmain function argument. |
Return value
- true: Main processing of component continuable
- false: Requested to stop the component
Description
This function is useful for determining whether the main processing of the component is continuable.
The main processing of the component should continue as long as this function returns true, and should terminate promptly if it returns false. Therefore, in the main processing, ensure that this function is called periodically (at most every 5 seconds) and the return value is checked.
If this function returns false but the component does not stop for a given amount of time, the system may force to stop the component's thread.
hive_timestamp() … Get current time#
Get the current system time
Definition
hive_time_t hive_timestamp();
Arguments
None
Return value
- Current system time
Description
This function gets the current system time.
See hive_time_t for timestamp units.
hive_get_api_error() … Get occurring error information#
Function to get information about errors that occur during component execution
Definition
HIVE_API_ERROR hive_get_api_error();
Arguments None
Return value
- HIVE_API_ERROR: Error information
Description
This function gets information about errors that occur during component execution.
See the HIVE_API_ERROR structure for the content of the error information.
Usage example: Getting error information
:
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() … Get data type name (string)#
Function to get the name of the data type of SpeeDBee Synapse (string)
Definition
const char *HIVE_DATA_TYPE_NAME(hive_primitive_type_t primitive_type);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | hive_primitive_type_t primitive_type |
Data type |
Return value
- Returns the name of the data type passed in as a string
Description
This function gets the name of the SpeeDBee Synapse data type (hive_primitive_type_t) as a character string.
Usage example: Getting the name (string) of a data type
HIVE_LOG_INFO("HIVE_DATA_TYPE_NAME: %s", HIVE_DATA_TYPE_NAME(HIVE_TYPE_INT16));
:
HIVE_AGGREGATION_STAT_TYPE_NAME() … Get statistics type name (string)#
Function to get the name of the statistic type of SpeeDBee Synapse (string)
Definition
const char *HIVE_AGGREGATION_STAT_TYPE_NAME(hive_aggregation_stat_type_t stat_type);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | hive_aggregation_stat_type_t stat_type |
Statistic type |
Return value
- Returns the name of the statistic type passed in as a string
Description
This function gets the name of the statistic type of SpeeDBee Synapse.
Usage example: Getting the name (string) of a statistic type
HIVE_LOG_INFO("HIVE_AGGREGATION_STAT_TYPE_NAME: %s", HIVE_AGGREGATION_STAT_TYPE_NAME(HIVE_AGGREGATION_STAT_TYPE_BASICSUM));
:
HIVE_DATA_TYPE_FROM_NAME() … Get data type and array size from data name (string)#
Function to get the data type and array size of SpeeDBee Synapse from the data name (string)
Definition
HIVE_DATA_TYPE HIVE_DATA_TYPE_FROM_NAME(const char *typeName);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | char *typeName |
Data name |
Return value
- HIVE_DATA_TYPE: SpeeDBee Synapse data type and array size information
Description
This function gets the data type and array size of SpeeDBee Synapse from the data name (string).
Usage example: Getting data type and array size
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_get_common_variable() … Get component default variable#
Function to get a component default variable
Definition
const char *hive_get_common_variable(HIVE_COMPONENT component, const char *varname);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_COMPONENT component |
Component instance Pass the component instance exactly as it was passed to the premain/main/postmain function argument. |
| 1 | char *varname |
Variable name of the common variable to be acquired |
Return value
The top address of the value (string) set for the specified variable name. If no data exists, null is returned.
This memory is managed by the framework and does not require release by the user. However, if the same API is called again, the previous memory area will be overwritten. According to need, the user should copy the memory area.
Description
This function acquires the value of the set common variable by specifying the variable name.
Usage example: Getting data type and array size
const char *project_dir = hive_get_common_variable(component, "PROJECT_DIR");
HIVE_LOG_INFO("project_dir: %s", project_dir);
:
hive_lock() … Exclusive control between components#
Function to acquire a lock for exclusive control between components
Definition
HIVE_LOCK_RESULT hive_lock(HIVE_COMPONENT component, const char *key, bool interbase, uint64_t timeout);
HIVE_LOCK_RESULT synapse_lock(HIVE_COMPONENT component, const char *key, bool interbase, uint64_t timeout);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_COMPONENT component |
Component instance Pass the component instance exactly as it was passed to the premain/main/postmain function argument. |
| 2 | const char *key |
Arbitrary string to identify the exclusive control target |
| 3 | bool interbase |
Set to true when performing exclusive control across different component bases |
| 4 | uint64_t timeout |
Timeout duration while waiting for the lock to be released |
Return value
- HIVE_LOCK_OK: Lock acquired successfully
- HIVE_LOCK_TIMEOUT: Failed to acquire the lock within the specified timeout
- HIVE_LOCK_CANCELED: Stop request was received before the lock was acquired
Description
This function acquires a lock for the resource identified by the string specified in key to ensure exclusive control.
Only one thread can acquire the lock for the same key.
The acquired lock can be released using the corresponding API function hive_unlock().
Alternatively, if the component terminates holding the lock, it will be automatically released.
Usage example: Exclusive control logic using a device file
HIVE_LOCK_RESULT result = hive_lock(component, "/dev/serial", false, 10000000000);
if (result == HIVE_LOCK_TIMEOUT) {
HIVE_LOG_ERROR("could not take lock.");
return false;
} else if (result == HIVE_LOCK_CANCELED) {
return true;
}
// This section can only be executed by a single component instance
hive_unlock(component, "/dev/serial", false);
You may specify any arbitrary string for the key.
If the interbase argument is set to true, exclusive control can be achieved across different component bases by using the same key.
In this case, exclusive control can also be used with custom components using the Python API’s HiveComponentBase::lock().
If interbase is set to false, exclusive control is limited to components within the same component base only.
If another component instance has already acquired the lock when this function is called, execution within the function will be blocked.
The maximum blocking time can be specified in nanoseconds via the timeout argument. (The actual granularity depends on the clock precision of the execution environment.)
Specifying 0 will return immediately if the lock cannot be acquired.
To wait indefinitely until the lock is acquired, use HIVE_LOCK_NO_TIMEOUT as the value for timeout.
A thread cannot acquire the same key more than once simultaneously.
The thread enters a lock-wait state and remains blocked until a timeout occurs or a stop request is received.
hive_unlock() … Exclusive control between components#
Release a lock used for exclusive control between components
Definition
HIVE_LOCK_RESULT hive_unlock(HIVE_COMPONENT component, const char *key, bool interbase);
HIVE_LOCK_RESULT synapse_unlock(HIVE_COMPONENT component, const char *key, bool interbase);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_COMPONENT component |
Component instance Pass the component instance exactly as it was passed to the premain/main/postmain function argument. |
| 2 | const char *key |
Arbitrary string to identify the exclusive control target |
| 3 | bool interbase |
Set to true when performing exclusive control across different component bases |
Return value
- HIVE_LOCK_OK: Unlock successful
- HIVE_LOCK_ERROR: An error occurred
Description
This function releases a lock acquired using hive_lock.
Use the same key and interbase values as used during lock acquisition.
Usage example: Exclusive control logic using a device file
HIVE_LOCK_RESULT result = hive_lock(component, "lock-serialdevice", false, 10000000000);
if (result == HIVE_LOCK_TIMEOUT) {
HIVE_LOG_ERROR("could not take lock.");
return false;
} else if (result == HIVE_LOCK_CANCELED) {
return true;
}
// This section can only be executed by a single component instance
hive_unlock(component, "lock-serialdevice", false);
Types, Structures, and Functions#
hive_time_t … HIVE time type#
Integer representing the system time
Definition
typedef uint64_t hive_time_t;
Description
This is an integer value representing the time.
It is an unsigned 64-bit integer value, expressed in elapsed nanoseconds assuming that the Unix epoch (1970-1-1 00:00:00 [UTC]) is 0.
| Time | Value |
|---|---|
| 1970-1-1 00:00:00. 0 (UTC) | 0 |
| 1970-1-1 09:00:00. 0 (JST) | 0 |
| 1970-1-1 09:00:01. 0 (JST) | 1000000000 |
| 1970-1-1 09:01:00. 0 (JST) | 60000000000 |
| 1970-1-1 10:00:00. 0 (JST) | 3600000000000 |
| 2022-1-31 13:00:00. 0 (JST) | 1643688000000000000 |
| 2022-1-31 13:00:01. 0 (JST) | 1643688001000000000 |
| 2022-1-31 13:01:00. 0 (JST) | 1643688060000000000 |
| 2022-1-31 14:00:00. 0 (JST) | 1643691600000000000 |
hive_primitive_type_t … HIVE column primitive type#
Enum definition of the primitive types of columns
Definition
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;
Members
| No | Item | Value | Description |
|---|---|---|---|
| 1 | HIVE_TYPE_NONE |
0 | Incorrect type |
| 2 | HIVE_TYPE_BOOLEAN |
1 | Boolean type |
| 3 | HIVE_TYPE_INT8 |
2 | 8-bit signed integer |
| 4 | HIVE_TYPE_INT16 |
3 | 16-bit signed integer |
| 5 | HIVE_TYPE_INT32 |
4 | 32-bit signed integer |
| 6 | HIVE_TYPE_INT64 |
5 | 64-bit signed integer |
| 7 | HIVE_TYPE_UINT8 |
6 | 8-bit unsigned integer |
| 8 | HIVE_TYPE_UINT16 |
7 | 16-bit unsigned integer |
| 9 | HIVE_TYPE_UINT32 |
8 | 32-bit unsigned integer |
| 10 | HIVE_TYPE_UINT64 |
9 | 64-bit unsigned integer |
| 11 | HIVE_TYPE_FLOAT |
10 | 32-bit floating-point number |
| 12 | HIVE_TYPE_DOUBLE |
11 | 64-bit floating-point number |
| 13 | HIVE_TYPE_STRING |
13 | String |
| 14 | HIVE_TYPE_BINARY |
14 | Binary data |
| 15 | HIVE_TYPE_FILE |
16 | File data |
Description
This represents the base type of the column when creating a column for the OUT Port or retrieving column information from the IN Port.
HIVE_DATA_TYPE … HIVE column data type#
Structure to identify the data type of the column
Definition
typedef struct _tag_HIVE_DATA_TYPE {
uint8_t type;
uint8_t array;
} HIVE_DATA_TYPE;
Members
| No | Item | Description |
|---|---|---|
| 1 | uint8_t type |
Primitive type |
| 2 | uint8_t array |
Number of array elements |
Description
This structure indicates the data type of the column when creating a column for the OUT Port or retrieving column information from the IN Port.
The column data type can not only be the scalar type but also the array type, and so if the array type is specified, array is set to the number of elements. However, array = 0 indicates that the data type is scalar.
The following primitive types supports scalar only. Always set array to 0 because it cannot be an array.
HIVE_TYPE_TIMESTAMPHIVE_TYPE_STRINGHIVE_TYPE_BINARYHIVE_TYPE_FILE
HIVE_COMPONENT … Component instance#
Component instance information
Definition
typedef struct {
void *user_data;
} *HIVE_COMPONENT;
Members
| No | Item | Description |
|---|---|---|
| 1 | void *user_data |
Dedicated member that can be freely referenced and edited on the component side |
Description
This is a pointer to a structure that holds component execution information.
In addition to the above definition, other members are defined for the system side that controls components to reference and identify individual components.
It is required when calling various APIs, and so use it as an argument.
The user can view and edit user_data arbitrarily.
Use this if you have data that should persist beyond the component's callback function.
hive_interval_proc_t … Periodic function signature#
Function interface typedef specified when the hive_component_interval_call API is used.
Definition
typedef bool (*hive_interval_proc_t)(HIVE_COMPONENT component, void *data, hive_time_t now, int skipped, HIVE_STATUS status);
Arguments
| No | Item | Description |
|---|---|---|
| 1 | HIVE_COMPONENT component |
Component instancecomponent passed at the time of calling hive_component_interval_call. |
| 2 | void *data |
User data Arbitrary pointer specified by hive_component_interval_call. |
| 3 | hive_time_t now |
Timestamp of the time this function is called during each periodic execution |
| 4 | int skipped |
Number of skips of the periodic task that is not processed in time and is skipped |
| 5 | HIVE_STATUS status |
status used to register error information or the like |
Return value
- true: To continue the periodic processing
- false: To stop the periodic processing
Description
Function interface typedef specified when the hive_component_interval_call API is used.
Define periodic functions so that they match this declaration.
The return value of this function determines whether further periodic processing continues or stops. Ensure that true is returned unless an error prevents further processing from continuing.
HIVE_COLUMN_READ_RESULT … Result of reading column information (window data)#
Structure to store the result of reading column values from the IN Port
Definition
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;
Members
| No | Item | Description |
|---|---|---|
| 1 | hive_time_t timerange_begin |
Leading time in the time range of the data contained in this structure |
| 2 | hive_time_t timerange_end |
Last time in the time range of the data contained in this structure |
| 3 | const HIVE_INCOLUMN_LIST *incolumn_list |
List of columns connected to the IN Port |
| 6 | uint64_t window_id |
Window ID of this data |
| 6 | uint64_t event_id |
Event ID of this data |
| 6 | HIVE_RECORD *statistics_record |
Aggregation record |
| 6 | bool is_continued |
Whether the window continues to the next READ_RESULT |
| 4 | const char *buffer |
Space used internally by the system. Not to access |
| 5 | size_t buffer_size |
Space used internally by the system. Not to access |
Description
This is a data type received as a return value when the hive_continuous_reader_read() API is used.
This single structure holds data of one window. The window range varies depending on the IN Port settings.
To retrieve data from this structure, use HIVE_GET_RECORD_ITERATOR() or HIVE_RECORD_ITERATOR_GET_NEXT().
HIVE_RECORD … Column data record#
Structure that consolidates data of various columns with the same timestamp contained in window data
Definition
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;
Members
| No | Item | Description |
|---|---|---|
| 1 | uint8_t record_type |
Record type |
| 2 | uint8_t unused |
Unused space |
| 3 | uint16_t data_count |
Number of data in the record |
| 4 | uint32_t data_size |
Number of bytes of all data in the record |
| 5 | uint64_t timestamp |
Record timestamp |
| 6 | uint32_t offset[0] |
Space used internally by the system. Not to access |
Description
This is a data set with the same timestamp in the window data acquired from the IN Port.
It is acquirable with HIVE_RECORD_ITERATOR_GET_NEXT().
The number of data contained in this record, acquirable with data_count, is the same as the number of columns in incolumn_list of the window data.
Each piece of data in the record is accessible with HIVE_RECORD_GET_DATA(record, i).
HIVE_RECORD_DATA … Record data#
Structure containing individual data contained in a record
Definition
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;
Members
| No | Item | Description |
|---|---|---|
| 1 | uint16_t index |
Unused space |
| 2 | uint16_t stat_type |
Aggregation type of this data |
| 3 | uint32_t data_size |
Data size |
| 4 | uint64_t timestamp |
Timestamp |
| 5 | char data[0] |
Data |
Description
This is a structure that holds individual data in a record.
The data member is defined as a zero element char array, but actually has enough memory for data_size.
However, a data_size of 0 indicates that no data exists for this timestamp. Note that the data pointer will not be NULL even in this event.
HIVE_COLUMN_OPTIONS … Column options#
Structure to store optional information for column creation
Definition
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})
Members
| No | Item | Description |
|---|---|---|
| 1 | hive_column_type_t type |
Column type (column_type_low or column_type_middle) |
| 2 | double sampling_rate |
Sampling rate |
| 3 | int compression_unit |
Compression unit |
| 4 | int fixed_size_binary |
Binary fixed size |
| 5 | int max_binary_size |
Binary maximum size |
Description
This is optional information supplied as the fifth argument when a column is created with hive_outport_create_column(). This is not required.
Macro
The macro HIVE_COLUMN_OPTION_NONE is the default option definition. Normally use this macro.
The macro HIVE_COLUMN_OPTION_MIDDLE(r) is optional information for defining the middle type column. For middle columns, sampling rate specification is required.
HIVE_API_ERROR … API error#
API error information structure
Definition
typedef struct hive_HIVE_API_ERROR {
uint32_t code;
int system_errno;
int db_errno;
} HIVE_API_ERROR;
Members
| No | Item | Description |
|---|---|---|
| 1 | uint32_t code |
Numeric value representing the error type |
| 2 | int system_errno |
System error number |
| 3 | int db_errno |
Database error number |
Description
This structure holds the error type and detailed information when an API error occurs.
If an error occurs, the hive_get_api_error() function is useful to get this information.
code contains a numerical value that identifies the error that occurred.
If the API error is a system error, the error number is stored in system_errno. If it is not a system error, system_errno is 0.
If it is attributable to a database system error, that error number is stored in db_errno. If it is not attributable to a database system error, db_errno is 0.