tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 5707

 
 
 

Media Server Markup Language (MSML)

Part 4 of 6, p. 85 to 113
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 85 
9.9.  MSML Dialog Transform Package

   The MSML Dialog Transform Package gathers together the simple
   primitives that work as filters on half-duplex media streams.

9.9.1.  <vad>

   Voice activity detection (VAD) is used to detect voice and silence
   when speech recognition is not required.  Similar to both speech and
   DTMF, a VAD has different media conditions that it can match.  Those
   conditions can be qualified by a minimum length of time that is
   required for them to be considered recognized.

   Attributes:

      id: an optional identifier that may be referenced elsewhere for
      sending events to the vad primitive.

      starttimer: boolean value that defines whether the timer is
      started to allow recognition of the initial condition (voice,
      silence).  When set to false, the starttimer event must be
      received in order for the initial condition to be recognized.  The
      timer does not affect recognition of the transition conditions.
      Default is "false".

   Events:

      starttimer: starts the timer to allow recognition of the initial
      condition if it has not already been started.  Has no effect
      otherwise.

      terminate: terminates voice activity detection.

   Shadow Variables:

      none

   The following sections describe the child elements of <vad>.

9.9.1.1.  <voice>, <silence>, <tvoice>, <tsilence>

   Each child element corresponds to a condition that a VAD can detect.
   The first two detect when voice or silence has been initially present
   for a minimum length of time since the VAD was started.  The second
   two require that a transition to the voice or silence condition first
   occur.

Top      Up      ToC       Page 86 
   Attributes:

      len: the length of time the condition must persist in order to be
      recognized.  Mandatory.  In the case of <tvoice> and <tsilence>,
      the length of time applies only to the final recognized condition.

      sen: the maximum length of time the condition not being detected
      may occur without causing the detector to begin measuring that
      condition.

9.9.2.  <gain>

   Gain MAY be used to adjust of the gain of a media stream by a
   specific amount.  Application of <gain> removes any previous
   connection AGC setting used by the <agc> element.

   Attributes:

      id: an optional identifier that may be referenced elsewhere for
      sending events to the gain primitive.

      incr: an increment, expressed in dB, that will be used to adjust
      the gain when "louder" and "softer" events are received.  Default
      is 3 dB.

      amt: a specific gain to apply specified in dB.  Mandatory.

   Events:

      mute: self-explanatory.

      unmute: self-explanatory.

      reset: sets the gain to zero dB.

      louder: makes the audio on a stream louder.

      softer: makes the audio on a stream quieter.

      amt: sets the gain to the specified value between -96 dB and 96
      dB.

9.9.3.  <agc>

   Automatic gain control MAY be used to have a media server
   automatically adjust the gain of a media stream.  Application of
   <agc> removes any previous connection gain setting used by the <gain>
   element.

Top      Up      ToC       Page 87 
   Attributes:

      id: an optional identifier that may be referenced elsewhere for
      sending events to the gain primitive.

      tgtlvl: the desired target level for AGC, specified in dBm0 with a
      valid range of -40 to 0.  Mandatory.

      maxgain: an optional attribute used to specify the maximum gain
      that AGC will apply, specified in dBm0 with a valid range of 0 to
      40, with a default of 10.

   Events:

      mute: self-explanatory.

      unmute: self-explanatory.

9.9.4.  <gate>

   The <gate> element is a simple filter that will pass or halt media,
   regardless of the format of the media stream, based on the events it
   receives.  <gate> shares the same mute and unmute events for
   compatibility with the gain primitives <gain> and <agc>.

   Attributes:

      id: an optional identifier that may be referenced elsewhere for
      sending events to the gate primitive.

      initial: the values "pass" and "halt" define whether media is
      initially allowed to pass.  Default is to pass.

   Events:

      mute: halts media flow through the primitive.

      unmute: allows media to pass through the primitive.

9.9.5.  <clamp>

   This element MAY be used to filter DTMF tones from a media stream.
   Media other than DTMF tones is passed unchanged.

   Attributes:

      id: an optional identifier that may be referenced elsewhere for
      sending events to the clamp primitive.

Top      Up      ToC       Page 88 
   Events:

      none.

9.9.6.  <relay>

   This element is a simple primitive that copies its input to its
   output.

   Attributes:

      id: an optional identifier that may be referenced elsewhere for
      sending events to the relay primitive.

   Events:

      none.

9.10.  MSML Dialog Speech Package

   The MSML speech package defines functionality that MAY be used for
   automatic speech recognition <speech> and extends the <play>
   primitive defined in the MSML Dialog Base Package to include speech
   synthesis.  As such, this package depends on the MSML Dialog Base
   Package.

9.10.1.  <speech>

   The <speech> element activates grammars or user input rules
   associated with speech recognition.  If multiple grammars are
   specified, all are activated.  All active grammars share the same
   timers, recognition attributes, and <noinput> and <nomatch> elements.
   Each grammar may have its own <match> element.

   <speech> terminates if any of the <grammar>, <noinput>, or <nomatch>
   elements are matched the maximum number of times that they are
   allowed.  The number of times they may match may be specified as an
   attribute of <speech> or of the individual child elements.

   Attributes:

      id: an optional identifier that may be referenced elsewhere for
      sending events to the speech primitive.

      noint: specifies a time period during which speech input must be
      started; otherwise, the associated <noinput> element is invoked.

