## preludedb

preludedb

## Synopsis

    typedef             preludedb_t;
    typedef             preludedb_result_idents_t;
    typedef             preludedb_result_values_t;
    enum                preludedb_result_idents_order_t;
    #define             PRELUDEDB_ERRBUF_SIZE
    int                 preludedb_init                      (void);
    void                preludedb_deinit                    (void);
    int                 preludedb_new                       (preludedb_t **db,
                                                             preludedb_sql_t *sql,
                                                             const char *format_name,
                                                             char *errbuf,
                                                             size_t size);
    void                preludedb_destroy                   (preludedb_t *db);
    const char *        preludedb_get_format_name           (preludedb_t *db);
    const char *        preludedb_get_format_version        (preludedb_t *db);
    int                 preludedb_set_format                (preludedb_t *db,
                                                             const char *format_name);
    preludedb_sql_t *   preludedb_get_sql                   (preludedb_t *db);
    void                preludedb_result_idents_destroy     (preludedb_result_idents_t *result);
    int                 preludedb_result_idents_get_next    (preludedb_result_idents_t *result,
                                                             uint64_t *ident);
    void                preludedb_result_values_destroy     (preludedb_result_values_t *result);
    int                 preludedb_result_values_get_next    (preludedb_result_values_t *result,
                                                             idmef_value_t ***values);
    char *              preludedb_get_error                 (preludedb_t *db,
                                                             preludedb_error_t error,
                                                             char *errbuf,
                                                             size_t size);
    int                 preludedb_insert_message            (preludedb_t *db,
                                                             idmef_message_t *message);
    int                 preludedb_get_alert_idents          (preludedb_t *db,
                                                             idmef_criteria_t *criteria,
                                                             int limit,
                                                             int offset,
                                                             preludedb_result_idents_order_t order,
                                                             preludedb_result_idents_t **result);
    int                 preludedb_get_heartbeat_idents      (preludedb_t *db,
                                                             idmef_criteria_t *criteria,
                                                             int limit,
                                                             int offset,
                                                             preludedb_result_idents_order_t order,
                                                             preludedb_result_idents_t **result);
    int                 preludedb_get_alert                 (preludedb_t *db,
                                                             uint64_t ident,
                                                             idmef_message_t **message);
    int                 preludedb_get_heartbeat             (preludedb_t *db,
                                                             uint64_t ident,
                                                             idmef_message_t **message);
    int                 preludedb_delete_alert              (preludedb_t *db,
                                                             uint64_t ident);
    int                 preludedb_delete_heartbeat          (preludedb_t *db,
                                                             uint64_t ident);
    ssize_t             preludedb_delete_alert_from_list    (preludedb_t *db,
                                                             uint64_t *idents,
                                                             size_t size);
    ssize_t             preludedb_delete_alert_from_result_idents
                                                            (preludedb_t *db,
                                                             preludedb_result_idents_t *result);
    ssize_t             preludedb_delete_heartbeat_from_list
                                                            (preludedb_t *db,
                                                             uint64_t *idents,
                                                             size_t size);
    ssize_t             preludedb_delete_heartbeat_from_result_idents
                                                            (preludedb_t *db,
                                                             preludedb_result_idents_t *result);
    int                 preludedb_get_values                (preludedb_t *db,
                                                             preludedb_path_selection_t *path_selection,
                                                             idmef_criteria_t *criteria,
                                                             prelude_bool_t distinct,
                                                             int limit,
                                                             int offset,
                                                             preludedb_result_values_t **result);
    int                 preludedb_transaction_abort         (preludedb_t *db);
    int                 preludedb_transaction_end           (preludedb_t *db);
    int                 preludedb_transaction_start         (preludedb_t *db);

## Description

## Details

### preludedb_t

    typedef struct preludedb preludedb_t;

### preludedb_result_idents_t

    typedef struct preludedb_result_idents preludedb_result_idents_t;

### preludedb_result_values_t

    typedef struct preludedb_result_values preludedb_result_values_t;

### enum preludedb_result_idents_order_t

    typedef enum {
            PRELUDEDB_RESULT_IDENTS_ORDER_BY_NONE = 0,
            PRELUDEDB_RESULT_IDENTS_ORDER_BY_CREATE_TIME_DESC = 1,
            PRELUDEDB_RESULT_IDENTS_ORDER_BY_CREATE_TIME_ASC = 2
    } preludedb_result_idents_order_t;

### PRELUDEDB_ERRBUF_SIZE

    #define PRELUDEDB_ERRBUF_SIZE 512

### preludedb_init ()

    int                 preludedb_init                      (void);

Returns : |

### preludedb_deinit ()

    void                preludedb_deinit                    (void);

