## preludedb-sql

preludedb-sql

## Synopsis

    #define             PRELUDEDB_SQL_TIMESTAMP_STRING_SIZE
    enum                preludedb_sql_time_constraint_type_t;
    typedef             preludedb_sql_t;
    typedef             preludedb_sql_table_t;
    typedef             preludedb_sql_row_t;
    typedef             preludedb_sql_field_t;
    int                 preludedb_sql_new                   (preludedb_sql_t **new,
                                                             const char *type,
                                                             preludedb_sql_settings_t *settings);
    void                preludedb_sql_destroy               (preludedb_sql_t *sql);
    int                 preludedb_sql_enable_query_logging  (preludedb_sql_t *sql,
                                                             const char *filename);
    void                preludedb_sql_disable_query_logging (preludedb_sql_t *sql);
    const char *        preludedb_sql_get_plugin_error      (preludedb_sql_t *sql);
    int                 preludedb_sql_query                 (preludedb_sql_t *sql,
                                                             const char *query,
                                                             preludedb_sql_table_t **table);
    int                 preludedb_sql_query_sprintf         (preludedb_sql_t *sql,
                                                             preludedb_sql_table_t **table,
                                                             const char *format,
                                                             ...);
    int                 preludedb_sql_insert                (preludedb_sql_t *sql,
                                                             const char *table,
                                                             const char *fields,
                                                             const char *format,
                                                             ...);
    int                 preludedb_sql_build_limit_offset_string
                                                            (preludedb_sql_t *sql,
                                                             int limit,
                                                             int offset,
                                                             prelude_string_t *output);
    int                 preludedb_sql_transaction_start     (preludedb_sql_t *sql);
    int                 preludedb_sql_transaction_end       (preludedb_sql_t *sql);
    int                 preludedb_sql_transaction_abort     (preludedb_sql_t *sql);
    int                 preludedb_sql_escape_fast           (preludedb_sql_t *sql,
                                                             const char *input,
                                                             size_t input_size,
                                                             char **output);
    int                 preludedb_sql_escape                (preludedb_sql_t *sql,
                                                             const char *input,
                                                             char **output);
    int                 preludedb_sql_escape_binary         (preludedb_sql_t *sql,
                                                             unsigned char *input,
                                                             size_t input_size,
                                                             char **output);
    int                 preludedb_sql_unescape_binary       (preludedb_sql_t *sql,
                                                             const char *input,
                                                             size_t input_size,
                                                             unsigned char **output,
                                                             size_t *output_size);
    void                preludedb_sql_table_destroy         (preludedb_sql_table_t *table);
    const char *        preludedb_sql_table_get_column_name (preludedb_sql_table_t *table,
                                                             unsigned int column_num);
    int                 preludedb_sql_table_get_column_num  (preludedb_sql_table_t *table,
                                                             const char *column_name);
    unsigned int        preludedb_sql_table_get_column_count
                                                            (preludedb_sql_table_t *table);
    unsigned int        preludedb_sql_table_get_row_count   (preludedb_sql_table_t *table);
    int                 preludedb_sql_table_fetch_row       (preludedb_sql_table_t *table,
                                                             preludedb_sql_row_t **row);
    int                 preludedb_sql_row_fetch_field       (preludedb_sql_row_t *row,
                                                             unsigned int column_num,
                                                             preludedb_sql_field_t **field);
    int                 preludedb_sql_row_fetch_field_by_name
                                                            (preludedb_sql_row_t *row,
                                                             const char *column_name,
                                                             preludedb_sql_field_t **field);
    const char *        preludedb_sql_field_get_value       (preludedb_sql_field_t *field);
    size_t              preludedb_sql_field_get_len         (preludedb_sql_field_t *field);
    int                 preludedb_sql_field_to_int8         (preludedb_sql_field_t *field,
                                                             int8_t *value);
    int                 preludedb_sql_field_to_uint8        (preludedb_sql_field_t *field,
                                                             uint8_t *value);
    int                 preludedb_sql_field_to_int16        (preludedb_sql_field_t *field,
                                                             int16_t *value);
    int                 preludedb_sql_field_to_uint16       (preludedb_sql_field_t *field,
                                                             uint16_t *value);
    int                 preludedb_sql_field_to_int32        (preludedb_sql_field_t *field,
                                                             int32_t *value);
    int                 preludedb_sql_field_to_uint32       (preludedb_sql_field_t *field,
                                                             uint32_t *value);
    int                 preludedb_sql_field_to_int64        (preludedb_sql_field_t *field,
                                                             int64_t *value);
    int                 preludedb_sql_field_to_uint64       (preludedb_sql_field_t *field,
                                                             uint64_t *value);
    int                 preludedb_sql_field_to_float        (preludedb_sql_field_t *field,
                                                             float *value);
    int                 preludedb_sql_field_to_double       (preludedb_sql_field_t *field,
                                                             double *value);
    int                 preludedb_sql_field_to_string       (preludedb_sql_field_t *field,
                                                             prelude_string_t *output);
    int                 preludedb_sql_build_criterion_string
                                                            (preludedb_sql_t *sql,
                                                             prelude_string_t *output,
                                                             const char *field,
                                                             idmef_criterion_operator_t operator,
                                                             idmef_criterion_value_t *value);
    int                 preludedb_sql_time_from_timestamp   (idmef_time_t *time,
                                                             const char *time_buf,
                                                             int32_t gmtoff,
                                                             uint32_t usec);
    int                 preludedb_sql_time_to_timestamp     (preludedb_sql_t *sql,
                                                             const idmef_time_t *time,
                                                             char *time_buf,
                                                             size_t time_buf_size,
                                                             char *gmtoff_buf,
                                                             size_t gmtoff_buf_size,
                                                             char *usec_buf,
                                                             size_t usec_buf_size);

