preludedb: libpreludedb Reference Manual

## preludedb preludedb |

## Functions

int | preludedb_init ()
void | preludedb_deinit ()
int | preludedb_new ()
void | preludedb_destroy ()
const char * | preludedb_get_format_name ()
const char * | preludedb_get_format_version ()
int | preludedb_set_format ()
preludedb_sql_t * | preludedb_get_sql ()
void | preludedb_result_idents_destroy ()
void | preludedb_result_values_destroy ()
char * | preludedb_get_error ()
int | preludedb_insert_message ()
int | preludedb_get_alert_idents ()
int | preludedb_get_heartbeat_idents ()
int | preludedb_get_alert ()
int | preludedb_get_heartbeat ()
int | preludedb_delete_alert ()
int | preludedb_delete_heartbeat ()
ssize_t | preludedb_delete_alert_from_list ()
ssize_t | preludedb_delete_alert_from_result_idents ()
ssize_t | preludedb_delete_heartbeat_from_list ()
ssize_t | preludedb_delete_heartbeat_from_result_idents ()
int | preludedb_get_values ()
int | preludedb_transaction_abort ()
int | preludedb_transaction_end ()
int | preludedb_transaction_start ()

## Types and Values

typedef | preludedb_t
typedef | preludedb_result_idents_t
typedef | preludedb_result_values_t
enum | preludedb_result_idents_order_t
#define | PRELUDEDB_ERRBUF_SIZE

## Description

## Functions

### preludedb_init ()

    int
    preludedb_init (void);

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

#### Parameters

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.

#### Parameters

db | Pointer to a db object. |

### preludedb_get_format_name ()

    const char *
    preludedb_get_format_name (preludedb_t *db);

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

result | Pointer to an idents result object. |

### preludedb_result_values_destroy ()

    void
    preludedb_result_values_destroy (preludedb_result_values_t *result);

Destroy the `result` object.

#### Parameters

result | Pointer to a result values object. |

### preludedb_get_error ()

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

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

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.

FIXME: deprecated.

#### Parameters

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.

#### Parameters

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

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

#### Parameters

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

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

Delete all alerts from ident stored within `idents` .

#### Parameters

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

#### Parameters

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

Delete all heartbeat from ident stored within `idents` .

#### Parameters

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

#### Parameters

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

#### Parameters

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

1 if there are result, 0 if there are none, 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

db | Pointer to a preludedb_t object. |

#### Returns

0 on success or a negative value if an error occur.

## Types and Values

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

#### Members

PRELUDEDB_RESULT_IDENTS_ORDER_BY_NONE |  |
PRELUDEDB_RESULT_IDENTS_ORDER_BY_CREATE_TIME_DESC |  |
PRELUDEDB_RESULT_IDENTS_ORDER_BY_CREATE_TIME_ASC |  |

### PRELUDEDB_ERRBUF_SIZE

    #define PRELUDEDB_ERRBUF_SIZE 512