Subject: Re: Format of Packages

From: Brian Rosen <[email-masked]>
Date: Fri, 20 Aug 1999 18:05:42 -0400

I started putting this into the document.

I have quite a few comments, but most of them don't change the result much.

1. I've reworded most of the text to make it fit with the rest of the
protocol document

2. I've changed the "short name" designator.  I'm using "PackageID",
"PropertyID", "EventID", "ParameterID" instead.

3. IDs are defined as up to 64 characters, alphas and digits plus
underscore.  This corresponds to the definition of "NAME" in the ABNF.

4. I'm totally puzzled by the eventConfiguration stuff.
I don't know what it does, and why the EventDescriptor in an
Add/Move/Modify looks different from the EventDescriptor in
a Notify.  I can see that in some cases parameters might be
different, but not in all cases.  I can see having to specify "IN" and "OUT"
for parameters - whether they can appear in the Add/Move/Modify or whether
they can appear in Notify.  Is that
what you meant?  If so, the DESCRIPTION of the package should
specify IN, OUT or IN/OUT for each parameter, and that is what you do.

5. Statistics don't have parameters.  I don't see why you would
ever need such a thing.  If you do, bring it up on the list and supply a
decent example.  You specify units, not values.

6. Defining new behavior in the package description is not,
IMO the place to do it.  For those of you who haven't looked at the text, it
mandates that EVERY event have a parameter that specifies whether the event
rearms automatically or not.  I believe this idea requires a full
discussion.  I personally suspect that if this is desired capability, an
event parameter is NOT the way to do it, but let's first decide if we need
it at all.  At the moment, events rearm.  If you want to turn them off,
change the Event Descriptor.  An embedded event descriptor can do this
automatically.

Here is my version of what is left:
A Package shall contain the following sections:
1. Full Package name, PackageID, and description.  PackageIDs shall be a
string of up to 64 characters, containing no spaces, and consisting of
alphas and digits, and possibly including the special character underscore
("_").  The PackageID is used in a TerminationID.  The Package name is
descriptive only.
2. Properties defined by the package, specifying a Property name,
PropertyID, possible values, and description.  PropertyID shall be a string
of up to 64 characters, containing no spaces, and consisting of alphas and
digits, and possibly including the special character underscore ("_").  The
PropertyID is used in a TerminationID.  The Property name is descriptive
only.
3. Events defined by the package, specifying an Event name, EventID,
possible Parameter names, ParameterIDs and possible values for each
parameter.  EventIDs and ParameterIDs shall be a string of up to 64
characters, containing no spaces, and consisting of alphas and digits, and
possibly including the special character underscore ("_").  EventIDs and
PropertyIDs are used in an Event Descriptor.  The Event name is descriptive
only.
4. Signals defined by the package, specifying a Signal name, SignalID,
possible Parameter names, ParameterIDs and possible values for each
parameter. SignalID and ParameterIDs shall be a string of up to 64
characters, containing no spaces, and consisting of alphas and digits, and
possibly including the special character underscore ("_").SignalID and
PropertyIDs are used in a Signal Descriptor.  The Signal name is descriptive
only.
5. Statistics defined by the package, specifying a Statistic name,
StatisticID, units, and description. StatisticID shall be a string of up to
64 characters, containing no spaces, and consisting of alphas and digits,
and possibly including the special character underscore ("_").  The
StatisticID is used in a Statistics Descriptor.  The Statistic name is
descriptive only.

12.2 Example Package

Section 1. DTMF Package
PackageID: dtmf
Description: This package is used to detect and generate tones on the analog
trunk or line connection on a media gateway.
Section 2. Properties
2.1     Media Gateway Country Code
PropertyID: mgcountry
Possible values: 3 character string
Description: Country code from ITU??????
Section 3. Events
3.1     ToneDetected

