res_odbc_transaction.c

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2016, Digium, Inc.
 *
 * Mark Michelson <[email protected]>
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

#include "asterisk.h"

#include "asterisk/res_odbc.h"
#include "asterisk/res_odbc_transaction.h"
#include "asterisk/channel.h"
#include "asterisk/pbx.h"
#include "asterisk/app.h"
#include "asterisk/module.h"

/*** MODULEINFO
   <depend>generic_odbc</depend>
   <support_level>core</support_level>
 ***/

/*** DOCUMENTATION
   <function name="ODBC" language="en_US">
      <synopsis>
         Controls ODBC transaction properties.
      </synopsis>
      <syntax>
         <parameter name="property" required="true">
            <enumlist>
               <enum name="transaction">
                  <para>Gets or sets the active transaction ID.  If set, and the transaction ID does not
                  exist and a <replaceable>database name</replaceable> is specified as an argument, it will be created.</para>
               </enum>
               <enum name="forcecommit">
                  <para>Controls whether a transaction will be automatically committed when the channel
                  hangs up.  Defaults to forcecommit value from the relevant DSN (which defaults to false).
                  If a <replaceable>transaction ID</replaceable> is specified in the optional argument,
                  the property will be applied to that ID, otherwise to the current active ID.</para>
               </enum>
               <enum name="isolation">
                  <para>Controls the data isolation on uncommitted transactions.  May be one of the
                  following: <literal>read_committed</literal>, <literal>read_uncommitted</literal>,
                  <literal>repeatable_read</literal>, or <literal>serializable</literal>.  Defaults to the
                  database setting in <filename>res_odbc.conf</filename> or <literal>read_committed</literal>
                  if not specified.  If a <replaceable>transaction ID</replaceable> is specified as an optional argument, it will be
                  applied to that ID, otherwise the current active ID.</para>
               </enum>
            </enumlist>
         </parameter>
         <parameter name="argument" required="false" />
      </syntax>
      <description>
         <para>The ODBC() function allows setting several properties to influence how a connected
         database processes transactions.</para>
      </description>
   </function>
   <application name="ODBC_Commit" language="en_US">
      <synopsis>
         Commits a currently open database transaction.
      </synopsis>
      <syntax>
         <parameter name="transaction ID" required="no" />
      </syntax>
      <description>
         <para>Commits the database transaction specified by <replaceable>transaction ID</replaceable>
         or the current active transaction, if not specified.</para>
      </description>
   </application>
   <application name="ODBC_Rollback" language="en_US">
      <synopsis>
         Rollback a currently open database transaction.
      </synopsis>
      <syntax>
         <parameter name="transaction ID" required="no" />
      </syntax>
      <description>
         <para>Rolls back the database transaction specified by <replaceable>transaction ID</replaceable>
         or the current active transaction, if not specified.</para>
      </description>
   </application>
 ***/

struct odbc_txn_frame {
   AST_LIST_ENTRY(odbc_txn_frame) list;
   struct odbc_obj *obj;        /*!< Database handle within which transacted statements are run */
   /*!\brief Is this record the current active transaction within the channel?
    * Note that the active flag is really only necessary for statements which
    * are triggered from the dialplan, as there isn't a direct correlation
    * between multiple statements.  Applications wishing to use transactions
    * may simply perform each statement on the same odbc_obj, which keeps the
    * transaction persistent.
    */
   unsigned int active:1;
   unsigned int forcecommit:1;     /*!< Should uncommitted transactions be auto-committed on handle release? */
   unsigned int isolation;         /*!< Flags for how the DB should deal with data in other, uncommitted transactions */
   char name[0];                   /*!< Name of this transaction ID */
};

static struct odbc_txn_frame *release_transaction(struct odbc_txn_frame *tx);

static void odbc_txn_free(void *vdata)
{
   struct odbc_txn_frame *tx;
   AST_LIST_HEAD(, odbc_txn_frame) *oldlist = vdata;

   ast_debug(2, "odbc_txn_free(%p) called\n", vdata);

   AST_LIST_LOCK(oldlist);
   while ((tx = AST_LIST_REMOVE_HEAD(oldlist, list))) {
      release_transaction(tx);
   }
   AST_LIST_UNLOCK(oldlist);
   AST_LIST_HEAD_DESTROY(oldlist);
   ast_free(oldlist);
}

static const struct ast_datastore_info txn_info = {
   .type = "ODBC_Transaction",
   .destroy = odbc_txn_free,
};

static struct odbc_txn_frame *create_transaction(struct ast_channel *chan, const char *name, const char *dsn)
{
   struct ast_datastore *txn_store;
   AST_LIST_HEAD(, odbc_txn_frame) *oldlist;
   struct odbc_txn_frame *txn = NULL;
   struct odbc_txn_frame *otxn;

