preludedb-sql: libpreludedb Reference Manual

## preludedb-sql preludedb-sql |

## Functions

int | preludedb_sql_new ()
void | preludedb_sql_destroy ()
int | preludedb_sql_enable_query_logging ()
void | preludedb_sql_disable_query_logging ()
const char * | preludedb_sql_get_plugin_error ()
int | preludedb_sql_query ()
int | preludedb_sql_query_sprintf ()
int | preludedb_sql_insert ()
int | preludedb_sql_build_limit_offset_string ()
int | preludedb_sql_transaction_start ()
int | preludedb_sql_transaction_end ()
int | preludedb_sql_transaction_abort ()
int | preludedb_sql_escape_fast ()
int | preludedb_sql_escape ()
int | preludedb_sql_escape_binary ()
int | preludedb_sql_unescape_binary ()
void | preludedb_sql_table_destroy ()
const char * | preludedb_sql_table_get_column_name ()
int | preludedb_sql_table_get_column_num ()
unsigned int | preludedb_sql_table_get_column_count ()
unsigned int | preludedb_sql_table_get_row_count ()
int | preludedb_sql_table_fetch_row ()
int | preludedb_sql_row_fetch_field ()
int | preludedb_sql_row_fetch_field_by_name ()
char * | preludedb_sql_field_get_value ()
size_t | preludedb_sql_field_get_len ()
int | preludedb_sql_field_to_int8 ()
int | preludedb_sql_field_to_uint8 ()
int | preludedb_sql_field_to_int16 ()
int | preludedb_sql_field_to_uint16 ()
int | preludedb_sql_field_to_int32 ()
int | preludedb_sql_field_to_uint32 ()
int | preludedb_sql_field_to_int64 ()
int | preludedb_sql_field_to_uint64 ()
int | preludedb_sql_field_to_float ()
int | preludedb_sql_field_to_double ()
int | preludedb_sql_field_to_string ()
int | preludedb_sql_build_criterion_string ()
int | preludedb_sql_time_from_timestamp ()
int | preludedb_sql_time_to_timestamp ()

## Types and Values

#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

## Description

## Functions

### preludedb_sql_new ()

    int
    preludedb_sql_new (preludedb_sql_t **newdb,
                       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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

sql | Pointer to a sql object. |

### preludedb_sql_get_plugin_error ()

    const char *
    preludedb_sql_get_plugin_error (preludedb_sql_t *sql);

`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.

#### Parameters

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.

#### Parameters

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 returns results (i.e a SELECT can results, but an INSERT never results) and if the query is successful. |

#### Returns

number of affected rows, -1 if an error occurred.

### 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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).

#### Parameters

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).

#### Parameters

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.

#### Parameters

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.

#### Parameters

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,
                                 const unsigned char *input,
                                 size_t input_size,
                                 char **output);

Escape a binary buffer.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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);

Get the the number of row in the table. Depending on the database backend, this might require retrieving all rows.

#### Parameters

table | Pointer to a table object. |

#### Returns

the number of columns.

### 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.

#### Parameters

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,
                                   int column_num,
                                   preludedb_sql_field_t **field);

`preludedb_sql_row_fetch_field` is deprecated and should not be used in newly-written code.

use `preludedb_sql_row_get_field()` instead. Fetch the field of column `column_num`

#### Parameters

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);

`preludedb_sql_row_fetch_field_by_name` is deprecated and should not be used in newly-written code.

use `preludedb_sql_row_get_field_by_name()` instead. Fetch the field of column `column_name`

#### Parameters

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 ()

    char *
    preludedb_sql_field_get_value (preludedb_sql_field_t *field);

Get the raw value of the field.

#### Parameters

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.

#### Parameters

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);

### preludedb_sql_field_to_uint8 ()

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

### preludedb_sql_field_to_int16 ()

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

### preludedb_sql_field_to_uint16 ()

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

### preludedb_sql_field_to_int32 ()

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

### preludedb_sql_field_to_uint32 ()

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

### preludedb_sql_field_to_int64 ()

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

### preludedb_sql_field_to_uint64 ()

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

### preludedb_sql_field_to_float ()

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

### preludedb_sql_field_to_double ()

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

### 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` .

#### Parameters

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 idmef_operator,
                                          idmef_criterion_value_t *value);

Build a sql "field operator value" string.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

## Types and Values

### PRELUDEDB_SQL_TIMESTAMP_STRING_SIZE

    #define PRELUDEDB_SQL_TIMESTAMP_STRING_SIZE 128

### enum preludedb_sql_time_constraint_type_t

#### Members

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_MSEC |  |
PRELUDEDB_SQL_TIME_CONSTRAINT_USEC |  |
PRELUDEDB_SQL_TIME_CONSTRAINT_QUARTER |  |

### 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;