124 lines
3.7 KiB
C
124 lines
3.7 KiB
C
/*
|
|
* Asterisk -- An open source telephony toolkit.
|
|
*
|
|
* Copyright (C) 2021, Sangoma Technologies Corporation
|
|
*
|
|
* Kevin Harwell <kharwell@sangoma.com>
|
|
*
|
|
* 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.
|
|
*/
|
|
|
|
#ifndef RES_AEAP_TRANSACTION_H
|
|
#define RES_AEAP_TRANSACTION_H
|
|
|
|
#include "asterisk/res_aeap.h"
|
|
|
|
struct ao2_container;
|
|
struct ast_aeap_tsx_params;
|
|
struct aeap_transaction;
|
|
|
|
/*!
|
|
* \brief Create an Asterisk external application transactions container
|
|
*
|
|
* \returns A transaction object, or NULL on error
|
|
*/
|
|
struct ao2_container *aeap_transactions_create(void);
|
|
|
|
/*!
|
|
* \brief Create a transaction object, and add it to the given container
|
|
*
|
|
* \param transactions A transactions container
|
|
* \param id An id to use for the transaction
|
|
* \param params Transaction parameters
|
|
* \param aeap The aeap object that "owns" this transaction
|
|
*
|
|
* \returns 0 if successfully create and added, -1 on error
|
|
*/
|
|
struct aeap_transaction *aeap_transaction_create_and_add(struct ao2_container *transactions,
|
|
const char *id, struct ast_aeap_tsx_params *params, struct ast_aeap *aeap);
|
|
|
|
/*!
|
|
* \brief Clean up parameter references, and possibly call optional user object cleanup
|
|
*
|
|
* \param params Transaction parameters
|
|
*/
|
|
void aeap_transaction_params_cleanup(struct ast_aeap_tsx_params *params);
|
|
|
|
/*!
|
|
* \brief Retrieve a transaction for the id from the container
|
|
*
|
|
* \param transactions A transactions container
|
|
* \param id A transaction id
|
|
*
|
|
* \returns an AEAP transaction object, NULL if no transaction is found
|
|
*/
|
|
struct aeap_transaction *aeap_transaction_get(struct ao2_container *transactions,
|
|
const char *id);
|
|
|
|
/*!
|
|
* \brief Start the transaction
|
|
*
|
|
* \param tsx The transaction to initiate
|
|
*
|
|
* \returns 0 if successfully raised, and handled. Otherwise non zero.
|
|
*/
|
|
int aeap_transaction_start(struct aeap_transaction *tsx);
|
|
|
|
/*!
|
|
* \brief End a transaction, and remove it from the given container
|
|
*
|
|
* The "result" parameter is a value representing the state (success/failure,
|
|
* perhaps even something else) of transactional processing upon ending.
|
|
*
|
|
* \param tsx A transaction to end
|
|
* \param result A result to give to the transaction
|
|
*/
|
|
void aeap_transaction_end(struct aeap_transaction *tsx, int result);
|
|
|
|
/*!
|
|
* \brief Get a transaction's result
|
|
*
|
|
* A transaction's result is a value that represents the relative success (0), or
|
|
* failure (-1) of a transaction. For example, a timeout is considered a failure
|
|
* and will elicit a -1.
|
|
*
|
|
* This value though is also dependent upon the result of the message handler
|
|
* associated with the transaction. Meaning if an associated message is handled,
|
|
* then its result is stored as the transaction result and returned here.
|
|
*
|
|
* \param tsx A transaction object
|
|
*
|
|
* \returns The transaction result
|
|
*/
|
|
int aeap_transaction_result(struct aeap_transaction *tsx);
|
|
|
|
/*!
|
|
* \brief Cancel the transaction timer
|
|
*
|
|
* Stops the transaction timer, but does not end/stop the transaction itself
|
|
*
|
|
* \param transaction A transaction to cancel the timer on
|
|
*
|
|
* \returns 0 if canceled, non zero otherwise
|
|
*/
|
|
int aeap_transaction_cancel_timer(struct aeap_transaction *tsx);
|
|
|
|
/*!
|
|
* \brief Retrieve the user object associated with the transaction
|
|
*
|
|
* \param transaction A transaction object
|
|
*
|
|
* \returns A user object, or NULL if non associated
|
|
*/
|
|
void *aeap_transaction_user_obj(struct aeap_transaction *tsx);
|
|
|
|
#endif /* RES_AEAP_TRANSACTION_H */
|