### preludedb_new ()

    int                 preludedb_new                       (preludedb_t **db,
                                                             preludedb_sql_t *sql,
                                                             const char *format_name,
                                                             char *errbuf,
                                                             size_t size);

This function initialize the `db` object and detect the format of the underlying database if no format name is given.

`db` : | Pointer to a db object to initialize.
`sql` : | Pointer to a sql object.
`format_name` : | Format name of the underlying database, if NULL the format will be automatically detected
`errbuf` : | Buffer that will be set to an error message if an error occur.
`size` : | size of `errbuf`.
Returns : | 0 on success or a negative value if an error occur.

### preludedb_destroy ()

    void                preludedb_destroy                   (preludedb_t *db);

Destroy `db` object and the underlying `sql` object given as argument to preludedb_new.

`db` : | Pointer to a db object.

### preludedb_get_format_name ()

    const char *        preludedb_get_format_name           (preludedb_t *db);

`db` : | Pointer to a db object.
Returns : | the format name currently used by the `db` object.

### preludedb_get_format_version ()

    const char *        preludedb_get_format_version        (preludedb_t *db);

`db` : | Pointer to a db object.
Returns : | the format version currently used by the `db` object.

### preludedb_set_format ()

    int                 preludedb_set_format                (preludedb_t *db,
                                                             const char *format_name);

Change the current format plugin.

`db` : | Pointer to a db object.
`format_name` : | New format to use.
Returns : | 0 on success or negative value if an error occur.

### preludedb_get_sql ()

    preludedb_sql_t *   preludedb_get_sql                   (preludedb_t *db);

`db` : | Pointer to a db object.
Returns : | a pointer to the underlying sql object.

### preludedb_result_idents_destroy ()

    void                preludedb_result_idents_destroy     (preludedb_result_idents_t *result);

Destroy the `result` object.

`result` : | Pointer to an idents result object.

### preludedb_result_idents_get_next ()

    int                 preludedb_result_idents_get_next    (preludedb_result_idents_t *result,
                                                             uint64_t *ident);

Retrieve the next ident from the idents result object.

`result` : | Pointer to an idents result object.
`ident` : | Pointer to an ident where the next ident will be stored.
Returns : | 1 if an ident is available, 0 if there is no more idents available or a negative value if an error occur.

### preludedb_result_values_destroy ()

    void                preludedb_result_values_destroy     (preludedb_result_values_t *result);

Destroy the `result` object.

`result` : | Pointer to a result values object.

### preludedb_result_values_get_next ()

    int                 preludedb_result_values_get_next    (preludedb_result_values_t *result,
                                                             idmef_value_t ***values);

Retrieve the next values row from the values result object.

`result` : | Pointer to a values result object.
`values` : | Pointer to a values array where the next row of values will be stored.
Returns : | the number of returned values, 0 if there are no values or a negative value if an error occur.

### preludedb_get_error ()

    char *              preludedb_get_error                 (preludedb_t *db,
                                                             preludedb_error_t error,
                                                             char *errbuf,
                                                             size_t size);

Build an error message from the error code given as argument and from the sql plugin error string (if any) if the error code is db related.

`db` : | Pointer to a db object.
`error` : | Error code to build the error string from.
`errbuf` : | Buffer where the error message will be stored,
`size` : | size of this buffer must be PRELUDEDB_ERRBUF_SIZE.
Returns : | a pointer to the error string or NULL if an error occured.

### preludedb_insert_message ()

    int                 preludedb_insert_message            (preludedb_t *db,
                                                             idmef_message_t *message);

Insert an IDMEF message into the database.

`db` : | Pointer to a db object.
`message` : | Pointer to an IDMEF message.
Returns : | 0 on success, or a negative value if an error occur.

### preludedb_get_alert_idents ()

    int                 preludedb_get_alert_idents          (preludedb_t *db,
                                                             idmef_criteria_t *criteria,
                                                             int limit,
                                                             int offset,
                                                             preludedb_result_idents_order_t order,
                                                             preludedb_result_idents_t **result);

`db` : | Pointer to a db object.
`criteria` : | Pointer to an idmef criteria.
`limit` : | Limit of results or -1 if no limit.
`offset` : | Offset in results or -1 if no offset.
`order` : | Result order.
`result` : | Idents result.
Returns : | the number of result or a negative value if an error occured.

### preludedb_get_heartbeat_idents ()

    int                 preludedb_get_heartbeat_idents      (preludedb_t *db,
                                                             idmef_criteria_t *criteria,
                                                             int limit,
                                                             int offset,
                                                             preludedb_result_idents_order_t order,
                                                             preludedb_result_idents_t **result);

