Qt: adv options: fix RTL handling for synchronization
[vlc/solaris.git] / include / vlc_sql.h
blob5935fe9cba2ae08b5670ac942851ceeb88ac39eb
1 /*****************************************************************************
2 * vlc_sql.h: SQL abstraction layer
3 *****************************************************************************
4 * Copyright (C) 2009 the VideoLAN team
5 * $Id$
7 * Authors: Antoine Lejeune <phytos@videolan.org>
8 * Jean-Philippe André <jpeg@videolan.org>
9 * Srikanth Raju <srikiraju@gmail.com>
11 * This program is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; either version 2 of the License, or
14 * (at your option) any later version.
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, write to the Free Software
23 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
24 *****************************************************************************/
26 #ifndef VLC_SQL_H
27 # define VLC_SQL_H
29 # ifdef __cplusplus
30 extern "C" {
31 # endif
34 /*****************************************************************************
35 * General structure: SQL object.
36 *****************************************************************************/
38 /**
39 * Return values for the function @see sql_Run()
41 #define VLC_SQL_ROW 1
42 #define VLC_SQL_DONE 2
44 typedef struct sql_t sql_t;
45 typedef struct sql_sys_t sql_sys_t;
46 typedef struct sql_stmt_t sql_stmt_t;
48 typedef int ( *sql_query_callback_t ) ( void*, int, char**, char** );
50 typedef enum {
51 SQL_NULL,
52 SQL_INT,
53 SQL_DOUBLE,
54 SQL_TEXT,
55 SQL_BLOB
56 } sql_type_e;
58 typedef struct
60 int length;
61 union
63 int i;
64 double dbl;
65 char* psz;
66 void* ptr;
67 } value;
68 } sql_value_t;
70 struct sql_t
72 VLC_COMMON_MEMBERS
74 /** Module properties */
75 module_t *p_module;
77 /** Connection Data */
78 char *psz_host; /**< Location or host of the database */
79 char *psz_user; /**< Username used to connect to database */
80 char *psz_pass; /**< Password used to connect to database */
81 int i_port; /**< Port on which database is running */
83 /** Internal data */
84 sql_sys_t *p_sys;
86 /** All the functions are implemented as threadsafe functions */
87 /** Perform a query with a row-by-row callback function */
88 int (*pf_query_callback) ( sql_t *, const char *, sql_query_callback_t, void * );
90 /** Perform a query and return result directly */
91 int (*pf_query) ( sql_t *, const char *, char ***, int *, int * );
93 /** Get database tables */
94 int (*pf_get_tables) ( sql_t *, char *** );
96 /** Free result of a call to sql_Query or sql_GetTables */
97 void (*pf_free) ( sql_t *, char ** );
99 /** vmprintf replacement for SQL */
100 char* (*pf_vmprintf) ( const char*, va_list args );
102 /** Begin transaction */
103 int (*pf_begin) ( sql_t* );
105 /** Commit transaction */
106 int (*pf_commit) ( sql_t* );
108 /** Rollback transaction */
109 void (*pf_rollback) ( sql_t* );
111 /** Create a statement object */
112 sql_stmt_t* (*pf_prepare) ( sql_t* p_sql, const char* p_fmt,
113 int i_length );
115 /** Bind parameters to a statement */
116 int (*pf_bind) ( sql_t* p_sql, sql_stmt_t* p_stmt, int i_pos,
117 unsigned int type, const sql_value_t* p_value );
119 /** Run the prepared statement */
120 int (*pf_run) ( sql_t* p_sql, sql_stmt_t* p_stmt );
122 /** Reset the prepared statement */
123 int (*pf_reset) ( sql_t* p_sql, sql_stmt_t* p_stmt );
125 /** Destroy the statement object */
126 int (*pf_finalize) ( sql_t* p_sql, sql_stmt_t* p_stmt );
128 /** Get the datatype for a specified column */
129 int (*pf_gettype) ( sql_t* p_sql, sql_stmt_t* p_stmt, int i_col,
130 int* type );
132 /** Get the data from a specified column */
133 int (*pf_getcolumn) ( sql_t* p_sql, sql_stmt_t* p_stmt, int i_col,
134 int type, sql_value_t *p_res );
136 /** Get column size of a specified column */
137 int (*pf_getcolumnsize) ( sql_t* p_sql, sql_stmt_t* p_stmt, int i_col );
140 /*****************************************************************************
141 * SQL Function headers
142 *****************************************************************************/
145 * @brief Create a new SQL object.
146 * @param p_this Parent object to attach the SQL object to.
147 * @param psz_host URL to the database
148 * @param i_port Port on which the database is running
149 * @param psz_user Username to access the database
150 * @param psz_pass Password for the database
151 * @return The VLC SQL object, type sql_t.
153 VLC_API sql_t *sql_Create( vlc_object_t *p_this, const char *psz_name,
154 const char* psz_host, int i_port,
155 const char* psz_user, const char* psz_pass );
156 #define sql_Create( a, b, c, d, e, f ) sql_Create( VLC_OBJECT(a), b, c, d, e, f )
160 * @brief Destructor for p_sql object
161 * @param obj This p_sql object
162 * @return Nothing
164 VLC_API void sql_Destroy( vlc_object_t *obj );
165 #define sql_Destroy( a ) sql_Destroy( VLC_OBJECT( a ) )
169 * @brief Perform a query using a callback function
170 * @param p_sql This SQL object.
171 * @param psz_query The SQL query string.
172 * @param pf_callback A callback function that will be called for each row of
173 * the result: 1st argument is be p_opaque,
174 * 2nd argument is the number of columns,
175 * 3rd is the result columns (array of strings),
176 * 4th is the columns names (array of strings).
177 * @param p_opaque Any pointer to an object you may need in the callback.
178 * @return VLC_SUCCESS or VLC_EGENERIC.
179 * @note The query will not necessarily be processed in a separate thread, but
180 * it is threadsafe
182 static inline int sql_QueryCallback( sql_t *p_sql, const char *psz_query,
183 sql_query_callback_t pf_callback,
184 void *p_opaque )
186 return p_sql->pf_query_callback( p_sql, psz_query, pf_callback, p_opaque );
190 * @brief Perform a query directly
191 * @param p_sql This SQL object.
192 * @param psz_query The SQL query string.
193 * @param pppsz_result A pointer to a array of strings: result of the query.
194 * Dynamically allocated.
195 * @param pi_rows Pointer to an integer that will receive the number of result
196 * rows written.
197 * @param pi_cols Pointer to an integer that will receive the number of result
198 * columns written.
199 * @return VLC_SUCCESS or VLC_EGENERIC.
200 * @note pppsz_result will point to an array of strings, ppsz_result.
201 * This array of strings contains actually a 2D-matrix of strings where the
202 * first row (row 0) contains the SQL table header names.
203 * *pi_rows will be the number of result rows, so that the number of text rows
204 * in ppsz_result will be (*pi_rows + 1) (because of row 0).
205 * To get result[row,col] use (*pppsz_result)[ (row+1) * (*pi_cols) + col ].
206 * This function is threadsafe
208 static inline int sql_Query( sql_t *p_sql, const char *psz_query,
209 char ***pppsz_result, int *pi_rows, int *pi_cols )
211 return p_sql->pf_query( p_sql, psz_query, pppsz_result, pi_rows, pi_cols );
215 * @brief Get database table name list
216 * @param p_sql This SQL object.
217 * @param pppsz_tables Pointer to an array of strings. Dynamically allocated.
218 * Similar to pppsz_result of sql_Query but with only one row.
219 * @return Number of tables or <0 in case of error.
220 * @note This function is threadsafe
222 static inline int sql_GetTables( sql_t *p_sql, char ***pppsz_tables )
224 return p_sql->pf_get_tables( p_sql, pppsz_tables );
228 * @brief Free the result of a query.
229 * @param p_sql This SQL object.
230 * @param ppsz_result The result of sql_Query or sql_GetTables. See above.
231 * @return Nothing.
232 * @note This function is threadsafe
234 static inline void sql_Free( sql_t *p_sql, char **ppsz_result )
236 p_sql->pf_free( p_sql, ppsz_result );
240 * @brief printf-like function that can escape forbidden/reserved characters.
241 * @param p_sql This SQL object.
242 * @param psz_fmt Format of the string (with %q, %Q and %z enabled).
243 * @param ... Printf arguments
244 * @return Dynamically allocated string or NULL in case of error.
245 * @note Refer to SQLite documentation for more details about %q, %Q and %z.
247 static inline char* sql_Printf( sql_t *p_sql, const char *psz_fmt, ... )
249 va_list args;
250 va_start( args, psz_fmt );
251 char *r = p_sql->pf_vmprintf( psz_fmt, args );
252 va_end( args );
253 return r;
257 * @brief vprintf replacement for SQL queries, escaping forbidden characters
258 * @param p_sql This SQL object
259 * @param psz_fmt Format of the string
260 * @param arg Variable list of arguments
261 * @return Dynamically allocated string or NULL in case of error.
263 static inline char* sql_VPrintf( sql_t *p_sql, const char *psz_fmt,
264 va_list arg )
266 return p_sql->pf_vmprintf( psz_fmt, arg );
270 * @brief Begin a SQL transaction
271 * @param p_sql The SQL object
272 * @return VLC error code or success
273 * @note This function is threadsafe
275 static inline int sql_BeginTransaction( sql_t *p_sql )
277 return p_sql->pf_begin( p_sql );
281 * @brief Commit a SQL transaction
282 * @param p_sql The SQL object
283 * @return VLC error code or success
284 * @note This function is threadsafe
286 static inline int sql_CommitTransaction( sql_t *p_sql )
288 return p_sql->pf_commit( p_sql );
292 * @brief Rollback a SQL transaction
293 * @param p_sql The SQL object
294 * @return VLC error code or success
295 * @note This function is threadsafe
297 static inline void sql_RollbackTransaction( sql_t *p_sql )
299 p_sql->pf_rollback( p_sql );
303 * @brief Prepare an sql statement
304 * @param p_sql The SQL object
305 * @param p_fmt SQL query string
306 * @param i_length length of the string. If negative, length will be
307 * considered upto the first \0 character equivalent to strlen(p_fmt).
308 * Otherwise the first i_length bytes will be used
309 * @return a sql_stmt_t pointer or NULL on failure
311 static inline sql_stmt_t* sql_Prepare( sql_t* p_sql, const char* p_fmt,
312 int i_length )
314 return p_sql->pf_prepare( p_sql, p_fmt, i_length );
318 * @brief Bind arguments to a sql_stmt_t object
319 * @param p_sql The SQL object
320 * @param p_stmt Statement Object
321 * @param type Data type of the value
322 * @param p_value Value to be bound
323 * @param i_pos Position at which the parameter should be bound
324 * @return VLC_SUCCESS or VLC_EGENERIC
326 static inline int sql_BindGeneric( sql_t* p_sql, sql_stmt_t* p_stmt,
327 int i_pos, int type, const sql_value_t* p_value )
329 return p_sql->pf_bind( p_sql, p_stmt, i_pos, type, p_value );
333 * @brief Bind a NULL value to a position
334 * @param p_sql The SQL object
335 * @param p_stmt Statement Object
336 * @param i_pos Position at which the parameter should be bound
337 * @return VLC_SUCCESS or VLC_EGENERIC
339 static inline int sql_BindNull( sql_t *p_sql, sql_stmt_t* p_stmt, int i_pos )
341 int i_ret = sql_BindGeneric( p_sql, p_stmt, i_pos, SQL_NULL, NULL );
342 return i_ret;
346 * @brief Bind an integer to the statement object at some position
347 * @param p_sql The SQL object
348 * @param p_stmt Statement Object
349 * @param i_pos Position at which the parameter should be bound
350 * @param i_int Value to be bound
351 * @return VLC_SUCCESS or VLC_EGENERIC
353 static inline int sql_BindInteger( sql_t *p_sql, sql_stmt_t* p_stmt,
354 int i_pos, int i_int )
356 sql_value_t value;
357 value.length = 0;
358 value.value.i = i_int;
359 int i_ret = sql_BindGeneric( p_sql, p_stmt, i_pos, SQL_INT, &value );
360 return i_ret;
364 * @brief Bind a double to the statement object at some position
365 * @param p_sql The SQL object
366 * @param p_stmt Statement Object
367 * @param i_pos Position at which the parameter should be bound
368 * @param d_dbl Value to be bound
369 * @return VLC_SUCCESS or VLC_EGENERIC
371 static inline int sql_BindDouble( sql_t *p_sql, sql_stmt_t* p_stmt,
372 int i_pos, double d_dbl )
374 sql_value_t value;
375 value.length = 0;
376 value.value.dbl = d_dbl;
377 int i_ret = sql_BindGeneric( p_sql, p_stmt, i_pos, SQL_INT, &value );
378 return i_ret;
382 * @brief Bind Text to the statement
383 * @param p_sql The SQL object
384 * @param p_stmt Statement Object
385 * @param i_pos Position at which the parameter should be bound
386 * @param p_fmt Value to be bound
387 * @param i_length Length of text. If -ve text upto the first null char
388 * will be selected.
389 * @return VLC_SUCCESS or VLC_EGENERIC
391 static inline int sql_BindText( sql_t *p_sql, sql_stmt_t* p_stmt, int i_pos,
392 char* p_fmt, int i_length )
394 sql_value_t value;
395 value.length = i_length;
396 value.value.psz = p_fmt;
397 int i_ret = sql_BindGeneric( p_sql, p_stmt, i_pos, SQL_TEXT, &value );
398 return i_ret;
402 * @brief Bind a binary object to the statement
403 * @param p_sql The SQL object
404 * @param p_stmt Statement Object
405 * @param i_pos Position at which the parameter should be bound
406 * @param p_ptr Value to be bound
407 * @param i_length Size of the blob to read
408 * @return VLC_SUCCESS or VLC_EGENERIC
410 static inline int sql_BindBlob( sql_t *p_sql, sql_stmt_t* p_stmt, int i_pos,
411 void* p_ptr, int i_length )
413 sql_value_t value;
414 value.length = i_length;
415 value.value.ptr = p_ptr;
416 int i_ret = sql_BindGeneric( p_sql, p_stmt, i_pos, SQL_INT, &value );
417 return i_ret;
421 * @brief Run the SQL statement. If the statement fetches data, then only
422 * one row of the data is fetched at a time. Run this function again to
423 * fetch the next row.
424 * @param p_sql The SQL object
425 * @param p_stmt The statement
426 * @return VLC_SQL_DONE if done fetching all rows or there are no rows to fetch
427 * VLC_SQL_ROW if a row was fetched for this statement.
428 * VLC_EGENERIC if this function failed
430 static inline int sql_Run( sql_t* p_sql, sql_stmt_t* p_stmt )
432 return p_sql->pf_run( p_sql, p_stmt );
436 * @brief Reset the SQL statement. Resetting the statement will unbind all
437 * the values that were bound on this statement
438 * @param p_sql The SQL object
439 * @param p_stmt The sql statement object
440 * @return VLC_SUCCESS or VLC_EGENERIC
442 static inline int sql_Reset( sql_t* p_sql, sql_stmt_t* p_stmt )
444 return p_sql->pf_reset( p_sql, p_stmt );
448 * @brief Destroy the sql statement object. This will free memory.
449 * @param p_sql The SQL object
450 * @param p_stmt The statement object
451 * @return VLC_SUCCESS or VLC_EGENERIC
453 static inline int sql_Finalize( sql_t* p_sql, sql_stmt_t* p_stmt )
455 return p_sql->pf_finalize( p_sql, p_stmt );
459 * @brief Get the datatype of the result of the column
460 * @param p_sql The SQL object
461 * @param p_stmt The sql statement object
462 * @param i_col The column
463 * @param type pointer to datatype of the given column
464 * @return VLC_SUCCESS or VLC_EGENERIC
466 static inline int sql_GetColumnType( sql_t* p_sql, sql_stmt_t* p_stmt,
467 int i_col, int* type )
469 return p_sql->pf_gettype( p_sql, p_stmt, i_col, type );
473 * @brief Get the column data
474 * @param p_sql The SQL object
475 * @param p_stmt The statement object
476 * @param i_col The column number
477 * @param type Datatype of result
478 * @param p_res The structure which contains the value of the result
479 * @return VLC_SUCCESS or VLC_EGENERIC
481 static inline int sql_GetColumn( sql_t* p_sql, sql_stmt_t* p_stmt,
482 int i_col, int type, sql_value_t *p_res )
484 return p_sql->pf_getcolumn( p_sql, p_stmt, i_col, type, p_res );
488 * @brief Get an integer from the results of a statement
489 * @param p_sql The SQL object
490 * @param p_stmt The statement object
491 * @param i_col The column number
492 * @param i_res Pointer of the location for result to be stored
493 * @return VLC_SUCCESS or VLC_EGENERIC
495 static inline int sql_GetColumnInteger( sql_t* p_sql, sql_stmt_t* p_stmt,
496 int i_col, int* pi_res )
498 sql_value_t tmp;
499 int i_ret = p_sql->pf_getcolumn( p_sql, p_stmt, i_col, SQL_INT, &tmp );
500 if( i_ret == VLC_SUCCESS )
501 *pi_res = tmp.value.i;
502 return i_ret;
506 * @brief Get a double from the results of a statement
507 * @param p_sql The SQL object
508 * @param p_stmt The statement object
509 * @param i_col The column number
510 * @param d_res Pointer of the location for result to be stored
511 * @return VLC_SUCCESS or VLC_EGENERIC
513 static inline int sql_GetColumnDouble( sql_t* p_sql, sql_stmt_t* p_stmt,
514 int i_col, double* pd_res )
516 sql_value_t tmp;
517 int i_ret = p_sql->pf_getcolumn( p_sql, p_stmt, i_col, SQL_DOUBLE, &tmp );
518 if( i_ret == VLC_SUCCESS )
519 *pd_res = tmp.value.dbl;
520 return i_ret;
524 * @brief Get some text from the results of a statement
525 * @param p_sql The SQL object
526 * @param p_stmt The statement object
527 * @param i_col The column number
528 * @param pp_res Pointer of the location for result to be stored
529 * @return VLC_SUCCESS or VLC_EGENERIC
531 static inline int sql_GetColumnText( sql_t* p_sql, sql_stmt_t* p_stmt,
532 int i_col, char** pp_res )
534 sql_value_t tmp;
535 int i_ret = p_sql->pf_getcolumn( p_sql, p_stmt, i_col, SQL_TEXT, &tmp );
536 if( i_ret == VLC_SUCCESS )
537 *pp_res = tmp.value.psz;
538 return i_ret;
542 * @brief Get a blob from the results of a statement
543 * @param p_sql The SQL object
544 * @param p_stmt The statement object
545 * @param i_col The column number
546 * @param pp_res Pointer of the location for result to be stored
547 * @return VLC_SUCCESS or VLC_EGENERIC
549 static inline int sql_GetColumnBlob( sql_t* p_sql, sql_stmt_t* p_stmt,
550 int i_col, void** pp_res )
552 sql_value_t tmp;
553 int i_ret = p_sql->pf_getcolumn( p_sql, p_stmt, i_col, SQL_BLOB, &tmp );
554 if( i_ret == VLC_SUCCESS )
555 *pp_res = tmp.value.ptr;
556 return i_ret;
560 * @brief Get the size of the column in bytes
561 * @param p_sql The SQL object
562 * @param p_stmt The sql statement object
563 * @param i_col The column
564 * @return Size of the column in bytes, excluding the zero terminator
566 static inline int sql_GetColumnSize( sql_t* p_sql, sql_stmt_t* p_stmt,
567 int i_col )
569 return p_sql->pf_getcolumnsize( p_sql, p_stmt, i_col );
572 # ifdef __cplusplus
574 # endif /* C++ extern "C" */
576 #endif /* VLC_SQL_H */