Top      Up      ToC       Page 89 
      norect: specifies a maximum time period during which speech must
      begin to be matched; otherwise, the associated <nomatch> element
      is invoked.

      spcmplt: specifies the length of silence necessary after speech
      before a result will be finalized in the case where there is a
      complete match of an active grammar.  Following the silence, the
      appropriate <match> element will be triggered if the result is
      above the confidence level.  Otherwise, a <nomatch> element will
      be triggered.

      spincmplt: specifies the length of silence necessary after speech
      before a result will be finalized in the case where there is a
      incomplete match of all active grammars.  Following the silence,
      the <nomatch> element will be triggered.

      confidence: the minimum confidence level that the recognizer must
      have to consider a recognition result as matching a grammar.
      Expressed as an integer between 1-100.

      sens: specifies the sensitivity of the recognizer to determine
      whether speech is present.  Lower sensitivity may be required for
      the recognizer to work well in the presence of high background
      noise or line echo.

      starttimer: boolean value that defines whether the no input
      (noint) and no recognition (norect) are started initially.  When
      set to false, the starttimer event must be received in order to
      start them.  Default is "false".

      iterate: specifies the number of times the <grammar>, <noinput>,
      and <nomatch> elements may be executed unless those elements
      specify differently.  The value "forever" may be used to indicate
      that these may be executed any number of times.  Default is once
      '1'.

   Events:

      sens: sets the sensitivity of the recognizer as described above.

      starttimer: starts the no input (noint) and no recognition
      (norect) timers if they have not already been started.  Has no
      effect otherwise.

      terminate: terminates the speech input and assigns values to the
      shadow variables.

Top      Up      ToC       Page 90 
   Shadow Variables:

      speech.end: contains the event that caused the <speech> to
      terminate or is assigned one of "speech.match", "speech.noinput",
      or "speech.nomatch" depending upon which of the corresponding
      elements reached its maximum.

      speech.results: contains the results of a matched grammar.  The
      results are formatted using the Natural Language Semantics Markup
      Language (NLSML) [n4].  When this variable is referenced to return
      results, the results are returned as a separate MIME entity.

   The following sections describe the child elements of <speech>.

9.10.1.1.  <grammar>

   The <grammar> element specifies and activates a speech grammar based
   on Speech Recognition Grammar Specification (SRGS) [n3] XML notation.
   Grammars may be referenced by a URI or defined inline.  Child
   elements of <match> MUST be executed when the specified speech
   grammar is matched.

   Attributes:

      uri: specifies the location of an SRGS grammar when the grammar is
      not defined inline.

      iterate: specifies the number of times the <grammar> may be
      matched.  The value "forever" MAY be used to indicate that
      <grammar> may be matched any number of times.  This value
      overrides any specified in <speech>.  Default is once '1'.

9.10.1.2.  <match>

   <match> is a child of <grammar> and specifies the actions to take
   when the corresponding grammar is matched.

9.10.1.3.  <noinput>

   The <noinput> element is used when speech is being recognized.
   Children of the <noinput> element MUST be executed when speech has
   not been detected and the no input timeout (noint) occurs.

Top      Up      ToC       Page 91 
   Attributes:

      iterate: specifies the number of times the <noinput> may be
      triggered.  The value "forever" may be used to indicate that
      <noinput> may be triggered any number of times.  This value
      overrides any specified in <speech>.  Default is once '1'.

9.10.1.4.  <nomatch>

      The <nomatch> element is used when speech is being recognized.
      Children of the <nomatch> element MUST be executed when it is
      determined that none of the active grammars will match.

      Attributes:

      iterate: specifies the maximum number of times the <nomatch> may
      be triggered.  The value "forever" MAY be used to indicate that
      <nomatch> may be triggered any number of times.  This value
      overrides any specified in <speech>.  Default is once '1'.

9.10.1.5.  <speechexit>

   The <speechexit> element MUST be invoked when the speech input
   completes because one of <grammar>, <noinput>, or <nomatch> occurred
   its maximum number of times.

   Attributes:

      none

9.10.2.  <play>

   The <play> element, as defined in the MSML Dialog Base Package, is
   extended with a new child element for synthesizing speech.  From an
   XML perspective, <tts> is a member of a media substitution group.
   See the schema at the end of this document for details.

   The following sections describe the child elements of <play>.

9.10.2.1.  <tts>

   Contents of the <tts> element are rendered using text-to-speech
   services and must be compliant to the SSML specification [n11].
   Element content MAY be plain text, contain the SSML <speak> element,
   or the uri attribute should identify the location of text to be
   rendered.

Top      Up      ToC       Page 92 
   Attributes:

      uri: identifies the location of the text to be rendered.  The file
      and http schemes are supported.

      iterate: specifies the number of times the text-to-speech block is
      to be rendered.  Defaults to once '1'.

      xml:lang: specifies the language to use when it is not explicitly
      specified as an attribute for <speak>.

9.11.  MSML Dialog Fax Detection Package

   The Fax Detection Package defines primitives that allow a media
   server to provide facsimile detection services.