EventID: tonedt
Parameters:
3.1.2 Stream ID
ParameterID: streamid
Direction: IN
Possible Values: Integer in the range of 0-256
Description: id of audio stream to detect tones on.
3.1.3 Detected Tone List
ParameterID: listoftones
Direction: IN/OUT
Possible Values: a string (max 64 characters) consisting of the characters
'0','1','2','3','4','5','6','7','8','9','*','#','A','B','C','D','X','/'
'X' represents 0 to 9.
Description: one or more dtmf tones (to be) detected, separated by '/'
Example: "0/1/2/3/4/5/6/7/8/9/*/#".
3.1.4 Event Type
ParameterID: eventtype
Direction: OUT
Possible Values:
"MULTI": multiple digits have been accumulated and sent.
             "START": one tone start detected
"LONG":  one tone has been detected for more than 2 seconds
"END':  one tone end detected.
Description: What kind of detection has occurred
3.2.2 Duration
ParameterID: duration
Direction: OUT
Possible Values: Integer (32 bit)
Description:  When eventtype is END, the length of the tone detected

Description: Detects a DTMF tone.  Reports stream and which tone was
detected.
3.2     SilenceDetected
EventID: silencedt
Parameters:
3.2.1 Stream ID
ParameterID: streamid
Direction: IN
Possible Values: Integer in the range of 0-256
Description: id of audio stream to detect tones on.
3.2.2 Duration
ParameterID: duration
Direction: IN/OUT
Possible Values: Integer (32 bit)
Description:  How many ms to wait before trigger
Description: This event is triggered after a period of silence has occurred.
Section 4. Signals
4.1 Play Tones
SignalID: playtone
Parameters:
4.1.1 Stream ID
ParameterID: streamid
Direction: IN
Possible Values: Integer in the range of 0-256
Description: id of audio stream to play tones on.
4.1.2 Tone List
ParameterID: listoftones
Direction: IN/OUT
Possible Values: a string (max 64 characters) consisting of the characters
'0','1','2','3','4','5','6','7','8','9','*','#','A','B','C','D','X','/'
'X' represents 0 to 9.
Description: one or more dtmf tones to be played, separated by '/'
Example: "0/1/2/3/4/5/6/7/8/9/*/#".
4.1.3 Signal Type
ParameterID: signaltype
Possible values:
                "BR" brief duration (provisioned)
                "ON" Play until instructed to stop
                "TO" Play until timed out
4.1.4 Duration
ParameterID: duration
Direction: IN/OUT
Possible Values: Integer (32 bit)
Description:  If signalType is TO, How many ms to play each tone

