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

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;