git.sesse.net Git - vlc/blob - include/vlc_sql.h

   1 /*****************************************************************************
   2  * vlc_sql.h: SQL abstraction layer
   3  *****************************************************************************
   4  * Copyright (C) 2009 the VideoLAN team
   5  * $Id$
   6  *
   7  * Authors: Antoine Lejeune <phytos@videolan.org>
   8  *          Jean-Philippe André <jpeg@videolan.org>
   9  *          Srikanth Raju <srikiraju@gmail.com>
  10  *
  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.
  15  *
  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.
  20  *
  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  *****************************************************************************/
  25
  26 #if !defined( __LIBVLC__ )
  27 # error You are not libvlc or one of its plugins. You cannot include this file
  28 #endif
  29
  30 #ifndef VLC_SQL_H
  31 # define VLC_SQL_H
  32
  33 # ifdef __cplusplus
  34 extern "C" {
  35 # endif
  36
  37
  38 /*****************************************************************************
  39  * General structure: SQL object.
  40  *****************************************************************************/
  41
  42 typedef struct sql_t sql_t;
  43 typedef struct sql_sys_t sql_sys_t;
  44
  45 typedef int ( *sql_query_callback_t ) ( void*, int, char**, char** );
  46
  47 struct sql_t
  48 {
  49     VLC_COMMON_MEMBERS
  50
  51     /** Module properties */
  52     module_t  *p_module;
  53
  54     /** Connection Data */
  55     char *psz_host;         /**< Location or host of the database */
  56     char *psz_user;         /**< Username used to connect to database */
  57     char *psz_pass;         /**< Password used to connect to database */
  58     int i_port;             /**< Port on which database is running */
  59
  60     /** Internal data */
  61     sql_sys_t *p_sys;
  62
  63     /** Perform a query with a row-by-row callback function */
  64     int (*pf_query_callback) ( sql_t *, const char *, sql_query_callback_t, void * );
  65
  66     /** Perform a query and return result directly */
  67     int (*pf_query) ( sql_t *, const char *, char ***, int *, int * );
  68
  69     /** Get database tables */
  70     int (*pf_get_tables) ( sql_t *, char *** );
  71
  72     /** Free result of a call to sql_Query or sql_GetTables */
  73     void (*pf_free) ( sql_t *, char ** );
  74
  75     /** vmprintf replacement for SQL */
  76     char* (*pf_vmprintf) ( const char*, va_list args );
  77
  78     /** Begin transaction */
  79     int (*pf_begin) ( sql_t* );
  80
  81     /** Commit transaction */
  82     void (*pf_commit) ( sql_t* );
  83
  84     /** Rollback transaction */
  85     void (*pf_rollback) ( sql_t* );
  86 };
  87
  88
  89 /*****************************************************************************
  90  * SQL Function headers
  91  *****************************************************************************/
  92
  93 /**
  94  * @brief Create a new SQL object.
  95  * @param p_this Parent object to attach the SQL object to.
  96  * @param psz_host URL to the database
  97  * @param i_port Port on which the database is running
  98  * @param psz_user Username to access the database
  99  * @param psz_pass Password for the database
 100  * @return The VLC SQL object, type sql_t.
 101  **/
 102 VLC_EXPORT( sql_t*, sql_Create, ( vlc_object_t *p_this, const char *psz_name,
 103             const char* psz_host, int i_port,
 104             const char* psz_user, const char* psz_pass ) );
 105 #define sql_Create( a, b, c, d, e, f ) sql_Create( VLC_OBJECT(a), b, c, d, e, f )
 106
 107
 108 /**
 109  * @brief Destructor for p_sql object
 110  * @param obj This p_sql object
 111  * @return Nothing
 112  */
 113 VLC_EXPORT( void, sql_Destroy, ( vlc_object_t *obj ) );
 114 #define sql_Destroy( a ) sql_Destroy( VLC_OBJECT( a ) )
 115
 116
 117 /**
 118  * @brief Perform a query using a callback function
 119  * @param p_sql This SQL object.
 120  * @param psz_query The SQL query string.
 121  * @param pf_callback A callback function that will be called for each row of
 122  * the result: 1st argument is be p_opaque,
 123  *             2nd argument is the number of columns,
 124  *             3rd is the result columns (array of strings),
 125  *             4th is the columns names (array of strings).
 126  * @param p_opaque Any pointer to an object you may need in the callback.
 127  * @return VLC_SUCCESS or VLC_EGENERIC.
 128  * @note The query will not necessarily be processed in a separate thread!
 129  **/
 130 static inline int sql_QueryCallback( sql_t *p_sql, const char *psz_query,
 131                                      sql_query_callback_t pf_callback,
 132                                      void *p_opaque )
 133 {
 134     return p_sql->pf_query_callback( p_sql, psz_query, pf_callback, p_opaque );
 135 }
 136
 137 /**
 138  * @brief Perform a query directly
 139  * @param p_sql This SQL object.
 140  * @param psz_query The SQL query string.
 141  * @param pppsz_result A pointer to a array of strings: result of the query.
 142  * Dynamically allocated.
 143  * @param pi_rows Pointer to an integer that will receive the number of result
 144  * rows written.
 145  * @param pi_cols Pointer to an integer that will receive the number of result
 146  * columns written.
 147  * @return VLC_SUCCESS or VLC_EGENERIC.
 148  * @note pppsz_result will point to an array of strings, ppsz_result.
 149  * This array of strings contains actually a 2D-matrix of strings where the
 150  * first row (row 0) contains the SQL table header names.
 151  * *pi_rows will be the number of result rows, so that the number of text rows
 152  * in ppsz_result will be (*pi_rows + 1) (because of row 0).
 153  * To get result[row,col] use (*pppsz_result)[ (row+1) * (*pi_cols) + col ].
 154  **/
 155 static inline int sql_Query( sql_t *p_sql, const char *psz_query,
 156                              char ***pppsz_result, int *pi_rows, int *pi_cols )
 157 {
 158     return p_sql->pf_query( p_sql, psz_query, pppsz_result, pi_rows, pi_cols );
 159 }
 160
 161 /**
 162  * @brief Get database table name list
 163  * @param p_sql This SQL object.
 164  * @param pppsz_tables Pointer to an array of strings. Dynamically allocated.
 165  * Similar to pppsz_result of sql_Query but with only one row.
 166  * @return Number of tables or <0 in case of error.
 167  **/
 168 static inline int sql_GetTables( sql_t *p_sql, char ***pppsz_tables )
 169 {
 170     return p_sql->pf_get_tables( p_sql, pppsz_tables );
 171 }
 172
 173 /**
 174  * @brief Free the result of a query.
 175  * @param p_sql This SQL object.
 176  * @param ppsz_result The result of sql_Query or sql_GetTables. See above.
 177  * @return Nothing.
 178  **/
 179 static inline void sql_Free( sql_t *p_sql, char **ppsz_result )
 180 {
 181     p_sql->pf_free( p_sql, ppsz_result );
 182 }
 183
 184 /**
 185  * @brief printf-like function that can escape forbidden/reserved characters.
 186  * @param p_sql This SQL object.
 187  * @param psz_fmt Format of the string (with %q, %Q and %z enabled).
 188  * @param ... Printf arguments
 189  * @return Dynamically allocated string or NULL in case of error.
 190  * @note Refer to SQLite documentation for more details about %q, %Q and %z.
 191  **/
 192 static inline char* sql_Printf( sql_t *p_sql, const char *psz_fmt, ... )
 193 {
 194     va_list args;
 195     va_start( args, psz_fmt );
 196     char *r = p_sql->pf_vmprintf( psz_fmt, args );
 197     va_end( args );
 198     return r;
 199 }
 200
 201 /**
 202  * @brief vprintf replacement for SQL queries, escaping forbidden characters
 203  * @param p_sql This SQL object
 204  * @param psz_fmt Format of the string
 205  * @param arg Variable list of arguments
 206  * @return Dynamically allocated string or NULL in case of error.
 207  **/
 208 static inline char* sql_VPrintf( sql_t *p_sql, const char *psz_fmt,
 209                                  va_list arg )
 210 {
 211     return p_sql->pf_vmprintf( psz_fmt, arg );
 212 }
 213
 214 /**
 215  * @brief Begin a SQL transaction
 216  * @param p_sql The SQL object
 217  * @return VLC error code or success
 218  **/
 219 static inline int sql_BeginTransaction( sql_t *p_sql )
 220 {
 221     return p_sql->pf_begin( p_sql );
 222 }
 223
 224 /**
 225  * @brief Commit a SQL transaction
 226  * @param p_sql The SQL object
 227  * @return VLC error code or success
 228  **/
 229 static inline void sql_CommitTransaction( sql_t *p_sql )
 230 {
 231     p_sql->pf_commit( p_sql );
 232 }
 233
 234 /**
 235  * @brief Rollback a SQL transaction
 236  * @param p_sql The SQL object
 237  * @return VLC error code or success
 238  **/
 239 static inline void sql_RollbackTransaction( sql_t *p_sql )
 240 {
 241     p_sql->pf_rollback( p_sql );
 242 }
 243
 244 # ifdef __cplusplus
 245 }
 246 # endif /* C++ extern "C" */
 247
 248 #endif /* VLC_SQL_H */