> -----Original Message-----
> From: Mike Kallas [mailto:[email-masked]]
> Sent: Wednesday, August 11, 1999 11:38 PM
> To: [email-masked]
> Subject: Format of Packages
>
>
> The following is a TD I generated at the ITU meeting in
> Berlin last week. It
> is a proposal on how to generate and register megaco/H.248
> packages. We
> agreed to put it on the megaco list for comments. The ipphone
> packages are
> being reedited using this format. I am rewriting the generic
> packages using
> this format. Please comment.
>
> Mike
>
>
>
>
> ITU meeting Berlin              TD 16
>
> Author: Mike Kallas
>
> Purpose: Describe a format to describe packages for H.248 /
> Megaco protocol.
> Also describes how to register package names with IANA.
>
> Status: Preliminary draft, for information only
>
> This document was created to reconcile different package
> format proposal
> from MGCP, IPPHONE and APC-1629.
>
>
>
>
> A)      Package Description Format
>
> A Package will contain the following sections:
>
> x.1 Package name, short name, and description
>
> (short names are up to 20 characters)
>
> x.2 Gateway Properties audit
>
>         x.2.x Property name, short name, possible values,
> description. This
> section describes the ??? in the Audit command
>
> x.3 Events
>
>         x.3.1 Event Configuration
>
>         x.3.1.y Event name, short name, configuration
> parameters (described
> with short name), description. This section describes the
> eventdescriptor in
> the Modify command. eventDescriptor should be renamed
> eventConfigurationDescriptor. eventconfigurationdescriptor
> would list the
> events to be detected and configures the detection process.
>
>                                 eventconfigurationdescriptor already
> describes the way package name, event name, and parameters
> are filled. There
> is no need for syntax in the packages document. Syntax would
> be important if
> the package is intended to work outside megaco (for example
> H.323 Gatekeeper
> to H.323 telephone set) ??? let's ponder.
>
>                 Clearbufferedevents y / n
>
>         Every event has to support a parameter called
> "rerequest". If the
> value of "rerequest" is "Y", the event is requested by the
> MGC every time or
> else it would not be sent. If the value of "rerequest" is
> 'N', the event is
> requested once and notification occures every time it occurs.
> Notification
> uses the same "RequestId"
>
>         x.3.2 Observed Events
>
>         x.3.2.y Event name , short name, Event parameters
> (described with
> short name), description. This section describes the
> observedEventDescriptor
> in the Notify command. observedEventDescriptor is a list of
> accumulated
> events sent from the MG to the MGC. The event names in this
> section should
> match the events in section x.3.1.
>
> x.4 Signals
>
>         x.4.x Signal name, short name, Signal parameters
> (described with
> short name), description. . This section describes the
> signaldescriptor in
> the Modify command
>
> x.5 Statistics
>
>         x.5.1 Statistics Request
>
>                 x.5.1.y Statistic name, short name, request parameters
> (described with short name), description
>
>         x.5.2 Statistics Report
>
>                 x.5.2.y Statistic name, short name, report parameters
> (described with short name), description
>
> Example:
>
> 1.1     DTMF Package
>
> Short name dtmf
>
> This package it used to detect and generate tones on the
> analog trunk or
> line connection on a media gateway.
>
> 1.2 Gateway Properties audit
>
> 1.2.1 Gateway Country Code
>
> Short name mgcountry
>
> Possible values : 3 character string representing the country code.
>
> 1.3 Events
>
> 1.3.1 Event Configuration
>
> 1.3.1.1 ToneDetected
>
> Short name tonedt
>
> Configuration Parameters:
>
> streamid        id of audio stream to detect tones on.
> listoftones a string containing one or more of the dtmftoneid's to be
> detected, seperated by /
>                                 Example: "0/1/2/3/4/5/6/7/8/9/*/#".
> rerequest       'Y' Event has to be requested every time.
>                 'N' Event is requested once and reported multiple time
>                 'STOP' Stop reporting this event
>
> dtmftoneid's:
> '0','1','2','3','4','5','6','7','8','9','*','#','A','B','C','D','X'
> 'X' represents 0 to 9.
>
> 1.3.1.2 SilenceDetected
>
> Short name silencedt
>
> This event is triggered after a period of silence has occurred.
>
> Configuration Parameters:
>
> streamid        id of audio stream to detect tones on.
> duration        Silence duration that would trigger the event in ms.
> rerequest       'Y' Event has to be requested every time.
>                 'N' Event is requested once and reported multiple time
>                 'STOP' Stop reporting this event
>
>
> 1.3.2 Observed Events
>
> 1.3.2.1 ToneDetected
>
> Short name tonedt
>
> Event Parameters:
>
> eventtype       Possible values:
>                 "MULTI": multiple digits have been
> accumulated and sent.
>                 "START": one tone start detected
>                                 "LONG":         one tone has
> been detected
> for more than 2 seconds (Configurable)
>                                 "END':  one tone end detected.
>
> content a string containing one or more dtmftoneid's
>
> duration        this parameter is used when eventtype is
> "END" is represents
> the total duration for which the tome was detected in ms
>
> dtmftoneid's:
> '0','1','2','3','4','5','6','7','8','9','*','#','A','B','C','D'
>
> 1.3.2.2 SilenceDetected
>
> Short name silencedt
>
> Event Parameters:
>
> duration        duration of silence before the event was triggered.
>
> 1.4 Signals
>
> 1.4.1 PlayTone
>
> short name playtone
>
> Signal Parameters:
>
> streamid        id of audio stream to detect tones on.
> dtmftoneid      Tone to be played
> signaltype      Possible values:
>                 "BR" brief duration (provisionned)
>                 "ON" Play until instructed to stop
>                 "TO" Play until timed out
> duration        timeout duration in ms
>
> 1.4.1 StopTone
>
> short name stoptone
>
> stop tone play on streamid
>
> Signal Parameters:
>
> streamid        id of audio stream to detect tones on.
>
>
> B)      Package Registration
>
> A package can be registered with IANA for interoperability
> reasons. The
> following considerations have to be met:
>
> 1-      A string name and a serial number are registered for
> each package.
> 2-      A public document or a standard forum document can be
> referenced  as
> the document that describes the package. If a document is
> referenced the
> document should follow the structure described above and
> should be complete
> 3-      Reference documents (if they exist) should be
> available on a web
> server and should be fixed. The site should provide a
> mechanism to provide
> comments and appropriate responses should be returned. Minor
> fixes should be
> allowed. Major Changes (functional changes) should be
> submitted as a new
> package.
> 4-      If no description document is referenced, package
> names have to be 6
> characters or more.
> 5-      No domain specific package names are to be used
> 6-      H.248 / megaco will reserve the following package
> names for their
> generic packages
> *       dtmf
> *       generic
> *       keypad
> *       .. to be completed
> 7-      First come first server if all other conditions are met
> 8-      Restrictions so name space does not blow up ?? (maybe
> approval by
> ITU , IETF ???)
>