9.11.1.  <faxdetect>

   Fax tone detection is used to detect the presence of the T.30 Calling
   Tone (CNG) or Called Station Identification (CED) tone in a media
   stream.  Child elements of <faxdetectexit> MUST be executed when a
   CNG tone is detected.

   Attributes:

      id: an optional identifier that may be referenced elsewhere for
      sending events to the faxdetect primitive.

   Events:

      terminate: terminates fax tone detection and assigns values to the
      associated shadow variables.

   Shadow Variables:

      faxdetect.tone: A string that specifies the fax tone type detected
      by the media server.  Values supported SHOULD include "CED",
      "CNG", or empty string.  The empty string MUST be used if fax tone
      detection terminated before detection of a fax tone, resulting in
      execution of the <faxdetectexit> element.

      faxdetect.end: A string value that specifies the reason for
      termination of <faxdetect>.  Values supported SHOULD include
      "faxdetect.complete" (due to detection of CED or CNG tone),
      "faxdetect.failed.noresource" (failed due to lack of resources on
      the media server), "faxdetect.failed" (failed due to any other
      reason) "faxdetect.terminated" (terminated by <dialogend>), or
      undefined.

Top      Up      ToC       Page 93 
9.11.2.  <faxdetectexit>

   The <faxdetectexit> element MUST be invoked when fax detection,
   invoked via <faxdetect>, terminates.  Child elements of
   <faxdetectexit>, <send> and <exit>, allow events to be reported by
   the media server.

   Attributes:

      none

9.12.  MSML Dialog Fax Send/Receive Package

9.12.1.  <faxsend>

   The <faxsend> primitive provides the functionality of a calling fax
   terminal.  This typically means sending a set of pages.  However, it
   can also mean requesting the called terminal to send pages instead
   of, or in addition to, receiving pages.  The fax images to send are
   defined by the <sendobj> elements, described below.

   Requesting the called terminal to send pages happens when the
   <rxpoll> element is included as part of <faxsend>.  This element may
   be included in addition to, or instead of, the <sendobj> element.
   One <sendobj> (at a minimum) or <rxpoll> element must be present.
   When both are present, a media server will first send pages and will
   then poll the other terminal, requesting pages.

   Because fax is a distinct media type, the <faxsend> primitive is not
   expected to interact with other primitives.  Rather, it will interact
   using fax protocols with a remote fax terminal (or gateway) and will
   send requested status events to its invoking environment.  During fax
   operation, shadow variables are used to record the progress and
   parameters of the varying stages of fax operation.

   Status events are requested by including one or more status request
   elements.  These elements correspond to different stages or events in
   fax operation and cause predefined events to be sent to the invoking
   environment when they occur.  Since the only recipient of these
   events is expected to be a fax control agent, requests are simplified
   by associating a predefined namelist of shadow variables with each
   event.  This decision may be revisited to allowed tailored namelists
   based on further implementation experience.  Status requests apply
   both to sending and polling operation.

   Attributes:

      lclid: the identifier that a media server uses to identify itself.

Top      Up      ToC       Page 94 
      minspeed: the minimum acceptable speed to negotiate for the
      operation.

      maxspeed: the maximum speed to negotiate for the operation.  This
      attribute is primarily for testing purposes.

      ecm: specifies whether Error Correction Mode (ECM) is allowed to
      be used if supported by the remote terminal.  Defaults to "true".

   Events:

      terminate: terminates the fax send operation.

   Shadow Variables:

      fax.rmtid: the identifier of the remote fax terminal.

      fax.rate: the negotiated speed for the operation.

      fax.resolution: identifies the resolution of the image.  Both
      metric- and inch-based resolutions are defined.  Metric-based
      resolutions are 75x75, 150x150, 204x98, 204x196, 204x391, and
      408x391.  Inch-based resolutions are 200x200, 300x300, 400x400,
      and 600x600.

      fax.pagesize: identifies the negotiated page size.  Metric sizes
      are "A3", "A4", "A5", "A6", and "B4".  Inch-based page sizes are
      "Letter" and "Legal".

      fax.encoding: identifies the image encoding utilized.  Valid
      values are "MH", "R", "MMR", and "JPEG".

      fax.ecm: identifies whether ECM operation was used.

      fax.pagebadlines: the number of bad lines in a page.

      fax.objbadlines: the number of bad lines in an object.

      fax.opbadlines: the number of bad lines in an operation.

      fax.objuri: the objuri of the current object.

      fax.resendcount: the number of pages resent due to errors.

      fax.totalpages: the number of pages processed or stored.

      fax.totalobjects: the count of the objects used in the operation.

Top      Up      ToC       Page 95 
      fax.duration: the duration of the operation expressed as a
      duration in seconds and milliseconds (e.g., "23s250ms").

      fax.result: contains the reason that caused the fax operation to
      complete.  When the operation completes successfully, the value
      will be assigned "fax.success".  Other values include
      "fax.partial", "fax.nofax", "fax.remotedisconnect",
      "fax.uri.access.error", and "fax.invalid.startpage".

   The following sections describe the child elements of <faxsend>.