## Description

## Details

### PRELUDEDB_SQL_TIMESTAMP_STRING_SIZE

    #define PRELUDEDB_SQL_TIMESTAMP_STRING_SIZE 128

### enum preludedb_sql_time_constraint_type_t

    typedef enum {
    	PRELUDEDB_SQL_TIME_CONSTRAINT_YEAR,
    	PRELUDEDB_SQL_TIME_CONSTRAINT_MONTH,
    	PRELUDEDB_SQL_TIME_CONSTRAINT_YDAY,
    	PRELUDEDB_SQL_TIME_CONSTRAINT_MDAY,
    	PRELUDEDB_SQL_TIME_CONSTRAINT_WDAY,
    	PRELUDEDB_SQL_TIME_CONSTRAINT_HOUR,
    	PRELUDEDB_SQL_TIME_CONSTRAINT_MIN,
    	PRELUDEDB_SQL_TIME_CONSTRAINT_SEC
    } preludedb_sql_time_constraint_type_t;

### preludedb_sql_t

    typedef struct preludedb_sql preludedb_sql_t;

### preludedb_sql_table_t

    typedef struct preludedb_sql_table preludedb_sql_table_t;

### preludedb_sql_row_t

    typedef struct preludedb_sql_row preludedb_sql_row_t;

### preludedb_sql_field_t

    typedef struct preludedb_sql_field preludedb_sql_field_t;

### preludedb_sql_new ()

    int                 preludedb_sql_new                   (preludedb_sql_t **new,
                                                             const char *type,
                                                             preludedb_sql_settings_t *settings);

This function initialize the `new` object, load and setup the plugin that handle the database named `type` with the configuration stored in `settings`.

`new` : | Pointer to a sql object to initialize.
`type` : | Type of the database.
`settings` : | Settings for the choosen database.
Returns : | 0 on success or a negative value if an error occur.

### preludedb_sql_destroy ()

    void                preludedb_sql_destroy               (preludedb_sql_t *sql);

Destroy `sql` and the underlying plugin.

`sql` : | Pointer to a sql object.

### preludedb_sql_enable_query_logging ()

    int                 preludedb_sql_enable_query_logging  (preludedb_sql_t *sql,
                                                             const char *filename);

Log all queries in the specified file.

`sql` : | Pointer to a sql object.
`filename` : | Where the logs will be written.
Returns : | 0 on success, or a negative value if an error occur.

### preludedb_sql_disable_query_logging ()

    void                preludedb_sql_disable_query_logging (preludedb_sql_t *sql);

Disable query logging.

`sql` : | Pointer to a sql object.

### preludedb_sql_get_plugin_error ()

    const char *        preludedb_sql_get_plugin_error      (preludedb_sql_t *sql);

### Warning

