Add Doxygen documentation for API changes from 1.6.0 to 1.6.1
[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 #include "asterisk/strings.h"
35
36 typedef enum { ODBC_SUCCESS=0, ODBC_FAIL=-1} odbc_status;
37
38 /*! \brief Flags for use with ast_odbc_request_obj2 */
39 enum {
40         RES_ODBC_SANITY_CHECK = (1 << 0),
41         RES_ODBC_INDEPENDENT_CONNECTION = (1 << 1),
42 };
43
44 /*! \brief ODBC container */
45 struct odbc_obj {
46         ast_mutex_t lock;
47         SQLHDBC  con;                   /*!< ODBC Connection Handle */
48         struct odbc_class *parent;      /*!< Information about the connection is protected */
49         struct timeval last_used;       /*!< Used by idlecheck to determine if the connection should be renegotiated */
50 #ifdef DEBUG_THREADS
51         char file[80];
52         char function[80];
53         int lineno;
54 #endif
55         unsigned int used:1;            /*!< Is this connection currently in use? */
56         unsigned int up:1;
57         unsigned int tx:1;              /*!< Should this connection be unshared, regardless of the class setting? */
58         struct odbc_txn_frame *txf;     /*!< Reference back to the transaction frame, if applicable */
59         AST_LIST_ENTRY(odbc_obj) list;
60 };
61
62 struct odbc_cache_columns {
63         char *name;
64         SQLSMALLINT type;
65         SQLINTEGER size;
66         SQLSMALLINT decimals;
67         SQLSMALLINT radix;
68         SQLSMALLINT nullable;
69         SQLINTEGER octetlen;
70         AST_RWLIST_ENTRY(odbc_cache_columns) list;
71 };
72
73 struct odbc_cache_tables {
74         char *connection;
75         char *table;
76         AST_RWLIST_HEAD(_columns, odbc_cache_columns) columns;
77         AST_RWLIST_ENTRY(odbc_cache_tables) list;
78 };
79
80 /* functions */
81
82 /*! 
83  * \brief Executes a prepared statement handle
84  * \param obj The non-NULL result of odbc_request_obj()
85  * \param stmt The prepared statement handle
86  * \retval 0 on success
87  * \retval -1 on failure
88  *
89  * This function was originally designed simply to execute a prepared
90  * statement handle and to retry if the initial execution failed.
91  * Unfortunately, it did this by disconnecting and reconnecting the database
92  * handle which on most databases causes the statement handle to become
93  * invalid.  Therefore, this method has been deprecated in favor of
94  * odbc_prepare_and_execute() which allows the statement to be prepared
95  * multiple times, if necessary, in case of a loss of connection.
96  *
97  * This function really only ever worked with MySQL, where the statement handle is
98  * not prepared on the server.  If you are not using MySQL, you should avoid it.
99  */
100 int ast_odbc_smart_execute(struct odbc_obj *obj, SQLHSTMT stmt) __attribute__((deprecated));
101
102 /*! 
103  * \brief Retrieves a connected ODBC object
104  * \param name The name of the ODBC class for which a connection is needed.
105  * \param check Whether to ensure that a connection is valid before returning the handle.  Usually unnecessary.
106  * \retval ODBC object 
107  * \retval  NULL if there is no connection available with the requested name.
108  *
109  * Connection classes may, in fact, contain multiple connection handles.  If
110  * the connection is pooled, then each connection will be dedicated to the
111  * thread which requests it.  Note that all connections should be released
112  * when the thread is done by calling odbc_release_obj(), below.
113  */
114 #ifdef DEBUG_THREADS
115 struct odbc_obj *_ast_odbc_request_obj2(const char *name, struct ast_flags flags, const char *file, const char *function, int lineno);
116 #define ast_odbc_request_obj2(a, b)     _ast_odbc_request_obj2(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__)
117 #else
118 struct odbc_obj *ast_odbc_request_obj2(const char *name, struct ast_flags flags);
119 #endif
120
121 #ifdef DEBUG_THREADS
122 struct odbc_obj *_ast_odbc_request_obj(const char *name, int check, const char *file, const char *function, int lineno);
123 #define ast_odbc_request_obj(a, b)      _ast_odbc_request_obj(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__)
124 #else
125 struct odbc_obj *ast_odbc_request_obj(const char *name, int check);
126 #endif
127
128 /*!
129  * \brief Retrieve a stored ODBC object, if a transaction has been started.
130  * \param chan Channel associated with the transaction.
131  * \param objname Name of the database handle.  This name corresponds to the name passed
132  * to ast_odbc_request_obj2 (or formerly, to ast_odbc_request_obj).  Note that the
133  * existence of this parameter name explicitly allows for multiple transactions to be open
134  * at once, albeit to different databases.
135  * \retval A stored ODBC object, if a transaction was already started.
136  * \retval NULL, if no transaction yet exists.
137  */
138 struct odbc_obj *ast_odbc_retrieve_transaction_obj(struct ast_channel *chan, const char *objname);
139
140 /*! 
141  * \brief Releases an ODBC object previously allocated by odbc_request_obj()
142  * \param obj The ODBC object
143  */
144 void ast_odbc_release_obj(struct odbc_obj *obj);
145
146 /*! 
147  * \brief Checks an ODBC object to ensure it is still connected
148  * \param obj The ODBC object
149  * \retval 0 if connected
150  * \retval -1 otherwise.
151  */
152 int ast_odbc_sanity_check(struct odbc_obj *obj);
153
154 /*! \brief Checks if the database natively supports backslash as an escape character.
155  * \param obj The ODBC object
156  * \return Returns 1 if backslash is a native escape character, 0 if an ESCAPE clause is needed to support '\'
157  */
158 int ast_odbc_backslash_is_escape(struct odbc_obj *obj);
159
160 /*! \brief Executes an non prepared statement and returns the resulting
161  * statement handle.
162  * \param obj The ODBC object
163  * \param exec_cb A function callback, which, when called, should return a statement handle with result columns bound.
164  * \param data A parameter to be passed to the exec_cb parameter function, indicating which statement handle is to be prepared.
165  * \retval a statement handle
166  * \retval NULL on error
167  */
168 SQLHSTMT ast_odbc_direct_execute(struct odbc_obj *obj, SQLHSTMT (*exec_cb)(struct odbc_obj *obj, void *data), void *data);
169
170 /*! 
171  * \brief Prepares, executes, and returns the resulting statement handle.
172  * \param obj The ODBC object
173  * \param prepare_cb A function callback, which, when called, should return a statement handle prepared, with any necessary parameters or result columns bound.
174  * \param data A parameter to be passed to the prepare_cb parameter function, indicating which statement handle is to be prepared.
175  * \retval a statement handle 
176  * \retval NULL on error
177  */
178 SQLHSTMT ast_odbc_prepare_and_execute(struct odbc_obj *obj, SQLHSTMT (*prepare_cb)(struct odbc_obj *obj, void *data), void *data);
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 table 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.
187  * \since 1.6.1
188  */
189 struct odbc_cache_tables *ast_odbc_find_table(const char *database, const char *tablename);
190
191 /*!
192  * \brief Find a column entry within a cached table structure
193  * \param table Cached table structure, as returned from ast_odbc_find_table()
194  * \param colname The column name requested
195  * \retval A structure describing the column type, or NULL, if the column is not found.
196  * \since 1.6.1
197  */
198 struct odbc_cache_columns *ast_odbc_find_column(struct odbc_cache_tables *table, const char *colname);
199
200 /*!
201  * \brief Remove a cache entry from memory
202  * \param database Name of an ODBC class (used to ensure like-named tables in different databases are not confused)
203  * \param table Tablename for which a cached record should be removed
204  * \retval 0 if the cache entry was removed, or -1 if no matching entry was found.
205  * \since 1.6.1
206  */
207 int ast_odbc_clear_cache(const char *database, const char *tablename);
208
209 /*!
210  * \brief Release a table returned from ast_odbc_find_table
211  */
212 #define ast_odbc_release_table(ptr) if (ptr) { AST_RWLIST_UNLOCK(&(ptr)->columns); }
213
214 /*!\brief Wrapper for SQLGetData to use with dynamic strings
215  * \param buf Address of the pointer to the ast_str structure.
216  * \param maxlen The maximum size of the resulting string, or 0 for no limit.
217  * \param StatementHandle The statement handle from which to retrieve data.
218  * \param ColumnNumber Column number (1-based offset) for which to retrieve data.
219  * \param TargetType The SQL constant indicating what kind of data is to be retrieved (usually SQL_CHAR)
220  * \param StrLen_or_Ind A pointer to a length indicator, specifying the total length of data.
221  */
222 SQLRETURN ast_odbc_ast_str_SQLGetData(struct ast_str **buf, int pmaxlen, SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber, SQLSMALLINT TargetType, SQLLEN *StrLen_or_Ind);
223
224 #endif /* _ASTERISK_RES_ODBC_H */