diff options
Diffstat (limited to 'include/asterisk/channel.h')
| -rw-r--r-- | include/asterisk/channel.h | 273 |
1 files changed, 226 insertions, 47 deletions
diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h index 80476a4e0..3dfbe61d9 100644 --- a/include/asterisk/channel.h +++ b/include/asterisk/channel.h @@ -123,6 +123,7 @@ References: #ifndef _ASTERISK_CHANNEL_H #define _ASTERISK_CHANNEL_H +#include "asterisk/alertpipe.h" #include "asterisk/abstract_jb.h" #include "asterisk/astobj2.h" #include "asterisk/poll-compat.h" @@ -173,17 +174,17 @@ extern "C" { #include "asterisk/linkedlists.h" #include "asterisk/stringfields.h" #include "asterisk/datastore.h" -#include "asterisk/data.h" +#include "asterisk/format_cap.h" #include "asterisk/channelstate.h" #include "asterisk/ccss.h" #include "asterisk/framehook.h" #include "asterisk/stasis.h" -#include "asterisk/json.h" #include "asterisk/endpoints.h" #define DATASTORE_INHERIT_FOREVER INT_MAX -#define AST_MAX_FDS 11 +#define AST_MAX_FDS 11 /*!< original maximum number of file descriptors */ +#define AST_EXTENDED_FDS 12 /*!< the start of extended file descriptor positions */ /* * We have AST_MAX_FDS file descriptors in a channel. * Some of them have a fixed use: @@ -203,6 +204,8 @@ enum ast_bridge_result { typedef unsigned long long ast_group_t; +struct ast_stream_topology; + /*! \todo Add an explanation of an Asterisk generator */ struct ast_generator { @@ -630,6 +633,26 @@ struct ast_channel_tech { */ struct ast_channel *(* const requester)(const char *type, struct ast_format_cap *cap, const struct ast_assigned_ids *assignedids, const struct ast_channel *requestor, const char *addr, int *cause); + /*! + * \brief Requester - to set up call data structures (pvt's) with stream topology + * + * \param type type of channel to request + * \param topology Stream topology for requested channel + * \param assignedid Unique ID string to assign to channel + * \param requestor channel asking for data + * \param addr destination of the call + * \param cause Cause of failure + * + * \details + * Request a channel of a given type, with addr as optional information used + * by the low level module + * + * \retval NULL failure + * \retval non-NULL channel on success + */ + struct ast_channel *(* const requester_with_stream_topology)(const char *type, struct ast_stream_topology *topology, const struct ast_assigned_ids *assignedids, const struct ast_channel *requestor, const char *addr, int *cause); + + int (* const devicestate)(const char *device_number); /*!< Devicestate call back */ int (* const presencestate)(const char *presence_provider, char **subtype, char **message); /*!< Presencestate callback */ @@ -664,9 +687,33 @@ struct ast_channel_tech { /*! \brief Answer the channel */ int (* const answer)(struct ast_channel *chan); - /*! \brief Read a frame, in standard format (see frame.h) */ + /*! + * \brief Read a frame (or chain of frames from the same stream), in standard format (see frame.h) + * + * \param chan channel to read frames from + * + * \retval non-NULL on success + * \retval NULL on failure + * + * \note Each media frame from this callback will have the stream_num of it changed to the default + * stream num based on the type of media returned. As a result a multistream capable channel + * should not implement this callback. + */ struct ast_frame * (* const read)(struct ast_channel *chan); + /*! + * \brief Read a frame (or chain of frames from the same stream), in standard format (see frame.h), with stream num + * + * \param chan channel to read frames from + * + * \retval non-NULL on success + * \retval NULL on failure + * + * \note Each media frame from this callback should contain a stream_num value which is set to the + * stream that the media frame originated from. + */ + struct ast_frame * (* const read_stream)(struct ast_channel *chan); + /*! \brief Write a frame, in standard format (see frame.h) */ int (* const write)(struct ast_channel *chan, struct ast_frame *frame); @@ -887,10 +934,6 @@ enum { * world */ AST_CHAN_TP_INTERNAL = (1 << 2), - /*! - * \brief Channels with this particular technology support multiple simultaneous streams - */ - AST_CHAN_TP_MULTISTREAM = (1 << 3), }; /*! \brief ast_channel flags */ @@ -1373,6 +1416,25 @@ struct ast_channel *ast_channel_release(struct ast_channel *chan); */ struct ast_channel *ast_request(const char *type, struct ast_format_cap *request_cap, const struct ast_assigned_ids *assignedids, const struct ast_channel *requestor, const char *addr, int *cause); +/*! + * \brief Requests a channel (specifying stream topology) + * + * \param type type of channel to request + * \param topology Stream topology for requested channel + * \param assignedids Unique ID to create channel with + * \param requestor channel asking for data + * \param addr destination of the call + * \param cause Cause of failure + * + * \details + * Request a channel of a given type, with addr as optional information used + * by the low level module + * + * \retval NULL failure + * \retval non-NULL channel on success + */ +struct ast_channel *ast_request_with_stream_topology(const char *type, struct ast_stream_topology *topology, const struct ast_assigned_ids *assignedids, const struct ast_channel *requestor, const char *addr, int *cause); + enum ast_channel_requestor_relationship { /*! The requestor is the future bridge peer of the channel. */ AST_CHANNEL_REQUESTOR_BRIDGE_PEER, @@ -1926,14 +1988,37 @@ int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception); /*! * \brief Reads a frame + * * \param chan channel to read a frame from + * * \return Returns a frame, or NULL on error. If it returns NULL, you * best just stop reading frames and assume the channel has been * disconnected. + * + * \note This function will filter frames received from the channel so + * that only frames from the default stream for each media type + * are returned. All other media frames from other streams will + * be absorbed internally and a NULL frame returned instead. */ struct ast_frame *ast_read(struct ast_channel *chan); /*! + * \brief Reads a frame, but does not filter to just the default streams + * + * \param chan channel to read a frame from + * + * \return Returns a frame, or NULL on error. If it returns NULL, you + * best just stop reading frames and assume the channel has been + * disconnected. + * + * \note This function will not perform any filtering and will return + * media frames from all streams on the channel. To determine which + * stream a frame originated from the stream_num on it can be + * examined. + */ +struct ast_frame *ast_read_stream(struct ast_channel *chan); + +/*! * \brief Reads a frame, returning AST_FRAME_NULL frame if audio. * \param chan channel to read a frame from * \return Returns a frame, or NULL on error. If it returns NULL, you @@ -1945,6 +2030,26 @@ struct ast_frame *ast_read(struct ast_channel *chan); struct ast_frame *ast_read_noaudio(struct ast_channel *chan); /*! + * \brief Reads a frame, but does not filter to just the default streams, + * returning AST_FRAME_NULL frame if audio. + * + * \param chan channel to read a frame from + * + * \return Returns a frame, or NULL on error. If it returns NULL, you + * best just stop reading frames and assume the channel has been + * disconnected. + * + * \note This function will not perform any filtering and will return + * media frames from all streams on the channel. To determine which + * stream a frame originated from the stream_num on it can be + * examined. + * + * \note Audio is replaced with AST_FRAME_NULL to avoid + * transcode when the resulting audio is not necessary. + */ +struct ast_frame *ast_read_stream_noaudio(struct ast_channel *chan); + +/*! * \brief Write a frame to a channel * This function writes the given frame to the indicated channel. * \param chan destination channel of the frame @@ -2134,11 +2239,12 @@ int ast_waitfordigit(struct ast_channel *c, int ms); * Same as ast_waitfordigit() with audio fd for outputting read audio and ctrlfd to monitor for reading. * \param c channel to wait for a digit on * \param ms how many milliseconds to wait (<0 for indefinite). + * \param breakon string of DTMF digits to break upon or NULL for any. * \param audiofd audio file descriptor to write to if audio frames are received * \param ctrlfd control file descriptor to monitor for reading * \return Returns 1 if ctrlfd becomes available */ -int ast_waitfordigit_full(struct ast_channel *c, int ms, int audiofd, int ctrlfd); +int ast_waitfordigit_full(struct ast_channel *c, int ms, const char *breakon, int audiofd, int ctrlfd); /*! * \brief Reads multiple digits @@ -2359,12 +2465,6 @@ void ast_channel_set_caller_event(struct ast_channel *chan, const struct ast_par /*! Set the file descriptor on the channel */ void ast_channel_set_fd(struct ast_channel *chan, int which, int fd); -/*! Add a channel to an optimized waitfor */ -void ast_poll_channel_add(struct ast_channel *chan0, struct ast_channel *chan1); - -/*! Delete a channel from an optimized waitfor */ -void ast_poll_channel_del(struct ast_channel *chan0, struct ast_channel *chan1); - /*! Start a tone going */ int ast_tonepair_start(struct ast_channel *chan, int freq1, int freq2, int duration, int vol); /*! Stop a tone from playing */ @@ -3760,27 +3860,6 @@ int ast_channel_connected_line_macro(struct ast_channel *autoservice_chan, struc int ast_channel_connected_line_sub(struct ast_channel *autoservice_chan, struct ast_channel *sub_chan, const void *connected_info, int frame); /*! - * \brief Insert into an astdata tree, the channel structure. - * \param[in] tree The ast data tree. - * \param[in] chan The channel structure to add to tree. - * \param[in] add_bridged Add the bridged channel to the structure. - * \retval <0 on error. - * \retval 0 on success. - */ -int ast_channel_data_add_structure(struct ast_data *tree, struct ast_channel *chan, int add_bridged); - -/*! - * \brief Compare to channel structures using the data api. - * \param[in] tree The search tree generated by the data api. - * \param[in] chan The channel to compare. - * \param[in] structure_name The name of the node of the channel structure. - * \retval 0 The structure matches. - * \retval 1 The structure doesn't matches. - */ -int ast_channel_data_cmp_structure(const struct ast_data_search *tree, struct ast_channel *chan, - const char *structure_name); - -/*! * \since 1.8 * \brief Run a redirecting interception macro and update a channel's redirecting information * \deprecated You should use the ast_channel_redirecting_sub() function instead. @@ -4230,12 +4309,6 @@ struct ast_namedgroups *ast_channel_named_pickupgroups(const struct ast_channel void ast_channel_named_pickupgroups_set(struct ast_channel *chan, struct ast_namedgroups *value); /* Alertpipe accessors--the "internal" functions for channel.c use only */ -typedef enum { - AST_ALERT_READ_SUCCESS = 0, - AST_ALERT_NOT_READABLE, - AST_ALERT_READ_FAIL, - AST_ALERT_READ_FATAL, -} ast_alert_status_t; int ast_channel_alert_write(struct ast_channel *chan); int ast_channel_alert_writable(struct ast_channel *chan); ast_alert_status_t ast_channel_internal_alert_flush(struct ast_channel *chan); @@ -4257,11 +4330,30 @@ void ast_channel_internal_fd_set(struct ast_channel *chan, int which, int value) int ast_channel_fd(const struct ast_channel *chan, int which); int ast_channel_fd_isset(const struct ast_channel *chan, int which); -/* epoll data internal accessors */ -#ifdef HAVE_EPOLL -struct ast_epoll_data *ast_channel_internal_epfd_data(const struct ast_channel *chan, int which); -void ast_channel_internal_epfd_data_set(struct ast_channel *chan, int which , struct ast_epoll_data *value); -#endif +/*! + * \since 15 + * \brief Retrieve the number of file decriptor positions present on the channel + * + * \param chan The channel to get the count of + * + * \pre chan is locked + * + * \return The number of file descriptor positions + */ +int ast_channel_fd_count(const struct ast_channel *chan); + +/*! + * \since 15 + * \brief Add a file descriptor to the channel without a fixed position + * + * \param chan The channel to add the file descriptor to + * \param value The file descriptor + * + * \pre chan is locked + * + * \return The position of the file descriptor + */ +int ast_channel_fd_add(struct ast_channel *chan, int value); pthread_t ast_channel_blocker(const struct ast_channel *chan); void ast_channel_blocker_set(struct ast_channel *chan, pthread_t value); @@ -4345,6 +4437,31 @@ void ast_channel_dialed_causes_clear(const struct ast_channel *chan); struct ast_flags *ast_channel_flags(struct ast_channel *chan); /*! + * \since 13.17.0 + * \brief Set a flag on a channel + * + * \param chan The channel to set the flag on + * \param flag The flag to set + * + * \note This will lock the channel internally. If the channel is already + * locked it is still safe to call. + */ + +void ast_channel_set_flag(struct ast_channel *chan, unsigned int flag); + +/*! + * \since 13.17.0 + * \param Clear a flag on a channel + * + * \param chan The channel to clear the flag from + * \param flag The flag to clear + * + * \note This will lock the channel internally. If the channel is already + * locked it is still safe to call. + */ +void ast_channel_clear_flag(struct ast_channel *chan, unsigned int flag); + +/*! * \since 12.4.0 * \brief Return whether or not any manager variables have been set * @@ -4548,6 +4665,9 @@ struct ast_bridge_channel *ast_channel_get_bridge_channel(struct ast_channel *ch * * \note absolutely _NO_ channel locks should be held before calling this function. * + * \note The dialplan location on the returned channel is where the channel + * should be started in the dialplan if it is returned to it. + * * \param yankee The channel to gain control of * \retval NULL Could not gain control of the channel * \retval non-NULL The channel @@ -4796,4 +4916,63 @@ struct ast_stream_topology *ast_channel_set_stream_topology( */ struct ast_stream *ast_channel_get_default_stream(struct ast_channel *chan, enum ast_media_type type); +/*! + * \brief Determine if a channel is multi-stream capable + * + * \param channel The channel to test + * + * \pre chan is locked + * + * \return Returns true if the channel is multi-stream capable. + */ +int ast_channel_is_multistream(struct ast_channel *chan); + +/*! + * \brief Request that the stream topology of a channel change + * + * \param chan The channel to change + * \param topology The new stream topology + * \param change_source The source that initiated the change + * + * \note Absolutely _NO_ channel locks should be held before calling this function. + * + * \retval 0 request has been accepted to be attempted + * \retval -1 request could not be attempted + * + * \note This function initiates an asynchronous request to change the stream topology. It is not + * guaranteed that the topology will change and until an AST_CONTROL_STREAM_TOPOLOGY_CHANGED + * frame is received from the channel the current handler of the channel must tolerate the + * stream topology as it currently exists. + * + * \note This interface is provided for applications and resources to request that the topology change. + * It is not for use by the channel driver itself. + */ +int ast_channel_request_stream_topology_change(struct ast_channel *chan, + struct ast_stream_topology *topology, void *change_source); + +/*! + * \brief Provide notice to a channel that the stream topology has changed + * + * \param chan The channel to provide notice to + * \param topology The new stream topology + * + * \pre chan is locked Absolutely _NO_ other channels can be locked. + * + * \retval 0 success + * \retval -1 failure + * + * \note This interface is provided for applications and resources to accept a topology change. + * It is not for use by the channel driver itself. + */ +int ast_channel_stream_topology_changed(struct ast_channel *chan, struct ast_stream_topology *topology); + +/*! + * \brief Retrieve the source that initiated the last stream topology change + * + * \param chan The channel + * + * \retval The channel's stream topology change source + */ +void *ast_channel_get_stream_topology_change_source(struct ast_channel *chan); + #endif /* _ASTERISK_CHANNEL_H */ |