Wed Jan 8 2020 09:49:42

Asterisk developer's documentation


bridging_technology.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2009, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@digium.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 /*! \file
20  * \brief Channel Bridging API
21  * \author Joshua Colp <jcolp@digium.com>
22  */
23 
24 #ifndef _ASTERISK_BRIDGING_TECHNOLOGY_H
25 #define _ASTERISK_BRIDGING_TECHNOLOGY_H
26 
27 #if defined(__cplusplus) || defined(c_plusplus)
28 extern "C" {
29 #endif
30 
31 /*! \brief Preference for choosing the bridge technology */
33  /*! Bridge technology should have high precedence over other bridge technologies */
35  /*! Bridge technology is decent, not the best but should still be considered over low */
37  /*! Bridge technology is low, it should not be considered unless it is absolutely needed */
39 };
40 
41 /*!
42  * \brief Structure that is the essence of a bridge technology
43  */
45  /*! Unique name to this bridge technology */
46  const char *name;
47  /*! The capabilities that this bridge technology is capable of */
49  /*! Preference level that should be used when determining whether to use this bridge technology or not */
51  /*! Callback for when a bridge is being created */
52  int (*create)(struct ast_bridge *bridge);
53  /*! Callback for when a bridge is being destroyed */
54  int (*destroy)(struct ast_bridge *bridge);
55  /*! Callback for when a channel is being added to a bridge */
56  int (*join)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
57  /*! Callback for when a channel is leaving a bridge */
58  int (*leave)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
59  /*! Callback for when a channel is suspended from the bridge */
60  void (*suspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
61  /*! Callback for when a channel is unsuspended from the bridge */
62  void (*unsuspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
63  /*! Callback to see if a channel is compatible with the bridging technology */
64  int (*compatible)(struct ast_bridge_channel *bridge_channel);
65  /*! Callback for writing a frame into the bridging technology */
66  enum ast_bridge_write_result (*write)(struct ast_bridge *bridge, struct ast_bridge_channel *bridged_channel, struct ast_frame *frame);
67  /*! Callback for when a file descriptor trips */
68  int (*fd)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, int fd);
69  /*! Callback for replacement thread function */
70  int (*thread)(struct ast_bridge *bridge);
71  /*! Callback for poking a bridge thread */
72  int (*poke)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
73  /*! Formats that the bridge technology supports */
75  /*! Bit to indicate whether the bridge technology is currently suspended or not */
76  unsigned int suspended:1;
77  /*! Module this bridge technology belongs to. Is used for reference counting when creating/destroying a bridge. */
78  struct ast_module *mod;
79  /*! Linked list information */
81 };
82 
83 /*! \brief Register a bridge technology for use
84  *
85  * \param technology The bridge technology to register
86  * \param mod The module that is registering the bridge technology
87  *
88  * \retval 0 on success
89  * \retval -1 on failure
90  *
91  * Example usage:
92  *
93  * \code
94  * ast_bridge_technology_register(&simple_bridge_tech);
95  * \endcode
96  *
97  * This registers a bridge technology declared as the structure
98  * simple_bridge_tech with the bridging core and makes it available for
99  * use when creating bridges.
100  */
102 
103 /*! \brief See \ref __ast_bridge_technology_register() */
104 #define ast_bridge_technology_register(technology) __ast_bridge_technology_register(technology, ast_module_info->self)
105 
106 /*! \brief Unregister a bridge technology from use
107  *
108  * \param technology The bridge technology to unregister
109  *
110  * \retval 0 on success
111  * \retval -1 on failure
112  *
113  * Example usage:
114  *
115  * \code
116  * ast_bridge_technology_unregister(&simple_bridge_tech);
117  * \endcode
118  *
119  * This unregisters a bridge technlogy declared as the structure
120  * simple_bridge_tech with the bridging core. It will no longer be
121  * considered when creating a new bridge.
122  */
124 
125 /*! \brief Feed notification that a frame is waiting on a channel into the bridging core
126  *
127  * \param bridge The bridge that the notification should influence
128  * \param bridge_channel Bridge channel the notification was received on (if known)
129  * \param chan Channel the notification was received on (if known)
130  * \param outfd File descriptor that the notification was received on (if known)
131  *
132  * Example usage:
133  *
134  * \code
135  * ast_bridge_handle_trip(bridge, NULL, chan, -1);
136  * \endcode
137  *
138  * This tells the bridging core that a frame has been received on
139  * the channel pointed to by chan and that it should be read and handled.
140  *
141  * \note This should only be used by bridging technologies.
142  */
143 void ast_bridge_handle_trip(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_channel *chan, int outfd);
144 
145 /*! \brief Suspend a bridge technology from consideration
146  *
147  * \param technology The bridge technology to suspend
148  *
149  * Example usage:
150  *
151  * \code
152  * ast_bridge_technology_suspend(&simple_bridge_tech);
153  * \endcode
154  *
155  * This suspends the bridge technology simple_bridge_tech from being considered
156  * when creating a new bridge. Existing bridges using the bridge technology
157  * are not affected.
158  */
160 
161 /*! \brief Unsuspend a bridge technology
162  *
163  * \param technology The bridge technology to unsuspend
164  *
165  * Example usage:
166  *
167  * \code
168  * ast_bridge_technology_unsuspend(&simple_bridge_tech);
169  * \endcode
170  *
171  * This makes the bridge technology simple_bridge_tech considered when
172  * creating a new bridge again.
173  */
175 
176 #if defined(__cplusplus) || defined(c_plusplus)
177 }
178 #endif
179 
180 #endif /* _ASTERISK_BRIDGING_TECHNOLOGY_H */
Main Channel structure associated with a channel.
Definition: channel.h:742
struct ast_module::@278 entry
AST_RWLIST_ENTRY(ast_bridge_technology) entry
void ast_bridge_technology_suspend(struct ast_bridge_technology *technology)
Suspend a bridge technology from consideration.
Definition: bridging.c:1236
void(* suspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
int(* poke)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
void(* unsuspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
int __ast_bridge_technology_register(struct ast_bridge_technology *technology, struct ast_module *mod)
Register a bridge technology for use.
Definition: bridging.c:63
int(* join)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
int(* create)(struct ast_bridge *bridge)
void ast_bridge_technology_unsuspend(struct ast_bridge_technology *technology)
Unsuspend a bridge technology.
Definition: bridging.c:1242
enum ast_bridge_preference preference
int(* thread)(struct ast_bridge *bridge)
int ast_bridge_technology_unregister(struct ast_bridge_technology *technology)
Unregister a bridge technology from use.
Definition: bridging.c:99
int(* compatible)(struct ast_bridge_channel *bridge_channel)
void ast_bridge_handle_trip(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_channel *chan, int outfd)
Feed notification that a frame is waiting on a channel into the bridging core.
Definition: bridging.c:277
Structure that contains information about a bridge.
Definition: bridging.h:149
int64_t format_t
Definition: frame_defs.h:32
struct ast_module * mod
int(* destroy)(struct ast_bridge *bridge)
enum ast_bridge_write_result(* write)(struct ast_bridge *bridge, struct ast_bridge_channel *bridged_channel, struct ast_frame *frame)
int(* fd)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, int fd)
Structure that contains information regarding a channel in a bridge.
Definition: bridging.h:117
Structure that is the essence of a bridge technology.
ast_bridge_write_result
Return values for bridge technology write function.
Definition: bridging.h:102
Data structure associated with a single frame of data.
Definition: frame.h:142
int(* leave)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
ast_bridge_preference
Preference for choosing the bridge technology.