   if (ast_strlen_zero(dsn)) {
      return NULL;
   }

   ast_channel_lock(chan);
   if ((txn_store = ast_channel_datastore_find(chan, &txn_info, NULL))) {
      oldlist = txn_store->data;
   } else {
      if (!(txn_store = ast_datastore_alloc(&txn_info, NULL))) {
         ast_log(LOG_ERROR, "Unable to allocate a new datastore.  Cannot create a new transaction.\n");
         ast_channel_unlock(chan);
         return NULL;
      }

      if (!(oldlist = ast_calloc(1, sizeof(*oldlist)))) {
         ast_log(LOG_ERROR, "Unable to allocate datastore list head.  Cannot create a new transaction.\n");
         ast_datastore_free(txn_store);
         ast_channel_unlock(chan);
         return NULL;
      }

      txn_store->data = oldlist;
      AST_LIST_HEAD_INIT(oldlist);
      ast_channel_datastore_add(chan, txn_store);
   }
   ast_channel_unlock(chan);

   txn = ast_calloc(1, sizeof(*txn) + strlen(name) + 1);
   if (!txn) {
      return NULL;
   }

   strcpy(txn->name, name); /* SAFE */
   txn->obj = ast_odbc_request_obj(dsn, 0);
   if (!txn->obj) {
      ast_free(txn);
      return NULL;
   }
   txn->isolation = ast_odbc_class_get_isolation(txn->obj->parent);
   txn->forcecommit = ast_odbc_class_get_forcecommit(txn->obj->parent);
   txn->active = 1;

   if (SQLSetConnectAttr(txn->obj->con, SQL_ATTR_AUTOCOMMIT, (void *)SQL_AUTOCOMMIT_OFF, 0) == SQL_ERROR) {
      ast_odbc_print_errors(SQL_HANDLE_DBC, txn->obj->con, "SetConnectAttr (Autocommit)");
      ast_odbc_release_obj(txn->obj);
      ast_free(txn);
      return NULL;
   }

   /* Set the isolation property */
   if (SQLSetConnectAttr(txn->obj->con, SQL_ATTR_TXN_ISOLATION, (void *)(long)txn->isolation, 0) == SQL_ERROR) {
      ast_odbc_print_errors(SQL_HANDLE_DBC, txn->obj->con, "SetConnectAttr");
      ast_odbc_release_obj(txn->obj);
      ast_free(txn);
      return NULL;
   }

   /* On creation, the txn becomes active, and all others inactive */
   AST_LIST_LOCK(oldlist);
   AST_LIST_TRAVERSE(oldlist, otxn, list) {
      otxn->active = 0;
   }
   AST_LIST_INSERT_TAIL(oldlist, txn, list);
   AST_LIST_UNLOCK(oldlist);

   return txn;
}

static struct odbc_txn_frame *find_transaction(struct ast_channel *chan, const char *name, int active)
{
   struct ast_datastore *txn_store;
   AST_LIST_HEAD(, odbc_txn_frame) *oldlist;
   struct odbc_txn_frame *txn = NULL;

   if (!chan || (!active && !name)) {
      return NULL;
   }

   ast_channel_lock(chan);
   txn_store = ast_channel_datastore_find(chan, &txn_info, NULL);
   ast_channel_unlock(chan);

   if (!txn_store) {
      /* No datastore? Definitely no transaction then */
      return NULL;
   }

   oldlist = txn_store->data;
   AST_LIST_LOCK(oldlist);

   AST_LIST_TRAVERSE(oldlist, txn, list) {
      if (active) {
         if (txn->active) {
            break;
         }
      } else if (!strcasecmp(txn->name, name)) {
         break;
      }
   }
   AST_LIST_UNLOCK(oldlist);

   return txn;
}

static struct odbc_txn_frame *release_transaction(struct odbc_txn_frame *tx)
{
   if (!tx) {
      return NULL;
   }

   ast_debug(2, "release_transaction(%p) called (tx->obj = %p\n", tx, tx->obj);

   ast_debug(1, "called on a transactional handle with %s\n", tx->forcecommit ? "COMMIT" : "ROLLBACK");
   if (SQLEndTran(SQL_HANDLE_DBC, tx->obj->con, tx->forcecommit ? SQL_COMMIT : SQL_ROLLBACK) == SQL_ERROR) {
      ast_odbc_print_errors(SQL_HANDLE_DBC, tx->obj->con, "SQLEndTran");
   }

   /* Transaction is done, reset autocommit
    *
    * XXX I'm unsure if this is actually necessary, since we're releasing
    * the connection back to unixODBC. However, if unixODBC pooling is enabled,
    * it can't hurt to do just in case.
    */
   if (SQLSetConnectAttr(tx->obj->con, SQL_ATTR_AUTOCOMMIT, (void *)SQL_AUTOCOMMIT_ON, 0) == SQL_ERROR) {
      ast_odbc_print_errors(SQL_HANDLE_DBC, tx->obj->con, "SQLSetAttr");
   }