`preludedb_sql_get_plugin_error` is deprecated and should not be used in newly-written code. Use `preludedb_strerror()`.

Get sql plugin specific error message.

`sql` : | Pointer to a sql object.
Returns : | a non NULL pointer or a NULL pointer if no error is available.

### preludedb_sql_query ()

    int                 preludedb_sql_query                 (preludedb_sql_t *sql,
                                                             const char *query,
                                                             preludedb_sql_table_t **table);

Execute a SQL query.

`sql` : | Pointer to a sql object.
`query` : | The SQL query to execute.
`table` : | Pointer to a table where the query result will be stored if the type of query return results (i.e a SELECT can results, but an INSERT never results) and if the query is sucessfull.
Returns : | the number of result or a negative value if an error occured.

### preludedb_sql_query_sprintf ()

    int                 preludedb_sql_query_sprintf         (preludedb_sql_t *sql,
                                                             preludedb_sql_table_t **table,
                                                             const char *format,
                                                             ...);

Execute a SQL query.

`sql` : | Pointer to a sql object.
`table` : | Pointer to a table where the query result will be stored if the type of query return results (i.e a SELECT can results, but an INSERT never results) and if the query is sucessfull.
`format` : | The SQL query to execute in a printf format string.
`...` : | Arguments referenced in `format`.
Returns : | 1 if the query returns results, 0 if it does not, or negative value if an error occur.

### preludedb_sql_insert ()

    int                 preludedb_sql_insert                (preludedb_sql_t *sql,
                                                             const char *table,
                                                             const char *fields,
                                                             const char *format,
                                                             ...);

Insert values in a table.

`sql` : | Pointer to a sql object.
`table` : | the name of the table where to insert values.
`fields` : | a list of comma separated field names where the values will be inserted.
`format` : | The values to insert in a printf format string.
`...` : | Argument referenced throught `format`.
Returns : | 0 on success or a negative value if an error occur.

### preludedb_sql_build_limit_offset_string ()

    int                 preludedb_sql_build_limit_offset_string
                                                            (preludedb_sql_t *sql,
                                                             int limit,
                                                             int offset,
                                                             prelude_string_t *output);

Build a limit/offset string for a SQL query, depending on the underlying type of database.

`sql` : | Pointer to a sql object.
`limit` : | The limit value, a value inferior to zero will disable the limit.
`offset` : | The offset value, a value inferior to zero will disable the offset.
`output` : | Where the limit/offset built string will be stored.
Returns : | 0 on success or a negative value if an error occur.

### preludedb_sql_transaction_start ()

    int                 preludedb_sql_transaction_start     (preludedb_sql_t *sql);

Begin a sql transaction.

`sql` : | Pointer to a sql object.
Returns : | 0 on success or a negative value if an error occur.

### preludedb_sql_transaction_end ()

    int                 preludedb_sql_transaction_end       (preludedb_sql_t *sql);

Finish a sql transaction (SQL COMMIT command).

`sql` : | Pointer to a sql object.
Returns : | 0 on success or a negative value if an error occur.

### preludedb_sql_transaction_abort ()

    int                 preludedb_sql_transaction_abort     (preludedb_sql_t *sql);

Abort a sql transaction (SQL ROLLBACK command).

`sql` : | Pointer to a sql object.
Returns : | 0 on success or a negative value if an error occur.

### preludedb_sql_escape_fast ()

    int                 preludedb_sql_escape_fast           (preludedb_sql_t *sql,
                                                             const char *input,
                                                             size_t input_size,
                                                             char **output);

Escape a string buffer.

`sql` : | Pointer to a sql object.
`input` : | Buffer to escape
`input_size` : | Buffer size.
`output` : | Where the new escaped buffer will be stored.
Returns : | 0 on success or a negative value if an error occur.

### preludedb_sql_escape ()

    int                 preludedb_sql_escape                (preludedb_sql_t *sql,
                                                             const char *input,
                                                             char **output);

Escape a string buffer.

`sql` : | Pointer to a sql object.
`input` : | Buffer to escape.
`output` : | Where the new escaped buffer will be stored.
Returns : | 0 on success or a negative value if an error occur.

### preludedb_sql_escape_binary ()

    int                 preludedb_sql_escape_binary         (preludedb_sql_t *sql,
                                                             unsigned char *input,
                                                             size_t input_size,
                                                             char **output);

