MediaServiceInternal - Avaya Internal Use Only
This object provides a way for a snap-in to send MSML to a media server. It fulfills the same role as the
MediaService
object does for media operations like "play announcement" or "collect digits" or similar.
Two methods are provided:
- sendMsml(Call call, String msml, MsmlListener msmlListener) - the call-based method
- sendMsml(Participant participant, String msml, MsmlListener msmlListener) - the participant-based method
Invocation of either method initiates an asynchronous send of a MSML document to the media server. The MSML document is not a complete
document but excludes both the
<?xml> and the
<msml> elements. The following is an example of such a MSML
String:
<join id1="conn:supervisor" id2="conn:agent"/>
Each method also takes a listener. An instance of the listener, which is defined by the snap-in and which implements the
MsmlListener interface, provides a way for the snap-in to receive asynchronous responses, which indicate if the MSML has
been processed successfully. MSML events that are generated for MSML documents containing dialogs are also passed to the listener.
For many types of MSML documents, the decision to use one method or the other is unimportant, as the methods are interchangeable for many
scenarios. However, as will be explained later, in certain cases the MSML is given special treatment, which can result in the methods
giving different behavior.
Unless the special treatment of the MSML in a particular scenario dictates use of the participant-based method, it is suggested that the
call-based method always be used, both for consistency and to ensure that the "MSML transmission pipe" to the media server exists for the
length of the call (as described later).
Special Treatment of MSML
Two types of special treatment are applied to MSML documents:
- The API recognizes when a MSML document contains a dialogstart tag (in such a case the MSML can only consist of a single dialogstart
element and no other tags; failure to abide by this constraint will result in undefined behavior). Then, a dialog ID is automatically
generated for and associated with the dialog. This ID is the same value as the one returned from either sendMsml method.
The dialog then is afforded the same kind of treatment as the standard media operations like "play announcement", "search speech", etc.
As a result, the ID then can subsequently be passed to either stop method of the MediaServer object,
which will result in a MSML dialogend being sent to the media server for the dialog. Additionally, depending on which
sendMsml method has been used, a dialogend will be sent to the media server if the call/participant ends before the
dialog has terminated naturally. Other similar treatment is also provided for the dialog. NOTE that the only way to pass dialogs to the
media server is one at a time in a MSML document that contains only the dialogstart. The reason for this constraint is that it is the
only way for the API to properly route MSML events to the correct listener instance. Additionally, use of the {DIALOG_ID} variable
described in the next item is required for placement of the dialog ID (name) in the MSML containing the dialogstart tag.
- Either/both of the variables {CONN_CONF_ID} or {DIALOG_ID} can be embedded in a MSML document. At any point where
the {CONN_CONF_ID} variable is present, the variable will be replaced by an ID that identifies the call's conference or a connection
(session) from the call. The specific ID that is substituted depends on which version of the sendMsml method is used. If
the call-based method is used, the {CONN_CONF_ID} variable is replaced by the conference ID, including the "conf:" prefix. If the
participant-based method is used, the {CONN_CONF_ID} variable is replaced by the connection ID, including the "conn:" prefix, that
identifies the partipant's connection on the media server. Similarly, if the MSML contains a dialogstart tag (which triggers the special
dialog treatment previously described), the automatically generated dialog ID will replace the variable {DIALOG_ID} anywhere it exists in
the MSML; the substituted dialog ID will not include the "dialog:" prefix.
For example, consider the following MSML:
<dialogstart xmlns:ns2="http://convedia.com/ext" target="{CONN_CONF_ID}" type="application/moml+xml" name="{DIALOG_ID}">
<play iterate="1" maxtime="2147483647ms" barge="true" cleardb="false">
<audio uri="http://info.dr.avaya.com/~joele/testing1234.wav" />
<playexit>
<exit namelist="play.end" />
</playexit>
</play>
</dialogstart>
Use of the call-based method will result in MSML like this:
<dialogstart xmlns:ns2="http://convedia.com/ext" target="conf:1a348ae6-5579-11e8-9c2d-fa7ae01bbebc" type="application/moml+xml" name="25bc9534-5579-11e8-9c2d-fa7ae01bbebc">
<play iterate="1" maxtime="2147483647ms" barge="true" cleardb="false">
<audio uri="http://info.dr.avaya.com/~joele/testing1234.wav" />
<playexit>
<exit namelist="play.end" />
</playexit>
</play>
</dialogstart>
Use of the participant-based method will result in MSML like this:
<dialogstart xmlns:ns2="http://convedia.com/ext" target="conn:1a348ae6-5579-11e8-9c2d-fa7ae01bbebc" type="application/moml+xml" name="25bc9534-5579-11e8-9c2d-fa7ae01bbebc">
<play iterate="1" maxtime="2147483647ms" barge="true" cleardb="false">
<audio uri="http://info.dr.avaya.com/~joele/testing1234.wav" />
<playexit>
<exit namelist="play.end" />
</playexit>
</play>
</dialogstart>
In addition to the two types of treatment above, there is one other key difference between the two methods. The call-based method
establishes a "MSML transmission pipe" that persists for the length of the call. The participant-based method establishes a
"MSML transmission pipe" that persists as long as the participant is on the call. Of course, if the "no participant remains" calling
policy is in use, the lifetime of the call can be much longer than the time that a participant is on the call.