   ast_odbc_release_obj(tx->obj);
   ast_free(tx);
   return NULL;
}

static int commit_exec(struct ast_channel *chan, const char *data)
{
   struct odbc_txn_frame *tx;

   if (ast_strlen_zero(data)) {
      tx = find_transaction(chan, NULL, 1);
   } else {
      tx = find_transaction(chan, data, 0);
   }

   /* XXX COMMIT_RESULT is set to OK even if no transaction was found. Very misleading */
   pbx_builtin_setvar_helper(chan, "COMMIT_RESULT", "OK");

   if (tx) {
      if (SQLEndTran(SQL_HANDLE_DBC, tx->obj->con, SQL_COMMIT) == SQL_ERROR) {
         struct ast_str *errors = ast_odbc_print_errors(SQL_HANDLE_DBC, tx->obj->con, "SQLEndTran");
         pbx_builtin_setvar_helper(chan, "COMMIT_RESULT", ast_str_buffer(errors));
      }
   }
   return 0;
}

static int rollback_exec(struct ast_channel *chan, const char *data)
{
   struct odbc_txn_frame *tx;

   if (ast_strlen_zero(data)) {
      tx = find_transaction(chan, NULL, 1);
   } else {
      tx = find_transaction(chan, data, 0);
   }

   /* XXX ROLLBACK_RESULT is set to OK even if no transaction was found. Very misleading */
   pbx_builtin_setvar_helper(chan, "ROLLBACK_RESULT", "OK");

   if (tx) {
      if (SQLEndTran(SQL_HANDLE_DBC, tx->obj->con, SQL_ROLLBACK) == SQL_ERROR) {
         struct ast_str *errors = ast_odbc_print_errors(SQL_HANDLE_DBC, tx->obj->con, "SQLEndTran");
         pbx_builtin_setvar_helper(chan, "ROLLBACK_RESULT", ast_str_buffer(errors));
      }
   }
   return 0;
}

static int acf_transaction_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
{
   AST_DECLARE_APP_ARGS(args,
      AST_APP_ARG(property);
      AST_APP_ARG(opt);
   );
   struct odbc_txn_frame *tx;

   AST_STANDARD_APP_ARGS(args, data);
   if (strcasecmp(args.property, "transaction") == 0) {
      if ((tx = find_transaction(chan, NULL, 1))) {
         ast_copy_string(buf, tx->name, len);
         return 0;
      }
   } else if (strcasecmp(args.property, "isolation") == 0) {
      if (!ast_strlen_zero(args.opt)) {
         tx = find_transaction(chan, args.opt, 0);
      } else {
         tx = find_transaction(chan, NULL, 1);
      }
      if (tx) {
         ast_copy_string(buf, ast_odbc_isolation2text(tx->isolation), len);
         return 0;
      }
   } else if (strcasecmp(args.property, "forcecommit") == 0) {
      if (!ast_strlen_zero(args.opt)) {
         tx = find_transaction(chan, args.opt, 0);
      } else {
         tx = find_transaction(chan, NULL, 1);
      }
      if (tx) {
         ast_copy_string(buf, tx->forcecommit ? "1" : "0", len);
         return 0;
      }
   }
   return -1;
}

/* XXX The idea of "active" transactions is silly and makes things
 * more prone to error. It would be much better if the transaction
 * always had to be specified by name so that no implicit behavior
 * occurred.
 */
static int mark_transaction_active(struct ast_channel *chan, struct odbc_txn_frame *tx)
{
   struct ast_datastore *txn_store;
   AST_LIST_HEAD(, odbc_txn_frame) *oldlist;
   struct odbc_txn_frame *active = NULL, *txn;

   if (!chan) {
      return -1;
   }

   ast_channel_lock(chan);
   if (!(txn_store = ast_channel_datastore_find(chan, &txn_info, NULL))) {
      ast_channel_unlock(chan);
      return -1;
   }

   oldlist = txn_store->data;
   AST_LIST_LOCK(oldlist);
   AST_LIST_TRAVERSE(oldlist, txn, list) {
      if (txn == tx) {
         txn->active = 1;
         active = txn;
      } else {
         txn->active = 0;
      }
   }
   AST_LIST_UNLOCK(oldlist);
   ast_channel_unlock(chan);
   return active ? 0 : -1;
}