9.12.1.1.  <sendobj>

   <sendobj> is used to define a fax transmission.  There MAY be
   multiple instances of the element, which will be transmitted in
   order.

   Attributes:

      objuri: a URI that points to the fax image that will be
      transmitted.  Mandatory.

      startpage: the first page of a multi-page objuri to send.

      pagecount: page count.

9.12.1.2.  <hdrfooter>

   <hdrfooter> describes the header/footer that a media server MAY put
   on pages.  The header or footer may be defined as the content of the
   <format> child element.  The <format> element is only allowed if the
   type attribute has a value of "header" or "footer".

   Attributes:

      type: specifies whether a header or a footer should be put on
      pages and identifies the source of the header or footer.  The
      following enumerated values may be used:

         "header" indicates that the media server should put a header on
                  pages using the contents of the <format> element.

         "nohdr"  indicates that there should be no header or footer.

         "footer" indicates that the media server should put a footer on
                  pages using the contents of the <format> element.

Top      Up      ToC       Page 96 
      style: defines the style of insertion onto a fax page that a media
      server should use for the header or footer.  Valid styles are
      "append", "overlay", or "replace".

   <format> is a child of the <hdrfooter> element that defines the style
   format to be used for the header or footer.  It uses a "C" language
   style format statement (as shown below) to define the contents and
   layout of the header or footer.

      code    length   name              format
       %a       3     day of week       3-character abbreviation
       %d       2     date              01-31
       %m       2     month             01-12
       %y       2     year              00-99
       %Y       4     year              0000-9999
       %I       2     12 hour           01-12
       %H       2     24 hour           00-23
       %M       2     minute            00-59
       %S       2     seconds           00-59
       %p       2     AM/PM             AM or PM
       %P       2     page number       01-99
       %T       2     total pages       01-99
       %l       20    local ID (sender) 0-9, + or spaces
       %r       20    remote ID (rcvr)  0-9, + or spaces
       %%       1     percent           display % in header/ftr

9.12.1.3.  <rxpoll>

   <rxpoll> provides the information necessary for a receive polling
   operation to occur.  The object(s) to be received are defined by one
   or more <rcvobj> elements.  The <rcvobj> is defined further under the
   child elements of <faxrcv>.  The <rxpoll> element MAY also include a
   description of the header/footer that a media server SHOULD put on
   received pages.  The <hdrfooter> element and its usage is described
   above.

   Attributes:

      rmtid: specifies the identifier of the remote fax terminal that is
      to be associated with a polling operation.  A media server MUST
      NOT execute a polling operation unless the value of rmtid matches
      that of the connected remote machine.  Mandatory.

Top      Up      ToC       Page 97 
9.12.1.4.  <faxstart>

   The <faxstart> element requests that an event be sent when fax
   operation has begun.  When triggered, the following will be executed:

   <send target="source" event="fax.start"/>

9.12.1.5.  <faxnegotiate>

   The <faxnegotiate> element requests that an event be sent when a
   negotiation has been completed.  Multiple events MAY be sent each
   time a Digital Command Signal (DCS) frame is sent or received.  When
   triggered, the following will be executed:

      <send target="source" event="fax.negotiate"
         namelist="fax.rmtid
            fax.rate
            fax.resolution
            fax.pagesize
            fax.encoding
            fax.ecm"/>

9.12.1.6.  <faxpagedone>

   The <faxpagedone> element requests that an event be sent when a page
   has been sent or received.  When triggered, the following will be
   executed:

      <send target="source" event="fax.pagedone"
            namelist="fax.resolution
            fax.pagesize
            fax.encoding
            fax.pagebadlines
            fax.resendcount"/>

9.12.1.7.  <faxobjectdone>

   The <faxobjectdone> element requests that an event be sent when an
   objuri has been completed.  When triggered, the following will be
   executed:

      <send target="source" event="fax.objectdone"
            namelist="fax.objuri
            fax.objbadlines
            fax.resendcount
            fax.totalpages
            fax.result"/>

Top      Up      ToC       Page 98 
9.12.1.8.  <faxopcomplete>

   The <faxopcomplete> element requests that an event be sent when an
   operation has been completed.  When triggered, the following will be
   executed:

      <send target="source" event="fax.opcomplete"
            namelist="fax.totalpages
            fax.opbadlines
            fax.resendcount
            fax.totalobjects
            fax.duration
            fax.result"/>

9.12.1.9.  <faxpollstarted>

   The <faxpollstarted> element requests that an event be sent when a
   polling operation has started.  When triggered, the following will be
   executed:

      <send target="source" event="fax.opcomplete"
            namelist="fax.rmtid
            fax.rate
            fax.resolution
            fax.pagesize
            fax.encoding
            fax.ecm"/>

9.12.2.  <faxrcv>

   The <faxrcv> primitive provides the functionality of a called fax
   terminal.  Typically this type of operation is to receive pages.
   However, it can include sending pages instead of, or in addition to,
   receiving them.  The fax objects to receive are defined by the
   <rcvobj> elements, described below.

   A media server SHOULD send pages as a polled terminal when the
   <txpoll> element is included as part of <faxrcv>.  This element may
   be included in addition to, or instead of, the <rcvobj> element.  One
   <rcvobj> or <txpoll> element must be present.  When both are present,
   a media server SHOULD first receive pages and will then allow the
   other terminal to poll the media server, requesting pages.

   Because fax is a distinct media type, the <faxrcv> primitive is not
   expected to interact with other primitives.  Rather, it will interact
   using fax protocols with a remote fax terminal and will send

