00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2005, Digium, Inc. 00005 * Copyright (C) 2004 - 2005, Anthony Minessale II 00006 * Copyright (C) 2006, Tilghman Lesher 00007 * 00008 * Mark Spencer <markster@digium.com> 00009 * Anthony Minessale <anthmct@yahoo.com> 00010 * Tilghman Lesher <res_odbc_200603@the-tilghman.com> 00011 * 00012 * See http://www.asterisk.org for more information about 00013 * the Asterisk project. Please do not directly contact 00014 * any of the maintainers of this project for assistance; 00015 * the project provides a web site, mailing lists and IRC 00016 * channels for your use. 00017 * 00018 * This program is free software, distributed under the terms of 00019 * the GNU General Public License Version 2. See the LICENSE file 00020 * at the top of the source tree. 00021 */ 00022 00023 /*! \file 00024 * \brief ODBC resource manager 00025 */ 00026 00027 #ifndef _ASTERISK_RES_ODBC_H 00028 #define _ASTERISK_RES_ODBC_H 00029 00030 #include <sql.h> 00031 #include <sqlext.h> 00032 #include <sqltypes.h> 00033 #include "asterisk/linkedlists.h" 00034 00035 typedef enum { ODBC_SUCCESS=0, ODBC_FAIL=-1} odbc_status; 00036 00037 /*! \brief ODBC container */ 00038 struct odbc_obj { 00039 ast_mutex_t lock; 00040 SQLHDBC con; /* ODBC Connection Handle */ 00041 struct odbc_class *parent; /* Information about the connection is protected */ 00042 struct timeval last_used; 00043 #ifdef DEBUG_THREADS 00044 char file[80]; 00045 char function[80]; 00046 int lineno; 00047 #endif 00048 unsigned int used:1; 00049 unsigned int up:1; 00050 AST_LIST_ENTRY(odbc_obj) list; 00051 }; 00052 00053 /*!\brief These aren't used in any API calls, but they are kept in a common 00054 * location, simply for convenience and to avoid duplication. 00055 */ 00056 struct odbc_cache_columns { 00057 char *name; 00058 SQLSMALLINT type; 00059 SQLINTEGER size; 00060 SQLSMALLINT decimals; 00061 SQLSMALLINT radix; 00062 SQLSMALLINT nullable; 00063 SQLINTEGER octetlen; 00064 AST_RWLIST_ENTRY(odbc_cache_columns) list; 00065 }; 00066 00067 struct odbc_cache_tables { 00068 char *connection; 00069 char *table; 00070 AST_RWLIST_HEAD(_columns, odbc_cache_columns) columns; 00071 AST_RWLIST_ENTRY(odbc_cache_tables) list; 00072 }; 00073 00074 /* functions */ 00075 00076 /*! 00077 * \brief Executes a prepared statement handle 00078 * \param obj The non-NULL result of odbc_request_obj() 00079 * \param stmt The prepared statement handle 00080 * \retval 0 on success 00081 * \retval -1 on failure 00082 * 00083 * This function was originally designed simply to execute a prepared 00084 * statement handle and to retry if the initial execution failed. 00085 * Unfortunately, it did this by disconnecting and reconnecting the database 00086 * handle which on most databases causes the statement handle to become 00087 * invalid. Therefore, this method has been deprecated in favor of 00088 * odbc_prepare_and_execute() which allows the statement to be prepared 00089 * multiple times, if necessary, in case of a loss of connection. 00090 * 00091 * This function really only ever worked with MySQL, where the statement handle is 00092 * not prepared on the server. If you are not using MySQL, you should avoid it. 00093 */ 00094 int ast_odbc_smart_execute(struct odbc_obj *obj, SQLHSTMT stmt) __attribute__((deprecated)); 00095 00096 /*! 00097 * \brief Retrieves a connected ODBC object 00098 * \param name The name of the ODBC class for which a connection is needed. 00099 * \param check Whether to ensure that a connection is valid before returning the handle. Usually unnecessary. 00100 * \retval ODBC object 00101 * \retval NULL if there is no connection available with the requested name. 00102 * 00103 * Connection classes may, in fact, contain multiple connection handles. If 00104 * the connection is pooled, then each connection will be dedicated to the 00105 * thread which requests it. Note that all connections should be released 00106 * when the thread is done by calling odbc_release_obj(), below. 00107 */ 00108 #ifdef DEBUG_THREADS 00109 struct odbc_obj *_ast_odbc_request_obj(const char *name, int check, const char *file, const char *function, int lineno); 00110 #define ast_odbc_request_obj(a, b) _ast_odbc_request_obj(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__) 00111 #else 00112 struct odbc_obj *ast_odbc_request_obj(const char *name, int check); 00113 #endif 00114 00115 /*! 00116 * \brief Releases an ODBC object previously allocated by odbc_request_obj() 00117 * \param obj The ODBC object 00118 */ 00119 void ast_odbc_release_obj(struct odbc_obj *obj); 00120 00121 /*! 00122 * \brief Checks an ODBC object to ensure it is still connected 00123 * \param obj The ODBC object 00124 * \retval 0 if connected 00125 * \retval -1 otherwise. 00126 */ 00127 int ast_odbc_sanity_check(struct odbc_obj *obj); 00128 00129 /*! \brief Checks if the database natively supports backslash as an escape character. 00130 * \param obj The ODBC object 00131 * \return Returns 1 if backslash is a native escape character, 0 if an ESCAPE clause is needed to support '\' 00132 */ 00133 int ast_odbc_backslash_is_escape(struct odbc_obj *obj); 00134 00135 /*! \brief Executes an non prepared statement and returns the resulting 00136 * statement handle. 00137 * \param obj The ODBC object 00138 * \param exec_cb A function callback, which, when called, should return a statement handle with result columns bound. 00139 * \param data A parameter to be passed to the exec_cb parameter function, indicating which statement handle is to be prepared. 00140 * \retval a statement handle 00141 * \retval NULL on error 00142 */ 00143 SQLHSTMT ast_odbc_direct_execute(struct odbc_obj *obj, SQLHSTMT (*exec_cb)(struct odbc_obj *obj, void *data), void *data); 00144 00145 /*! 00146 * \brief Prepares, executes, and returns the resulting statement handle. 00147 * \param obj The ODBC object 00148 * \param prepare_cb A function callback, which, when called, should return a statement handle prepared, with any necessary parameters or result columns bound. 00149 * \param data A parameter to be passed to the prepare_cb parameter function, indicating which statement handle is to be prepared. 00150 * \retval a statement handle 00151 * \retval NULL on error 00152 */ 00153 SQLHSTMT ast_odbc_prepare_and_execute(struct odbc_obj *obj, SQLHSTMT (*prepare_cb)(struct odbc_obj *obj, void *data), void *data); 00154 00155 /*! 00156 * \brief Find or create an entry describing the table specified. 00157 * \param database Name of an ODBC class on which to query the table 00158 * \param table Tablename to describe 00159 * \retval A structure describing the table layout, or NULL, if the table is not found or another error occurs. 00160 * When a structure is returned, the contained columns list will be 00161 * rdlock'ed, to ensure that it will be retained in memory. 00162 * \since 1.6.1 00163 */ 00164 struct odbc_cache_tables *ast_odbc_find_table(const char *database, const char *tablename); 00165 00166 /*! 00167 * \brief Find a column entry within a cached table structure 00168 * \param table Cached table structure, as returned from ast_odbc_find_table() 00169 * \param colname The column name requested 00170 * \retval A structure describing the column type, or NULL, if the column is not found. 00171 * \since 1.6.1 00172 */ 00173 struct odbc_cache_columns *ast_odbc_find_column(struct odbc_cache_tables *table, const char *colname); 00174 00175 /*! 00176 * \brief Remove a cache entry from memory 00177 * \param database Name of an ODBC class (used to ensure like-named tables in different databases are not confused) 00178 * \param table Tablename for which a cached record should be removed 00179 * \retval 0 if the cache entry was removed, or -1 if no matching entry was found. 00180 * \since 1.6.1 00181 */ 00182 int ast_odbc_clear_cache(const char *database, const char *tablename); 00183 00184 /*! 00185 * \brief Release a table returned from ast_odbc_find_table 00186 */ 00187 #define ast_odbc_release_table(ptr) if (ptr) { AST_RWLIST_UNLOCK(&(ptr)->columns); } 00188 00189 #endif /* _ASTERISK_RES_ODBC_H */