Merge the adaptive realtime branch, which will make adding new required fields
[asterisk/asterisk.git] / include / asterisk / res_odbc.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  * Copyright (C) 2004 - 2005, Anthony Minessale II
6  * Copyright (C) 2006, Tilghman Lesher
7  *
8  * Mark Spencer <markster@digium.com>
9  * Anthony Minessale <anthmct@yahoo.com>
10  * Tilghman Lesher <res_odbc_200603@the-tilghman.com>
11  *
12  * See http://www.asterisk.org for more information about
13  * the Asterisk project. Please do not directly contact
14  * any of the maintainers of this project for assistance;
15  * the project provides a web site, mailing lists and IRC
16  * channels for your use.
17  *
18  * This program is free software, distributed under the terms of
19  * the GNU General Public License Version 2. See the LICENSE file
20  * at the top of the source tree.
21  */
22
23 /*! \file
24  * \brief ODBC resource manager
25  */
26
27 #ifndef _ASTERISK_RES_ODBC_H
28 #define _ASTERISK_RES_ODBC_H
29
30 #include <sql.h>
31 #include <sqlext.h>
32 #include <sqltypes.h>
33 #include "asterisk/linkedlists.h"
34
35 typedef enum { ODBC_SUCCESS=0, ODBC_FAIL=-1} odbc_status;
36
37 /*! \brief ODBC container */
38 struct odbc_obj {
39         ast_mutex_t lock;
40         SQLHDBC  con;                   /* ODBC Connection Handle */
41         struct odbc_class *parent;      /* Information about the connection is protected */
42         struct timeval last_used;
43         unsigned int used:1;
44         unsigned int up:1;
45         AST_LIST_ENTRY(odbc_obj) list;
46 };
47
48 /*!\brief These aren't used in any API calls, but they are kept in a common
49  * location, simply for convenience and to avoid duplication.
50  */
51 struct odbc_cache_columns {
52         char *name;
53         SQLSMALLINT type;
54         SQLINTEGER size;
55         SQLSMALLINT decimals;
56         SQLSMALLINT radix;
57         SQLSMALLINT nullable;
58         SQLINTEGER octetlen;
59         AST_RWLIST_ENTRY(odbc_cache_columns) list;
60 };
61
62 struct odbc_cache_tables {
63         char *connection;
64         char *table;
65         AST_RWLIST_HEAD(_columns, odbc_cache_columns) columns;
66         AST_RWLIST_ENTRY(odbc_cache_tables) list;
67 };
68
69 /* functions */
70
71 /*! 
72  * \brief Executes a prepared statement handle
73  * \param obj The non-NULL result of odbc_request_obj()
74  * \param stmt The prepared statement handle
75  * \retval 0 on success
76  * \retval -1 on failure
77  *
78  * This function was originally designed simply to execute a prepared
79  * statement handle and to retry if the initial execution failed.
80  * Unfortunately, it did this by disconnecting and reconnecting the database
81  * handle which on most databases causes the statement handle to become
82  * invalid.  Therefore, this method has been deprecated in favor of
83  * odbc_prepare_and_execute() which allows the statement to be prepared
84  * multiple times, if necessary, in case of a loss of connection.
85  *
86  * This function really only ever worked with MySQL, where the statement handle is
87  * not prepared on the server.  If you are not using MySQL, you should avoid it.
88  */
89 int ast_odbc_smart_execute(struct odbc_obj *obj, SQLHSTMT stmt) __attribute__ ((deprecated));
90
91 /*! 
92  * \brief Retrieves a connected ODBC object
93  * \param name The name of the ODBC class for which a connection is needed.
94  * \param check Whether to ensure that a connection is valid before returning the handle.  Usually unnecessary.
95  * \retval ODBC object 
96  * \retval  NULL if there is no connection available with the requested name.
97  *
98  * Connection classes may, in fact, contain multiple connection handles.  If
99  * the connection is pooled, then each connection will be dedicated to the
100  * thread which requests it.  Note that all connections should be released
101  * when the thread is done by calling odbc_release_obj(), below.
102  */
103 struct odbc_obj *ast_odbc_request_obj(const char *name, int check);
104
105 /*! 
106  * \brief Releases an ODBC object previously allocated by odbc_request_obj()
107  * \param obj The ODBC object
108  */
109 void ast_odbc_release_obj(struct odbc_obj *obj);
110
111 /*! 
112  * \brief Checks an ODBC object to ensure it is still connected
113  * \param obj The ODBC object
114  * \retval 0 if connected
115  * \retval -1 otherwise.
116  */
117 int ast_odbc_sanity_check(struct odbc_obj *obj);
118
119 /*! \brief Checks if the database natively supports backslash as an escape character.
120  * \param obj The ODBC object
121  * \return Returns 1 if backslash is a native escape character, 0 if an ESCAPE clause is needed to support '\'
122  */
123 int ast_odbc_backslash_is_escape(struct odbc_obj *obj);
124
125 /*! \brief Executes an non prepared statement and returns the resulting
126  * statement handle.
127  * \param obj The ODBC object
128  * \param exec_cb A function callback, which, when called, should return a statement handle with result columns bound.
129  * \param data A parameter to be passed to the exec_cb parameter function, indicating which statement handle is to be prepared.
130  * \retval a statement handle
131  * \retval NULL on error
132  */
133 SQLHSTMT ast_odbc_direct_execute(struct odbc_obj *obj, SQLHSTMT (*exec_cb)(struct odbc_obj *obj, void *data), void *data);
134
135 /*! 
136  * \brief Prepares, executes, and returns the resulting statement handle.
137  * \param obj The ODBC object
138  * \param prepare_cb A function callback, which, when called, should return a statement handle prepared, with any necessary parameters or result columns bound.
139  * \param data A parameter to be passed to the prepare_cb parameter function, indicating which statement handle is to be prepared.
140  * \retval a statement handle 
141  * \retval NULL on error
142  */
143 SQLHSTMT ast_odbc_prepare_and_execute(struct odbc_obj *obj, SQLHSTMT (*prepare_cb)(struct odbc_obj *obj, void *data), void *data);
144
145 #endif /* _ASTERISK_RES_ODBC_H */