Top      Up      ToC       Page 99 
   requested status events to its invoking environment.  During fax
   operation, shadow variables are used to record the progress and
   parameters of the varying stages of fax operation.

   Status events are requested by including one or more status request
   elements.  These elements correspond to different stages or events in
   fax operation and cause predefined events to be sent to the invoking
   environment when they occur.  Since the only recipient of these
   events is expected to be a fax control agent, requests are simplified
   by associating a predefined namelist of shadow variables with each
   event.  This decision may be revisited to allowed tailored namelists
   based on further implementation experience.  Status requests apply
   both to receiving and polling operation.

   Attributes:

      id: an optional identifier that may be referenced elsewhere for
      sending events to the faxrecv primitive.

      lclid: the identifier that a media server uses to identify itself.

      ecm: specifies whether ECM mode is allowed to be used if supported
      by the remote terminal.  Defaults to "true".

   Events:

      terminate: terminates the fax reception operation.

   Shadow Variables:

      <faxrcv> supports the same set of shadow variables as <faxsend>

      The following sections describe the child elements of <faxrcv>.

      In addition to the elements defined below, <faxrcv> MAY also have
      the following child elements, which were defined under <faxsend>:

      o  <hdrfooter>
      o  <faxstart>
      o  <faxnegotiate>
      o  <faxpagedone>
      o  <faxobjectdone>
      o  <faxopcomplete>
      o  <faxpollstarted>

   Their meaning and usage are the same as previously defined.

Top      Up      ToC       Page 100 
9.12.2.1.  <rcvobj>

   <rcvobj> is used to define fax objects that a media server will
   receive.  There may be multiple instances of the element, which will
   be used in order.

   Attributes:

      objuri: a URI that points to the location that a received image is
      to be stored.  Mandatory.

      maxpages: the maximum number of pages that will be stored in
      objuri.

9.12.2.2.  <txpoll>

   <txpoll> provides the information for a polling operation to occur as
   part of a fax receive operation.  An object or multiple objects to be
   sent may be supplied by one or more <sendobj> elements.  In the event
   of multiple occurrences, a media server MUST select the <sendobj>
   element whose rmtid attribute matches that of the remote terminal.

   The <sendobj> element was defined previously as a child element of
   <faxsend>.  The <txpoll> element is extended with an rmtid attribute
   that specifies the identifier of the remote fax terminal and is used
   to select the specific <sendobj> to send.

   A media server SHOULD put a header/footer on transmitted pages based
   on any <hdrfooter> element included as part of <txpoll>.

   Attributes:

      rmtid: specifies the identifier of the remote fax terminal that is
      to be associated with a polling operation.  A media server MUST
      NOT execute a polling operation unless the value of rmtid matches
      that of the connected remote machine.  Mandatory.

10.  MSML Audit Package

10.1.  MSML Audit Core Package

   This section describes the MSML Audit Core Package that MAY be
   implemented to support auditing services.

   Audit requests and results may vary based on the information being
   audited.  The MSML Audit Core Package specifies the framework to send
   audit request, defines a state list, and builds audit results.  The

Top      Up      ToC       Page 101 
   additional audit packages define package specific state lists and
   associated audit result content.  The additional audit packages MUST
   be defined within the framework specified by the Audit Core Package.

10.1.1.  <audit>

   The <audit> element is an optional child element of <msml>, which MAY
   be used by MSML clients to perform state auditing of current media
   resources allocated and in use by the media server.  The requested
   state information is returned in an MSML response.

   Attributes:

      queryid: the identifier of the MSML object being queried by the
      MSML client.  Mandatory.  Supported object types: conference or
      connection.  Wildcards are allowed.

      statelist: a list of one or more state parameters that are being
      queried.  Optional.  If not present, the media server SHOULD
      return the id of audited object only.  Each object type may
      contain a set of states.  If the "statelist" contains any state
      that does not match the audited object type, the request MUST be
      rejected.

      mark: in the case of an error, the value of the mark attribute
      from the last successfully executed element that included the mark
      attribute.

   State Parameters:

      The state parameter MUST be named using a dot-notation format
      "audit.X.a.b.c...", where X is the mandatory field that indicates
      the class name of the object (e.g., "conf" or "conn") and the
      "a.b.c..."  is the optional field used to describe the actual name
      of the state parameter in a hierarchical manner.  The wildcard "*"
      MAY be used as part of a state name; however, it MUST only be used
      in the last field of the dot-notation (e.g., "audit.conf.*" is
      valid, but "audit.conf.*.a" is invalid).  When a wildcard is used,
      it is equivalent to querying all the states below the specified
      level.  Each field (e.g., within "a.b.c...") will result in
      individual element names <a>, <b>, and <c> in the audit result to
      contain corresponding state value.  The parent/child relationship
      between these elements follows the hierarchy of the state name
      (i.e., <c> is child element of <b>, and <b> is child element of
      <a>).

