7.1.14.9 Example
As an example, consider the following dial plan:
0 Local operator
00 Long-distance operator
xxxx Local extension number (starts with 1-7)
8xxxxxxx Local number
#xxxxxxx Off-site extension
*xx Star services
91xxxxxxxxxx Long-distance number
9011 + up to 15 digits International number
If the DTMF detection package described in E.6 is used to collect the
dialed digits, then the dialing plan shown above results in the
following digit map:
(0| 00|[1-7]xxx|8xxxxxxx|Fxxxxxxx|Exx|91xxxxxxxxxx|9011x.)
7.1.15 Statistics descriptor
The Statistics Descriptor provides information describing the status
and usage of a Termination during its existence within a specific
Context. There is a set of standard statistics kept for each
Termination where appropriate (number of octets sent and received for
example). The particular statistical properties that are reported
for a given Termination are determined by the Packages realized by
the Termination. By default, statistics are reported when the
Termination is Subtracted from the Context. This behaviour can be
overridden by including an empty AuditDescriptor in the Subtract
command. Statistics may also be returned from the AuditValue
command, or any Add/Move/Modify command using the Audit descriptor.
Statistics are cumulative; reporting Statistics does not reset them.
Statistics are reset when a Termination is Subtracted from a Context.
7.1.16 Packages descriptor
Used only with the AuditValue command, the PackageDescriptor returns
a list of Packages realized by the Termination.
7.1.17 ObservedEvents descriptor
ObservedEvents is supplied with the Notify command to inform the MGC
of which event(s) were detected. Used with the AuditValue command,
the ObservedEventsDescriptor returns events in the event buffer which
have not been Notified. ObservedEvents contains the
RequestIdentifier of the EventsDescriptor that triggered the
notification, the event(s) detected, optionally the detection time(s)
and any parameters of the observed event. Detection times are
reported with a precision of hundredths of a second.
7.1.18 Topology descriptor
A Topology descriptor is used to specify flow directions between
Terminations in a Context. Contrary to the descriptors in previous
subclauses, the Topology descriptor applies to a Context instead of a
Termination. The default topology of a Context is that each
Termination's transmission is received by all other Terminations.
The Topology descriptor is optional to implement. An MG that does
not support Topology descriptors, but receives a command containing
one, returns Error 444 Unsupported or unknown descriptor, and
optionally includes a string containing the name of the unsupported
Descriptor ("Topology") in the error text in the error descriptor.
The Topology descriptor occurs before the commands in an action. It
is possible to have an action containing only a Topology descriptor,
provided that the Context to which the action applies already exists.
A Topology descriptor consists of a sequence of triples of the form
(T1, T2, association). T1 and T2 specify Terminations within the
Context, possibly using the ALL or CHOOSE wildcard. The association
specifies how media flows between these two Terminations as follows.
- (T1, T2, isolate) means that the Terminations matching T2 do not
receive media from the Terminations matching T1, nor vice versa.
- (T1, T2, oneway) means that the Terminations that match T2 receive
media from the Terminations matching T1, but not vice versa. In
this case use of the ALL wildcard such that there are Terminations
that match both T1 and T2 is not allowed.
- (T1, T2, bothway) means that the Terminations matching T2 receive
media from the Terminations matching T1, and vice versa. In this
case it is allowed to use wildcards such that there are
Terminations that match both T1 and T2. However, if there is a
Termination that matches both, no loopback is introduced.
CHOOSE wildcards may be used in T1 and T2 as well, under the
following restrictions:
- the action (see clause 8) of which the topology descriptor is part
contains an Add command in which a CHOOSE wildcard is used;
- if a CHOOSE wildcard occurs in T1 or T2, then a partial name SHALL
NOT be specified.
The CHOOSE wildcard in a Topology descriptor matches the
TerminationID that the MG assigns in the first Add command that uses
a CHOOSE wildcard in the same action. An existing Termination that
matches T1 or T2 in the Context to which a Termination is added, is
connected to the newly added Termination as specified by the Topology
descriptor.
If a termination is not mentioned within a Topology Descriptor, any
topology associated with it remains unchanged. If, however, a new
termination is added into a context its association with the other
terminations within the context defaults to bothway, unless a
Topology Descriptor is given to change this (e.g., if T3 is added to
a context with T1 and T2 with topology (T3, T1, oneway) it will be
connected bothway to T2).
Figure 7 and the table following it show some examples of the effect
of including topology descriptors in actions. In these examples it
is assumed that the topology descriptors are applied in sequence.
+------------------+ +------------------+ +------------------+
| +----+ | | +----+ | | +----+ |
| | T2 | | | | T2 | | | | T2 | |
| +----+ | | +----+ | | +----+ |
| ^ ^ | | ^ | | ^ |
| | | | | | | | | |
| +--+ +--+ | | +---+ | | +--+ |
| | | | | | | | | |
| v v | | v | | | |
| +----+ +----+ | | +----+ +----+ | | +----+ +----+ |
| | T1 |<-->| T3 | | | | T1 |<-->| T3 | | | | T1 |<-->| T3 | |
| +----+ +----+ | | +----+ +----+ | | +----+ +----+ |
+------------------+ +------------------+ +------------------+
1. No Topology Desc. 2. T1, T2, Isolate 3. T3, T2, Oneway
+------------------+ +------------------+ +------------------+
| +----+ | | +----+ | | +----+ |
| | T2 | | | | T2 | | | | T2 | |
| +----+ | | +----+ | | +----+ |
| | | | ^ | | ^ ^ |
| | | | | | | | | |
| +--+ | | +---+ | | +--+ +--+ |
| | | | | | | | | |
| v | | v | | v v |
| +----+ +----+ | | +----+ +----+ | | +----+ +----+ |
| | T1 |<-->| T3 | | | | T1 |<-->| T3 | | | | T1 |<-->| T3 | |
| +----+ +----+ | | +----+ +----+ | | +----+ +----+ |
+------------------+ +------------------+ +------------------+
4. T2, T3 oneway 5. T2, T3 bothway 6. T1, T2 bothway
Note: the direction of the arrow indicates the direction of flow.
Figure 7: Example topologies
Topology Description
1 No topology descriptors When no topology descriptors are
included, all Terminations have a
bothway connection to all other
Terminations.
2 T1, T2 Isolate Removes the connection between T1 and
T2. T3 has a bothway connection with
both T1 and T2. T1 and T2 have bothway
connection to T3.
3 T3, T2 oneway A oneway connection from T3 to T2 (i.e.,
T2 receives media flow from T3). A
bothway connection between T1 and T3.
4 T2, T3 oneway A oneway connection between T2 to T3.
T1 and T3 remain bothway connected.
5 T2, T3 bothway T2 is bothway connected to T3. This
results in the same as 2.
6 T1, T2 bothway (T2, T3 All Terminations have a bothway
bothway and T1, T3 connection to all other Terminations.
bothway may be implied or
explicit).
A oneway connection must be implemented in such a way that the other
Terminations in the Context are not aware of the change in topology.
7.1.19 Error Descriptor
If a responder encounters an error when processing a transaction
request, it must include an error descriptor in its response. A
Notify request may contain an error descriptor as well.
An error descriptor consists of an IANA-registered error code,
optionally accompanied by an error text. H.248.8 contains a list of
valid error codes and error descriptions.
An error descriptor shall be specified at the "deepest level" that is
semantically appropriate for the error being described and that is
possible given any parsing problems with the original request. An
error descriptor may refer to a syntactical construct other than
where it appears. For example, Error descriptor 422 - Syntax Error
in Action, could appear within a command even though it refers to the
larger construct - the action - and not the particular command within
which it appears.
7.2 Command Application Programming Interface
Following is an Application Programming Interface (API) describing
the Commands of the protocol. This API is shown to illustrate the
Commands and their parameters and is not intended to specify
implementation (e.g., via use of blocking function calls). It
describes the input parameters in parentheses after the command name
and the return values in front of the Command. This is only for
descriptive purposes; the actual Command syntax and encoding are
specified in later subclauses. The order of parameters to commands
is not fixed. Descriptors may appear as parameters to commands in
any order. The descriptors SHALL be processed in the order in which
they appear.
Any reply to a command may contain an error descriptor; the API does
not specifically show this.
All parameters enclosed by square brackets ([. . .]) are considered
optional.
7.2.1 Add
The Add Command adds a Termination to a Context.
TerminationID
[,MediaDescriptor]
[,ModemDescriptor]
[,MuxDescriptor]
[,EventsDescriptor]
[,SignalsDescriptor]
[,DigitMapDescriptor]
[,ObservedEventsDescriptor]
[,EventBufferDescriptor]
[,StatisticsDescriptor]
[,PackagesDescriptor]
Add( TerminationID
[, MediaDescriptor]
[, ModemDescriptor]
[, MuxDescriptor]
[, EventsDescriptor]
[, EventBufferDescriptor]
[, SignalsDescriptor]
[, DigitMapDescriptor]
[, AuditDescriptor]
)
The TerminationID specifies the Termination to be added to the
Context. The Termination is either created, or taken from the null
Context. If a CHOOSE wildcard is used in the TerminationID, the
selected TerminationID will be returned. Wildcards may be used in an
Add, but such usage would be unusual. If the wildcard matches more
than one TerminationID, all possible matches are attempted, with
results reported for each one. The order of attempts when multiple
TerminationIDs match is not specified.
The optional MediaDescriptor describes all media streams.
The optional ModemDescriptor and MuxDescriptor specify a modem and
multiplexer if applicable. For convenience, if a Multiplex
descriptor is present in an Add command and lists any Terminations
that are not currently in the Context, such Terminations are added to
the Context as if individual Add commands listing the Terminations
were invoked. If an error occurs on such an implied Add, error 471 -
Implied Add for Multiplex failure shall be returned and further
processing of the command shall cease.
The EventsDescriptor parameter is optional. If present, it provides
the list of events that should be detected on the Termination.
The EventBufferDescriptor parameter is optional. If present, it
provides the list of events that the MG is requested to detect and
buffer when EventBufferControl equals LockStep.
The SignalsDescriptor parameter is optional. If present, it provides
the list of signals that should be applied to the Termination.
The DigitMapDescriptor parameter is optional. If present, it defines
a DigitMap definition that may be used in an EventsDescriptor.
The AuditDescriptor is optional. If present, the command will return
descriptors as specified in the AuditDescriptor.
All descriptors that can be modified could be returned by MG if a
parameter was underspecified or overspecified. ObservedEvents,
Statistics, and Packages, and the EventBuffer descriptors are
returned only if requested in the AuditDescriptor.
Add SHALL NOT be used on a Termination with a serviceState of
"OutofService".
7.2.2 Modify
The Modify Command modifies the properties of a Termination.
TerminationID
[,MediaDescriptor]
[,ModemDescriptor]
[,MuxDescriptor]
[,EventsDescriptor]
[,SignalsDescriptor]
[,DigitMapDescriptor]
[,ObservedEventsDescriptor]
[,EventBufferDescriptor]
[,StatisticsDescriptor]
[,PackagesDescriptor]
Modify( TerminationID
[, MediaDescriptor]
[, ModemDescriptor]
[, MuxDescriptor]
[, EventsDescriptor]
[, EventBufferDescriptor]
[, SignalsDescriptor]
[, DigitMapDescriptor]
[, AuditDescriptor]
)
The TerminationID may be specific if a single Termination in the
Context is to be modified. Use of wildcards in the TerminationID may
be appropriate for some operations. If the wildcard matches more
than one TerminationID, all possible matches are attempted, with
results reported for each one. The order of attempts when multiple
TerminationIDs match is not specified. The CHOOSE option is an
error, as the Modify command may only be used on existing
Terminations.
For convenience, if a Multiplex Descriptor is present in a Modify
command, then:
- if the new Multiplex Descriptor lists any Terminations that are
not currently in the Context, such Terminations are added to the
context as if individual commands listing the Terminations were
invoked.
- if any Terminations listed previously in the Multiplex Descriptor
are no longer present in the new Multiplex Descriptor, they are
subtracted from the context as if individual Subtract commands
listing the Terminations were invoked.
The remaining parameters to Modify are the same as those to Add.
Possible return values are the same as those to Add.
7.2.3 Subtract
The Subtract Command disconnects a Termination from its Context and
returns statistics on the Termination's participation in the Context.
TerminationID
[,MediaDescriptor]
[,ModemDescriptor]
[,MuxDescriptor]
[,EventsDescriptor]
[,SignalsDescriptor]
[,DigitMapDescriptor]
[,ObservedEventsDescriptor]
[,EventBufferDescriptor]
[,StatisticsDescriptor]
[,PackagesDescriptor]
Subtract(TerminationID
[, AuditDescriptor]
)
TerminationID in the input parameters represents the Termination that
is being subtracted. The TerminationID may be specific or may be a
wildcard value indicating that all (or a set of related) Terminations
in the Context of the Subtract Command are to be subtracted. If the
wildcard matches more than one TerminationID, all possible matches
are attempted, with results reported for each one. The order of
attempts when multiple TerminationIDs match is not specified.
The use of CHOOSE in the TerminationID is an error, as the Subtract
command may only be used on existing Terminations.
ALL may be used as the ContextID as well as the TerminationId in a
Subtract, which would have the effect of deleting all Contexts,
deleting all ephemeral Terminations, and returning all physical
Terminations to Null Context. Subtract of a termination from the
Null Context is not allowed.
For convenience, if a multiplexing Termination is the object of a
Subtract command, then any bearer Terminations listed in its
Multiplex Descriptor are subtracted from the context as if individual
Subtract commands listing the Terminations were invoked.
By default, the Statistics parameter is returned to report
information collected on the Termination or Terminations specified in
the Command. The information reported applies to the Termination's
or Terminations' existence in the Context from which it or they are
being subtracted.
The AuditDescriptor is optional. If present, the command will return
only those descriptors as specified in the AuditDescriptor, which may
be empty. If omitted, the Statistics descriptor is returned, by
default. Possible return values are the same as those to Add.
When a provisioned Termination is Subtracted from a Context, its
property values shall revert to:
- the default value, if specified for the property and not
overridden by provisioning;
- otherwise, the provisioned value.
7.2.4 Move
The Move Command moves a Termination to another Context from its
current Context in one atomic operation. The Move command is the
only command that refers to a Termination in a Context different from
that to which the command is applied. The Move command shall not be
used to move Terminations to or from the null Context.
TerminationID
[,MediaDescriptor]
[,ModemDescriptor]
[,MuxDescriptor]
[,EventsDescriptor]
[,SignalsDescriptor]
[,DigitMapDescriptor]
[,ObservedEventsDescriptor]
[,EventBufferDescriptor]
[,StatisticsDescriptor]
[,PackagesDescriptor]
Move( TerminationID
[, MediaDescriptor]
[, ModemDescriptor]
[, MuxDescriptor]
[, EventsDescriptor]
[, EventBufferDescriptor]
[, SignalsDescriptor]
[, DigitMapDescriptor]
[, AuditDescriptor]
)
The TerminationID specifies the Termination to be moved. It may be
wildcarded, but CHOOSE shall not be used in the TerminationID. If
the wildcard matches more than one TerminationID, all possible
matches are attempted, with results reported for each one. The order
of attempts when multiple TerminationIDs match is not specified. The
Context to which the Termination is moved is indicated by the target
ContextId in the Action. If the last remaining Termination is moved
out of a Context, the Context is deleted.
The Move command does not affect the properties of the Termination on
which it operates, except those properties explicitly modified by
descriptors included in the Move command. The AuditDescriptor with
the Statistics option, for example, would return statistics on the
Termination just prior to the Move. Possible descriptors returned
from Move are the same as for Add.
For convenience, if a multiplexing Termination is the object of a
Move command, then any bearer Terminations listed in its Multiplex
Descriptor are also moved as if individual Move commands listing the
Terminations were invoked.
Move SHALL NOT be used on a Termination with a serviceState of
"OutofService".
7.2.5 AuditValue
The AuditValue Command returns the current values of properties,
events, signals and statistics associated with Terminations.
TerminationID
[,MediaDescriptor]
[,ModemDescriptor]
[,MuxDescriptor]
[,EventsDescriptor]
[,SignalsDescriptor]
[,DigitMapDescriptor]
[,ObservedEventsDescriptor]
[,EventBufferDescriptor]
[,StatisticsDescriptor]
[,PackagesDescriptor]
AuditValue(TerminationID,
AuditDescriptor
)
TerminationID may be specific or wildcarded. If the wildcard matches
more than one TerminationID, all possible matches are attempted, with
results reported for each one. The order of attempts when multiple
TerminationIDs match is not specified. If a wildcarded response is
requested, only one command return is generated, with the contents
containing the union of the values of all Terminations matching the
wildcard. This convention may reduce the volume of data required to
audit a group of Terminations. Use of CHOOSE is an error.
The appropriate descriptors, with the current values for the
Termination, are returned from AuditValue. Values appearing in
multiple instances of a descriptor are defined to be alternate values
supported, with each parameter in a descriptor considered
independent.
ObservedEvents returns a list of events in the EventBuffer. If the
ObservedEventsDescriptor is audited while a DigitMap is active, the
returned ObservedEvents descriptor also includes a digit map
completion event that shows the current dial string but does not show
a Termination method.
EventBuffer returns the set of events and associated parameter values
currently enabled in the EventBufferDescriptor. PackagesDescriptor
returns a list of packages realized by the Termination.
DigitMapDescriptor returns the name or value of the current DigitMap
for the Termination. DigitMap requested in an AuditValue command
with TerminationID ALL returns all DigitMaps in the gateway.
Statistics returns the current values of all statistics being kept on
the Termination. Specifying an empty Audit descriptor results in
only the TerminationID being returned. This may be useful to get a
list of TerminationIDs when used with wildcard. Annexes A and B
provide a special syntax for presenting such a list in condensed
form, such that the AuditValue command tag does not have to be
repeated for each TerminationID.
AuditValue results depend on the Context, viz. specific, null, or
wildcarded. (Note that ContextID ALL does not include the null
Context.) The TerminationID may be specific, or wildcarded.
The following are examples of what is returned in case the context
and/or the termination is wildcarded and a wildcarded response has
been specified.
Assume that the gateway has 4 terminations: t1/1, t1/2, t2/1 and
t2/2. Assume that terminations t1/* have implemented packages aaa
and bbb and that terminations t2/* have implemented packages ccc and
ddd. Assume that Context 1 has t1/1 and t2/1 in it and that Context
2 has t1/2 and t2/2 in it.
The command:
Context=1{AuditValue=t1/1{Audit{Packages}}}
Returns:
Context=1{AuditValue=t1/1{Packages{aaa,bbb}}}
The command:
Context=*{AuditValue=t2/*{Audit{Packages}}}
Returns:
Context=1{AuditValue=t2/1{Packages{ccc,ddd}}},
Context=2{AuditValue=t2/2{Packages{ccc,ddd}}}
The command:
Context=*{W-AuditValue=t1/*{Audit{Packages}}}
Returns:
Context=*{W-AuditValue=t1/*{Packages{aaa,bbb}}}
Note: A wildcard response may also be used for other commands such as
Subtract.
The following illustrates other information that can be obtained with
the AuditValue Command:
ContextID TerminationID Information Obtained
Specific wildcard Audit of matching Terminations in a Context
Specific specific Audit of a single Termination in a Context
Null Root Audit of Media Gateway state and events
Null wildcard Audit of all matching Terminations in the
null Context
Null specific Audit of a single Termination outside of any
Context
All wildcard Audit of all matching Terminations and the
Context to which they are associated
All Root List of all ContextIds (the ContextID list
should be returned by using multiple action
replies, each containing a ContextID from
the list)
All Specific (Non-null) ContextID in which the
Termination currently exists
7.2.6 AuditCapabilities
The AuditCapabilities Command returns the possible values of
properties, events, signals and statistics associated with
Terminations.
TerminationID
[,MediaDescriptor]
[,ModemDescriptor]
[,MuxDescriptor]
[,EventsDescriptor]
[,SignalsDescriptor]
[,ObservedEventsDescriptor]
[,EventBufferDescriptor]
[,StatisticsDescriptor]
AuditCapabilities(TerminationID,
AuditDescriptor
)
The appropriate descriptors, with the possible values for the
Termination are returned from AuditCapabilities. Descriptors may be
repeated where there are multiple possible values. If a wildcarded
response is requested, only one command return is generated, with the
contents containing the union of the values of all Terminations
matching the wildcard. This convention may reduce the volume of data
required to audit a group of Terminations.
Interpretation of what capabilities are requested for various values
of ContextID and TerminationID is the same as in AuditValue.
The EventsDescriptor returns the list of possible events on the
Termination together with the list of all possible values for the
EventsDescriptor Parameters. EventBufferDescriptor returns the same
information as EventsDescriptor. The SignalsDescriptor returns the
list of possible signals that could be applied to the Termination
together with the list of all possible values for the Signals
Parameters. StatisticsDescriptor returns the names of the statistics
being kept on the termination. ObservedEventsDescriptor returns the
names of active events on the Termination. DigitMap and Packages are
not legal in AuditCapability.
The following illustrates other information that can be obtained with
the AuditCapabilties Command:
ContextID TerminationID Information Obtained
Specific wildcard Audit of matching Terminations in a Context
Specific specific Audit of a single Termination in a Context
Null Root Audit of MG state and events
Null wildcard Audit of all matching Terminations in the
Null Context
Null specific Audit of a single Termination outside of any
Context
All wildcard Audit of all matching Terminations and the
Context to which they are associated
All Root Same as for AuditValue
All Specific Same as for AuditValue
7.2.7 Notify
The Notify Command allows the Media Gateway to notify the Media
Gateway Controller of events occurring within the Media Gateway.
TerminationID
Notify(TerminationID,
ObservedEventsDescriptor,
[ErrorDescriptor]
)
The TerminationID parameter specifies the Termination issuing the
Notify Command. The TerminationID shall be a fully qualified name.
The ObservedEventsDescriptor contains the RequestID and a list of
events that the Media Gateway detected in the order that they were
detected. Each event in the list is accompanied by parameters
associated with the event and optionally an indication of the time
that the event was detected. Procedures for sending Notify commands
with RequestID equal to 0 are for further study.
Notify Commands with RequestID not equal to 0 shall occur only as the
result of detection of an event specified by an Events descriptor
which is active on the Termination concerned.
The RequestID returns the RequestID parameter of the EventsDescriptor
that triggered the Notify Command. It is used to correlate the
notification with the request that triggered it. The events in the
list must have been requested via the triggering EventsDescriptor or
embedded events descriptor unless the RequestID is 0 (which is for
further study).
The ErrorDescriptor may be sent in the Notify Command as a result of
Error 518 - Event buffer full.
7.2.8 ServiceChange
The ServiceChange Command allows the Media Gateway to notify the
Media Gateway Controller that a Termination or group of Terminations
is about to be taken out of service or has just been returned to
service. The Media Gateway Controller may indicate that
Termination(s) shall be taken out of or returned to service. The
Media Gateway may notify the MGC that the capability of a Termination
has changed. It also allows a MGC to hand over control of a MG to
another MGC.
TerminationID,
[ServiceChangeDescriptor]
ServiceChange ( TerminationID,
ServiceChangeDescriptor
)
The TerminationID parameter specifies the Termination(s) that are
taken out of or returned to service. Wildcarding of Termination
names is permitted, with the exception that the CHOOSE mechanism
shall not be used. Use of the "Root" TerminationID indicates a
ServiceChange affecting the entire Media Gateway.
The ServiceChangeDescriptor contains the following parameters as
required:
- ServiceChangeMethod
- ServiceChangeReason
- ServiceChangeDelay
- ServiceChangeAddress
- ServiceChangeProfile
- ServiceChangeVersion
- ServiceChangeMgcId
- TimeStamp
The ServiceChangeMethod parameter specifies the type of ServiceChange
that will or has occurred:
1) Graceful - indicates that the specified Terminations will be taken
out of service after the specified ServiceChangeDelay; established
connections are not yet affected, but the Media Gateway Controller
should refrain from establishing new connections and should
attempt to gracefully tear down existing connections on the
Termination(s) affected by the serviceChange command. The MG
should set Termination serviceState at the expiry of
ServiceChangeDelay or the removal of the Termination from an
active Context (whichever is first), to "out of service".
2) Forced - indicates that the specified Terminations were taken
abruptly out of service and any established connections associated
with them may be lost. For non-Root terminations, the MGC is
responsible for cleaning up the Context (if any) with which the
failed Termination is associated. At a minimum the Termination
shall be subtracted from the Context. The Termination
serviceState should be "out of service". For the root
termination, the MGC can assume that all connections are lost on
the MG and thus can consider that all the terminations have been
subtracted.
3) Restart - indicates that service will be restored on the specified
Terminations after expiration of the ServiceChangeDelay. The
serviceState should be set to "inService" upon expiry of
ServiceChangeDelay.
4) Disconnected - always applied with the Root TerminationID,
indicates that the MG lost communication with the MGC, but it was
subsequently restored to the same MGC (possibly after trying other
MGCs on a pre-provisioned list). Since MG state may have changed,
the MGC may wish to use the Audit command to resynchronize its
state with the MG's.
5) Handoff - sent from the MGC to the MG, this reason indicates that
the MGC is going out of service and a new MGC association must be
established. Sent from the MG to the MGC, this indicates that the
MG is attempting to establish a new association in accordance with
a Handoff received from the MGC with which it was previously
associated.
6) Failover - sent from MG to MGC to indicate the primary MG is out
of service and a secondary MG is taking over. This serviceChange
method is also sent from the MG to the MGC when the MG detects
that MGC has failed.
7) Another value whose meaning is mutually understood between the MG
and the MGC.
The ServiceChangeReason parameter specifies the reason why the
ServiceChange has or will occur. It consists of an alphanumeric
token (IANA registered) and, optionally, an explanatory string.
The optional ServiceChangeAddress parameter specifies the address
(e.g., IP port number for IP networks) to be used for subsequent
communications. It can be specified in the input parameter
descriptor or the returned result descriptor. ServiceChangeAddress
and ServiceChangeMgcId parameters must not both be present in the
ServiceChangeDescriptor or the ServiceChangeResultDescriptor. The
ServiceChangeAddress provides an address to be used within the
Context of the association currently being negotiated, while the
ServiceChangeMgcId provides an alternate address where the MG should
seek to establish another association. Note that the use of
ServiceChangeAddress is not encouraged. MGCs and MGs must be able to
cope with the ServiceChangeAddress being either a full address or
just a port number in the case of TCP transports.
The optional ServiceChangeDelay parameter is expressed in seconds.
If the delay is absent or set to zero, the delay value should be
considered to be null. In the case of a "graceful"
ServiceChangeMethod, a null delay indicates that the Media Gateway
Controller should wait for the natural removal of existing
connections and should not establish new connections. For "graceful"
only, a null delay means the MG must not set serviceState "out of
service" until the Termination is in the null Context.
The optional ServiceChangeProfile parameter specifies the Profile (if
any) of the protocol supported. The ServiceChangeProfile includes
the version of the profile supported.
The optional ServiceChangeVersion parameter contains the protocol
version and is used if protocol version negotiation occurs (see
11.3).
The optional TimeStamp parameter specifies the actual time as kept by
the sender. As such, it is not necessarily absolute time according
to, for example, a local time zone - it merely establishes an
arbitrary starting time against which all future timestamps
transmitted by a sender during this association shall be compared.
It can be used by the responder to determine how its notion of time
differs from that of its correspondent. TimeStamp is sent with a
precision of hundredths of a second.
The optional Extension parameter may contain any value whose meaning
is mutually understood by the MG and MGC.
A ServiceChange Command specifying the "Root" for the TerminationID
and ServiceChangeMethod equal to Restart is a registration command by
which a Media Gateway announces its existence to the Media Gateway
Controller. The Media Gateway may also announce a registration
command by specifying the "Root" for the TerminationID and
ServiceChangeMethod equal to Failover when the MG detects MGC
failures. The Media Gateway is expected to be provisioned with the
name of one primary and optionally some number of alternate Media
Gateway Controllers. Acknowledgement of the ServiceChange Command
completes the registration process, except when the MGC has returned
an alternative ServiceChangeMgcId as described in the following
paragraph. The MG may specify the transport ServiceChangeAddress to
be used by the MGC for sending messages in the ServiceChangeAddress
parameter in the input ServiceChangeDescriptor. The MG may specify
an address in the ServiceChangeAddress parameter of the ServiceChange
request, and the MGC may also do so in the ServiceChange reply. In
either case, the recipient must use the supplied address as the
destination for all subsequent transaction requests within the
association. At the same time, as indicated in clause 9, transaction
replies and pending indications must be sent to the address from
which the corresponding requests originated. This must be done even
if it implies extra messaging because commands and responses cannot
be packed together. The TimeStamp parameter shall be sent with a
registration command and its response.
The Media Gateway Controller may return a ServiceChangeMgcId
parameter that describes the Media Gateway Controller that should
preferably be contacted for further service by the Media Gateway. In
this case the Media Gateway shall reissue the ServiceChange command
to the new Media Gateway Controller. The MGC specified in a
ServiceChangeMgcId, if provided, shall be contacted before any
further alternate MGCs. On a HandOff message from MGC to MG, the
ServiceChangeMgcId is the new MGC that will take over from the
current MGC.
The return from ServiceChange is empty except when the Root
terminationID is used. In that case it includes the following
parameters as required:
- ServiceChangeAddress, if the responding MGC wishes to specify a
new destination for messages from the MG for the remainder of the
association;
- ServiceChangeMgcId, if the responding MGC does not wish to sustain
an association with the MG;
- ServiceChangeProfile, if the responder wishes to negotiate the
profile to be used for the association;
- ServiceChangeVersion, if the responder wishes to negotiate the
version of the protocol to be used for the association.
The following ServiceChangeReasons are defined. This list may be
extended by an IANA registration as outlined in 13.3.
900 Service Restored
901 Cold Boot
902 Warm Boot
903 MGC Directed Change
904 Termination malfunctioning
905 Termination taken out of service
906 Loss of lower layer connectivity (e.g., downstream sync)
907 Transmission Failure
908 MG Impending Failure
909 MGC Impending Failure
910 Media Capability Failure
911 Modem Capability Failure
912 Mux Capability Failure
913 Signal Capability Failure
914 Event Capability Failure
915 State Loss
7.2.9 Manipulating and Auditing Context Attributes
The commands of the protocol as discussed in the preceding subclauses
apply to Terminations. This subclause specifies how Contexts are
manipulated and audited.
Commands are grouped into actions (see clause 8). An action applies
to one Context. In addition to commands, an action may contain
Context manipulation and auditing instructions.
An action request sent to a MG may include a request to audit
attributes of a Context. An action may also include a request to
change the attributes of a Context.
The Context properties that may be included in an action reply are
used to return information to a MGC. This can be information
requested by an audit of Context attributes or details of the effect
of manipulation of a Context.
If a MG receives an action which contains both a request to audit
context attributes and a request to manipulate those attributes, the
response SHALL include the values of the attributes after processing
the manipulation request.
7.2.10 Generic Command Syntax
The protocol can be encoded in a binary format or in a text format.
MGCs should support both encoding formats. MGs may support both
formats.
The protocol syntax for the binary format of the protocol is defined
in Annex A. Annex C specifies the encoding of the Local and Remote
descriptors for use with the binary format.
A complete ABNF of the text encoding of the protocol per RFC2234 is
given in Annex B. SDP is used as the encoding of the Local and
Remote descriptors for use with the text encoding as modified in
7.1.8.
7.3 Command Error Codes
Errors consist of an IANA registered error code and an explanatory
string. Sending the explanatory string is optional. Implementations
are encouraged to append diagnostic information to the end of the
string.
When a MG reports an error to a MGC, it does so in an error
descriptor. An error descriptor consists of an error code and
optionally the associated explanatory string.
H.248.8 contains the error codes supported by Recommendations in the
H.248 sub-series.
8 Transactions
Commands between the Media Gateway Controller and the Media Gateway
are grouped into Transactions, each of which is identified by a
TransactionID. Transactions consist of one or more Actions. An
Action consists of a non-empty series of Commands, Context property
modifications, or Context property audits that are limited to
operating within a single Context. Consequently, each Action
typically specifies a ContextID. However, there are two
circumstances where a specific ContextID is not provided with an
Action. One is the case of modification of a Termination outside of
a Context. The other is where the controller requests the gateway to
create a new Context. Figure 8 is a graphic representation of the
Transaction, Action and Command relationships.
+----------------------------------------------------------+
| Transaction x |
| +----------------------------------------------------+ |
| | Action 1 | |
| | +---------+ +---------+ +---------+ +---------+ | |
| | | Command | | Command | | Command | | Command | | |
| | | 1 | | 2 | | 3 | | 4 | | |
| | +---------+ +---------+ +---------+ +---------+ | |
| +----------------------------------------------------+ |
| |
| +----------------------------------------------------+ |
| | Action 2 | |
| | +---------+ | |
| | | Command | | |
| | | 1 | | |
| | +---------+ | |
| +----------------------------------------------------+ |
| |
| +----------------------------------------------------+ |
| | Action 3 | |
| | +---------+ +---------+ +---------+ | |
| | | Command | | Command | | Command | | |
| | | 1 | | 2 | | 3 | | |
| | +---------+ +---------+ +---------+ | |
| +----------------------------------------------------+ |
+----------------------------------------------------------+
Figure 8: Transactions, Actions and Commands
Transactions are presented as TransactionRequests. Corresponding
responses to a TransactionRequest are received in a single reply,
possibly preceded by a number of TransactionPending messages (see
8.2.3).
Transactions guarantee ordered Command processing. That is, Commands
within a Transaction are executed sequentially. Ordering of
Transactions is NOT guaranteed - transactions may be executed in any
order, or simultaneously.
At the first failing Command in a Transaction, processing of the
remaining Commands in that Transaction stops. If a command contains
a wildcarded TerminationID, the command is attempted with each of the
actual TerminationIDs matching the wildcard. A response within the
TransactionReply is included for each matching TerminationID, even if
one or more instances generated an error. If any TerminationID
matching a wildcard results in an error when executed, any commands
following the wildcarded command are not attempted.
Commands may be marked as "Optional" which can override this
behaviour - if a command marked as Optional results in an error,
subsequent commands in the Transaction will be executed. If a
command fails, the MG shall as far as possible restore the state that
existed prior to the attempted execution of the command before
continuing with command processing.
A TransactionReply includes the results for all of the Commands in
the corresponding TransactionRequest. The TransactionReply includes
the return values for the Commands that were executed successfully,
and the Command and error descriptor for any Command that failed.
TransactionPending is used to periodically notify the receiver that a
Transaction has not completed yet, but is actively being processed.
Applications SHOULD implement an application level timer per
transaction. Expiration of the timer should cause a retransmission
of the request. Receipt of a Reply should cancel the timer. Receipt
of Pending should restart the timer.
8.1 Common parameters
8.1.1 Transaction Identifiers
Transactions are identified by a TransactionID, which is assigned by
sender and is unique within the scope of the sender. A response
containing an error descriptor to indicate that the TransactionID is
missing in a request shall use TransactionID 0 in the corresponding
TransactionReply.
8.1.2 Context Identifiers
Contexts are identified by a ContextID, which is assigned by the
Media Gateway and is unique within the scope of the Media Gateway.
The Media Gateway Controller shall use the ContextID supplied by the
Media Gateway in all subsequent Transactions relating to that
Context. The protocol makes reference to a distinguished value that
may be used by the Media Gateway Controller when referring to a
Termination that is currently not associated with a Context, namely
the null ContextID.
The CHOOSE wildcard is used to request that the Media Gateway create
a new Context.
The MGC may use the ALL wildcard to address all Contexts on the MG.
The null Context is not included when the ALL wildcard is used.
The MGC shall not use partially specified ContextIDs containing the
CHOOSE or ALL wildcards.
8.2 Transaction Application Programming Interface
Following is an Application Programming Interface (API) describing
the Transactions of the protocol. This API is shown to illustrate
the Transactions and their parameters and is not intended to specify
implementation (e.g., via use of blocking function calls). It will
describe the input parameters and return values expected to be used
by the various Transactions of the protocol from a very high level.
Transaction syntax and encodings are specified in later subclauses.
8.2.1 TransactionRequest
The TransactionRequest is invoked by the sender. There is one
Transaction per request invocation. A request contains one or more
Actions, each of which specifies its target Context and one or more
Commands per Context.
TransactionRequest(TransactionId {
ContextID {Command ... Command},
. . .
ContextID {Command ... Command } })
The TransactionID parameter must specify a value for later
correlation with the TransactionReply or TransactionPending response
from the receiver.
The ContextID parameter must specify a value to pertain to all
Commands that follow up to either the next specification of a
ContextID parameter or the end of the TransactionRequest, whichever
comes first.
The Command parameter represents one of the Commands mentioned in 7.2
(Command Application Programming Interface).
8.2.2 TransactionReply
The TransactionReply is invoked by the receiver. There is one reply
invocation per transaction. A reply contains one or more Actions,
each of which must specify its target Context and one or more
Responses per Context. The TransactionReply is invoked by the
responder when it has processed the TransactionRequest.
A TransactionRequest has been processed:
- when all actions in that TransactionRequest have been processed;
or
- when an error is encountered in processing that
TransactionRequest, except when the error is in an optional
command.
A command has been processed when all descriptors in that command
have been processed.
A SignalsDescriptor is considered to have been processed when it has
been established that the descriptor is syntactically valid, the
requested signals are supported and they have been queued to be
applied.
An EventsDescriptor or EventBufferDescriptor is considered to have
been processed when it has been established that the descriptor is
syntactically valid, the requested events can be observed, any
embedded signals can be generated, any embedded events can be
detected, and the MG has been brought into a state in which the
events will be detected.
TransactionReply(TransactionID {
ContextID { Response ... Response },
. . .
ContextID { Response ... Response } })
The TransactionID parameter must be the same as that of the
corresponding TransactionRequest.
The ContextID parameter must specify a value to pertain to all
Responses for the action. The ContextID may be specific, all or
null.
Each of the Response parameters represents a return value as
mentioned in 7.2, or an error descriptor if the command execution
encountered an error. Commands after the point of failure are not
processed and, therefore, Responses are not issued for them.
An exception to this occurs if a command has been marked as optional
in the Transaction request. If the optional command generates an
error, the transaction still continues to execute, so the Reply
would, in this case, have Responses after an Error.
Section 7.1.19 Error Descriptor specifies the generation of error
descriptors. The text below discusses several individual cases.
If the receiver encounters an error in processing a ContextID, the
requested Action response will consist of the Context ID and a single
error descriptor, 422 - Syntax Error in Action.
If the receiver encounters an error such that it cannot determine a
legal Action, it will return a TransactionReply consisting of the
TransactionID and a single error descriptor, 422 - Syntax Error in
Action. If the end of an action cannot be reliably determined but
one or more commands can be parsed, it will process them and then
send 422 - Syntax Error in Action as the last action for the
transaction. If the receiver encounters an error such that is cannot
determine a legal Transaction, it will return a TransactionReply with
a null TransactionID and a single error descriptor (403 - Syntax
Error in TransactionRequest).
If the end of a transaction cannot be reliably determined and one or
more Actions can be parsed, it will process them and then return 403
- Syntax Error in Transaction as the last action reply for the
transaction. If no Actions can be parsed, it will return 403 -
Syntax Error in TransactionRequest as the only reply.
If the terminationID cannot be reliably determined, it will send 442
- Syntax Error in Command as the action reply.
If the end of a command cannot be reliably determined, it will return
442 - Syntax Error in Command as the reply to the last action it can