This commit adds the ability to make ARI REST requests over the same
websocket used to receive events.
For full details on how to use the new capability, visit...
https://docs.asterisk.org/Configuration/Interfaces/Asterisk-REST-Interface-ARI/ARI-REST-over-WebSocket/
Changes:
* Added utilities to http.c:
* ast_get_http_method_from_string().
* ast_http_parse_post_form().
* Added utilities to json.c:
* ast_json_nvp_array_to_ast_variables().
* ast_variables_to_json_nvp_array().
* Added definitions for new events to carry REST responses.
* Created res/ari/ari_websocket_requests.c to house the new request handlers.
* Moved non-event specific code out of res/ari/resource_events.c into
res/ari/ari_websockets.c
* Refactored res/res_ari.c to move non-http code out of ast_ari_callback()
(which is http specific) and into ast_ari_invoke() so it can be shared
between both the http and websocket transports.
UpgradeNote: This commit adds the ability to make ARI REST requests over the same
websocket used to receive events.
See https://docs.asterisk.org/Configuration/Interfaces/Asterisk-REST-Interface-ARI/ARI-REST-over-WebSocket/
Issues:
* The bridging core allowed multiple bridges to be created with the same
unique bridgeId at the same time. Only the last bridge created with the
duplicate name was actually saved to the core bridges container.
* The bridging core was creating a stasis topic for the bridge and saving it
in the bridge->topic field but not increasing its reference count. In the
case where two bridges were created with the same uniqueid (which is also
the topic name), the second bridge would get the _existing_ topic the first
bridge created. When the first bridge was destroyed, it would take the
topic with it so when the second bridge attempted to publish a message to
it it either FRACKed or SEGVd.
* The bridge destructor, which also destroys the bridge topic, is run from the
bridge manager thread not the caller's thread. This makes it possible for
an ARI developer to create a new one with the same uniqueid believing the
old one was destroyed when, in fact, the old one's destructor hadn't
completed. This could cause the new bridge to get the old one's topic just
before the topic was destroyed. When the new bridge attempted to publish
a message on that topic, asterisk could either FRACK or SEGV.
* The ARI bridges resource also allowed multiple bridges to be created with
the same uniqueid but it kept the duplicate bridges in its app_bridges
container. This created a situation where if you added two bridges with
the same "bridge1" uniqueid, all operations on "bridge1" were performed on
the first bridge created and the second was basically orphaned. If you
attempted to delete what you thought was the second bridge, you actually
deleted the first one created.
Changes:
* A new API `ast_bridge_topic_exists(uniqueid)` was created to determine if
a topic already exists for a bridge.
* `bridge_base_init()` in bridge.c and `ast_ari_bridges_create()` in
resource_bridges.c now call `ast_bridge_topic_exists(uniqueid)` to check
if a bridge with the requested uniqueid already exists and will fail if it
does.
* `bridge_register()` in bridges.c now checks the core bridges container to
make sure a bridge doesn't already exist with the requested uniqueid.
Although most callers of `bridge_register()` will have already called
`bridge_base_init()`, which will now fail on duplicate bridges, there
is no guarantee of this so we must check again.
* The core bridges container allocation was changed to reject duplicate
uniqueids instead of silently replacing an existing one. This is a "belt
and suspenders" check.
* A global mutex was added to bridge.c to prevent concurrent calls to
`bridge_base_init()` and `bridge_register()`.
* Even though you can no longer create multiple bridges with the same uniqueid
at the same time, it's still possible that the bridge topic might be
destroyed while a second bridge with the same uniqueid was trying to use
it. To address this, the bridging core now increments the reference count
on bridge->topic when a bridge is created and decrements it when the
bridge is destroyed.
* `bridge_create_common()` in res_stasis.c now checks the stasis app_bridges
container to make sure a bridge with the requested uniqueid doesn't already
exist. This may seem like overkill but there are so many entrypoints to
bridge creation that we need to be safe and catch issues as soon in the
process as possible.
* The stasis app_bridges container allocation was changed to reject duplicate
uniqueids instead of adding them. This is a "belt and suspenders" check.
* The `bridge show all` CLI command now shows the bridge name as well as the
bridge id.
* Response code 409 "Conflict" was added as a possible response from the ARI
bridge create resources to signal that a bridge with the requested uniqueid
already exists.
* Additional debugging was added to multiple bridging and stasis files.
Resolves: #211
Introduce a ChannelTransfer event and the ability to notify progress to
ARI. Implement emitting this event from the PJSIP channel instead of
handling the transfer in Asterisk when configured.
Introduce a dialplan function to the PJSIP channel to switch between the
"core" and "ari-only" behavior.
UserNote: Call transfers on the PJSIP channel can now be controlled by
ARI. This can be enabled by using the PJSIP_TRANSFER_HANDLING(ari-only)
dialplan function.
* Dump a git blame of each file in rest-api/api-docs.
* Get the commit for each "resourcePath" and "httpMethod" entry.
* Find the tags for each commit (same as other processes).
* Insert a "since" array after each "resourcePath" and "httpMethod" entry.
This patch introduces a new identifier for channels: tenantid. It's
a stringfield on the channel that can be used for general purposes. It
will be inherited by other channels the same way that linkedid is.
You can set tenantid in a few ways. The first is to set it in the
dialplan with the Set and CHANNEL functions:
exten => example,1,Set(CHANNEL(tenantid)=My tenant ID)
It can also be accessed via CHANNEL:
exten => example,2,NoOp(CHANNEL(tenantid))
Another method is to use the new tenantid option for pjsip endpoints in
pjsip.conf:
[my_endpoint]
type=endpoint
tenantid=My tenant ID
This is considered the best approach since you will be able to see the
tenant ID as early as the Newchannel event.
It can also be set using set_var in pjsip.conf on the endpoint like
setting other channel variable:
set_var=CHANNEL(tenantid)=My tenant ID
Note that set_var will not show tenant ID on the Newchannel event,
however.
Tenant ID has also been added to CDR. It's read-only and can be accessed
via CDR(tenantid). You can also get the tenant ID of the last channel
communicated with via CDR(peertenantid).
Tenant ID will also show up in CEL records if it has been set, and the
version number has been bumped accordingly.
Fixes: #740
UserNote: tenantid has been added to channels. It can be read in
dialplan via CHANNEL(tenantid), and it can be set using
Set(CHANNEL(tenantid)=My tenant ID). In pjsip.conf, it is recommended to
use the new tenantid option for pjsip endpoints (e.g., tenantid=My
tenant ID) so that it will show up in Newchannel events. You can set it
like any other channel variable using set_var in pjsip.conf as well, but
note that this will NOT show up in Newchannel events. Tenant ID is also
available in CDR and can be accessed with CDR(tenantid). The peer tenant
ID can also be accessed with CDR(peertenantid). CEL includes tenant ID
as well if it has been set.
UpgradeNote: A new versioned struct (ast_channel_initializers) has been
added that gets passed to __ast_channel_alloc_ap. The new function
ast_channel_alloc_with_initializers should be used when creating
channels that require the use of this struct. Currently the only value
in the struct is for tenantid, but now more fields can be added to the
struct as necessary rather than the __ast_channel_alloc_ap function. A
new option (tenantid) has been added to endpoints in pjsip.conf as well.
CEL has had its version bumped to include tenant ID.
A stasis event is now produced when using the TONE_DETECT dialplan
function. This event is published over ARI using the ChannelToneDetected
event. This change does not make it available over AMI.
Fixes: #811
UserNote: Setting the TONE_DETECT dialplan function on a channel
in ARI will now cause a ChannelToneDetected ARI event to be raised
when the specified tone is detected.
This fixes a number of broken links throughout the
tree, mostly caused by wiki.asterisk.org being replaced
with docs.asterisk.org, which should eliminate the
need for sporadic fixes as in f28047db36.
Resolves: #430
This change adds support for refers that are not session based. It
includes a refer implementation for the PJSIP technology which results
in out-of-dialog REFERs being sent to a PJSIP endpoint. These can be
triggered using the new ARI endpoint `/endpoints/refer`.
Resolves: #71
UserNote: There is a new ARI endpoint `/endpoints/refer` for referring
an endpoint to some URI or endpoint.
Add new type 'sdp_label' when creating a bridge using the ARI. This will
add labels to the SDP for each stream, the label is set to the
corresponding channel id.
Resolves: #91
UserNote: When creating a bridge using the ARI the 'type' argument now
accepts a new value 'sdp_label' which will configure the bridge to add
labels for each stream in the SDP with the corresponding channel id.
This change exposes the channel driver's unique id (i.e. the Call-ID
for chan_sip/chan_pjsip based channels) to ARI channel resources
as `protocol_id`.
ASTERISK-30027
Reported by: Moritz Fain
Tested by: Moritz Fain
Change-Id: I7cc6e7a9d29efe74bc27811d788dac20fe559b87
When we try to play a list of sound files in the same Play command,
we get only one PlaybackFinish event, after all sounds are played.
But in the case where the Play fails (because channel is destroyed
for example), Asterisk will send one PlaybackFinish event for each
sound file still to be played. If the list is big, Asterisk is
sending many events.
This patch adds a failed state so we can understand that the play
failed. On that case we don't send the event, if we still have a
list of sounds to be played.
When we reach the last sound, we send the PlaybackFinish with
the failed state.
ASTERISK-29464 #close
Change-Id: I4c2e5921cc597702513af0d7c6c2c982e1798322
Currently, it was not possible to create bridge with video_mode single.
This made hard to put the bridge in a vidoe_single mode.
So, added video_single option for Bridge creation using the ARI.
This allows create a bridge with video_mode single.
ASTERISK-29055
Change-Id: I43e720e5c83fc75fafe10fe22808ae7f055da2ae
This change adds the same variable functionality that
is available for originating a channel to the create
call. Now when creating a channel you can specify
dialplan variables to set instead of having to do another
API call.
ASTERISK-28896
Change-Id: If13997ba818136d7c070585504fc4164378aa992
When a text message was received any associated variable was not written to
the ARI TextMessageReceived event. This occurred because Asterisk only wrote
out "send" variables. However, even those "send" variables would fail ARI
validation due to a TextMessageVariable formatting bug.
Since it seems the TextMessageReceived event has never been able to include
actual variables it was decided to remove the TextMessageVariable object type
from ARI, and simply return a JSON object of key/value pairs for variables.
This aligns more with how the ARI sendMessage handles variables, and other
places in ARI.
ASTERISK-28755 #close
Change-Id: Ia6051c01a53b30cf7edef84c27df4ed4479b8b6f
This commit adds support for
[AudioSocket](
https://wiki.asterisk.org/wiki/display/AST/AudioSocket),
a very simple bidirectional audio streaming protocol. There are both
channel and application interfaces.
A description of the protocol can be found on the above referenced
GitHub page. A short talk about the reasons and implementation can be
found on [YouTube](https://www.youtube.com/watch?v=tjduXbZZEgI), from
CommCon 2019.
ARI support has also been added via the existing "externalMedia" ARI
functionality. The UUID is specified using the arbitrary "data" field.
ASTERISK-28484 #close
Change-Id: Ie866e6c4fa13178ec76f2a6971ad3590a3a588b5
This patch adds a new flag "inhibitConnectedLineUpdates" to the 'addChannel'
operation in the Bridges REST API. When set, this flag avoids generating COLP
frames when the specified channels enter the bridge.
ASTERISK-28629
Change-Id: Ib995d4f0c6106279aa448b34b042b68f0f2ca5dc
When we created the External Media addition to ARI we created an
ExternalMedia object to be returned from the channels/externalMedia
REST endpoint. This object contained the channel object that was
created plus local_address and local_port attributes (which are
also in the Channel variables). At the time, we thought that
creating an ExternalMedia object would give us more flexibility
in the future but as we created the sample speech to text
application, we discovered that it doesn't work so well with ARI
client libraries that a) don't have the ExternalMedia object
defined and/or b) can't promote the embedded channel structure
to a first-class Channel object.
This change causes the channels/externalMedia REST endpoint to
return a Channel object (like channels/create and channels/originate)
instead of the ExternalMedia object.
Change-Id: If280094debd35102cf21e0a31a5e0846fec14af9
The Channel resource has a new sub-resource "externalMedia".
This allows an application to create a channel for the sole purpose
of exchanging media with an external server. Once created, this
channel could be placed into a bridge with existing channels to
allow the external server to inject audio into the bridge or
receive audio from the bridge.
See https://wiki.asterisk.org/wiki/display/AST/External+Media+and+ARI
for more information.
Change-Id: I9618899198880b4c650354581b50c0401b58bc46
Currently, DELETE /ari/channels/<channelID> supports only few hangup reasons.
It's good enough for simple use, but when it needs to set the detail reason,
it comes challenges.
Added reason_code query parameter for that.
ASTERISK-28385
Change-Id: I1cf1d991ffd759d0591b347445a55f416ddc3ff2
It was difficult to check the channel's current application and
parameters using ARI for current channels. Added app_name, app_data
items to show the current application information.
ASTERISK-28343
Change-Id: Ia48972b3850e5099deab0faeaaf51223a1f2f38c
Added ARI resource for channel statistics.
GET /ari/channels/{channelId}/rtp_statistics : It returns given
channel's rtp statistics detail.
ASTERISK-28320
Change-Id: I4343eec070438cec13f2a4f22e7fd9e574381376
Changed to requirement to having timestamp for all of ARI events.
The below ARI events were changed to having timestamp.
PlaybackStarted, PlaybackContinuing, PlaybackFinished,
RecordingStarted, RecordingFinished, RecordingFailed,
ApplicationReplaced, ApplicationMoveFailed
ASTERISK-28326
Change-Id: I382c2fef58f5fe107e1074869a6d05310accb41f
Added the ability to move between Stasis applications within Stasis.
This can be done by calling 'move' in an application, providing (at
minimum) the channel's id and the application to switch to. If the
application is not registered or active, nothing will happen and the
channel will remain in the current application, and an event will be
triggered to let the application know that the move failed. The event
name is "ApplicationMoveFailed", and provides the "destination" that the
channel was attempting to move to, as well as the usual channel
information. Optionally, a list of arguments can be passed to the
function call for the receiving application. A full example of a 'move'
call would look like this:
client.channels.move(channelId, app, appArgs)
The control object used to control the channel in Stasis can now switch
which application it belongs to, rather than belonging to one Stasis
application for its lifetime. This allows us to use the same control
object instead of having to tear down the current one and create
another.
ASTERISK-28267 #close
Change-Id: I43d12b10045a98a8d42541889b85695be26f288a
This small feature will help to checking the bridge's status to
figure out which bridge is in old/zombie or not. Also added
detail items for the 'bridge show *' cli to provide more detail
info. And added creation item to the ARI as well.
ASTERISK-28279
Change-Id: I460238c488eca4d216b9176576211cb03286e040
Event type filtering is now enabled, and configurable per application. An app is
now able to specify which events are sent to the application by configuring an
allowed and/or disallowed list(s). This can be done by issuing the following:
PUT /applications/{applicationName}/eventFilter
And then enumerating the allowed/disallowed event types as a body parameter.
ASTERISK-28106
Change-Id: I9671ba1fcdb3b6c830b553d4c5365aed5d588d5b
Added ARI resource.
GET /ari/asterisk/ping : It returns "pong" message with timestamp
and asterisk id. It would be useful for simple heath check.
Change-Id: I8d24e1dcc96f60f73437c68d9463ed746f688b29
The ARI DELETE /channels command takes a "reason" parameter
Previously, there were only five reasons implemented
This patch adds more reasons to choose from for more
complex setups
ASTERISK-28198 #close
Change-Id: I85996f1076c9946d65c778413f040a845a90fecc
I've audited all modules that include any header which includes
asterisk/optional_api.h. All modules which use OPTIONAL_API now declare
those dependencies in AST_MODULE_INFO using requires or optional_modules
as appropriate.
In addition ARI dependency declarations have been reworked. Instead of
declaring additional required modules in res/ari/resource_*.c we now add
them to an optional array "requiresModules" in api-docs for each module.
This allows the AST_MODULE_INFO dependencies to include those missing
modules.
Change-Id: Ia0c70571f5566784f63605e78e1ceccb4f79c606
A couple of places were setting the status to "UNKNOWN" when qualifies were
being disabled. Instead this should be set to the "CREATED" status that
represents when a contact is given (uri available), but the qualify frequency
is set to zero so we don't know the status.
This patch updates the relevant places with "CREATED". It also updates the
"CREATED" status description (value shown in CLI/AMI/ARI output) to a value
of "NonQualified"/"NonQual" as this description is hopefully less confusing.
ASTERISK-27467
Change-Id: Id67509d25df92a72eb3683720ad2a95a27b50c89
Add bridge_features structure to bridge creation. Specifically, this
implements mute and DTMF suppression, but others should be able to be
easily added to the same structure.
ASTERISK-27322 #close
Reported by: Darren Sessions
Sponsored by: AVOXI
Change-Id: Id4002adfb65c9a8027ee9e1a5f477e0f01cf9d61
This change adds 'video_sfu' as a requested bridge type when
creating a bridge. By specifying this a mixing type bridge is
created that exchanges video in an SFU fashion.
Change-Id: I2ada47cf5f3fc176518b647c0b4aa39d55339606
In order to not have version number overlap between different versions
of Asterisk, each new major version of Asterisk will mean we also bump
the ARI major version number.
This particular change does NOT introduce any known breaking changes to
ARI.
For discussion relating to this topice, see:
http://lists.digium.com/pipermail/asterisk-dev/2016-November/075964.html
Change-Id: I712ee0df177a8fe1252da2bc029705268b97b665
In multi-party bridges, Asterisk currently supports two video modes:
* Follow the talker, in which the speaker with the most energy is shown
to all participants but the speaker, and the speaker sees the
previous video source
* Explicitly set video sources, in which all participants see a locked
video source
Prior to this patch, ARI had no ability to manipulate the video source.
This isn't important for two-party bridges, in which Asterisk merely
relays the video between the participants. However, in a multi-party
bridge, it can be advantageous to allow an external application to
manipulate the video source.
This patch provides two new routes to accomplish this:
(1) setVideoSource: POST /bridges/{bridgeId}/videoSource/{channelId}
Sets a video source to an explicit channel
(2) clearVideoSource: DELETE /bridges/{bridgeId}/videoSource
Removes any explicit video source, and sets the video mode to talk
detection
ASTERISK-26595 #close
Change-Id: I98e455d5bffc08ea5e8d6b84ccaf063c714e6621
This works the same as for AMI manager variables. Set
"channelvars=foo,bar" in your ari.conf general section, and then the
channel variables "foo" and "bar" (along with their values), will
appear in every Stasis websocket channel event.
ASTERISK-26492 #close
patches:
ari_vars.diff submitted by Mark Michelson
Change-Id: I5609ba239259577c0948645df776d7f3bc864229
This is similar to what is done for origination, but for the 14 and up
channel creation method. When attempting to create a channel, if a
channel ID is specified and a channel already exists with that ID, then
a 409 is returned.
Change-Id: I77f9253278c6947939c418073b6b31065489187c
ARI and AMI allow for an explicit channel ID to be specified
when originating channels. Unfortunately, there is nothing in
place to prevent someone from using the same ID for multiple
channels. Further complicating things, adding ID validation to channel
allocation makes it impossible for ARI to discern why channel allocation
failed, resulting in a vague error code being returned.
The fix for this is to institute a new method for channel errors to be
discerned. The method mirrors errno, in that when an error occurs, the
caller can consult the channel errno value to determine what the error
was. This initial iteration of the feature only introduces "unknown" and
"channel ID exists" errors. However, it's possible to add more errors as
needed.
ARI uses this feature to determine why channel allocation failed and can
return a 409 error during origination to show that a channel with the
given ID already exists.
ASTERISK-26421
Change-Id: Ibba7ae68842dab6df0c2e9c45559208bc89d3d06
This patch adds the Asterisk EID field to all outgoing ARI events.
Because this field should be added to all events as they are
transmitted, it is appended to the JSON message just prior to it being
handed off to the application message handler. This makes it somewhat
resilient to both new events being added to ARI, as well as other
potential event transport mechanisms.
ASTERISK-26470 #close
Change-Id: Ieff0ecc24464e83f3f44e9c3e7bd9a5d70b87a1d
In ARI, the channels API allows to hangup a channel with a hangup reason.
This commit adds a new reason "answered_elsewhere".
When using a SIP channel, this will eventually allow Asterisk to add a proper
"Reason" header to a CANCEL message.
ASTERISK-26321
Change-Id: Ia97675bd4acd6a7f58eb467953dfb94559f6583d
ARI was recently outfitted with operations to create and dial channels.
This leads to the ability to try funny stuff. You could create a channel
and then immediately try to play back media on it. You could create a
channel, dial it, and while it is ringing attempt to make it continue in
the dialplan.
This commit attempts to fix this by adding a channel state check to
operations that should not be able to operate on outbound channels that
have not yet answered. If a channel is in an invalid state, we will send
a 412 response.
ASTERISK-26047 #close
Reported by Mark Michelson
Change-Id: I2ca51bf9ef2b44a1dc5a73f2d2de35c62c37dfd8
If you create a local channel and don't specify an originator channel
to take capabilities from, we automatically add all audio formats to
the new channel's capabilities. When we try to make the channel
compatible with another, the "best format" functions pick the best
format available, which in this case will be slin192. While this is
great for preserving quality, it's the worst for performance and
overkill for the vast majority of applications.
In the absense of any other information, adding all formats is the
correct thing to do and it's not always possible to supply an
originator so a new parameter 'formats' has been added to the channel
create/originate functions. It's just a comma separated list of formats
to make availalble for the channel. Example: "ulaw,slin,slin16".
'formats' and 'originator' are mutually exclusive.
To facilitate determination of format names, the format name has been
added to "core show codecs".
ASTERISK-26070 #close
Change-Id: I091b23ecd41c1b4128d85028209772ee139f604b
This patch adds a new feature to ARI that allows a client to download
the media associated with a stored recording. The new route is
/recordings/stored/{name}/file, and transmits the underlying binary file
using Asterisk's HTTP server's underlying file transfer facilities.
Because this REST route returns non-JSON, a few small enhancements had
to be made to the Python Swagger generation code, as well as the
mustache templates that generate the ARI bindings.
ASTERISK-26042 #close
Change-Id: I49ec5c4afdec30bb665d9c977ab423b5387e0181
Many ARI applications will want to play multiple media files in a row to
a resource. The most common use case is when building long-ish IVR prompts
made up of multiple, smaller sound files. Today, that requires building a
small state machine, listening for each PlaybackFinished event, and triggering
the next sound file to play. While not especially challenging, it is tedious
work. Since requiring developers to write tedious code to do normal activities
stinks, this patch adds the ability to play back a list of media files to a
resource.
Each of the 'play' operations on supported resources (channels and bridges)
now accepts a comma delineated list of media URIs to play. A single Playback
resource is created as a handle to the entire list. The operation of playing
a list is identical to playing a single media URI, save that a new event,
PlaybackContinuing, is raised instead of a PlaybackFinished for each non-final
media URI. When the entire list is finished being played, a PlaybackFinished
event is raised.
In order to help inform applications where they are in the list playback, the
Playback resource now includes a new, optional attribute, 'next_media_uri',
that contains the next URI in the list to be played.
It's important to note the following:
- If an offset is provided to the 'play' operations, it only applies to the
first media URI, as it would be weird to skip n seconds forward in every
media resource.
- Operations that control the position of the media only affect the current
media being played. For example, once a media resource in the list
completes, a 'reverse' operation on a subsequent media resource will not
start a previously completed media resource at the appropiate offset.
- This patch does not add any new operations to control the list. Hopefully,
user feedback and/or future patches would add that if people want it.
ASTERISK-26022 #close
Change-Id: Ie1ea5356573447b8f51f2e7964915ea01792f16f
George Joseph
Holger Hans Peter Freyther
Ben Ford
gibbz00
Naveen Albert
Maximilian Fridrich
Joe Searle
Mike Bradeen
Moritz Fain
Andre Barbosa
Sungtae Kim
Joshua C. Colp
Kevin Harwell
Friendly Automation
Seán C McCord
Jean Aunis
George Joseph
sungtae kim
Sebastian Damm
Corey Farrell
Joshua Colp
Mark Michelson
zuul
Matt Jordan
Sebastien Duthil