Top      Up      ToC       Page 102 
10.1.2.  <auditresult>

   The <auditresult> element is an optional child element of <result>,
   which MUST be used by the media server to return the audit result.  A
   specific instance of the <auditresult> element contains the state
   information of a single active object.  Therefore, if multiple
   objects are within the scope of the audit request, then one
   <auditresult> element per object MUST be present.  A zero occurrence
   of <auditresult> element indicates that there are no active resources
   within the scope of the audit request.

   Attributes:

      targetid: the identifier of a conference or connection.
      Mandatory.  Wildcard is not allowed.

   The <auditresult> may contain child element(s) that return additional
   state information, corresponding to the "statelist" attribute in the
   <audit> request.  The child element names correspond to the fields of
   the state parameter name (e.g., "a.b.c..."), following the same
   hierarchical structure.

10.2.  MSML Audit Conference Package

   This section describes the MSML Audit Conference Package that MUST be
   implemented to support auditing of conference services.  The MSML
   Audit Conference Package follows the framework specified by the MSML
   Audit Core Package.  This package defines the state parameter list
   and audit result for conference auditing.

10.2.1.  State Parameters

   All conference state parameter names MUST be prefixed by
   "audit.conf".

      confconfig: query the conferences general configuration.

      confconfig.audiomix: query the audio mixer's general configuration
      in the conference.

      confconfig.audiomix.asn: query the current ASN setting in the
      audio mixer.

      confconfig.audiomix.n-loudest: query the current n-loudest setting
      in the audio mixer.

      confconfig.videolayout: query the video layout's general
      configuration in the conference.

Top      Up      ToC       Page 103 
      confconfig.videolayout.root: query the root window setting of the
      video layout.

      confconfig.videolayout.selector: query the video stream selector
      setting of the video layout.

      confconfig.controller: query who is the conference controller.

      dialog: query the active dialog information on the conference.
      See MSML Audit Dialog Package for details.

      stream: query the active stream information on the conference.
      See MSML Audit Stream Package for details.

10.2.2.  <auditresult>

   The <auditresult> attribute of "targetid" is required to indicate
   results for auditing a conference.

   The <auditresult> element may optionally contain the following child
   elements, returning additional conference state information, if
   corresponding states are queried and available.

10.2.2.1.  confconfig

   The <confconfig> element is used to return the general configuration
   state(s) of a conference, using the following attributes.

   Attributes:

      deletewhen: as defined by <createconference> element in MSML
      Conference Core Package.

      term: as defined by <createconference> element in MSML Conference
      Core Package.

10.2.2.2.  confconfig.audiomix

   The <audiomix> element contains the general audio mixer configuration
   using the following attributes.

   Attributes:

      id: as defined by <audiomix> element in MSML Conference Core
      Package.

      samplerate: as defined by <audiomix> element in MSML Conference
      Core Package.

Top      Up      ToC       Page 104 
10.2.2.3.  confconfig.audiomix.asn

   The <asn> element contains the current ASN setting of an audio mixer,
   if ASN is enabled.  The state values are included in the following
   attributes.

   Attributes:

      ri: as defined by <asn> element in MSML Conference Core Package.

      asth: as defined by <asn> element in MSML Conference Core Package.

10.2.2.4.  confconfig.audiomix.n-loudest

   The <n-loudest> element contains the current n-loudest setting of the
   audio mixer.  The state values are included in the following
   attributes.

   Attributes:

      n: as defined by <n-loudest> element in MSML Conference Core
      Package.

10.2.2.5.  confconfig.videolayout

   The <videolayout> element contains the general video layout
   configuration using the following attributes.

   Attributes:

      id: as defined by <videolayout> in MSML Conference Core Package.

      type: as defined by <videolayout> in MSML Conference Core Package.

10.2.2.6.  confconfig.videolayout.root

   The <root> element is used to contain root window settings.

   Attributes:

      size: as defined by <root> element in MSML Conference Core
      Package.

      backgroundcolor: as defined by <root> element in MSML Conference
      Core Package.

      Backgroundimage: as defined by <root> element in MSML Conference
      Core Package.

Top      Up      ToC       Page 105 
10.2.2.7.  confconfig.videolayout.selector

   The <selector> element is used to contain selector settings.

   Attributes:

      id: as defined by <selector> element in MSML Conference Core
      Package.

      method: as defined by <selector> element in MSML Conference Core
      Package.

      status: as defined by <selector> element in MSML Conference Core
      Package.

      blankothers: as defined by <selector> element in MSML Conference
      Core Package.

      si: as defined by <selector> element in MSML Conference Core
      Package when selector method is "vas".

      speakersees: as defined by <selector> element in MSML Conference
      Core Package when selector method is "vas".

10.2.2.8.  confconfig.controller

   The <controller> element is used to return the conference controller
   id in its content.  The conference controller is the SIP dialog that
   carries the <createconference> request.  The return value is the MSML
   connection id.

10.2.2.9.  dialog

   If conference dialog state is queried, the audit result is returned
   using the <dialog> element as specified in the MSML Audit Dialog
   Package.

10.2.2.10.  stream

   If conference stream state is queried, the audit result is returned
   using the <stream> element as specified in the MSML Audit Stream
   Package.