static int acf_transaction_write(struct ast_channel *chan, const char *cmd, char *s, const char *value)
{
   AST_DECLARE_APP_ARGS(args,
      AST_APP_ARG(property);
      AST_APP_ARG(opt);
   );
   struct odbc_txn_frame *tx;

   AST_STANDARD_APP_ARGS(args, s);
   if (strcasecmp(args.property, "transaction") == 0) {
      /* Set active transaction */
      if ((tx = find_transaction(chan, value, 0))) {
         mark_transaction_active(chan, tx);
      } else if (!create_transaction(chan, value, args.opt)) {
         pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "FAILED_TO_CREATE");
         return -1;
      }
      pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "OK");
      return 0;
   } else if (strcasecmp(args.property, "forcecommit") == 0) {
      /* Set what happens when an uncommitted transaction ends without explicit Commit or Rollback */
      if (ast_strlen_zero(args.opt)) {
         tx = find_transaction(chan, NULL, 1);
      } else {
         tx = find_transaction(chan, args.opt, 0);
      }
      if (!tx) {
         pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "FAILED_TO_CREATE");
         return -1;
      }
      if (ast_true(value)) {
         tx->forcecommit = 1;
      } else if (ast_false(value)) {
         tx->forcecommit = 0;
      } else {
         ast_log(LOG_ERROR, "Invalid value for forcecommit: '%s'\n", S_OR(value, ""));
         pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "INVALID_VALUE");
         return -1;
      }

      pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "OK");
      return 0;
   } else if (strcasecmp(args.property, "isolation") == 0) {
      /* How do uncommitted transactions affect reads? */
      /* XXX This is completely useless. The problem is that setting the isolation here
       * does not actually alter the connection. The only time the isolation gets set is
       * when the transaction is created. The only way to set isolation is to set it on
       * the ODBC class's configuration in res_odbc.conf.
       */
      int isolation = ast_odbc_text2isolation(value);
      if (ast_strlen_zero(args.opt)) {
         tx = find_transaction(chan, NULL, 1);
      } else {
         tx = find_transaction(chan, args.opt, 0);
      }
      if (!tx) {
         pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "FAILED_TO_CREATE");
         return -1;
      }
      if (isolation == 0) {
         pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "INVALID_VALUE");
         ast_log(LOG_ERROR, "Invalid isolation specification: '%s'\n", S_OR(value, ""));
      } else if (SQLSetConnectAttr(tx->obj->con, SQL_ATTR_TXN_ISOLATION, (void *)(long)isolation, 0) == SQL_ERROR) {
         pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "SQL_ERROR");
         ast_odbc_print_errors(SQL_HANDLE_DBC, tx->obj->con, "SetConnectAttr (Txn isolation)");
      } else {
         pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "OK");
         tx->isolation = isolation;
      }
      return 0;
   } else {
      ast_log(LOG_ERROR, "Unknown property: '%s'\n", args.property);
      return -1;
   }
}

struct odbc_obj *ast_odbc_retrieve_transaction_obj(struct ast_channel *chan, const char *objname)
{
   struct ast_datastore *txn_store;
   AST_LIST_HEAD(, odbc_txn_frame) *oldlist;
   struct odbc_txn_frame *txn = NULL;

   if (!chan || !objname) {
      /* No channel == no transaction */
      return NULL;
   }

   ast_channel_lock(chan);
   if ((txn_store = ast_channel_datastore_find(chan, &txn_info, NULL))) {
      oldlist = txn_store->data;
   } else {
      ast_channel_unlock(chan);
      return NULL;
   }

   AST_LIST_LOCK(oldlist);
   ast_channel_unlock(chan);

   AST_LIST_TRAVERSE(oldlist, txn, list) {
      if (txn->obj && txn->obj->parent && !strcmp(ast_odbc_class_get_name(txn->obj->parent), objname)) {
         AST_LIST_UNLOCK(oldlist);
         return txn->obj;
      }
   }
   AST_LIST_UNLOCK(oldlist);
   return NULL;
}

static struct ast_custom_function odbc_function = {
   .name = "ODBC",
   .read = acf_transaction_read,
   .write = acf_transaction_write,
};

static const char * const app_commit = "ODBC_Commit";
static const char * const app_rollback = "ODBC_Rollback";

/* XXX res_odbc takes the path of disallowing unloads from happening.
 * It's not a great precedent, but since trying to deal with unloading the module
 * while transactions are active seems like a huge pain to deal with, we'll go
 * the same way here.
 */
static int unload_module(void)
{
   return -1;
}

static int load_module(void)
{
   ast_register_application_xml(app_commit, commit_exec);
   ast_register_application_xml(app_rollback, rollback_exec);
   ast_custom_function_register(&odbc_function);
   return 0;
}

AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER, "ODBC transaction resource",
   .support_level = AST_MODULE_SUPPORT_CORE,
   .load = load_module,
   .unload = unload_module,
   .load_pri = AST_MODPRI_REALTIME_DEPEND,
);