`db` : | Pointer to a db object.
`criteria` : | Pointer to an idmef criteria.
`limit` : | Limit of results or -1 if no limit.
`offset` : | Offset in results or -1 if no offset.
`order` : | Result order.
`result` : | Idents result.
Returns : | the number of result or a negative value if an error occured.

### preludedb_get_alert ()

    int                 preludedb_get_alert                 (preludedb_t *db,
                                                             uint64_t ident,
                                                             idmef_message_t **message);

`db` : | Pointer to a db object.
`ident` : | Internal database ident of the alert.
`message` : | Pointer to an idmef message object where the retrieved message will be stored.
Returns : | 0 on success or a negative value if an error occur.

### preludedb_get_heartbeat ()

    int                 preludedb_get_heartbeat             (preludedb_t *db,
                                                             uint64_t ident,
                                                             idmef_message_t **message);

`db` : | Pointer to a db object.
`ident` : | Internal database ident of the heartbeat.
`message` : | Pointer to an idmef message object where the retrieved message will be stored.
Returns : | 0 on success or a negative value if an error occur.

### preludedb_delete_alert ()

    int                 preludedb_delete_alert              (preludedb_t *db,
                                                             uint64_t ident);

Delete an alert.

`db` : | Pointer to a db object.
`ident` : | Internal database ident of the alert.
Returns : | 0 on success, or a negative value if an error occur.

### preludedb_delete_heartbeat ()

    int                 preludedb_delete_heartbeat          (preludedb_t *db,
                                                             uint64_t ident);

Delete an heartbeat.

`db` : | Pointer to a db object.
`ident` : | Internal database ident of the heartbeat.
Returns : | 0 on success, or a negative value if an error occur.

### preludedb_delete_alert_from_list ()

    ssize_t             preludedb_delete_alert_from_list    (preludedb_t *db,
                                                             uint64_t *idents,
                                                             size_t size);

Delete all alerts from ident stored within `idents`.

`db` : | Pointer to a db object.
`idents` : | Pointer to an array of idents.
`size` : | Size of `idents`.
Returns : | the number of alert deleted on success, or a negative value if an error occur.

### preludedb_delete_alert_from_result_idents ()

    ssize_t             preludedb_delete_alert_from_result_idents
                                                            (preludedb_t *db,
                                                             preludedb_result_idents_t *result);

Delete all alert from ident stored within `result`.

`db` : | Pointer to a db object.
`result` : | Pointer to an idents result object.
Returns : | the number of alert deleted on success, or a negative value if an error occur.

### preludedb_delete_heartbeat_from_list ()

    ssize_t             preludedb_delete_heartbeat_from_list
                                                            (preludedb_t *db,
                                                             uint64_t *idents,
                                                             size_t size);

Delete all heartbeat from ident stored within `idents`.

`db` : | Pointer to a db object.
`idents` : | Pointer to an array of idents.
`size` : | Size of `idents`.
Returns : | the number of heartbeat deleted on success, or a negative value if an error occur.

### preludedb_delete_heartbeat_from_result_idents ()

    ssize_t             preludedb_delete_heartbeat_from_result_idents
                                                            (preludedb_t *db,
                                                             preludedb_result_idents_t *result);

Delete all heartbeat from ident stored within `result`.

`db` : | Pointer to a db object.
`result` : | Pointer to an idents result object.
Returns : | the number of heartbeat deleted on success, or a negative value if an error occur.

### preludedb_get_values ()

    int                 preludedb_get_values                (preludedb_t *db,
                                                             preludedb_path_selection_t *path_selection,
                                                             idmef_criteria_t *criteria,
                                                             prelude_bool_t distinct,
                                                             int limit,
                                                             int offset,
                                                             preludedb_result_values_t **result);

`db` : | Pointer to a db object.
`path_selection` : | Pointer to a path selection.
`criteria` : | Pointer to a criteria object.
`distinct` : | Get distinct or not distinct result rows.
`limit` : | Limit of results or -1 if no limit.
`offset` : | Offset in results or -1 if no offset.
`result` : | Values result.
Returns : | the number of result or a negative value if an error occured.

### preludedb_transaction_abort ()

    int                 preludedb_transaction_abort         (preludedb_t *db);

Abort a sql transaction (SQL ROLLBACK command) initiated with `preludedb_transaction_start()`. Internal transaction handling will be enabled again once this function return.

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

### preludedb_transaction_end ()

    int                 preludedb_transaction_end           (preludedb_t *db);

Terminate a sql transaction (SQL COMMIT command) initiated with `preludedb_transaction_start()`. Internal transaction handling will be enabled again once this function return.

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

### preludedb_transaction_start ()

    int                 preludedb_transaction_start         (preludedb_t *db);

Begin a transaction using `db` object. Internal transaction handling will be disabled until `preludedb_transaction_end()` or `preludedb_transaction_abort()` is called.

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