Asterisk - The Open Source Telephony Project GIT-master-0bf3178
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>
34#include "asterisk/strings.h"
35
36typedef enum { ODBC_SUCCESS=0, ODBC_FAIL=-1} odbc_status;
37
38/*! \brief Flags for use with \see ast_odbc_request_obj2 */
39enum {
43};
44
45/*! \brief ODBC container */
46struct 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
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 */
97int 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#define ast_odbc_request_obj2(name, check) _ast_odbc_request_obj2(name, check, __FILE__, __PRETTY_FUNCTION__, __LINE__)
107struct odbc_obj *_ast_odbc_request_obj2(const char *name, struct ast_flags flags, const char *file, const char *function, int lineno);
108
109/*!
110 * \brief Get a ODBC connection object
111 *
112 * The "check" parameter is leftover from an earlier implementation where database connections
113 * were cached by res_odbc. Since connections are managed by unixODBC now, this parameter is
114 * only kept around for API compatibility.
115 *
116 * \param name The name of the res_odbc.conf section describing the database to connect to
117 * \param check unused
118 * \return A connection to the database. Call ast_odbc_release_obj() when finished.
119 */
120#define ast_odbc_request_obj(name, check) _ast_odbc_request_obj(name, check, __FILE__, __PRETTY_FUNCTION__, __LINE__)
121struct odbc_obj *_ast_odbc_request_obj(const char *name, int check, const char *file, const char *function, int lineno);
122
123/*!
124 * \brief Releases an ODBC object previously allocated by ast_odbc_request_obj()
125 * \param obj The ODBC object
126 */
127void ast_odbc_release_obj(struct odbc_obj *obj);
128
129/*!
130 * \brief Checks an ODBC object to ensure it is still connected
131 * \param obj The ODBC object
132 * \retval 0 if connected
133 * \retval -1 otherwise.
134 */
136
137/*! \brief Checks if the database natively supports backslash as an escape character.
138 * \param obj The ODBC object
139 * \retval 1 if backslash is a native escape character
140 * \retval 0 if an ESCAPE clause is needed to support '\'
141 */
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 * \return a statement handle
150 * \retval NULL on error
151 */
152SQLHSTMT 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 * \return a statement handle
160 * \retval NULL on error
161 */
162SQLHSTMT 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 * \param sql The SQL query
169 * \note This should be used in place of SQLPrepare
170 */
171int ast_odbc_prepare(struct odbc_obj *obj, SQLHSTMT *stmt, const char *sql);
172
173/*! \brief Execute a unprepared SQL query.
174 * \param obj The ODBC object
175 * \param stmt The statement
176 * \param sql The SQL query
177 * \note This should be used in place of SQLExecDirect
178 */
179SQLRETURN ast_odbc_execute_sql(struct odbc_obj *obj, SQLHSTMT *stmt, const char *sql);
180
181/*!
182 * \brief Find or create an entry describing the table specified.
183 * \param database Name of an ODBC class on which to query the table
184 * \param tablename Tablename to describe
185 * \return A structure describing the table layout.
186 * \retval NULL if the table is not found or another error occurs.
187 * When a structure is returned, the contained columns list will be
188 * rdlock'ed, to ensure that it will be retained in memory. The information
189 * will be cached until a reload event or when ast_odbc_clear_cache() is called
190 * with the relevant parameters.
191 * \since 1.6.1
192 */
193struct odbc_cache_tables *ast_odbc_find_table(const char *database, const char *tablename);
194
195/*!
196 * \brief Find a column entry within a cached table structure
197 * \param table Cached table structure, as returned from ast_odbc_find_table()
198 * \param colname The column name requested
199 * \return A structure describing the column type, or NULL, if the column is not found.
200 * \since 1.6.1
201 */
202struct odbc_cache_columns *ast_odbc_find_column(struct odbc_cache_tables *table, const char *colname);
203
204/*!
205 * \brief Remove a cache entry from memory
206 * This function may be called to clear entries created and cached by the
207 * ast_odbc_find_table() API call.
208 * \param database Name of an ODBC class (used to ensure like-named tables in different databases are not confused)
209 * \param tablename Tablename for which a cached record should be removed
210 * \retval 0 if the cache entry was removed.
211 * \retval -1 if no matching entry was found.
212 * \since 1.6.1
213 */
214int ast_odbc_clear_cache(const char *database, const char *tablename);
215
216/*!
217 * \brief Release a table returned from ast_odbc_find_table
218 */
219#define ast_odbc_release_table(ptr) if (ptr) { AST_RWLIST_UNLOCK(&(ptr)->columns); }
220
221/*!\brief Wrapper for SQLGetData to use with dynamic strings
222 * \param buf Address of the pointer to the ast_str structure.
223 * \param pmaxlen The maximum size of the resulting string, or 0 for no limit.
224 * \param StatementHandle The statement handle from which to retrieve data.
225 * \param ColumnNumber Column number (1-based offset) for which to retrieve data.
226 * \param TargetType The SQL constant indicating what kind of data is to be retrieved (usually SQL_CHAR)
227 * \param StrLen_or_Ind A pointer to a length indicator, specifying the total length of data.
228 */
229SQLRETURN ast_odbc_ast_str_SQLGetData(struct ast_str **buf, int pmaxlen, SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber, SQLSMALLINT TargetType, SQLLEN *StrLen_or_Ind);
230
231/*!
232 * \brief Shortcut for printing errors to logs after a failed SQL operation.
233 *
234 * \param handle_type The type of SQL handle on which to gather diagnostics
235 * \param handle The SQL handle to gather diagnostics from
236 * \param operation The name of the failed operation.
237 * \return The error string that was printed to the logs
238 */
239struct ast_str *ast_odbc_print_errors(SQLSMALLINT handle_type, SQLHANDLE handle, const char *operation);
240
241/*!
242 * \brief Get the transaction isolation setting for an ODBC class
243 */
244unsigned int ast_odbc_class_get_isolation(struct odbc_class *class);
245
246/*!
247 * \brief Get the transaction forcecommit setting for an ODBC class
248 */
249unsigned int ast_odbc_class_get_forcecommit(struct odbc_class *class);
250
251/*!
252 * \brief Get the name of an ODBC class.
253 */
254const char *ast_odbc_class_get_name(struct odbc_class *class);
255
256/*!
257 * \brief Convert from textual transaction isolation values to their numeric constants
258 */
259int ast_odbc_text2isolation(const char *txt);
260
261/*!
262 * \brief Convert from numeric transaction isolation values to their textual counterparts
263 */
264const char *ast_odbc_isolation2text(int iso);
265
266/*!
267 * \brief Return the current configured maximum number of connections for a class
268 */
269unsigned int ast_odbc_get_max_connections(const char *name);
270
271#endif /* _ASTERISK_RES_ODBC_H */
static char * table
Definition: cdr_odbc.c:55
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
static const char name[]
Definition: format_mp3.c:68
A set of macros to manage forward-linked lists.
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
#define AST_RWLIST_HEAD(name, type)
Defines a structure to be used to hold a read/write list of specified type.
Definition: linkedlists.h:199
#define AST_RWLIST_ENTRY
Definition: linkedlists.h:415
odbc_status
Definition: res_odbc.h:36
@ ODBC_FAIL
Definition: res_odbc.h:36
@ ODBC_SUCCESS
Definition: res_odbc.h:36
@ RES_ODBC_INDEPENDENT_CONNECTION
Definition: res_odbc.h:41
@ RES_ODBC_CONNECTED
Definition: res_odbc.h:42
@ RES_ODBC_SANITY_CHECK
Definition: res_odbc.h:40
int ast_odbc_prepare(struct odbc_obj *obj, SQLHSTMT *stmt, const char *sql)
Prepares a SQL query on a statement.
Definition: res_odbc.c:454
unsigned int ast_odbc_class_get_isolation(struct odbc_class *class)
Get the transaction isolation setting for an ODBC class.
Definition: res_odbc.c:540
void ast_odbc_release_obj(struct odbc_obj *obj)
Releases an ODBC object previously allocated by ast_odbc_request_obj()
Definition: res_odbc.c:804
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:232
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:848
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:343
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:332
int ast_odbc_sanity_check(struct odbc_obj *obj)
Checks an ODBC object to ensure it is still connected.
struct odbc_obj * _ast_odbc_request_obj(const char *name, int check, const char *file, const char *function, int lineno)
Definition: res_odbc.c:998
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:515
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:833
const char * ast_odbc_isolation2text(int iso)
Convert from numeric transaction isolation values to their textual counterparts.
Definition: res_odbc.c:132
const char * ast_odbc_class_get_name(struct odbc_class *class)
Get the name of an ODBC class.
Definition: res_odbc.c:550
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:498
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:360
unsigned int ast_odbc_class_get_forcecommit(struct odbc_class *class)
Get the transaction forcecommit setting for an ODBC class.
Definition: res_odbc.c:545
SQLRETURN ast_odbc_execute_sql(struct odbc_obj *obj, SQLHSTMT *stmt, const char *sql)
Execute a unprepared SQL query.
Definition: res_odbc.c:469
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:398
int ast_odbc_text2isolation(const char *txt)
Convert from textual transaction isolation values to their numeric constants.
Definition: res_odbc.c:147
struct odbc_obj * _ast_odbc_request_obj2(const char *name, struct ast_flags flags, const char *file, const char *function, int lineno)
Definition: res_odbc.c:908
int ast_odbc_smart_execute(struct odbc_obj *obj, SQLHSTMT stmt)
Executes a prepared statement handle.
Definition: res_odbc.c:480
String manipulation functions.
Structure used to handle boolean flags.
Definition: utils.h:199
Support for dynamic strings.
Definition: strings.h:623
These structures are used for adaptive capabilities.
Definition: res_odbc.h:59
SQLSMALLINT decimals
Definition: res_odbc.h:63
SQLSMALLINT radix
Definition: res_odbc.h:64
SQLSMALLINT type
Definition: res_odbc.h:61
SQLINTEGER octetlen
Definition: res_odbc.h:66
SQLINTEGER size
Definition: res_odbc.h:62
SQLSMALLINT nullable
Definition: res_odbc.h:65
char * connection
Definition: res_odbc.h:71
struct odbc_cache_tables::_columns columns
ODBC container.
Definition: res_odbc.h:46
char * sql_text
Definition: res_odbc.h:54
struct odbc_class * parent
Definition: res_odbc.h:48
struct odbc_obj::@255 list
SQLHDBC con
Definition: res_odbc.h:47