Asterisk - The Open Source Telephony Project  21.4.1
transaction.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2021, Sangoma Technologies Corporation
5  *
6  * Kevin Harwell <kharwell@sangoma.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 #ifndef RES_AEAP_TRANSACTION_H
20 #define RES_AEAP_TRANSACTION_H
21 
22 #include "asterisk/res_aeap.h"
23 
24 struct ao2_container;
25 struct ast_aeap_tsx_params;
26 struct aeap_transaction;
27 
28 /*!
29  * \brief Create an Asterisk external application transactions container
30  *
31  * \returns A transaction object, or NULL on error
32  */
33 struct ao2_container *aeap_transactions_create(void);
34 
35 /*!
36  * \brief Create a transaction object, and add it to the given container
37  *
38  * \param transactions A transactions container
39  * \param id An id to use for the transaction
40  * \param params Transaction parameters
41  * \param aeap The aeap object that "owns" this transaction
42  *
43  * \returns 0 if successfully create and added, -1 on error
44  */
45 struct aeap_transaction *aeap_transaction_create_and_add(struct ao2_container *transactions,
46  const char *id, struct ast_aeap_tsx_params *params, struct ast_aeap *aeap);
47 
48 /*!
49  * \brief Clean up parameter references, and possibly call optional user object cleanup
50  *
51  * \param params Transaction parameters
52  */
53 void aeap_transaction_params_cleanup(struct ast_aeap_tsx_params *params);
54 
55 /*!
56  * \brief Retrieve a transaction for the id from the container
57  *
58  * \param transactions A transactions container
59  * \param id A transaction id
60  *
61  * \returns an AEAP transaction object, NULL if no transaction is found
62  */
63 struct aeap_transaction *aeap_transaction_get(struct ao2_container *transactions,
64  const char *id);
65 
66 /*!
67  * \brief Start the transaction
68  *
69  * \param tsx The transaction to initiate
70  *
71  * \returns 0 if successfully raised, and handled. Otherwise non zero.
72  */
73 int aeap_transaction_start(struct aeap_transaction *tsx);
74 
75 /*!
76  * \brief End a transaction, and remove it from the given container
77  *
78  * The "result" parameter is a value representing the state (success/failure,
79  * perhaps even something else) of transactional processing upon ending.
80  *
81  * \param tsx A transaction to end
82  * \param result A result to give to the transaction
83  */
84 void aeap_transaction_end(struct aeap_transaction *tsx, int result);
85 
86 /*!
87  * \brief Get a transaction's result
88  *
89  * A transaction's result is a value that represents the relative success (0), or
90  * failure (-1) of a transaction. For example, a timeout is considered a failure
91  * and will elicit a -1.
92  *
93  * This value though is also dependent upon the result of the message handler
94  * associated with the transaction. Meaning if an associated message is handled,
95  * then its result is stored as the transaction result and returned here.
96  *
97  * \param tsx A transaction object
98  *
99  * \returns The transaction result
100  */
101 int aeap_transaction_result(struct aeap_transaction *tsx);
102 
103 /*!
104  * \brief Cancel the transaction timer
105  *
106  * Stops the transaction timer, but does not end/stop the transaction itself
107  *
108  * \param tsx A transaction to cancel the timer on
109  *
110  * \returns 0 if canceled, non zero otherwise
111  */
112 int aeap_transaction_cancel_timer(struct aeap_transaction *tsx);
113 
114 /*!
115  * \brief Retrieve the user object associated with the transaction
116  *
117  * \param tsx A transaction object
118  *
119  * \returns A user object, or NULL if non associated
120  */
121 void *aeap_transaction_user_obj(struct aeap_transaction *tsx);
122 
123 #endif /* RES_AEAP_TRANSACTION_H */
Asterisk External Application Protocol API.
Parameters to be used when sending a transaction based message.
Definition: res_aeap.h:331
struct ast_aeap * aeap
Definition: transaction.c:34
struct ast_aeap_tsx_params params
Definition: transaction.c:46
Generic container type.
Definition: aeap.c:47