---

From: Christian Huitema <[email-masked]>
Date: Fri, 20 Aug 1999 18:45:15 -0400

Brian,

The relation between events in "modify" and events in "notify" is the
following:

1) In modify, you request the gateway to detect some event. You need to qualify
the event name with a list of actions, what to do when the event is detected.
2) In modify, you request the gateway to provide some signals. You may need to
qualify the signal name with a list of parameters, such as for example the
string to be displayed in the caller-id event.
3) In notify, you provide the names of the events that were detected. You may
need to qualify the name with a list of parameters.

The fact is, the syntax of the "notified event" should be much closer to the
"signal descriptor" than to the "event descriptor." Consider two gateways
connected by a trunk, in the following hypothetical configuration:

                  +------+                    +------+
                  | MGC1 |                    | MGC2 |
                  +------+                    +------+
                     |(Modify)                   ^
                     v                           | (Notify)
                   +-----+                    +----+
     IP network )--| MG1 |---(analog trunk)---|MG 2|--(IP network
                   +-----+                    +----+

When MGC1 sends a Modify request that triggers a "signal" on the analog
termination, MG1 applies the corresponding frequencies, etc., on the analog
line, and MG2 detects the corresponding "event."

This is, by the way, why I believe that events and signals should share the
same names.
Christian Huitema

---

From: David Stonehouse <[email-masked]>
Date: Mon, 23 Aug 1999 10:44:44 -0400

Brian,

One thing that I don't see in your response is what you do with Mike's
suggestion on how to stop signals.  From my understanding, the protocol
currently doesn't specify how this is done.  I would propose that this be done
by the presence or absence of the signal in the SignalDescriptor.  IMO, this is
preferred over a format which required explicitly turning off a signal because
of the situation in which the MGC wanted to turn off all signals to a
wildcarded group of terminations (see example below).

The same argument would be given for why the EventDescriptor should have the
same mechanism for how to stop / start scanning.

Also, with this method, if the MGC sends a message for a Termination that does
not have a SignalsDescriptor and/or EventsDescriptor, it should continue to use
the last SignalsDescriptor and/or EventsDescriptor sent from the MGC.  The
advantage to this (besides a modest savings in messaging bandwidth) is that the
GW doesn't have to bother with processing signal/event desciptors for commands
that have nothing to do with tones/scanning.

This would require the following changes to the grammar:

eventsDescriptor = EventsDescriptorToken  EQUAL RequestID
                                 LBRKT [ requestedEvent  *(COMMA
requestedEvent) ] RBRKT

signalsDescriptor = SignalsDescriptorToken
                                 LBRKT [ signalRequest *(COMMA signalRequest) ]
RBRKT

With these change to the July 31 syntax, a message from the MGC to "shut down"
the gateway might have the following format:

Transaction 001 {
Context * {
Modify * {
   .
  (Other settings...)
   .
Signals { }  // The GW knows to turn off any signals being applied to the
terminations
Events=1001 { }   // The GW stops scanning for any events
   .
   .
} } }

Dave Stonehouse