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 #include "asterisk/strings.h" 00035 00036 typedef enum { ODBC_SUCCESS=0, ODBC_FAIL=-1} odbc_status; 00037 00038 /*! \brief Flags for use with \see ast_odbc_request_obj2 */ 00039 enum { 00040 RES_ODBC_SANITY_CHECK = (1 << 0), 00041 RES_ODBC_INDEPENDENT_CONNECTION = (1 << 1), 00042 RES_ODBC_CONNECTED = (1 << 2), 00043 }; 00044 00045 /*! \brief ODBC container */ 00046 struct odbc_obj { 00047 ast_mutex_t lock; 00048 SQLHDBC con; /*!< ODBC Connection Handle */ 00049 struct odbc_class *parent; /*!< Information about the connection is protected */ 00050 struct timeval last_used; /*!< Used by idlecheck to determine if the connection should be renegotiated */ 00051 #ifdef DEBUG_THREADS 00052 char file[80]; 00053 char function[80]; 00054 int lineno; 00055 #endif 00056 unsigned int used:1; /*!< Is this connection currently in use? */ 00057 unsigned int up:1; 00058 unsigned int tx:1; /*!< Should this connection be unshared, regardless of the class setting? */ 00059 struct odbc_txn_frame *txf; /*!< Reference back to the transaction frame, if applicable */ 00060 AST_LIST_ENTRY(odbc_obj) list; 00061 }; 00062 00063 /*!\brief These structures are used for adaptive capabilities */ 00064 struct odbc_cache_columns { 00065 char *name; 00066 SQLSMALLINT type; 00067 SQLINTEGER size; 00068 SQLSMALLINT decimals; 00069 SQLSMALLINT radix; 00070 SQLSMALLINT nullable; 00071 SQLINTEGER octetlen; 00072 AST_RWLIST_ENTRY(odbc_cache_columns) list; 00073 }; 00074 00075 struct odbc_cache_tables { 00076 char *connection; 00077 char *table; 00078 AST_RWLIST_HEAD(_columns, odbc_cache_columns) columns; 00079 AST_RWLIST_ENTRY(odbc_cache_tables) list; 00080 }; 00081 00082 /* functions */ 00083 00084 /*! 00085 * \brief Executes a prepared statement handle 00086 * \param obj The non-NULL result of odbc_request_obj() 00087 * \param stmt The prepared statement handle 00088 * \retval 0 on success 00089 * \retval -1 on failure 00090 * 00091 * This function was originally designed simply to execute a prepared 00092 * statement handle and to retry if the initial execution failed. 00093 * Unfortunately, it did this by disconnecting and reconnecting the database 00094 * handle which on most databases causes the statement handle to become 00095 * invalid. Therefore, this method has been deprecated in favor of 00096 * odbc_prepare_and_execute() which allows the statement to be prepared 00097 * multiple times, if necessary, in case of a loss of connection. 00098 * 00099 * This function really only ever worked with MySQL, where the statement handle is 00100 * not prepared on the server. If you are not using MySQL, you should avoid it. 00101 */ 00102 int ast_odbc_smart_execute(struct odbc_obj *obj, SQLHSTMT stmt) __attribute__((deprecated)); 00103 00104 /*! 00105 * \brief Retrieves a connected ODBC object 00106 * \param name The name of the ODBC class for which a connection is needed. 00107 * \param flags One or more of the following flags: 00108 * \li RES_ODBC_SANITY_CHECK Whether to ensure that a connection is valid before returning the handle. Usually unnecessary. 00109 * \li RES_ODBC_INDEPENDENT_CONNECTION Return a handle which is independent from all others. Usually used when starting a transaction. 00110 * \li RES_ODBC_CONNECTED Only return a connected handle. Intended for use with peers which use idlecheck, which are checked periodically for reachability. 00111 * \return ODBC object 00112 * \retval NULL if there is no connection available with the requested name. 00113 * 00114 * Connection classes may, in fact, contain multiple connection handles. If 00115 * the connection is pooled, then each connection will be dedicated to the 00116 * thread which requests it. Note that all connections should be released 00117 * when the thread is done by calling ast_odbc_release_obj(), below. 00118 */ 00119 struct odbc_obj *_ast_odbc_request_obj2(const char *name, struct ast_flags flags, const char *file, const char *function, int lineno); 00120 struct odbc_obj *_ast_odbc_request_obj(const char *name, int check, const char *file, const char *function, int lineno); 00121 00122 #define ast_odbc_request_obj2(a, b) _ast_odbc_request_obj2(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__) 00123 #define ast_odbc_request_obj(a, b) _ast_odbc_request_obj(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__) 00124 00125 /*! 00126 * \brief Retrieve a stored ODBC object, if a transaction has been started. 00127 * \param chan Channel associated with the transaction. 00128 * \param objname Name of the database handle. This name corresponds to the name passed 00129 * to \see ast_odbc_request_obj2 (or formerly, to ast_odbc_request_obj). Note that the 00130 * existence of this parameter name explicitly allows for multiple transactions to be open 00131 * at once, albeit to different databases. 00132 * \retval A stored ODBC object, if a transaction was already started. 00133 * \retval NULL, if no transaction yet exists. 00134 */ 00135 struct odbc_obj *ast_odbc_retrieve_transaction_obj(struct ast_channel *chan, const char *objname); 00136 00137 /*! 00138 * \brief Releases an ODBC object previously allocated by ast_odbc_request_obj() 00139 * \param obj The ODBC object 00140 */ 00141 void ast_odbc_release_obj(struct odbc_obj *obj); 00142 00143 /*! 00144 * \brief Checks an ODBC object to ensure it is still connected 00145 * \param obj The ODBC object 00146 * \retval 0 if connected 00147 * \retval -1 otherwise. 00148 */ 00149 int ast_odbc_sanity_check(struct odbc_obj *obj); 00150 00151 /*! \brief Checks if the database natively supports backslash as an escape character. 00152 * \param obj The ODBC object 00153 * \return Returns 1 if backslash is a native escape character, 0 if an ESCAPE clause is needed to support '\' 00154 */ 00155 int ast_odbc_backslash_is_escape(struct odbc_obj *obj); 00156 00157 /*! \brief Executes an non prepared statement and returns the resulting 00158 * statement handle. 00159 * \param obj The ODBC object 00160 * \param exec_cb A function callback, which, when called, should return a statement handle with result columns bound. 00161 * \param data A parameter to be passed to the exec_cb parameter function, indicating which statement handle is to be prepared. 00162 * \retval a statement handle 00163 * \retval NULL on error 00164 */ 00165 SQLHSTMT ast_odbc_direct_execute(struct odbc_obj *obj, SQLHSTMT (*exec_cb)(struct odbc_obj *obj, void *data), void *data); 00166 00167 /*! 00168 * \brief Prepares, executes, and returns the resulting statement handle. 00169 * \param obj The ODBC object 00170 * \param prepare_cb A function callback, which, when called, should return a statement handle prepared, with any necessary parameters or result columns bound. 00171 * \param data A parameter to be passed to the prepare_cb parameter function, indicating which statement handle is to be prepared. 00172 * \retval a statement handle 00173 * \retval NULL on error 00174 */ 00175 SQLHSTMT ast_odbc_prepare_and_execute(struct odbc_obj *obj, SQLHSTMT (*prepare_cb)(struct odbc_obj *obj, void *data), void *data); 00176 00177 /*! 00178 * \brief Find or create an entry describing the table specified. 00179 * \param database Name of an ODBC class on which to query the table 00180 * \param tablename Tablename to describe 00181 * \retval A structure describing the table layout, or NULL, if the table is not found or another error occurs. 00182 * When a structure is returned, the contained columns list will be 00183 * rdlock'ed, to ensure that it will be retained in memory. The information 00184 * will be cached until a reload event or when ast_odbc_clear_cache() is called 00185 * with the relevant parameters. 00186 * \since 1.6.1 00187 */ 00188 struct odbc_cache_tables *ast_odbc_find_table(const char *database, const char *tablename); 00189 00190 /*! 00191 * \brief Find a column entry within a cached table structure 00192 * \param table Cached table structure, as returned from ast_odbc_find_table() 00193 * \param colname The column name requested 00194 * \retval A structure describing the column type, or NULL, if the column is not found. 00195 * \since 1.6.1 00196 */ 00197 struct odbc_cache_columns *ast_odbc_find_column(struct odbc_cache_tables *table, const char *colname); 00198 00199 /*! 00200 * \brief Remove a cache entry from memory 00201 * This function may be called to clear entries created and cached by the 00202 * ast_odbc_find_table() API call. 00203 * \param database Name of an ODBC class (used to ensure like-named tables in different databases are not confused) 00204 * \param tablename Tablename for which a cached record should be removed 00205 * \retval 0 if the cache entry was removed, or -1 if no matching entry was found. 00206 * \since 1.6.1 00207 */ 00208 int ast_odbc_clear_cache(const char *database, const char *tablename); 00209 00210 /*! 00211 * \brief Release a table returned from ast_odbc_find_table 00212 */ 00213 #define ast_odbc_release_table(ptr) if (ptr) { AST_RWLIST_UNLOCK(&(ptr)->columns); } 00214 00215 /*!\brief Wrapper for SQLGetData to use with dynamic strings 00216 * \param buf Address of the pointer to the ast_str structure. 00217 * \param pmaxlen The maximum size of the resulting string, or 0 for no limit. 00218 * \param StatementHandle The statement handle from which to retrieve data. 00219 * \param ColumnNumber Column number (1-based offset) for which to retrieve data. 00220 * \param TargetType The SQL constant indicating what kind of data is to be retrieved (usually SQL_CHAR) 00221 * \param StrLen_or_Ind A pointer to a length indicator, specifying the total length of data. 00222 */ 00223 SQLRETURN ast_odbc_ast_str_SQLGetData(struct ast_str **buf, int pmaxlen, SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber, SQLSMALLINT TargetType, SQLLEN *StrLen_or_Ind); 00224 00225 /*! \brief Checks if the database natively supports implicit conversion from an empty string to a number (0). 00226 * \param obj The ODBC object 00227 * \return Returns 1 if the implicit conversion is valid and non-text columns can take empty strings, 0 if the conversion is not valid and NULLs should be used instead '\' 00228 */ 00229 int ast_odbc_allow_empty_string_in_nontext(struct odbc_obj *obj); 00230 00231 #endif /* _ASTERISK_RES_ODBC_H */