Top      Up      ToC       Page 106 
10.3.  MSML Audit Connection Package

   This section describes the MSML Audit Connection Package that MAY be
   implemented to support auditing connection services.  The MSML Audit
   Connection Package follows the framework specified by the MSML Audit
   Core Package.  This package defines the state parameter list and
   audit result for connection auditing.

10.3.1.  State Parameters

   Connection state parameter names are prefixed by "audit.conn".

      sipdialog: queries the identifier of the SIP dialog with which the
      connection is associated.

      sipdialog.localseq: queries one of the SIP dialog states - local
      sequence number.

      sipdialog.remoteseq: queries one of the SIP dialog states - remote
      sequence number.

      sipdialog.localURI: queries one of the SIP dialog states - local
      URI.

      sipdialog.remoteURI: queries one of the SIP dialog states - remote
      URI.

      sipdialog.remotetarget: queries one of the SIP dialog states -
      remote target.

      sipdialog.routeset: queries one of the SIP dialog states - route
      set.

      localsdp: queries the local SDP body of the connection.

      remotesdp: queries the remote SDP body of the connection.

      dialog: queries the active dialog information on the connection.
      See MSML Audit Dialog Package for details.

      stream: queries the active stream information on the connection.
      See MSML Audit Stream Package for details.

10.3.2.  <auditresult>

   The <auditresult> attribute "targetid" MUST specify a connection
   identifier for a connection result.

Top      Up      ToC       Page 107 
   The <auditresult> element MAY contain the following child elements
   optionally to return additional connection state information if the
   corresponding states are queried and are available.

10.3.2.1.  sipdialog

   The <sipdialog> element contains the associated SIP dialog
   information.  The SIP dialog ID information is returned using the
   following attributes.

      Attributes:

         callid: call-ID value as defined in [n1].  Mandatory.

         localtag: local-tag value as defined in [n1].  Mandatory.

         remotetag: remote-tag value as defined in [n1].  Mandatory.

   This element can contain the following child elements optionally to
   return additional SIP dialog state information to the client if the
   corresponding states are queried and available.

10.3.2.2.  sipdialog.localseq

   The <localseq> element contains the local sequence number.  The local
   sequence number is one of the SIP dialog states as defined in [n1].

10.3.2.3.  sipdialog.remoteseq

   The <remoteseq> element contains the remote sequence number.  The
   remote sequence number is one of the SIP dialog states as defined in
   [n1].

10.3.2.4.  sipdialog.localuri

   The <localuri> element contains the local URI value.  The local URI
   is one of the SIP dialog states as defined in [n1].

10.3.2.5.  sipdialog.remoteuri

   The <remoteuri> element contains the remote URI value.  The remote
   URI is one of the SIP dialog states as defined in [n1].

10.3.2.6.  sipdialog.remotetarget

   The <remotetarget> element contains the remote target value.  The
   remote target is one of the SIP dialog states as defined in [n1].

Top      Up      ToC       Page 108 
10.3.2.7.  sipdialog.routeset

   The <routeset> element contains the route-set value (an ordered list
   of URIs separated by comma).  The route set is one of the SIP dialog
   states as defined in [n1].

10.3.2.8.  localsdp

   The <localsdp> element contains the local SDP body.

10.3.2.9.  remotesdp

   The <remotesdp> element contains the remote SDP body.

10.3.2.10.  dialog

   If the connection dialog state is queried, the audit result returns
   the queried information using the <dialog> element, as specified in
   the MSML Audit Dialog Package.

10.3.2.11.  stream

   If the connection stream state is queried, the audit result returns
   the queried information using the <stream> element, as specified in
   the MSML Audit Stream Package.

10.4.  MSML Audit Dialog Package

   This section describes the MSML Audit Dialog Package that MAY be
   implemented to support auditing dialogs.  The MSML Audit Dialog
   Package follows the framework specified by the MSML Audit Core
   Package.

   The MSML Audit Dialog Package must be used together with either the
   MSML Audit Conference Package or MSML Audit Connection Package, since
   the dialogs are applicable to conferences or connections.

10.4.1.  State Parameters

   Dialog state parameter names are prefixed by "dialog".  Since this
   package must be used together with the MSML Audit Conference Package
   or MSML Audit Connection Package, the complete dialog state name must
   be prefixed by "audit.conf.dialog" or "audit.conn.dialog", depending
   on the context within which the dialog state is queried.

   dialog: queries the number of active dialog(s) running on the target
   (a conference or connection); basic dialog information will be
   returned.

Top      Up      ToC       Page 109 
   dialog.duration: queries the amount of time a dialog has been
   running.

   dialog.primitive: queries the media primitive currently being
   executed by the dialog.

   dialog.controller: queries the dialog controller.

10.4.2.  <dialog>

   The <dialog> element is a child element of <auditresult>, which
   contains the active dialog information on the target identified by
   the attribute "targetid" of the <audioresult> element.

   Basic dialog information is returned using the following attributes.

   Attributes:

      src: as defined by the <dialogstart> element in the MSML Dialog
      Core Package.

      type: as defined by the <dialogstart> element in the MSML Dialog
      Core Package.  Mandatory.

      name: as defined by the <dialogstart> element in the MSML Dialog
      Core Package.  Mandatory.

   This element may contain the following child elements optionally to
   return additional dialog information if the corresponding state
   parameter has been queried and the state value is available.

