Thu Jul 9 13:40:40 2009

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 
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 */

Generated on Thu Jul 9 13:40:40 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7