Sat Mar 10 01:54:25 2012

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 #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 #endif /* _ASTERISK_RES_ODBC_H */

Generated on Sat Mar 10 01:54:25 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7