Asterisk - The Open Source Telephony Project  GIT-master-1b41629
res_odbc.h
Go to the documentation of this file.
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 #include "asterisk/strings.h"
35 
36 typedef enum { ODBC_SUCCESS=0, ODBC_FAIL=-1} odbc_status;
37 
38 /*! \brief Flags for use with \see ast_odbc_request_obj2 */
39 enum {
42  RES_ODBC_CONNECTED = (1 << 2),
43 };
44 
45 /*! \brief ODBC container */
46 struct odbc_obj {
47  SQLHDBC con; /*!< ODBC Connection Handle */
48  struct odbc_class *parent; /*!< Information about the connection is protected */
49 #ifdef DEBUG_THREADS
50  char file[80];
51  char function[80];
52  int lineno;
53 #endif
54  char *sql_text; /*!< The SQL text currently executing */
56 };
57 
58 /*!\brief These structures are used for adaptive capabilities */
60  char *name;
61  SQLSMALLINT type;
62  SQLINTEGER size;
63  SQLSMALLINT decimals;
64  SQLSMALLINT radix;
65  SQLSMALLINT nullable;
66  SQLINTEGER octetlen;
68 };
69 
71  char *connection;
72  char *table;
75 };
76 
77 /* functions */
78 
79 /*!
80  * \brief Executes a prepared statement handle
81  * \param obj The non-NULL result of odbc_request_obj()
82  * \param stmt The prepared statement handle
83  * \retval 0 on success
84  * \retval -1 on failure
85  *
86  * This function was originally designed simply to execute a prepared
87  * statement handle and to retry if the initial execution failed.
88  * Unfortunately, it did this by disconnecting and reconnecting the database
89  * handle which on most databases causes the statement handle to become
90  * invalid. Therefore, this method has been deprecated in favor of
91  * odbc_prepare_and_execute() which allows the statement to be prepared
92  * multiple times, if necessary, in case of a loss of connection.
93  *
94  * This function really only ever worked with MySQL, where the statement handle is
95  * not prepared on the server. If you are not using MySQL, you should avoid it.
96  */
97 int ast_odbc_smart_execute(struct odbc_obj *obj, SQLHSTMT stmt) __attribute__((deprecated));
98 
99 /*!
100  * \brief Retrieves a connected ODBC object
101  *
102  * \deprecated
103  *
104  * This is only around for backwards-compatibility with older versions of Asterisk.
105  */
106 struct odbc_obj *_ast_odbc_request_obj2(const char *name, struct ast_flags flags, const char *file, const char *function, int lineno);
107 
108 /*!
109  * \brief Get a ODBC connection object
110  *
111  * The "check" parameter is leftover from an earlier implementation where database connections
112  * were cached by res_odbc. Since connections are managed by unixODBC now, this parameter is
113  * only kept around for API compatibility.
114  *
115  * \param name The name of the res_odbc.conf section describing the database to connect to
116  * \param check unused
117  * \return A connection to the database. Call ast_odbc_release_obj() when finished.
118  */
119 struct odbc_obj *_ast_odbc_request_obj(const char *name, int check, const char *file, const char *function, int lineno);
120 
121 #define ast_odbc_request_obj2(a, b) _ast_odbc_request_obj2(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__)
122 #define ast_odbc_request_obj(a, b) _ast_odbc_request_obj(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__)
123 
124 /*!
125  * \brief Releases an ODBC object previously allocated by ast_odbc_request_obj()
126  * \param obj The ODBC object
127  */
128 void ast_odbc_release_obj(struct odbc_obj *obj);
129 
130 /*!
131  * \brief Checks an ODBC object to ensure it is still connected
132  * \param obj The ODBC object
133  * \retval 0 if connected
134  * \retval -1 otherwise.
135  */
136 int ast_odbc_sanity_check(struct odbc_obj *obj);
137 
138 /*! \brief Checks if the database natively supports backslash as an escape character.
139  * \param obj The ODBC object
140  * \return Returns 1 if backslash is a native escape character, 0 if an ESCAPE clause is needed to support '\'
141  */
142 int ast_odbc_backslash_is_escape(struct odbc_obj *obj);
143 
144 /*! \brief Executes an non prepared statement and returns the resulting
145  * statement handle.
146  * \param obj The ODBC object
147  * \param exec_cb A function callback, which, when called, should return a statement handle with result columns bound.
148  * \param data A parameter to be passed to the exec_cb parameter function, indicating which statement handle is to be prepared.
149  * \retval a statement handle
150  * \retval NULL on error
151  */
152 SQLHSTMT ast_odbc_direct_execute(struct odbc_obj *obj, SQLHSTMT (*exec_cb)(struct odbc_obj *obj, void *data), void *data);
153 
154 /*!
155  * \brief Prepares, executes, and returns the resulting statement handle.
156  * \param obj The ODBC object
157  * \param prepare_cb A function callback, which, when called, should return a statement handle prepared, with any necessary parameters or result columns bound.
158  * \param data A parameter to be passed to the prepare_cb parameter function, indicating which statement handle is to be prepared.
159  * \retval a statement handle
160  * \retval NULL on error
161  */
162 SQLHSTMT ast_odbc_prepare_and_execute(struct odbc_obj *obj, SQLHSTMT (*prepare_cb)(struct odbc_obj *obj, void *data), void *data);
163 
164 /*!
165  * \brief Prepares a SQL query on a statement.
166  * \param obj The ODBC object
167  * \param stmt The statement
168  * \parma sql The SQL query
169  * \note This should be used in place of SQLPrepare
170  */
171 int ast_odbc_prepare(struct odbc_obj *obj, SQLHSTMT *stmt, const char *sql);
172 
173 /*! \brief Execute a nonprepared SQL query.
174  * \param obj The ODBC object
175  * \param sql The SQL query
176  * \note This should be used in place of SQLExecDirect
177  */
178 SQLRETURN ast_odbc_execute_sql(struct odbc_obj *obj, SQLHSTMT *stmt, const char *sql);
179 
180 /*!
181  * \brief Find or create an entry describing the table specified.
182  * \param database Name of an ODBC class on which to query the table
183  * \param tablename Tablename to describe
184  * \retval A structure describing the table layout, or NULL, if the table is not found or another error occurs.
185  * When a structure is returned, the contained columns list will be
186  * rdlock'ed, to ensure that it will be retained in memory. The information
187  * will be cached until a reload event or when ast_odbc_clear_cache() is called
188  * with the relevant parameters.
189  * \since 1.6.1
190  */
191 struct odbc_cache_tables *ast_odbc_find_table(const char *database, const char *tablename);
192 
193 /*!
194  * \brief Find a column entry within a cached table structure
195  * \param table Cached table structure, as returned from ast_odbc_find_table()
196  * \param colname The column name requested
197  * \retval A structure describing the column type, or NULL, if the column is not found.
198  * \since 1.6.1
199  */
200 struct odbc_cache_columns *ast_odbc_find_column(struct odbc_cache_tables *table, const char *colname);
201 
202 /*!
203  * \brief Remove a cache entry from memory
204  * This function may be called to clear entries created and cached by the
205  * ast_odbc_find_table() API call.
206  * \param database Name of an ODBC class (used to ensure like-named tables in different databases are not confused)
207  * \param tablename Tablename for which a cached record should be removed
208  * \retval 0 if the cache entry was removed, or -1 if no matching entry was found.
209  * \since 1.6.1
210  */
211 int ast_odbc_clear_cache(const char *database, const char *tablename);
212 
213 /*!
214  * \brief Release a table returned from ast_odbc_find_table
215  */
216 #define ast_odbc_release_table(ptr) if (ptr) { AST_RWLIST_UNLOCK(&(ptr)->columns); }
217 
218 /*!\brief Wrapper for SQLGetData to use with dynamic strings
219  * \param buf Address of the pointer to the ast_str structure.
220  * \param pmaxlen The maximum size of the resulting string, or 0 for no limit.
221  * \param StatementHandle The statement handle from which to retrieve data.
222  * \param ColumnNumber Column number (1-based offset) for which to retrieve data.
223  * \param TargetType The SQL constant indicating what kind of data is to be retrieved (usually SQL_CHAR)
224  * \param StrLen_or_Ind A pointer to a length indicator, specifying the total length of data.
225  */
226 SQLRETURN ast_odbc_ast_str_SQLGetData(struct ast_str **buf, int pmaxlen, SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber, SQLSMALLINT TargetType, SQLLEN *StrLen_or_Ind);
227 
228 /*!
229  * \brief Shortcut for printing errors to logs after a failed SQL operation.
230  *
231  * \param handle_type The type of SQL handle on which to gather diagnostics
232  * \param handle The SQL handle to gather diagnostics from
233  * \param operation The name of the failed operation.
234  * \return The error string that was printed to the logs
235  */
236 struct ast_str *ast_odbc_print_errors(SQLSMALLINT handle_type, SQLHANDLE handle, const char *operation);
237 
238 /*!
239  * \brief Get the transaction isolation setting for an ODBC class
240  */
241 unsigned int ast_odbc_class_get_isolation(struct odbc_class *class);
242 
243 /*!
244  * \brief Get the transaction forcecommit setting for an ODBC class
245  */
246 unsigned int ast_odbc_class_get_forcecommit(struct odbc_class *class);
247 
248 /*!
249  * \brief Get the name of an ODBC class.
250  */
251 const char *ast_odbc_class_get_name(struct odbc_class *class);
252 
253 /*!
254  * \brief Convert from textual transaction isolation values to their numeric constants
255  */
256 int ast_odbc_text2isolation(const char *txt);
257 
258 /*!
259  * \brief Convert from numeric transaction isolation values to their textual counterparts
260  */
261 const char *ast_odbc_isolation2text(int iso);
262 
263 /*!
264  * \brief Return the current configured maximum number of connections for a class
265  */
266 unsigned int ast_odbc_get_max_connections(const char *name);
267 
268 #endif /* _ASTERISK_RES_ODBC_H */
SQLHDBC con
Definition: res_odbc.h:47
int ast_odbc_backslash_is_escape(struct odbc_obj *obj)
Checks if the database natively supports backslash as an escape character.
Definition: res_odbc.c:842
struct odbc_obj::@288 list
String manipulation functions.
struct odbc_obj * _ast_odbc_request_obj2(const char *name, struct ast_flags flags, const char *file, const char *function, int lineno)
Retrieves a connected ODBC object.
Definition: res_odbc.c:917
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
int ast_odbc_prepare(struct odbc_obj *obj, SQLHSTMT *stmt, const char *sql)
Prepares a SQL query on a statement.
Definition: res_odbc.c:463
SQLSMALLINT nullable
Definition: res_odbc.h:65
char * connection
Definition: res_odbc.h:71
struct odbc_obj * _ast_odbc_request_obj(const char *name, int check, const char *file, const char *function, int lineno)
Get a ODBC connection object.
Definition: res_odbc.c:984
These structures are used for adaptive capabilities.
Definition: res_odbc.h:59
SQLINTEGER octetlen
Definition: res_odbc.h:66
static char * table
Definition: cdr_odbc.c:58
int ast_odbc_smart_execute(struct odbc_obj *obj, SQLHSTMT stmt)
Executes a prepared statement handle.
Definition: res_odbc.c:489
unsigned int ast_odbc_get_max_connections(const char *name)
Return the current configured maximum number of connections for a class.
Definition: res_odbc.c:857
unsigned int ast_odbc_class_get_isolation(struct odbc_class *class)
Get the transaction isolation setting for an ODBC class.
Definition: res_odbc.c:549
ODBC container.
Definition: res_odbc.h:46
struct odbc_cache_columns * ast_odbc_find_column(struct odbc_cache_tables *table, const char *colname)
Find a column entry within a cached table structure.
Definition: res_odbc.c:341
A set of macros to manage forward-linked lists.
const char * ast_odbc_isolation2text(int iso)
Convert from numeric transaction isolation values to their textual counterparts.
Definition: res_odbc.c:132
struct odbc_class * parent
Definition: res_odbc.h:48
struct ast_str * ast_odbc_print_errors(SQLSMALLINT handle_type, SQLHANDLE handle, const char *operation)
Shortcut for printing errors to logs after a failed SQL operation.
Definition: res_odbc.c:524
struct odbc_cache_tables * ast_odbc_find_table(const char *database, const char *tablename)
Find or create an entry describing the table specified.
Definition: res_odbc.c:241
SQLHSTMT ast_odbc_direct_execute(struct odbc_obj *obj, SQLHSTMT(*exec_cb)(struct odbc_obj *obj, void *data), void *data)
Executes an non prepared statement and returns the resulting statement handle.
Definition: res_odbc.c:369
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:584
int ast_odbc_text2isolation(const char *txt)
Convert from textual transaction isolation values to their numeric constants.
Definition: res_odbc.c:147
odbc_status
Definition: res_odbc.h:36
unsigned int ast_odbc_class_get_forcecommit(struct odbc_class *class)
Get the transaction forcecommit setting for an ODBC class.
Definition: res_odbc.c:554
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
static struct columns columns
static const char name[]
Definition: cdr_mysql.c:74
SQLINTEGER size
Definition: res_odbc.h:62
int ast_odbc_clear_cache(const char *database, const char *tablename)
Remove a cache entry from memory This function may be called to clear entries created and cached by t...
Definition: res_odbc.c:352
int ast_odbc_sanity_check(struct odbc_obj *obj)
Checks an ODBC object to ensure it is still connected.
Structure used to handle boolean flags.
Definition: utils.h:199
#define AST_RWLIST_ENTRY
Definition: linkedlists.h:414
SQLRETURN ast_odbc_execute_sql(struct odbc_obj *obj, SQLHSTMT *stmt, const char *sql)
Execute a nonprepared SQL query.
Definition: res_odbc.c:478
SQLHSTMT ast_odbc_prepare_and_execute(struct odbc_obj *obj, SQLHSTMT(*prepare_cb)(struct odbc_obj *obj, void *data), void *data)
Prepares, executes, and returns the resulting statement handle.
Definition: res_odbc.c:407
SQLSMALLINT decimals
Definition: res_odbc.h:63
char * sql_text
Definition: res_odbc.h:54
SQLSMALLINT radix
Definition: res_odbc.h:64
SQLRETURN ast_odbc_ast_str_SQLGetData(struct ast_str **buf, int pmaxlen, SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber, SQLSMALLINT TargetType, SQLLEN *StrLen_or_Ind)
Wrapper for SQLGetData to use with dynamic strings.
Definition: res_odbc.c:507
SQLSMALLINT type
Definition: res_odbc.h:61
void ast_odbc_release_obj(struct odbc_obj *obj)
Releases an ODBC object previously allocated by ast_odbc_request_obj()
Definition: res_odbc.c:813
#define AST_RWLIST_HEAD(name, type)
Defines a structure to be used to hold a read/write list of specified type.
Definition: linkedlists.h:198
const char * ast_odbc_class_get_name(struct odbc_class *class)
Get the name of an ODBC class.
Definition: res_odbc.c:559