home *** CD-ROM | disk | FTP | other *** search
/ mail.altrad.com / 2015.02.mail.altrad.com.tar / mail.altrad.com / TEST / vlc-2-0-5-win32.exe / sdk / include / vlc / plugins / vlc_sql.h < prev    next >
C/C++ Source or Header  |  2012-12-12  |  19KB  |  577 lines
  1. /*****************************************************************************
  2.  * vlc_sql.h: SQL abstraction layer
  3.  *****************************************************************************
  4.  * Copyright (C) 2009 VLC authors and VideoLAN
  5.  * $Id: 39e9ad4f0f5721db7d717242cb61c9dcbe249f5f $
  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 it
  12.  * under the terms of the GNU Lesser General Public License as published by
  13.  * the Free Software Foundation; either version 2.1 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 Lesser General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU Lesser General Public License
  22.  * along with this program; if not, write to the Free Software Foundation,
  23.  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  24.  *****************************************************************************/
  25.  
  26. #ifndef VLC_SQL_H
  27. # define VLC_SQL_H
  28.  
  29. # ifdef __cplusplus
  30. extern "C" {
  31. # endif
  32.  
  33.  
  34. /*****************************************************************************
  35.  * General structure: SQL object.
  36.  *****************************************************************************/
  37.  
  38. /**
  39.  * Return values for the function @see sql_Run()
  40.  */
  41. #define VLC_SQL_ROW 1
  42. #define VLC_SQL_DONE 2
  43.  
  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;
  47.  
  48. typedef int ( *sql_query_callback_t ) ( void*, int, char**, char** );
  49.  
  50. typedef enum {
  51.     SQL_NULL,
  52.     SQL_INT,
  53.     SQL_DOUBLE,
  54.     SQL_TEXT,
  55.     SQL_BLOB
  56. } sql_type_e;
  57.  
  58. typedef struct
  59. {
  60.     int length;
  61.     union
  62.     {
  63.         int i;
  64.         double dbl;
  65.         char* psz;
  66.         void* ptr;
  67.     } value;
  68. } sql_value_t;
  69.  
  70. struct sql_t
  71. {
  72.     VLC_COMMON_MEMBERS
  73.  
  74.     /** Module properties */
  75.     module_t  *p_module;
  76.  
  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 */
  82.  
  83.     /** Internal data */
  84.     sql_sys_t *p_sys;
  85.  
  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 * );
  89.  
  90.     /** Perform a query and return result directly */
  91.     int (*pf_query) ( sql_t *, const char *, char ***, int *, int * );
  92.  
  93.     /** Get database tables */
  94.     int (*pf_get_tables) ( sql_t *, char *** );
  95.  
  96.     /** Free result of a call to sql_Query or sql_GetTables */
  97.     void (*pf_free) ( sql_t *, char ** );
  98.  
  99.     /** vmprintf replacement for SQL */
  100.     char* (*pf_vmprintf) ( const char*, va_list args );
  101.  
  102.     /** Begin transaction */
  103.     int (*pf_begin) ( sql_t* );
  104.  
  105.     /** Commit transaction */
  106.     int (*pf_commit) ( sql_t* );
  107.  
  108.     /** Rollback transaction */
  109.     void (*pf_rollback) ( sql_t* );
  110.  
  111.     /** Create a statement object */
  112.     sql_stmt_t* (*pf_prepare) ( sql_t* p_sql, const char* p_fmt,
  113.                                 int i_length );
  114.  
  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 );
  118.  
  119.     /** Run the prepared statement */
  120.     int (*pf_run) ( sql_t* p_sql, sql_stmt_t* p_stmt );
  121.  
  122.     /** Reset the prepared statement */
  123.     int (*pf_reset) ( sql_t* p_sql, sql_stmt_t* p_stmt );
  124.  
  125.     /** Destroy the statement object */
  126.     int (*pf_finalize) ( sql_t* p_sql, sql_stmt_t* p_stmt );
  127.  
  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 );
  131.  
  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 );
  135.  
  136.     /** Get column size of a specified column */
  137.     int (*pf_getcolumnsize) ( sql_t* p_sql, sql_stmt_t* p_stmt, int i_col );
  138. };
  139.  
  140. /*****************************************************************************
  141.  * SQL Function headers
  142.  *****************************************************************************/
  143.  
  144. /**
  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.
  152.  **/
  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 )
  157.  
  158.  
  159. /**
  160.  * @brief Destructor for p_sql object
  161.  * @param obj This p_sql object
  162.  * @return Nothing
  163.  */
  164. VLC_API void sql_Destroy( vlc_object_t *obj );
  165. #define sql_Destroy( a ) sql_Destroy( VLC_OBJECT( a ) )
  166.  
  167.  
  168. /**
  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
  181.  **/
  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 )
  185. {
  186.     return p_sql->pf_query_callback( p_sql, psz_query, pf_callback, p_opaque );
  187. }
  188.  
  189. /**
  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
  207.  **/
  208. static inline int sql_Query( sql_t *p_sql, const char *psz_query,
  209.                              char ***pppsz_result, int *pi_rows, int *pi_cols )
  210. {
  211.     return p_sql->pf_query( p_sql, psz_query, pppsz_result, pi_rows, pi_cols );
  212. }
  213.  
  214. /**
  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
  221.  **/
  222. static inline int sql_GetTables( sql_t *p_sql, char ***pppsz_tables )
  223. {
  224.     return p_sql->pf_get_tables( p_sql, pppsz_tables );
  225. }
  226.  
  227. /**
  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
  233.  **/
  234. static inline void sql_Free( sql_t *p_sql, char **ppsz_result )
  235. {
  236.     p_sql->pf_free( p_sql, ppsz_result );
  237. }
  238.  
  239. /**
  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.
  246.  **/
  247. static inline char* sql_Printf( sql_t *p_sql, const char *psz_fmt, ... )
  248. {
  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;
  254. }
  255.  
  256. /**
  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.
  262.  **/
  263. static inline char* sql_VPrintf( sql_t *p_sql, const char *psz_fmt,
  264.                                  va_list arg )
  265. {
  266.     return p_sql->pf_vmprintf( psz_fmt, arg );
  267. }
  268.  
  269. /**
  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
  274.  **/
  275. static inline int sql_BeginTransaction( sql_t *p_sql )
  276. {
  277.     return p_sql->pf_begin( p_sql );
  278. }
  279.  
  280. /**
  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
  285.  **/
  286. static inline int sql_CommitTransaction( sql_t *p_sql )
  287. {
  288.     return p_sql->pf_commit( p_sql );
  289. }
  290.  
  291. /**
  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
  296.  **/
  297. static inline void sql_RollbackTransaction( sql_t *p_sql )
  298. {
  299.     p_sql->pf_rollback( p_sql );
  300. }
  301.  
  302. /**
  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
  310.  */
  311. static inline sql_stmt_t* sql_Prepare( sql_t* p_sql, const char* p_fmt,
  312.         int i_length )
  313. {
  314.     return p_sql->pf_prepare( p_sql, p_fmt, i_length );
  315. }
  316.  
  317. /**
  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
  325.  */
  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 )
  328. {
  329.     return p_sql->pf_bind( p_sql, p_stmt, i_pos, type, p_value );
  330. }
  331.  
  332. /**
  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
  338.  */
  339. static inline int sql_BindNull( sql_t *p_sql, sql_stmt_t* p_stmt, int i_pos )
  340. {
  341.     int i_ret = sql_BindGeneric( p_sql, p_stmt, i_pos, SQL_NULL, NULL );
  342.     return i_ret;
  343. }
  344.  
  345. /**
  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
  352.  */
  353. static inline int sql_BindInteger( sql_t *p_sql, sql_stmt_t* p_stmt,
  354.                                    int i_pos, int i_int )
  355. {
  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;
  361. }
  362.  
  363. /**
  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
  370.  */
  371. static inline int sql_BindDouble( sql_t *p_sql, sql_stmt_t* p_stmt,
  372.                                   int i_pos, double d_dbl )
  373. {
  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;
  379. }
  380.  
  381. /**
  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
  390.  */
  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 )
  393. {
  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;
  399. }
  400.  
  401. /**
  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
  409.  */
  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 )
  412. {
  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;
  418. }
  419.  
  420. /**
  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
  429.  */
  430. static inline int sql_Run( sql_t* p_sql, sql_stmt_t* p_stmt )
  431. {
  432.     return p_sql->pf_run( p_sql, p_stmt );
  433. }
  434.  
  435. /**
  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
  441.  */
  442. static inline int sql_Reset( sql_t* p_sql, sql_stmt_t* p_stmt )
  443. {
  444.     return p_sql->pf_reset( p_sql, p_stmt );
  445. }
  446.  
  447. /**
  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
  452.  */
  453. static inline int sql_Finalize( sql_t* p_sql, sql_stmt_t* p_stmt )
  454. {
  455.     return p_sql->pf_finalize( p_sql, p_stmt );
  456. }
  457.  
  458. /**
  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
  465.  */
  466. static inline int sql_GetColumnType( sql_t* p_sql, sql_stmt_t* p_stmt,
  467.         int i_col, int* type )
  468. {
  469.     return p_sql->pf_gettype( p_sql, p_stmt, i_col, type );
  470. }
  471.  
  472. /**
  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
  480.  */
  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 )
  483. {
  484.     return p_sql->pf_getcolumn( p_sql, p_stmt, i_col, type, p_res );
  485. }
  486.  
  487. /**
  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
  494.  */
  495. static inline int sql_GetColumnInteger( sql_t* p_sql, sql_stmt_t* p_stmt,
  496.         int i_col, int* pi_res )
  497. {
  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;
  503. }
  504.  
  505. /**
  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
  512.  */
  513. static inline int sql_GetColumnDouble( sql_t* p_sql, sql_stmt_t* p_stmt,
  514.         int i_col, double* pd_res )
  515. {
  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;
  521. }
  522.  
  523. /**
  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
  530.  */
  531. static inline int sql_GetColumnText( sql_t* p_sql, sql_stmt_t* p_stmt,
  532.         int i_col, char** pp_res )
  533. {
  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;
  539. }
  540.  
  541. /**
  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
  548.  */
  549. static inline int sql_GetColumnBlob( sql_t* p_sql, sql_stmt_t* p_stmt,
  550.         int i_col, void** pp_res )
  551. {
  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;
  557. }
  558.  
  559. /**
  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
  565.  */
  566. static inline int sql_GetColumnSize( sql_t* p_sql, sql_stmt_t* p_stmt,
  567.         int i_col )
  568. {
  569.     return p_sql->pf_getcolumnsize( p_sql, p_stmt, i_col );
  570. }
  571.  
  572. # ifdef __cplusplus
  573. }
  574. # endif /* C++ extern "C" */
  575.  
  576. #endif /* VLC_SQL_H */
  577.