Wed Aug 18 22:33:55 2010

Asterisk developer's documentation


res_odbc.h

Go to the documentation of this file.
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 */

Generated on Wed Aug 18 22:33:55 2010 for Asterisk - the Open Source PBX by  doxygen 1.4.7