10.4.2.1.  <duration>

   The <duration> element returns the duration that a dialog has been
   running on the specified target.  The duration value is included in
   the element content.  It is a positive integer value (in unit of
   seconds).

10.4.2.2.  <primitive>

   The <primitive> element returns the currently active media primitive
   in its content.  The active media primitive is the primitive that is
   currently being executed.  Possible return values are play, dtmf,
   collect, dtmfgen, tonegen, record, or none.

Top      Up      ToC       Page 110 
10.4.2.3.  <controller>

   The <controller> element returns the dialog controller id in its
   content.  The dialog controller is the SIP dialog that carries the
   <dialogstart> request.  The returned value is the MSML connection id.

10.5.  MSML Audit Stream Package

   This section describes the MSML Audit Stream Package that MAY be
   implemented to support auditing stream.  The MSML Audit Stream
   Package follows the framework specified by the MSML Audit Core
   Package.

   The MSML Audit Stream Package MUST be used together with either the
   MSML Audit Conference Package or the MSML Audit Connection Package,
   since the stream is applicable between conferences, between
   connections, or between conferences and connections.

10.5.1.  State Parameters

   Stream state parameter names are prefixed by "stream".  Since this
   package must be used together with the MSML Audit Conference Package
   or MSML Audit Connection Package, the complete stream state name must
   be prefixed by "audit.conf.stream" or "audit.conn.stream", depending
   on the context within which the stream state is queried.

   stream: queries the number of active streams created on the audited
   object; basic stream information will be returned.

   stream.clamp: queries the clamping status.

   stream.gain: queries the gain control information.

   stream.visual: queries the visual setting.

10.5.2.  <stream>

   The <stream> element is a child element of <auditresult> and contains
   the active stream information on the target identified by the
   attribute "targetid" of the <audioresult> element.

   Basic stream information is returned using the following attributes.

   Attributes:

      joinwith: an identifier of either a connection or a conference
      with which the audited object is joined.  Mandatory.  Wildcard is
      not allowed.

Top      Up      ToC       Page 111 
      media: as defined by the <stream> element in the MSML Conference
      Core Package.  Mandatory.

      dir: direction of stream, from audited target perspective, "from"
      or "to".  Mandatory.

      compressed: as defined by the <stream> element in the MSML
      Conference Core Package.

      display: as defined by the <stream> element in the MSML Conference
      Core Package.

      override: as defined by the <stream> element in the MSML
      Conference Core Package.

      preferred: as defined by the <stream> element in the MSML
      Conference Core Package.

   This element MAY contain the following child elements that optionally
   return additional stream information, if the corresponding state
   parameter is queried and the state value is available.

10.5.2.1.  <clamp>

   The <clamp> element is included if stream clamping is active.  The
   currently active clamping state values are returned using the
   attributes as defined by the <clamp> element in the MSML Conference
   Core Package.

10.5.2.2.  <gain>

   The <gain> element is included if stream gain is active.  The current
   gain control state values are returned using the attributes as
   defined by the <gain> element in the MSML Conference Core Package.

10.5.2.3.  <visual>

   The <visual> element is included if stream visual display is active.
   The current visual display settings are returned using the attributes
   as defined by the <visual> element in the MSML Conference Core
   Package.

11.  Response Codes

   Response codes are used to indicate reasons for failures as well as
   completion status.  The appropriate code and description must be
   passed to the invoking environment on failure.

Top      Up      ToC       Page 112 
   The response codes defined in this section are returned as the value
   of the response attribute to the <result> element.  Some values may
   also be returned as part of a namelist to an "msml.dialog.exit" event
   generated when an executing MSML dialog fails.

   Informational (1xx)

      Reserved for future use

   Success (200)

      200  OK

   Request Error (4xx)

      400  Bad Request
      401  Unknown Element
      402  Unsupported Element
      403  Missing mandatory element content
      404  Forbidden element content
      405  Invalid element content
      406  Unknown attribute
      407  Attribute not supported
      408  Missing mandatory attribute
      409  Forbidden attribute is present

      410  Invalid attribute value

      420  Unsupported media description language
      421  Unknown media description language
      422  Ambiguous request (both URI and inline description)
      423  External document fetch error
      424  Syntax error in foreign language
      425  Semantic error in foreign language
      426  Unknown error executing foreign language

      430  Object does not exist
      431  Object instance name already used
      432  Conference name already in use
      433  reserved
      434  External document fetch error

      440  Cannot join objects of the specified class
      441  Objects have incompatible media types
      442  reserved
      443  reserved
      444  Number of media inputs exceeded

Top      Up      ToC       Page 113 
      450  Objects have incompatible media formats
      451  Incompatible media stream format

   Server Error (5xx)

      500  Internal media server error
      503  Service Unavailable
      510  Not in service
      511  Service Unavailable
      520  No resource to fulfill request
      521  Internal limit exceeded



(page 113 continued on part 5)

Next RFC Part