Wed Jan 8 2020 09:49:50

Asterisk developer's documentation


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 {
48  SQLHDBC con; /*!< ODBC Connection Handle */
49  struct odbc_class *parent; /*!< Information about the connection is protected */
50  struct timeval last_used; /*!< Used by idlecheck to determine if the connection should be renegotiated */
51 #ifdef DEBUG_THREADS
52  char file[80];
53  char function[80];
54  int lineno;
55 #endif
56  unsigned int used:1; /*!< Is this connection currently in use? */
57  unsigned int up:1;
58  unsigned int tx:1; /*!< Should this connection be unshared, regardless of the class setting? */
59  struct odbc_txn_frame *txf; /*!< Reference back to the transaction frame, if applicable */
61 };
62 
63 /*!\brief These structures are used for adaptive capabilities */
65  char *name;
66  SQLSMALLINT type;
67  SQLINTEGER size;
68  SQLSMALLINT decimals;
69  SQLSMALLINT radix;
70  SQLSMALLINT nullable;
71  SQLINTEGER octetlen;
72  AST_RWLIST_ENTRY(odbc_cache_columns) list;
73 };
74 
76  char *connection;
77  char *table;
78  AST_RWLIST_HEAD(_columns, odbc_cache_columns) columns;
79  AST_RWLIST_ENTRY(odbc_cache_tables) list;
80 };
81 
82 /* functions */
83 
84 /*!
85  * \brief Executes a prepared statement handle
86  * \param obj The non-NULL result of odbc_request_obj()
87  * \param stmt The prepared statement handle
88  * \retval 0 on success
89  * \retval -1 on failure
90  *
91  * This function was originally designed simply to execute a prepared
92  * statement handle and to retry if the initial execution failed.
93  * Unfortunately, it did this by disconnecting and reconnecting the database
94  * handle which on most databases causes the statement handle to become
95  * invalid. Therefore, this method has been deprecated in favor of
96  * odbc_prepare_and_execute() which allows the statement to be prepared
97  * multiple times, if necessary, in case of a loss of connection.
98  *
99  * This function really only ever worked with MySQL, where the statement handle is
100  * not prepared on the server. If you are not using MySQL, you should avoid it.
101  */
102 int ast_odbc_smart_execute(struct odbc_obj *obj, SQLHSTMT stmt) __attribute__((deprecated));
103 
104 /*!
105  * \brief Retrieves a connected ODBC object
106  * \param name The name of the ODBC class for which a connection is needed.
107  * \param flags One or more of the following flags:
108  * \li RES_ODBC_SANITY_CHECK Whether to ensure that a connection is valid before returning the handle. Usually unnecessary.
109  * \li RES_ODBC_INDEPENDENT_CONNECTION Return a handle which is independent from all others. Usually used when starting a transaction.
110  * \li RES_ODBC_CONNECTED Only return a connected handle. Intended for use with peers which use idlecheck, which are checked periodically for reachability.
111  * \return ODBC object
112  * \retval NULL if there is no connection available with the requested name.
113  *
114  * Connection classes may, in fact, contain multiple connection handles. If
115  * the connection is pooled, then each connection will be dedicated to the
116  * thread which requests it. Note that all connections should be released
117  * when the thread is done by calling ast_odbc_release_obj(), below.
118  */
119 struct odbc_obj *_ast_odbc_request_obj2(const char *name, struct ast_flags flags, const char *file, const char *function, int lineno);
120 struct odbc_obj *_ast_odbc_request_obj(const char *name, int check, const char *file, const char *function, int lineno);
121 
122 #define ast_odbc_request_obj2(a, b) _ast_odbc_request_obj2(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__)
123 #define ast_odbc_request_obj(a, b) _ast_odbc_request_obj(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__)
124 
125 /*!
126  * \brief Retrieve a stored ODBC object, if a transaction has been started.
127  * \param chan Channel associated with the transaction.
128  * \param objname Name of the database handle. This name corresponds to the name passed
129  * to \see ast_odbc_request_obj2 (or formerly, to ast_odbc_request_obj). Note that the
130  * existence of this parameter name explicitly allows for multiple transactions to be open
131  * at once, albeit to different databases.
132  * \retval A stored ODBC object, if a transaction was already started.
133  * \retval NULL, if no transaction yet exists.
134  */
135 struct odbc_obj *ast_odbc_retrieve_transaction_obj(struct ast_channel *chan, const char *objname);
136 
137 /*!
138  * \brief Releases an ODBC object previously allocated by ast_odbc_request_obj()
139  * \param obj The ODBC object
140  */
141 void ast_odbc_release_obj(struct odbc_obj *obj);
142 
143 /*!
144  * \brief Checks an ODBC object to ensure it is still connected
145  * \param obj The ODBC object
146  * \retval 0 if connected
147  * \retval -1 otherwise.
148  */
149 int ast_odbc_sanity_check(struct odbc_obj *obj);
150 
151 /*! \brief Checks if the database natively supports backslash as an escape character.
152  * \param obj The ODBC object
153  * \return Returns 1 if backslash is a native escape character, 0 if an ESCAPE clause is needed to support '\'
154  */
155 int ast_odbc_backslash_is_escape(struct odbc_obj *obj);
156 
157 /*! \brief Executes an non prepared statement and returns the resulting
158  * statement handle.
159  * \param obj The ODBC object
160  * \param exec_cb A function callback, which, when called, should return a statement handle with result columns bound.
161  * \param data A parameter to be passed to the exec_cb parameter function, indicating which statement handle is to be prepared.
162  * \retval a statement handle
163  * \retval NULL on error
164  */
165 SQLHSTMT ast_odbc_direct_execute(struct odbc_obj *obj, SQLHSTMT (*exec_cb)(struct odbc_obj *obj, void *data), void *data);
166 
167 /*!
168  * \brief Prepares, executes, and returns the resulting statement handle.
169  * \param obj The ODBC object
170  * \param prepare_cb A function callback, which, when called, should return a statement handle prepared, with any necessary parameters or result columns bound.
171  * \param data A parameter to be passed to the prepare_cb parameter function, indicating which statement handle is to be prepared.
172  * \retval a statement handle
173  * \retval NULL on error
174  */
175 SQLHSTMT ast_odbc_prepare_and_execute(struct odbc_obj *obj, SQLHSTMT (*prepare_cb)(struct odbc_obj *obj, void *data), void *data);
176 
177 /*!
178  * \brief Find or create an entry describing the table specified.
179  * \param database Name of an ODBC class on which to query the table
180  * \param tablename Tablename to describe
181  * \retval A structure describing the table layout, or NULL, if the table is not found or another error occurs.
182  * When a structure is returned, the contained columns list will be
183  * rdlock'ed, to ensure that it will be retained in memory. The information
184  * will be cached until a reload event or when ast_odbc_clear_cache() is called
185  * with the relevant parameters.
186  * \since 1.6.1
187  */
188 struct odbc_cache_tables *ast_odbc_find_table(const char *database, const char *tablename);
189 
190 /*!
191  * \brief Find a column entry within a cached table structure
192  * \param table Cached table structure, as returned from ast_odbc_find_table()
193  * \param colname The column name requested
194  * \retval A structure describing the column type, or NULL, if the column is not found.
195  * \since 1.6.1
196  */
197 struct odbc_cache_columns *ast_odbc_find_column(struct odbc_cache_tables *table, const char *colname);
198 
199 /*!
200  * \brief Remove a cache entry from memory
201  * This function may be called to clear entries created and cached by the
202  * ast_odbc_find_table() API call.
203  * \param database Name of an ODBC class (used to ensure like-named tables in different databases are not confused)
204  * \param tablename Tablename for which a cached record should be removed
205  * \retval 0 if the cache entry was removed, or -1 if no matching entry was found.
206  * \since 1.6.1
207  */
208 int ast_odbc_clear_cache(const char *database, const char *tablename);
209 
210 /*!
211  * \brief Release a table returned from ast_odbc_find_table
212  */
213 #define ast_odbc_release_table(ptr) if (ptr) { AST_RWLIST_UNLOCK(&(ptr)->columns); }
214 
215 /*!\brief Wrapper for SQLGetData to use with dynamic strings
216  * \param buf Address of the pointer to the ast_str structure.
217  * \param pmaxlen The maximum size of the resulting string, or 0 for no limit.
218  * \param StatementHandle The statement handle from which to retrieve data.
219  * \param ColumnNumber Column number (1-based offset) for which to retrieve data.
220  * \param TargetType The SQL constant indicating what kind of data is to be retrieved (usually SQL_CHAR)
221  * \param StrLen_or_Ind A pointer to a length indicator, specifying the total length of data.
222  */
223 SQLRETURN ast_odbc_ast_str_SQLGetData(struct ast_str **buf, int pmaxlen, SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber, SQLSMALLINT TargetType, SQLLEN *StrLen_or_Ind);
224 
225 /*! \brief Checks if the database natively supports implicit conversion from an empty string to a number (0).
226  * \param obj The ODBC object
227  * \return Returns 1 if the implicit conversion is valid and non-text columns can take empty strings, 0 if the conversion is not valid and NULLs should be used instead '\'
228  */
230 
231 #endif /* _ASTERISK_RES_ODBC_H */
SQLHDBC con
Definition: res_odbc.h:48
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:1118
Main Channel structure associated with a channel.
Definition: channel.h:742
struct odbc_obj * ast_odbc_retrieve_transaction_obj(struct ast_channel *chan, const char *objname)
Retrieve a stored ODBC object, if a transaction has been started.
Definition: res_odbc.c:1456
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:1241
SQLSMALLINT nullable
Definition: res_odbc.h:70
char * connection
Definition: res_odbc.h:76
unsigned int tx
Definition: res_odbc.h:58
struct odbc_obj * _ast_odbc_request_obj(const char *name, int check, const char *file, const char *function, int lineno)
Definition: res_odbc.c:1450
These structures are used for adaptive capabilities.
Definition: res_odbc.h:64
SQLINTEGER octetlen
Definition: res_odbc.h:71
int ast_odbc_smart_execute(struct odbc_obj *obj, SQLHSTMT stmt)
Executes a prepared statement handle.
Definition: res_odbc.c:687
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:566
unsigned int used
Definition: res_odbc.h:56
A set of macros to manage forward-linked lists.
unsigned int up
Definition: res_odbc.h:57
struct odbc_class * parent
Definition: res_odbc.h:49
struct odbc_obj::@207 list
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:449
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:594
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:364
int ast_odbc_allow_empty_string_in_nontext(struct odbc_obj *obj)
Checks if the database natively supports implicit conversion from an empty string to a number (0)...
Definition: res_odbc.c:1123
struct odbc_txn_frame * txf
Definition: res_odbc.h:59
odbc_status
Definition: res_odbc.h:36
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
SQLINTEGER size
Definition: res_odbc.h:67
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:577
int ast_odbc_sanity_check(struct odbc_obj *obj)
Checks an ODBC object to ensure it is still connected.
Definition: res_odbc.c:735
Structure used to handle boolean flags.
Definition: utils.h:200
#define AST_RWLIST_ENTRY
Definition: linkedlists.h:414
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:622
ast_mutex_t lock
Definition: res_odbc.h:47
SQLSMALLINT decimals
Definition: res_odbc.h:68
struct timeval last_used
Definition: res_odbc.h:50
SQLSMALLINT radix
Definition: res_odbc.h:69
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:718
SQLSMALLINT type
Definition: res_odbc.h:66
void ast_odbc_release_obj(struct odbc_obj *obj)
Releases an ODBC object previously allocated by ast_odbc_request_obj()
Definition: res_odbc.c:1112
struct odbc_obj * obj
Definition: res_odbc.c:165
Structure for mutex and tracking information.
Definition: lock.h:121
#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