Asterisk - The Open Source Telephony Project  21.4.1
transport.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_TRANSPORT_H
20 #define RES_AEAP_TRANSPORT_H
21 
22 #include <stdint.h>
23 
24 #include "asterisk/res_aeap.h"
25 
26 struct aeap_transport;
27 
28 /*!
29  * \brief Asterisk external application transport virtual table
30  *
31  * Callbacks to be implemented by "derived" transports
32  */
34  /*!
35  * \brief Connect a transport
36  *
37  * \param self The transport object
38  * \param url The URL to connect to
39  * \param protocol The connection protocol to use if applicable
40  * \param timeout How long (in milliseconds) to attempt to connect (-1 equals infinite)
41  *
42  * \returns 0 on success, or -1 on error
43  */
44  int (*connect)(struct aeap_transport *self, const char *url, const char *protocol, int timeout);
45 
46  /*!
47  * \brief Disconnect a transport
48  *
49  * \param self The transport object
50  *
51  * \returns 0 on success, or -1 on error
52  */
53  int (*disconnect)(struct aeap_transport *self);
54 
55  /*!
56  * \brief Destroy a transport
57  *
58  * \param self The transport object
59  */
60  void (*destroy)(struct aeap_transport *self);
61 
62  /*!
63  * \brief Read data from a transport
64  *
65  * \param self The transport object
66  * \param buf The buffer data is read read into
67  * \param size The size of the given data buffer
68  * \param rtype [out] The type of data read
69  *
70  * \returns Total number of bytes read, or less than zero on error
71  */
72  intmax_t (*read)(struct aeap_transport *self, void *buf, intmax_t size,
73  enum AST_AEAP_DATA_TYPE *rtype);
74 
75  /*!
76  * \brief Write data to a transport
77  *
78  * \param self The transport object
79  * \param buf The data to write
80  * \param size The size of data to write
81  * \param wtype The type of data to write
82  *
83  * \returns Total number of bytes written, or less than zero on error
84  */
85  intmax_t (*write)(struct aeap_transport *self, const void *buf, intmax_t size,
86  enum AST_AEAP_DATA_TYPE wtype);
87 };
88 
89 /*!
90  * \brief Asterisk external application transport structure to be
91  * "derived" by specific transport implementation types
92  *
93  * Transports are assumed to support simultaneous reading and writing,
94  * thus separate read and write locks. A transport type not supporting
95  * such can simply apply the opposing lock during a read or write, i.e.
96  * lock the write lock during a read and vice versa.
97  */
99  /*! Transport virtual table */
101  /*! Whether or not the transport is connected */
102  unsigned int connected;
103  /*! Lock used when reading */
105  /*! Lock used when writing */
107 };
108 
109 /*!
110  * \brief Create an Asterisk external application transport
111  *
112  * \param type The type of transport to create
113  *
114  * \returns An Asterisk external application transport, or NULL on error
115  */
116 struct aeap_transport *aeap_transport_create(const char *type);
117 
118 /*!
119  * \brief Connect a transport
120  *
121  * \param transport The transport to connect
122  * \param url The URL to connect to
123  * \param protocol The connection protocol to use if applicable
124  * \param timeout How long (in milliseconds) to attempt to connect (-1 equals infinite)
125  *
126  * \returns 0 on success, or -1 on error
127  */
128 int aeap_transport_connect(struct aeap_transport *transport, const char *url,
129  const char *protocol, int timeout);
130 
131 /*!
132  * \brief Create an Asterisk external application transport, and connect it
133  *
134  * \param type The type of transport to create
135  * \param url The URL to connect to
136  * \param protocol The connection protocol to use if applicable
137  * \param timeout How long (in milliseconds) to attempt to connect (-1 equals infinite)
138  *
139  * \returns An Asterisk external application transport, or NULL on error
140  */
141 struct aeap_transport *aeap_transport_create_and_connect(const char* type,
142  const char *url, const char *protocol, int timeout);
143 
144 /*!
145  * \brief Disconnect a transport
146  *
147  * \note Locks both the transport's read and write locks before calling transport
148  * instance's disconnect, and unlocks both before returning.
149  *
150  * \param transport The transport to disconnect
151  *
152  * \returns 0 on success, or -1 on error
153  */
154 int aeap_transport_disconnect(struct aeap_transport *transport);
155 
156 /*!
157  * \brief Whether or not the transport is in a connected state
158  *
159  * \param transport The transport object
160  *
161  * \returns True if connected, false otherwise
162  */
163 int aeap_transport_is_connected(struct aeap_transport *transport);
164 
165 /*!
166  * \brief Destroy a transport
167  *
168  * \param transport The transport to destroy
169  */
170 void aeap_transport_destroy(struct aeap_transport *transport);
171 
172 /*!
173  * \brief Read data from the transport
174  *
175  * This is a blocking read, and will not return until the transport
176  * implementation returns.
177  *
178  * \note Locks transport's read lock before calling transport instance's
179  * read, and unlocks it before returning.
180  *
181  * \param transport The transport to read from
182  * \param buf The buffer data is read into
183  * \param size The size of data given data buffer
184  * \param rtype [out] The type of data read
185  *
186  * \returns Total number of bytes read, or less than zero on error
187  */
188 intmax_t aeap_transport_read(struct aeap_transport *transport, void *buf, intmax_t size,
189  enum AST_AEAP_DATA_TYPE *rtype);
190 
191 /*!
192  * \brief Write data to the transport
193  *
194  * \note Locks transport's write lock before calling transport instance's
195  * write, and unlocks it before returning.
196  *
197  * \param transport The transport to write to
198  * \param buf The data to write
199  * \param size The size of data to write
200  * \param wtype The type of data to write
201  *
202  * \returns Total number of bytes written, or less than zero on error
203  */
204 intmax_t aeap_transport_write(struct aeap_transport *transport, const void *buf, intmax_t size,
205  enum AST_AEAP_DATA_TYPE wtype);
206 
207 #endif /* RES_AEAP_TRANSPORT_H */
void(* destroy)(struct aeap_transport *self)
Destroy a transport.
Definition: transport.h:60
Asterisk External Application Protocol API.
intmax_t(* read)(struct aeap_transport *self, void *buf, intmax_t size, enum AST_AEAP_DATA_TYPE *rtype)
Read data from a transport.
Definition: transport.h:72
intmax_t(* write)(struct aeap_transport *self, const void *buf, intmax_t size, enum AST_AEAP_DATA_TYPE wtype)
Write data to a transport.
Definition: transport.h:85
ast_mutex_t read_lock
Definition: transport.h:104
int(* disconnect)(struct aeap_transport *self)
Disconnect a transport.
Definition: transport.h:53
unsigned int connected
Definition: transport.h:102
Asterisk external application transport virtual table.
Definition: transport.h:33
ast_mutex_t write_lock
Definition: transport.h:106
int(* connect)(struct aeap_transport *self, const char *url, const char *protocol, int timeout)
Connect a transport.
Definition: transport.h:44
AST_AEAP_DATA_TYPE
Supported Asterisk external application data types.
Definition: res_aeap.h:135
Asterisk external application transport structure to be "derived" by specific transport implementatio...
Definition: transport.h:98
Structure for mutex and tracking information.
Definition: lock.h:135
struct aeap_transport_vtable * vtable
Definition: transport.h:100