<p>Friendly Automation <strong>submitted</strong> this change.</p><p><a href="https://gerrit.asterisk.org/c/asterisk/+/17529">View Change</a></p><div style="white-space:pre-wrap">Approvals:
Kevin Harwell: Looks good to me, but someone else must approve
George Joseph: Looks good to me, approved
Friendly Automation: Approved for Submit
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">odbc: Fix for Doxygen.<br><br>ASTERISK-29754<br><br>Change-Id: Ia09eb68d283d201d9a6fbeccfc0efe83fe0502a5<br>---<br>M funcs/func_odbc.c<br>M include/asterisk/res_odbc.h<br>M res/res_config_odbc.c<br>M res/res_odbc.c<br>4 files changed, 28 insertions(+), 35 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/funcs/func_odbc.c b/funcs/func_odbc.c</span><br><span>index 9d6d0fc..22bc45b 100644</span><br><span>--- a/funcs/func_odbc.c</span><br><span>+++ b/funcs/func_odbc.c</span><br><span>@@ -296,7 +296,7 @@</span><br><span> * to callers in most cases.</span><br><span> *</span><br><span> * When finished with the returned structure, the caller must call</span><br><span style="color: hsl(0, 100%, 40%);">- * \ref release_dsn</span><br><span style="color: hsl(120, 100%, 40%);">+ * \ref release_obj_or_dsn</span><br><span> *</span><br><span> * \param name Name of the DSN as found in res_odbc.conf</span><br><span> * \retval NULL Unable to retrieve or create the DSN</span><br><span>diff --git a/include/asterisk/res_odbc.h b/include/asterisk/res_odbc.h</span><br><span>index 789caba..9827c81 100644</span><br><span>--- a/include/asterisk/res_odbc.h</span><br><span>+++ b/include/asterisk/res_odbc.h</span><br><span>@@ -103,6 +103,7 @@</span><br><span> *</span><br><span> * This is only around for backwards-compatibility with older versions of Asterisk.</span><br><span> */</span><br><span style="color: hsl(120, 100%, 40%);">+#define ast_odbc_request_obj2(name, check) _ast_odbc_request_obj2(name, check, __FILE__, __PRETTY_FUNCTION__, __LINE__)</span><br><span> struct odbc_obj *_ast_odbc_request_obj2(const char *name, struct ast_flags flags, const char *file, const char *function, int lineno);</span><br><span> </span><br><span> /*!</span><br><span>@@ -116,11 +117,9 @@</span><br><span> * \param check unused</span><br><span> * \return A connection to the database. Call ast_odbc_release_obj() when finished.</span><br><span> */</span><br><span style="color: hsl(120, 100%, 40%);">+#define ast_odbc_request_obj(name, check) _ast_odbc_request_obj(name, check, __FILE__, __PRETTY_FUNCTION__, __LINE__)</span><br><span> struct odbc_obj *_ast_odbc_request_obj(const char *name, int check, const char *file, const char *function, int lineno);</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-#define ast_odbc_request_obj2(a, b) _ast_odbc_request_obj2(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__)</span><br><span style="color: hsl(0, 100%, 40%);">-#define ast_odbc_request_obj(a, b) _ast_odbc_request_obj(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__)</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span> /*!</span><br><span> * \brief Releases an ODBC object previously allocated by ast_odbc_request_obj()</span><br><span> * \param obj The ODBC object</span><br><span>@@ -137,7 +136,8 @@</span><br><span> </span><br><span> /*! \brief Checks if the database natively supports backslash as an escape character.</span><br><span> * \param obj The ODBC object</span><br><span style="color: hsl(0, 100%, 40%);">- * \return Returns 1 if backslash is a native escape character, 0 if an ESCAPE clause is needed to support '\'</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval 1 if backslash is a native escape character</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval 0 if an ESCAPE clause is needed to support '\'</span><br><span> */</span><br><span> int ast_odbc_backslash_is_escape(struct odbc_obj *obj);</span><br><span> </span><br><span>@@ -146,7 +146,7 @@</span><br><span> * \param obj The ODBC object</span><br><span> * \param exec_cb A function callback, which, when called, should return a statement handle with result columns bound.</span><br><span> * \param data A parameter to be passed to the exec_cb parameter function, indicating which statement handle is to be prepared.</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval a statement handle</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return a statement handle</span><br><span> * \retval NULL on error</span><br><span> */</span><br><span> SQLHSTMT ast_odbc_direct_execute(struct odbc_obj *obj, SQLHSTMT (*exec_cb)(struct odbc_obj *obj, void *data), void *data);</span><br><span>@@ -156,7 +156,7 @@</span><br><span> * \param obj The ODBC object</span><br><span> * \param prepare_cb A function callback, which, when called, should return a statement handle prepared, with any necessary parameters or result columns bound.</span><br><span> * \param data A parameter to be passed to the prepare_cb parameter function, indicating which statement handle is to be prepared.</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval a statement handle</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return a statement handle</span><br><span> * \retval NULL on error</span><br><span> */</span><br><span> SQLHSTMT ast_odbc_prepare_and_execute(struct odbc_obj *obj, SQLHSTMT (*prepare_cb)(struct odbc_obj *obj, void *data), void *data);</span><br><span>@@ -165,13 +165,14 @@</span><br><span> * \brief Prepares a SQL query on a statement.</span><br><span> * \param obj The ODBC object</span><br><span> * \param stmt The statement</span><br><span style="color: hsl(0, 100%, 40%);">- * \parma sql The SQL query</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param sql The SQL query</span><br><span> * \note This should be used in place of SQLPrepare</span><br><span> */</span><br><span> int ast_odbc_prepare(struct odbc_obj *obj, SQLHSTMT *stmt, const char *sql);</span><br><span> </span><br><span> /*! \brief Execute a unprepared SQL query.</span><br><span> * \param obj The ODBC object</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param stmt The statement</span><br><span> * \param sql The SQL query</span><br><span> * \note This should be used in place of SQLExecDirect</span><br><span> */</span><br><span>@@ -181,7 +182,8 @@</span><br><span> * \brief Find or create an entry describing the table specified.</span><br><span> * \param database Name of an ODBC class on which to query the table</span><br><span> * \param tablename Tablename to describe</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval A structure describing the table layout, or NULL, if the table is not found or another error occurs.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return A structure describing the table layout.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval NULL if the table is not found or another error occurs.</span><br><span> * When a structure is returned, the contained columns list will be</span><br><span> * rdlock'ed, to ensure that it will be retained in memory. The information</span><br><span> * will be cached until a reload event or when ast_odbc_clear_cache() is called</span><br><span>@@ -194,7 +196,7 @@</span><br><span> * \brief Find a column entry within a cached table structure</span><br><span> * \param table Cached table structure, as returned from ast_odbc_find_table()</span><br><span> * \param colname The column name requested</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval A structure describing the column type, or NULL, if the column is not found.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return A structure describing the column type, or NULL, if the column is not found.</span><br><span> * \since 1.6.1</span><br><span> */</span><br><span> struct odbc_cache_columns *ast_odbc_find_column(struct odbc_cache_tables *table, const char *colname);</span><br><span>@@ -205,7 +207,8 @@</span><br><span> * ast_odbc_find_table() API call.</span><br><span> * \param database Name of an ODBC class (used to ensure like-named tables in different databases are not confused)</span><br><span> * \param tablename Tablename for which a cached record should be removed</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval 0 if the cache entry was removed, or -1 if no matching entry was found.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval 0 if the cache entry was removed.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval -1 if no matching entry was found.</span><br><span> * \since 1.6.1</span><br><span> */</span><br><span> int ast_odbc_clear_cache(const char *database, const char *tablename);</span><br><span>diff --git a/res/res_config_odbc.c b/res/res_config_odbc.c</span><br><span>index 0d4f767..178a483 100644</span><br><span>--- a/res/res_config_odbc.c</span><br><span>+++ b/res/res_config_odbc.c</span><br><span>@@ -158,13 +158,13 @@</span><br><span> * \brief Execute an SQL query and return ast_variable list</span><br><span> * \param database</span><br><span> * \param table</span><br><span style="color: hsl(0, 100%, 40%);">- * \param ap list containing one or more field/operator/value set.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param fields list containing one or more field/operator/value set.</span><br><span> *</span><br><span> * Select database and preform query on table, prepare the sql statement</span><br><span> * Sub-in the values to the prepared statement and execute it. Return results</span><br><span> * as a ast_variable list.</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval var on success</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return var on success</span><br><span> * \retval NULL on failure</span><br><span> */</span><br><span> static struct ast_variable *realtime_odbc(const char *database, const char *table, const struct ast_variable *fields)</span><br><span>@@ -329,14 +329,14 @@</span><br><span> * \brief Execute an Select query and return ast_config list</span><br><span> * \param database</span><br><span> * \param table</span><br><span style="color: hsl(0, 100%, 40%);">- * \param ap list containing one or more field/operator/value set.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param fields list containing one or more field/operator/value set.</span><br><span> *</span><br><span> * Select database and preform query on table, prepare the sql statement</span><br><span> * Sub-in the values to the prepared statement and execute it.</span><br><span> * Execute this prepared query against several ODBC connected databases.</span><br><span> * Return results as an ast_config variable.</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval var on success</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return var on success</span><br><span> * \retval NULL on failure</span><br><span> */</span><br><span> static struct ast_config *realtime_multi_odbc(const char *database, const char *table, const struct ast_variable *fields)</span><br><span>@@ -504,13 +504,13 @@</span><br><span> * \param table</span><br><span> * \param keyfield where clause field</span><br><span> * \param lookup value of field for where clause</span><br><span style="color: hsl(0, 100%, 40%);">- * \param ap list containing one or more field/value set(s).</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param fields list containing one or more field/value set(s).</span><br><span> *</span><br><span> * Update a database table, prepare the sql statement using keyfield and lookup</span><br><span> * control the number of records to change. All values to be changed are stored in ap list.</span><br><span> * Sub-in the values to the prepared statement and execute it.</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval number of rows affected</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return number of rows affected</span><br><span> * \retval -1 on failure</span><br><span> */</span><br><span> static int update_odbc(const char *database, const char *table, const char *keyfield, const char *lookup, const struct ast_variable *fields)</span><br><span>@@ -660,16 +660,15 @@</span><br><span> </span><br><span> /*!</span><br><span> * \brief Execute an UPDATE query</span><br><span style="color: hsl(0, 100%, 40%);">- * \param database</span><br><span style="color: hsl(0, 100%, 40%);">- * \param table</span><br><span style="color: hsl(0, 100%, 40%);">- * \param ap list containing one or more field/value set(s).</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param database, table, lookup_fields</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param update_fields list containing one or more field/value set(s).</span><br><span> *</span><br><span> * Update a database table, preparing the sql statement from a list of</span><br><span> * key/value pairs specified in ap. The lookup pairs are specified first</span><br><span> * and are separated from the update pairs by a sentinel value.</span><br><span> * Sub-in the values to the prepared statement and execute it.</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval number of rows affected</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return number of rows affected</span><br><span> * \retval -1 on failure</span><br><span> */</span><br><span> static int update2_odbc(const char *database, const char *table, const struct ast_variable *lookup_fields, const struct ast_variable *update_fields)</span><br><span>@@ -729,13 +728,13 @@</span><br><span> * \brief Execute an INSERT query</span><br><span> * \param database</span><br><span> * \param table</span><br><span style="color: hsl(0, 100%, 40%);">- * \param ap list containing one or more field/value set(s)</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param fields list containing one or more field/value set(s)</span><br><span> *</span><br><span> * Insert a new record into database table, prepare the sql statement.</span><br><span> * All values to be changed are stored in ap list.</span><br><span> * Sub-in the values to the prepared statement and execute it.</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval number of rows affected</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return number of rows affected</span><br><span> * \retval -1 on failure</span><br><span> */</span><br><span> static int store_odbc(const char *database, const char *table, const struct ast_variable *fields)</span><br><span>@@ -812,13 +811,13 @@</span><br><span> * \param table</span><br><span> * \param keyfield where clause field</span><br><span> * \param lookup value of field for where clause</span><br><span style="color: hsl(0, 100%, 40%);">- * \param ap list containing one or more field/value set(s)</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param fields list containing one or more field/value set(s)</span><br><span> *</span><br><span> * Delete a row from a database table, prepare the sql statement using keyfield and lookup</span><br><span> * control the number of records to change. Additional params to match rows are stored in ap list.</span><br><span> * Sub-in the values to the prepared statement and execute it.</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval number of rows affected</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return number of rows affected</span><br><span> * \retval -1 on failure</span><br><span> */</span><br><span> static int destroy_odbc(const char *database, const char *table, const char *keyfield, const char *lookup, const struct ast_variable *fields)</span><br><span>diff --git a/res/res_odbc.c b/res/res_odbc.c</span><br><span>index 0dc8124..7cc0874 100644</span><br><span>--- a/res/res_odbc.c</span><br><span>+++ b/res/res_odbc.c</span><br><span>@@ -27,7 +27,7 @@</span><br><span> * \author Anthony Minessale II <anthmct@yahoo.com></span><br><span> * \author Tilghman Lesher <tilghman@digium.com></span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \arg See also: \ref cdr_odbc</span><br><span style="color: hsl(120, 100%, 40%);">+ * \arg See also: \ref cdr_odbc.c</span><br><span> */</span><br><span> </span><br><span> /*! \li \ref res_odbc.c uses the configuration file \ref res_odbc.conf</span><br><span>@@ -215,13 +215,6 @@</span><br><span> }</span><br><span> </span><br><span> /*!</span><br><span style="color: hsl(0, 100%, 40%);">- * \brief Find or create an entry describing the table specified.</span><br><span style="color: hsl(0, 100%, 40%);">- * \param database Name of an ODBC class on which to query the table</span><br><span style="color: hsl(0, 100%, 40%);">- * \param tablename Tablename to describe</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval A structure describing the table layout, or NULL, if the table is not found or another error occurs.</span><br><span style="color: hsl(0, 100%, 40%);">- * When a structure is returned, the contained columns list will be</span><br><span style="color: hsl(0, 100%, 40%);">- * rdlock'ed, to ensure that it will be retained in memory.</span><br><span style="color: hsl(0, 100%, 40%);">- *</span><br><span> * XXX This creates a connection and disconnects it. In some situations, the caller of</span><br><span> * this function has its own connection and could donate it to this function instead of</span><br><span> * needing to create another one.</span><br><span>@@ -235,8 +228,6 @@</span><br><span> * the need to cache tables is questionable. Instead, the table structure can be fetched from</span><br><span> * the DB directly each time, resulting in a single owner of the data.</span><br><span> * * Make odbc_cache_tables a refcounted object.</span><br><span style="color: hsl(0, 100%, 40%);">- *</span><br><span style="color: hsl(0, 100%, 40%);">- * \since 1.6.1</span><br><span> */</span><br><span> struct odbc_cache_tables *ast_odbc_find_table(const char *database, const char *tablename)</span><br><span> {</span><br><span></span><br></pre><div style="white-space:pre-wrap"></div><p>To view, visit <a href="https://gerrit.asterisk.org/c/asterisk/+/17529">change 17529</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.asterisk.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.asterisk.org/c/asterisk/+/17529"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: asterisk </div>
<div style="display:none"> Gerrit-Branch: 16 </div>
<div style="display:none"> Gerrit-Change-Id: Ia09eb68d283d201d9a6fbeccfc0efe83fe0502a5 </div>
<div style="display:none"> Gerrit-Change-Number: 17529 </div>
<div style="display:none"> Gerrit-PatchSet: 2 </div>
<div style="display:none"> Gerrit-Owner: Alexander Traud <pabstraud@compuserve.com> </div>
<div style="display:none"> Gerrit-Reviewer: Friendly Automation </div>
<div style="display:none"> Gerrit-Reviewer: George Joseph <gjoseph@digium.com> </div>
<div style="display:none"> Gerrit-Reviewer: Kevin Harwell <kharwell@digium.com> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>