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 00034 typedef enum { ODBC_SUCCESS=0, ODBC_FAIL=-1} odbc_status; 00035 00036 /*! \brief ODBC container */ 00037 struct odbc_obj { 00038 ast_mutex_t lock; 00039 SQLHDBC con; /* ODBC Connection Handle */ 00040 struct odbc_class *parent; /* Information about the connection is protected */ 00041 struct timeval last_used; 00042 unsigned int used:1; 00043 unsigned int up:1; 00044 AST_LIST_ENTRY(odbc_obj) list; 00045 }; 00046 00047 /* functions */ 00048 00049 /*! 00050 * \brief Executes a prepared statement handle 00051 * \param obj The non-NULL result of odbc_request_obj() 00052 * \param stmt The prepared statement handle 00053 * \retval 0 on success 00054 * \retval -1 on failure 00055 * 00056 * This function was originally designed simply to execute a prepared 00057 * statement handle and to retry if the initial execution failed. 00058 * Unfortunately, it did this by disconnecting and reconnecting the database 00059 * handle which on most databases causes the statement handle to become 00060 * invalid. Therefore, this method has been deprecated in favor of 00061 * odbc_prepare_and_execute() which allows the statement to be prepared 00062 * multiple times, if necessary, in case of a loss of connection. 00063 * 00064 * This function really only ever worked with MySQL, where the statement handle is 00065 * not prepared on the server. If you are not using MySQL, you should avoid it. 00066 */ 00067 int ast_odbc_smart_execute(struct odbc_obj *obj, SQLHSTMT stmt) __attribute__((deprecated)); 00068 00069 /*! 00070 * \brief Retrieves a connected ODBC object 00071 * \param name The name of the ODBC class for which a connection is needed. 00072 * \param check Whether to ensure that a connection is valid before returning the handle. Usually unnecessary. 00073 * \retval ODBC object 00074 * \retval NULL if there is no connection available with the requested name. 00075 * 00076 * Connection classes may, in fact, contain multiple connection handles. If 00077 * the connection is pooled, then each connection will be dedicated to the 00078 * thread which requests it. Note that all connections should be released 00079 * when the thread is done by calling odbc_release_obj(), below. 00080 */ 00081 struct odbc_obj *ast_odbc_request_obj(const char *name, int check); 00082 00083 /*! 00084 * \brief Releases an ODBC object previously allocated by odbc_request_obj() 00085 * \param obj The ODBC object 00086 */ 00087 void ast_odbc_release_obj(struct odbc_obj *obj); 00088 00089 /*! 00090 * \brief Checks an ODBC object to ensure it is still connected 00091 * \param obj The ODBC object 00092 * \retval 0 if connected 00093 * \retval -1 otherwise. 00094 */ 00095 int ast_odbc_sanity_check(struct odbc_obj *obj); 00096 00097 /*! \brief Checks if the database natively supports backslash as an escape character. 00098 * \param obj The ODBC object 00099 * \return Returns 1 if backslash is a native escape character, 0 if an ESCAPE clause is needed to support '\' 00100 */ 00101 int ast_odbc_backslash_is_escape(struct odbc_obj *obj); 00102 00103 /*! \brief Executes an non prepared statement and returns the resulting 00104 * statement handle. 00105 * \param obj The ODBC object 00106 * \param exec_cb A function callback, which, when called, should return a statement handle with result columns bound. 00107 * \param data A parameter to be passed to the exec_cb parameter function, indicating which statement handle is to be prepared. 00108 * \retval a statement handle 00109 * \retval NULL on error 00110 */ 00111 SQLHSTMT ast_odbc_direct_execute(struct odbc_obj *obj, SQLHSTMT (*exec_cb)(struct odbc_obj *obj, void *data), void *data); 00112 00113 /*! 00114 * \brief Prepares, executes, and returns the resulting statement handle. 00115 * \param obj The ODBC object 00116 * \param prepare_cb A function callback, which, when called, should return a statement handle prepared, with any necessary parameters or result columns bound. 00117 * \param data A parameter to be passed to the prepare_cb parameter function, indicating which statement handle is to be prepared. 00118 * \retval a statement handle 00119 * \retval NULL on error 00120 */ 00121 SQLHSTMT ast_odbc_prepare_and_execute(struct odbc_obj *obj, SQLHSTMT (*prepare_cb)(struct odbc_obj *obj, void *data), void *data); 00122 00123 #endif /* _ASTERISK_RES_ODBC_H */