1 /*****************************************************************************
2 * vlc_sql.h: SQL abstraction layer
3 *****************************************************************************
4 * Copyright (C) 2009 the VideoLAN team
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 #if !defined( __LIBVLC__ )
27 # error You are not libvlc or one of its plugins. You cannot include this file
38 /*****************************************************************************
39 * General structure: SQL object.
40 *****************************************************************************/
42 typedef struct sql_t sql_t;
43 typedef struct sql_sys_t sql_sys_t;
45 typedef int ( *sql_query_callback_t ) ( void*, int, char**, char** );
51 /** Module properties */
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 */
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 * );
66 /** Perform a query and return result directly */
67 int (*pf_query) ( sql_t *, const char *, char ***, int *, int * );
69 /** Get database tables */
70 int (*pf_get_tables) ( sql_t *, char *** );
72 /** Free result of a call to sql_Query or sql_GetTables */
73 void (*pf_free) ( sql_t *, char ** );
75 /** vmprintf replacement for SQL */
76 char* (*pf_vmprintf) ( const char*, va_list args );
78 /** Begin transaction */
79 int (*pf_begin) ( sql_t* );
81 /** Commit transaction */
82 void (*pf_commit) ( sql_t* );
84 /** Rollback transaction */
85 void (*pf_rollback) ( sql_t* );
89 /*****************************************************************************
90 * SQL Function headers
91 *****************************************************************************/
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.
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 )
109 * @brief Destructor for p_sql object
110 * @param obj This p_sql object
113 VLC_EXPORT( void, sql_Destroy, ( vlc_object_t *obj ) );
114 #define sql_Destroy( a ) sql_Destroy( VLC_OBJECT( a ) )
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!
130 static inline int sql_QueryCallback( sql_t *p_sql, const char *psz_query,
131 sql_query_callback_t pf_callback,
134 return p_sql->pf_query_callback( p_sql, psz_query, pf_callback, p_opaque );
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
145 * @param pi_cols Pointer to an integer that will receive the number of result
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 ].
155 static inline int sql_Query( sql_t *p_sql, const char *psz_query,
156 char ***pppsz_result, int *pi_rows, int *pi_cols )
158 return p_sql->pf_query( p_sql, psz_query, pppsz_result, pi_rows, pi_cols );
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.
168 static inline int sql_GetTables( sql_t *p_sql, char ***pppsz_tables )
170 return p_sql->pf_get_tables( p_sql, pppsz_tables );
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.
179 static inline void sql_Free( sql_t *p_sql, char **ppsz_result )
181 p_sql->pf_free( p_sql, ppsz_result );
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.
192 static inline char* sql_Printf( sql_t *p_sql, const char *psz_fmt, ... )
195 va_start( args, psz_fmt );
196 char *r = p_sql->pf_vmprintf( psz_fmt, args );
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.
208 static inline char* sql_VPrintf( sql_t *p_sql, const char *psz_fmt,
211 return p_sql->pf_vmprintf( psz_fmt, arg );
215 * @brief Begin a SQL transaction
216 * @param p_sql The SQL object
217 * @return VLC error code or success
219 static inline int sql_BeginTransaction( sql_t *p_sql )
221 return p_sql->pf_begin( p_sql );
225 * @brief Commit a SQL transaction
226 * @param p_sql The SQL object
227 * @return VLC error code or success
229 static inline void sql_CommitTransaction( sql_t *p_sql )
231 p_sql->pf_commit( p_sql );
235 * @brief Rollback a SQL transaction
236 * @param p_sql The SQL object
237 * @return VLC error code or success
239 static inline void sql_RollbackTransaction( sql_t *p_sql )
241 p_sql->pf_rollback( p_sql );
246 # endif /* C++ extern "C" */
248 #endif /* VLC_SQL_H */