Escape a binary buffer.

`sql` : | Pointer to a sql object.
`input` : | Buffer to escape.
`input_size` : | Buffer size.
`output` : | Where the new escaped buffer will be stored.
Returns : | 0 on success or a negative value if an error occur.

### preludedb_sql_unescape_binary ()

    int                 preludedb_sql_unescape_binary       (preludedb_sql_t *sql,
                                                             const char *input,
                                                             size_t input_size,
                                                             unsigned char **output,
                                                             size_t *output_size);

Unescape to a binary buffer.

`sql` : | Pointer to a sql object.
`input` : | Buffer to unescape.
`input_size` : | Buffer size.
`output` : | Where the new unescaped buffer will be stored.
`output_size` : | Size of the new unescape buffer.
Returns : | 0 on success or a negative value if an error occur.

### preludedb_sql_table_destroy ()

    void                preludedb_sql_table_destroy         (preludedb_sql_table_t *table);

Destroy the `table` object.

`table` : | Pointer to a table object.

### preludedb_sql_table_get_column_name ()

    const char *        preludedb_sql_table_get_column_name (preludedb_sql_table_t *table,
                                                             unsigned int column_num);

Get the name of the column number `column_num`.

`table` : | Pointer to a table object.
`column_num` : | Column number.
Returns : | the name of the column or NULL if the column `column_num` could not be found.

### preludedb_sql_table_get_column_num ()

    int                 preludedb_sql_table_get_column_num  (preludedb_sql_table_t *table,
                                                             const char *column_name);

Get the number of the column named `column_name`.

`table` : | Pointer to a table object.
`column_name` : | Column name.
Returns : | the number of the column or -1 if the column `column_name` could not be found.

### preludedb_sql_table_get_column_count ()

    unsigned int        preludedb_sql_table_get_column_count
                                                            (preludedb_sql_table_t *table);

Get the the number of columns.

`table` : | Pointer to a table object.
Returns : | the number of columns.

### preludedb_sql_table_get_row_count ()

    unsigned int        preludedb_sql_table_get_row_count   (preludedb_sql_table_t *table);

`table` : |
Returns : |

### preludedb_sql_table_fetch_row ()

    int                 preludedb_sql_table_fetch_row       (preludedb_sql_table_t *table,
                                                             preludedb_sql_row_t **row);

Fetch the next table's row.

`table` : | Pointer to a table object.
`row` : | Pointer to the row object where the result will be stored.
Returns : | 1 if the table returns a new row, 0 if there is no more rows to fetch or a negative value if an error occur.

### preludedb_sql_row_fetch_field ()

    int                 preludedb_sql_row_fetch_field       (preludedb_sql_row_t *row,
                                                             unsigned int column_num,
                                                             preludedb_sql_field_t **field);

Fetch the field of column `column_num`

`row` : | Pointer to a row object.
`column_num` : | The column number of the field to be fetched.
`field` : | Pointer to the field object where the result will be stored.
Returns : | 1 if the row returns a non-empty field, 0 if it returns an empty field, or a negative value if an error occur.

### preludedb_sql_row_fetch_field_by_name ()

    int                 preludedb_sql_row_fetch_field_by_name
                                                            (preludedb_sql_row_t *row,
                                                             const char *column_name,
                                                             preludedb_sql_field_t **field);

Fetch the field of column `column_name`

`row` : | Pointer to a row object.
`column_name` : | The column name of the field to be fetched.
`field` : | Pointer to the field object where the result will be stored.
Returns : | 1 if the row returns a non-empty field, 0 if it returns an empty field, or a negative value if an error occur.

### preludedb_sql_field_get_value ()

    const char *        preludedb_sql_field_get_value       (preludedb_sql_field_t *field);

Get the raw value of the field.

`field` : | Pointer to a field object.
Returns : | field value.

### preludedb_sql_field_get_len ()

    size_t              preludedb_sql_field_get_len         (preludedb_sql_field_t *field);

Get the field value length.

`field` : | Pointer to a field object.
Returns : | field value length.

### preludedb_sql_field_to_int8 ()

    int                 preludedb_sql_field_to_int8         (preludedb_sql_field_t *field,
                                                             int8_t *value);

`field` : |
`value` : |
Returns : |

### preludedb_sql_field_to_uint8 ()

    int                 preludedb_sql_field_to_uint8        (preludedb_sql_field_t *field,
                                                             uint8_t *value);

`field` : |
`value` : |
Returns : |

### preludedb_sql_field_to_int16 ()

    int                 preludedb_sql_field_to_int16        (preludedb_sql_field_t *field,
                                                             int16_t *value);

`field` : |
`value` : |
Returns : |

### preludedb_sql_field_to_uint16 ()

    int                 preludedb_sql_field_to_uint16       (preludedb_sql_field_t *field,
                                                             uint16_t *value);

`field` : |
`value` : |
Returns : |

### preludedb_sql_field_to_int32 ()

    int                 preludedb_sql_field_to_int32        (preludedb_sql_field_t *field,
                                                             int32_t *value);

`field` : |
`value` : |
Returns : |

### preludedb_sql_field_to_uint32 ()

    int                 preludedb_sql_field_to_uint32       (preludedb_sql_field_t *field,
                                                             uint32_t *value);

`field` : |
`value` : |
Returns : |

### preludedb_sql_field_to_int64 ()

    int                 preludedb_sql_field_to_int64        (preludedb_sql_field_t *field,
                                                             int64_t *value);

`field` : |
`value` : |
Returns : |

### preludedb_sql_field_to_uint64 ()

    int                 preludedb_sql_field_to_uint64       (preludedb_sql_field_t *field,
                                                             uint64_t *value);

`field` : |
`value` : |
Returns : |

### preludedb_sql_field_to_float ()

    int                 preludedb_sql_field_to_float        (preludedb_sql_field_t *field,
                                                             float *value);

`field` : |
`value` : |
Returns : |

### preludedb_sql_field_to_double ()

    int                 preludedb_sql_field_to_double       (preludedb_sql_field_t *field,
                                                             double *value);

`field` : |
`value` : |
Returns : |

### preludedb_sql_field_to_string ()

    int                 preludedb_sql_field_to_string       (preludedb_sql_field_t *field,
                                                             prelude_string_t *output);

Get the string value of `field`.

`field` : | Pointer to a field type.
`output` : | Pointer to a string object where the field value will be added.
Returns : | 0 on success, or a negative value if an error occur.

### preludedb_sql_build_criterion_string ()

    int                 preludedb_sql_build_criterion_string
                                                            (preludedb_sql_t *sql,
                                                             prelude_string_t *output,
                                                             const char *field,
                                                             idmef_criterion_operator_t operator,
                                                             idmef_criterion_value_t *value);

Build a sql "field operator value" string.

`sql` : | Pointer to a sql object.
`output` : | Pointer to a string object, where the result content will be stored.
`field` : | The sql field name.
`operator` : | The criterion operator.
`value` : | The criterion value.
Returns : | 0 on success, or a negative value if an error occur.

### preludedb_sql_time_from_timestamp ()

    int                 preludedb_sql_time_from_timestamp   (idmef_time_t *time,
                                                             const char *time_buf,
                                                             int32_t gmtoff,
                                                             uint32_t usec);

Set an idmef time using the timestamp, GMT offset and microseconds given in input.

`time` : | Pointer to a time object.
`time_buf` : | SQL timestamp.
`gmtoff` : | GMT offset.
`usec` : | Microseconds.
Returns : | 0 on success, or a negative value if an error occur.

### preludedb_sql_time_to_timestamp ()

    int                 preludedb_sql_time_to_timestamp     (preludedb_sql_t *sql,
                                                             const idmef_time_t *time,
                                                             char *time_buf,
                                                             size_t time_buf_size,
                                                             char *gmtoff_buf,
                                                             size_t gmtoff_buf_size,
                                                             char *usec_buf,
                                                             size_t usec_buf_size);

Set timestamp, GMT offset, and microseconds buffers with the idmef time object given in input.

`sql` : |
`time` : | Pointer to a time object.
`time_buf` : | SQL timestamp.
`time_buf_size` : | SQL timestamp buffer size.
`gmtoff_buf` : | GMT offset buffer.
`gmtoff_buf_size` : | GMT offset buffer size.
`usec_buf` : | Microseconds buffer.
`usec_buf_size` : | Microseconds buffer size.
Returns : | 0 on success, or a negative value if an error occur.