Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 3435

Media Gateway Control Protocol (MGCP) Version 1.0

Pages: 210
Informational
Errata
Obsoletes:  2705
Updated by:  3661
Part 6 of 8 – Pages 126 to 156
First   Prev   Next

Top   ToC   RFC3435 - Page 126   prevText

4.4 Race Conditions

MGCP deals with race conditions through the notion of a "quarantine list" and through explicit detection of desynchronization, e.g., for mismatched hook state due to glare for an endpoint.
Top   ToC   RFC3435 - Page 127
   MGCP does not assume that the transport mechanism will maintain the
   order of commands and responses.  This may cause race conditions,
   that may be obviated through a proper behavior of the Call Agent.
   (Note that some race conditions are inherent to distributed systems;
   they would still occur, even if the commands were transmitted in
   strict order.)

   In some cases, many gateways may decide to restart operation at the
   same time.  This may occur, for example, if an area loses power or
   transmission capability during an earthquake or an ice storm.  When
   power and transmission are reestablished, many gateways may decide to
   send "RestartInProgress" commands simultaneously, leading to very
   unstable operation.

4.4.1 Quarantine List

MGCP controlled gateways will receive "notification requests" that ask them to watch for a list of "events". The protocol elements that determine the handling of these events are the "Requested Events" list, the "Digit Map", the "Quarantine Handling", and the "Detect Events" list. When the endpoint is initialized, the requested events list only consists of persistent events for the endpoint, and the digit map is assumed empty. At this point, the endpoint MAY use an implicit NotificationRequest with the reserved RequestIdentifier zero ("0") to detect and report a persistent event, e.g., off-hook. A pre-existing off-hook condition MUST here result in the off-hook event being generated as well. The endpoint awaits the reception of a NotificationRequest command, after which the gateway starts observing the endpoint for occurrences of the events mentioned in the list, including persistent events. The events are examined as they occur. The action that follows is determined by the "action" parameter associated with the event in the list of requested events, and also by the digit map. The events that are defined as "accumulate" or "accumulate according to digit map" are accumulated in a list of events, the events that are marked as "accumulate according to the digit map" will additionally be accumulated in the "current dial string". This will go on until one event is encountered that triggers a notification which will be sent to the current "notified entity". The gateway, at this point, will transmit the Notify command and will place the endpoint in a "notification" state. As long as the endpoint is in this notification state, the events that are to be detected on the endpoint are stored in a "quarantine" buffer (FIFO)
Top   ToC   RFC3435 - Page 128
   for later processing.  The events are, in a sense, "quarantined".
   All events that are specified by the union of the RequestedEvents
   parameter and the most recently received DetectEvents parameter or,
   in the absence of the latter, all events that are referred to in the
   RequestedEvents, SHALL be detected and quarantined, regardless of the
   action associated with the event.  Persistent events are here viewed
   as implicitly included in RequestedEvents.  If the quarantine buffer
   reaches the capacity of the endpoint, a Quarantine Buffer Overflow
   event (see Appendix B) SHOULD be generated (when this event is
   supported, the endpoint MUST ensure it has capacity to include the
   event in the quarantine buffer).  Excess events will now be
   discarded.

   The endpoint exits the "notification state" when the response
   (whether success or failure) to the Notify command is received.  The
   Notify command may be retransmitted in the "notification state", as
   specified in Section 3.5 and 4.  If the endpoint is or becomes
   disconnected (see Section 4.3) during this, a response to the Notify
   command will never be received.  The Notify command is then lost and
   hence no longer considered pending, yet the endpoint is still in the
   "notification state".  Should that occur, completion of the
   disconnected procedure specified in Section 4.4.7 SHALL then lead the
   endpoint to exit the "notification state".

   When the endpoint exits the "notification state" it resets the list
   of observed events and the "current dial string" of the endpoint to a
   null value.

   Following that point, the behavior of the gateway depends on the
   value of the QuarantineHandling parameter in the triggering
   NotificationRequest command:

   If the Call Agent had specified, that it expected at most one
   notification in response to the notification request command, then
   the gateway SHALL simply keep on accumulating events in the
   quarantine buffer until it receives the next notification request
   command.

   If, however, the gateway is authorized to send multiple successive
   Notify commands, it will proceed as follows.  When the gateway exits
   the "notification state", it resets the list of observed events and
   the "current dial string" of the endpoint to a null value and starts
   processing the list of quarantined events, using the already received
   list of requested events and digit map.  When processing these
   events, the gateway may encounter an event which triggers a Notify
   command to be sent.  If that is the case, the gateway can adopt one
   of the two following behaviors:
Top   ToC   RFC3435 - Page 129
   * it can immediately transmit a Notify command that will report all
     events that were accumulated in the list of observed events until
     the triggering event, included, leaving the unprocessed events in
     the quarantine buffer,

   * or it can attempt to empty the quarantine buffer and transmit a
     single Notify command reporting several sets of events (in a single
     list of observed events) and possibly several dial strings.  The
     "current dial string" is reset to a null value after each
     triggering event.  The events that follow the last triggering event
     are left in the quarantine buffer.

   If the gateway transmits a Notify command, the endpoint will reenter
   and remain in the "notification state" until the acknowledgement is
   received (as described above).  If the gateway does not find a
   quarantined event that triggers a Notify command, it places the
   endpoint in a normal state.  Events are then processed as they come,
   in exactly the same way as if a Notification Request command had just
   been received.

   A gateway may receive at any time a new Notification Request command
   for the endpoint, including the case where the endpoint is
   disconnected.  Activating an embedded Notification Request is here
   viewed as receiving a new Notification Request as well, except that
   the current list of ObservedEvents remains unmodified rather than
   being processed again.  When a new notification request is received
   in the notification state, the gateway SHALL ensure that the pending
   Notify is received by the Call Agent prior to a new Notify (note that
   a Notify that was lost due to being disconnected, is no longer
   considered pending).  It does so by using the "piggybacking"
   functionality of the protocol.  The messages will then be sent in a
   single packet to the current "notified entity".  The steps involved
   are the following:

   a) the gateway sends a response to the new notification request.

   b) the endpoint is then taken out of the "notification state" without
      waiting for the acknowledgement of the pending Notify command.

   c) a copy of the unacknowledged Notify command is kept until an
      acknowledgement is received.  If a timer elapses, the Notify will
      be retransmitted.

   d) If the gateway has to transmit a new Notify before the previous
      Notify(s) is acknowledged, it constructs a packet that piggybacks
      a repetition of the old Notify(s) and the new Notify (ordered by
      age with the oldest first).  This datagram will be sent to the
      current "notified entity".
Top   ToC   RFC3435 - Page 130
   f) Gateways that cannot piggyback several messages in the same
      datagram and hence guarantee in-order delivery of two (or more)
      Notify's SHALL leave the endpoint in the "notification" state as
      long as the last Notify is not acknowledged.
Top   ToC   RFC3435 - Page 131
   The procedure is illustrated by the following diagram:

    +-------------------+
    | Processing Events |<--------------------------------------+
    +-------------------+                                       |
             |                                                  |
     Need to send NTFY                                          |
             |                                                  |
             v                                                  |
    +-------------------+                                       |
    | Outstanding NTFY  |---- No -------+                       |
    |                   |               |                       |
    +-------------------+               v                       |
             |                    +-----------+                 |
            Yes                   | Send NTFY |                 |
             |                    +-----------+                 |
             v                          |                       |
    +--------------------+              v                       |
    | Piggyback new NTFY |     +--------------------+           |
    | w. old outstanding |---->| Notification State |           |
    | NTFY(s)            |     +--------------------+           |
    +--------------------+       |               |              |
                             new RQNT        NTFY response      |
                             received        received           |
                                 |               |              |
                                 |               v              |
                                 |        +-------------+       |
                                 |        | Step mode ? |- No ->+
                                 |        +-------------+       ^
                                 |               |              |
                                 |              Yes             |
                                 |               |              |
                                 |               v              |
                                 |       +---------------+      |
                                 |       | Wait for RQNT |      |
                                 |       +---------------+      |
                                 |               |              |
                                 |         RQNT received        |
                                 |               |              |
                                 |               v              |
                                 |       +---------------+      |
                                 +------>| Apply RQNT and|----->+
                                         | send response |
                                         +---------------+
Top   ToC   RFC3435 - Page 132
   Gateways may also attempt to deliver the pending Notify prior to a
   successful response to the new NotificationRequest by using the
   "piggybacking" functionality of the protocol.  This was in fact
   required behavior in RFC 2705, however there are several
   complications in doing this, and the benefits are questionable.  In
   particular, the RFC 2705 mechanism did not guarantee in-order
   delivery of Notify's and responses to NotificationRequests in
   general, and hence Call Agents had to handle out-of-order delivery of
   these messages anyway.  The change to optional status is thus
   backwards compatible while greatly reducing complexity.

   After receiving the Notification Request command, the requested
   events list and digit map (if a new one was provided) are replaced by
   the newly received parameters, and the current dial string is reset
   to a null value.  Furthermore, when the Notification Request was
   received in the "notification state", the list of observed events is
   reset to a null value.  The subsequent behavior is conditioned by the
   value of the QuarantineHandling parameter.  The parameter may specify
   that quarantined events (and observed events which in this case is
   now an empty list), should be discarded, in which case they will be.
   If the parameter specifies that the quarantined (and observed) events
   are to be processed, the gateway will start processing the list of
   quarantined (and observed) events, using the newly received list of
   requested events and digit map (if provided).  When processing these
   events, the gateway may encounter an event which requires a Notify
   command to be sent.  If that is the case, the gateway will
   immediately transmit a Notify command that will report all events
   that were accumulated in the list of observed events until the
   triggering event, included leaving the unprocessed events in the
   quarantine buffer, and will enter the "notification state".

   A new notification request may be received while the gateway has
   accumulated events according to the previous notification request,
   but has not yet detected a notification-triggering events, i.e., the
   endpoint is not in the "notification state".  The handling of not-
   yet-notified events is determined, as with the quarantined events, by
   the quarantine handling parameter:

   * If the quarantine-handling parameter specifies that quarantined
     events shall be ignored, the observed events list is simply reset.

   * If the quarantine-handling parameter specifies that quarantined
     events shall be processed, the observed event list is transferred
     to the quarantined event list.  The observed event list is then
     reset, and the quarantined event list is processed.
Top   ToC   RFC3435 - Page 133
   Call Agents controlling endpoints in lockstep mode SHOULD provide the
   response to a successful Notify message and the new
   NotificationRequest in the same datagram using the piggybacking
   mechanism.

4.4.2 Explicit Detection

A key element of the state of several endpoints is the position of the hook. A race condition may occur when the user decides to go off-hook before the Call Agent has the time to ask the gateway to notify an off-hook event (the "glare" condition well known in telephony), or if the user goes on-hook before the Call Agent has the time to request the event's notification. To avoid this race condition, the gateway MUST check the condition of the endpoint before acknowledging a NotificationRequest. It MUST return an error: 1. If the gateway is requested to notify an "off-hook" transition while the phone is already off-hook, (error code 401 - phone off hook) 2. If the gateway is requested to notify an "on-hook" or "flash hook" condition while the phone is already on-hook (error code 402 - phone on hook). Additionally, individual signal definitions can specify that a signal will only operate under certain conditions, e.g., ringing may only be possible if the phone is already off-hook. If such prerequisites exist for a given signal, the gateway MUST return the error specified in the signal definition if the prerequisite is not met. It should be noted, that the condition check is performed at the time the notification request is received, whereas the actual event that caused the current condition may have either been reported, or ignored earlier, or it may currently be quarantined. The other state variables of the gateway, such as the list of RequestedEvents or list of requested signals, are entirely replaced after each successful NotificationRequest, which prevents any long term discrepancy between the Call Agent and the gateway. When a NotificationRequest is unsuccessful, whether it is included in a connection-handling command or not, the gateway MUST simply continue as if the command had never been received. As all other transactions, the NotificationRequest MUST operate as an atomic transaction, thus any changes initiated as a result of the command MUST be reverted.
Top   ToC   RFC3435 - Page 134
   Another race condition may occur when a Notify is issued shortly
   before the reception by the gateway of a NotificationRequest.  The
   RequestIdentifier is used to correlate Notify commands with
   NotificationRequest commands thereby enabling the Call Agent to
   determine if the Notify command was generated before or after the
   gateway received the new NotificationRequest.  This is especially
   important to avoid deadlocks in "step" mode.

4.4.3 Transactional Semantics

As the potential transaction completion times increase, e.g., due to external resource reservations, a careful definition of the transactional semantics becomes increasingly important. In particular the issue of race conditions, e.g., as it relates to hook-state, must be defined carefully. An important point to consider is, that the status of a pre-condition (e.g., hook-state) may in fact change between the time a transaction starts and the time it either completes successfully (transaction commit) or fails. In general, we can say that the successful execution of a transaction depends on one or more pre-conditions where the status of one or more of the pre-conditions may change dynamically between the transaction start and transaction commit. The simplest semantics for this is simply to require that all pre- conditions be met from the time the transaction is initiated until the transaction commits. If any pre-condition is not met before the completion of the transaction, the transaction will also fail. As an example, consider a transaction that includes a request for the "off-hook" event. When the transaction is initiated the phone is "on-hook" and this pre-condition is therefore met. If the hook-state changes to "off-hook" before the transaction completes, the pre- condition is no longer met, and the transaction therefore immediately fails. Finally, we need to consider the point in time when a new transaction takes effect and endpoint processing according to an old transaction stops. For example, assume that transaction T1 has been executed successfully and event processing is currently being done according to transaction T1. Now we receive a new transaction T2 specifying new event processing (for example a CreateConnection with an encapsulated NotificationRequest). Since we don't know whether T2 will complete successfully or not, we cannot start processing events according to T2 until the outcome of T2 is known. While we could suspend all event processing until the outcome of T2 is known, this would make for a less responsive system and hence SHOULD NOT be done. Instead, when a new transaction Ty is received and Ty modifies
Top   ToC   RFC3435 - Page 135
   processing according to an old transaction Tx, processing according
   to Tx SHOULD remain active for as long as possible, until a
   successful outcome of Ty is known to occur.  If Ty fails, then
   processing according to Tx will of course continue as usual.  Any
   changes incurred by Ty logically takes effect when Ty commits.  Thus,
   if the endpoint was in the notification state when Ty commits, and Ty
   contained a NotificationRequest, the endpoint will be taken out of
   the notification state when Ty commits.  Note that this is
   independent of whether the endpoint was in the notification state
   when Ty was initiated.  For example, a Notify could be generated due
   to processing according to Tx between the start and commit of Ty.  If
   the commit of Ty leads to the endpoint entering the notification
   state, a new NotificationRequest (Tz) is needed to exit the
   notification state.  This follows from the fact that transaction
   execution respects causal order.

   Another related issue is the use of wildcards, especially the "all
   of" wildcard, which may match more than one endpoint.  When a command
   is requested, and the endpoint identifier matches more than one
   endpoint, transactional semantics still apply.  Thus, the command
   MUST either succeed for all the endpoints, or it MUST fail for all of
   them.  A single response is consequently always issued.

4.4.4 Ordering of Commands, and Treatment of Misorder

MGCP does not mandate that the underlying transport protocol guarantees in-order delivery of commands to a gateway or an endpoint. This property tends to maximize the timeliness of actions, but it has a few drawbacks. For example: * Notify commands may be delayed and arrive at the Call Agent after the transmission of a new Notification Request command, * If a new NotificationRequest is transmitted before a previous one is acknowledged, there is no guarantee that the previous one will not be received and executed after the new one. Call Agents that want to guarantee consistent operation of the endpoints can use the following rules: 1) When a gateway handles several endpoints, commands pertaining to the different endpoints can be sent in parallel, for example following a model where each endpoint is controlled by its own process or its own thread. 2) When several connections are created on the same endpoint, commands pertaining to different connections can be sent in parallel.
Top   ToC   RFC3435 - Page 136
   3) On a given connection, there should normally be only one
      outstanding command (create or modify).  However, a
      DeleteConnection command can be issued at any time.  In
      consequence, a gateway may sometimes receive a ModifyConnection
      command that applies to a previously deleted connection.  Such
      commands will fail, and an error code MUST be returned (error code
      515 - incorrect connection-id, is RECOMMENDED).

   4) On a given endpoint, there should normally be only one outstanding
      NotificationRequest command at any time.  The RequestId parameter
      MUST be used to correlate Notify commands with the triggering
      notification request.

   5) In some cases, an implicitly or explicitly wildcarded
      DeleteConnection command that applies to a group of endpoints can
      step in front of a pending CreateConnection command.  The Call
      Agent should individually delete all connections whose completion
      was pending at the time of the global DeleteConnection command.
      Also, new CreateConnection commands for endpoints named by the
      wild-carding SHOULD NOT be sent until the wild-carded
      DeleteConnection command is acknowledged.

   6) When commands are embedded within each other, sequencing
      requirements for all commands must be adhered to.  For example a
      Create Connection command with a Notification Request in it must
      adhere to the sequencing requirements associated with both
      CreateConnection and NotificationRequest at the same time.

   7) AuditEndpoint and AuditConnection are not subject to any
      sequencing requirements.

   8) RestartInProgress MUST always be the first command sent by an
      endpoint as defined by the restart procedure.  Any other command
      or non-restart response (see Section 4.4.6), except for responses
      to auditing, MUST be delivered after this RestartInProgress
      command (piggybacking allowed).

   9) When multiple messages are piggybacked in a single packet, the
      messages are always processed in order.

   10) On a given endpoint, there should normally be only one
      outstanding EndpointConfiguration command at any time.

   Gateways MUST NOT make any assumptions as to whether Call Agents
   follow these rules or not.  Consequently gateways MUST always respond
   to commands, regardless of whether they adhere to the above rules or
   not.  To ensure consistent operation, gateways SHOULD behave as
   specified below when one or more of the above rules are not followed:
Top   ToC   RFC3435 - Page 137
   * Where a single outstanding command is expected (ModifyConnection,
     NotificationRequest, and EndpointConfiguration), but the same
     command is received in a new transaction before the old finishes
     executing, the gateway SHOULD fail the previous command.  This
     includes the case where one or more of the commands were
     encapsulated.  The use of error code 407 (transaction aborted) is
     RECOMMENDED.

   * If a ModifyConnection command is received for a pending
     CreateConnection command, the ModifyConnection command SHOULD
     simply be rejected.  The use of error code 400 (transient error) is
     RECOMMENDED.  Note that this situation constitutes a Call Agent
     programming error.

   * If a DeleteConnection command is received for a pending
     CreateConnection or ModifyConnection command, the pending command
     MUST be aborted.  The use of error code 407 (transaction aborted)
     is RECOMMENDED.

   Note, that where reception of a new command leads to aborting an old
   command, the old command SHOULD be aborted regardless of whether the
   new command succeeds or not.  For example, if a ModifyConnection
   command is aborted by a DeleteConnection command which itself fails
   due to an encapsulated NotificationRequest, the ModifyConnection
   command is still aborted.

4.4.5 Endpoint Service States

As described earlier, endpoints configured for operation may be either in-service or out-of-service. The actual service-state of the endpoint is reflected by the combination of the RestartMethod and RestartDelay parameters, which are sent with RestartInProgress commands (Section 2.3.12) and furthermore may be audited in AuditEndpoint commands (Section 2.3.10). The service-state of an endpoint affects how it processes a command. An endpoint in-service MUST process any command received, whereas an endpoint that is out-of-service MUST reject non-auditing commands, but SHOULD process auditing commands if possible. For backwards compatibility, auditing commands for an out-of-service endpoint may alternatively be rejected as well. Any command rejected due to an endpoint being out-of-service SHOULD generate error code 501 (endpoint not ready/out-of-service). Note that (per Section 2.1.2), unless otherwise specified for a command, endpoint names containing the "any of" wildcard only refer to endpoints in-service, whereas endpoint names containing the "all of" wildcard refer to all endpoints, regardless of service state.
Top   ToC   RFC3435 - Page 138
   The above relationships are illustrated in the table below which
   shows the current service-states and gateway processing of commands
   as a function of the RestartInProgress command sent and the response
   (if any) received to it.  The last column also lists (in parentheses)
   the RestartMethod to be returned if audited:
Top   ToC   RFC3435 - Page 139
    ------------------------------------------------------------------
   | Restart-  | Restart- |    2xx    | Service- |   Response to      |
   |    Method |    Delay | received ?|    State |   new command      |
   |------------------------------------------------------------------|
   | graceful  |   zero   |   Yes/No  |   In     | non-audit: 2xx     |
   |           |          |           |          | audit:     2xx     |
   |           |          |           |          |        (graceful)  |
   |-----------+----------+-----------+----------+--------------------|
   | graceful  | non-zero |   Yes/No  |   In*    | non-audit: 2xx     |
   |           |          |           |          | audit:     2xx     |
   |           |          |           |          |        (graceful)  |
   |-----------+----------+-----------+----------+--------------------|
   | forced    |   N/A    |   Yes/No  |   Out    | non-audit: 501     |
   |           |          |           |          | audit:     2xx     |
   |           |          |           |          |         (forced)   |
   |-----------+----------+-----------+----------+--------------------|
   | restart   |   zero   |    No     |   In     | non-audit: 2xx,405*|
   |           |          |           |          | audit:     2xx     |
   |           |          |           |          |         (restart)  |
   |-----------+----------+-----------+----------+--------------------|
   | restart   |   zero   |    Yes    |   In     | non-audit: 2xx     |
   |           |          |           |          | audit:     2xx     |
   |           |          |           |          |         (restart)  |
   |-----------+----------+-----------+----------+--------------------|
   | restart   | non-zero |    No     |   Out*   | non-audit: 501*    |
   |           |          |           |          | audit:     2xx     |
   |           |          |           |          |         (restart)  |
   |-----------+----------+-----------+----------+--------------------|
   | restart   | non-zero |    Yes    |   Out*   | non-audit: 501*    |
   |           |          |           |          | audit:     2xx     |
   |           |          |           |          |         (restart)  |
   |-----------+----------+-----------+----------+--------------------|
   | discon-   |   zero/  |    No     |   In     | non-audit: 2xx,    |
   |    nected | non-zero |           |          | audit:     2xx     |
   |           |          |           |          |      (disconnected)|
   |-----------+----------+-----------+----------+--------------------|
   | discon-   |   zero/  |    Yes    |   In     | non-audit: 2xx     |
   |    nected | non-zero |           |          | audit:     2xx     |
   |           |          |           |          |         (restart)  |
   |-----------+----------+-----------+----------+--------------------|
   | cancel-   |   N/A    |   Yes/No  |   In     | non-audit: 2xx     |
   |  graceful |          |           |          | audit:     2xx     |
   |           |          |           |          |         (restart)  |
    ------------------------------------------------------------------
Top   ToC   RFC3435 - Page 140
   Notes (*):

   * The three service-states marked with "*" will change after the
     expiration of the RestartDelay at which time an updated
     RestartInProgress command SHOULD be sent.

   * If the endpoint returns 2xx when the restart procedure has not yet
     completed, then in-order delivery MUST still be satisfied, i.e.,
     piggy-backing is to be used.  If instead, the command is not
     processed, 405 SHOULD be returned.

   * Following a "restart" RestartInProgress with a non-zero
     RestartDelay, error code 501 is only returned until the endpoint
     goes in-service, i.e., until the expiration of the RestartDelay.

4.4.6 Fighting the Restart Avalanche

Let's suppose that a large number of gateways are powered on simultaneously. If they were to all initiate a RestartInProgress transaction, the Call Agent would very likely be swamped, leading to message losses and network congestion during the critical period of service restoration. In order to prevent such avalanches, the following behavior is REQUIRED: 1) When a gateway is powered on, it MUST initiate a restart timer to a random value, uniformly distributed between 0 and a maximum waiting delay (MWD). Care should be taken to avoid synchronicity of the random number generation between multiple gateways that would use the same algorithm. 2) The gateway MUST then wait for either the end of this timer, the reception of a command from the Call Agent, or the detection of a local user activity, such as for example an off-hook transition on a residential gateway. 3) When the timer elapses, when a command is received, or when an activity is detected, the gateway MUST initiate the restart procedure. The restart procedure simply requires the endpoint to guarantee that the first * non-audit command, or * non-restart response (i.e., error codes other than 405, 501, and 520) to a non-audit command
Top   ToC   RFC3435 - Page 141
   that the Call Agent sees from this endpoint is a "restart"
   RestartInProgress command.  The endpoint is free to take full
   advantage of piggybacking to achieve this.  Endpoints that are
   considered in-service will have a RestartMethod of "restart", whereas
   endpoints considered out-of-service will have a RestartMethod of
   "forced" (also see Section 4.4.5).  Commands rejected due to an
   endpoint not yet having completed the restart procedure SHOULD use
   error code 405 (endpoint "restarting").

   The restart procedure is complete once a success response has been
   received.  If an error response is received, the subsequent behavior
   depends on the error code in question:

   * If the error code indicates a transient error (4xx), then the
     restart procedure MUST be initiated again (as a new transaction).

   * If the error code is 521, then the endpoint is redirected, and the
     restart procedure MUST be initiated again (as a new transaction).
     The 521 response MUST have included a NotifiedEntity which then is
     the "notified entity" towards which the restart is initiated.  If
     it did not include a NotifiedEntity, the response is treated as any
     other permanent error (see below).

   * If the error is any other permanent error (5xx), and the endpoint
     is not able to rectify the error, then the endpoint no longer
     initiates the restart procedure on its own (until
     rebooted/restarted) unless otherwise specified.  If a command is
     received for the endpoint, the endpoint MUST initiate the restart
     procedure again.

   Note that if the RestartInProgress is piggybacked with the response
   (R) to a command received while restarting, then retransmission of
   the RestartInProgress does not require piggybacking of the response
   R.  However, while the endpoint is restarting, a resend of the
   response R does require the RestartInProgress to be piggybacked to
   ensure in-order delivery of the two.

   Should the gateway enter the "disconnected" state while carrying out
   the restart procedure, the disconnected procedure specified in
   Section 4.4.7 MUST be carried out, except that a "restart" rather
   than "disconnected" message is sent during the procedure.

   Each endpoint in a gateway will have a provisionable Call Agent,
   i.e., "notified entity", to direct the initial restart message
   towards.  When the collection of endpoints in a gateway is managed by
   more than one Call Agent, the above procedure MUST be performed for
   each collection of endpoints managed by a given Call Agent.  The
   gateway MUST take full advantage of wild-carding to minimize the
Top   ToC   RFC3435 - Page 142
   number of RestartInProgress messages generated when multiple
   endpoints in a gateway restart and the endpoints are managed by the
   same Call Agent.  Note that during startup, it is possible for
   endpoints to start out as being out-of-service, and then become in-
   service as part of the gateway initialization procedure.  A gateway
   may thus choose to send first a "forced" RestartInProgress for all
   its endpoints, and subsequently a "restart" RestartInProgress for the
   endpoints that come in-service.  Alternatively, the gateway may
   simply send "restart" RestartInProgress for only those endpoints that
   are in-service, and "forced" RestartInProgress for the specific
   endpoints that are out-of-service.  Wild-carding MUST still be used
   to minimize the number of messages sent though.

   The value of MWD is a configuration parameter that depends on the
   type of the gateway.  The following reasoning can be used to
   determine the value of this delay on residential gateways.

   Call agents are typically dimensioned to handle the peak hour traffic
   load, during which, in average, 10% of the lines will be busy,
   placing calls whose average duration is typically 3 minutes.  The
   processing of a call typically involves 5 to 6 MGCP transactions
   between each endpoint and the Call Agent.  This simple calculation
   shows that the Call Agent is expected to handle 5 to 6 transactions
   for each endpoint, every 30 minutes on average, or, to put it
   otherwise, about one transaction per endpoint every 5 to 6 minutes on
   average.  This suggest that a reasonable value of MWD for a
   residential gateway would be 10 to 12 minutes.  In the absence of
   explicit configuration, residential gateways should adopt a value of
   600 seconds for MWD.

   The same reasoning suggests that the value of MWD should be much
   shorter for trunking gateways or for business gateways, because they
   handle a large number of endpoints, and also because the usage rate
   of these endpoints is much higher than 10% during the peak busy hour,
   a typical value being 60%.  These endpoints, during the peak hour,
   are thus expected to contribute about one transaction per minute to
   the Call Agent load.  A reasonable algorithm is to make the value of
   MWD per "trunk" endpoint six times shorter than the MWD per
   residential gateway, and also inversely proportional to the number of
   endpoints that are being restarted.  For example MWD should be set to
   2.5 seconds for a gateway that handles a T1 line, or to 60
   milliseconds for a gateway that handles a T3 line.
Top   ToC   RFC3435 - Page 143

4.4.7 Disconnected Endpoints

In addition to the restart procedure, gateways also have a "disconnected" procedure, which MUST be initiated when an endpoint becomes "disconnected" as described in Section 4.3. It should here be noted, that endpoints can only become disconnected when they attempt to communicate with the Call Agent. The following steps MUST be followed by an endpoint that becomes "disconnected": 1. A "disconnected" timer is initialized to a random value, uniformly distributed between 1 and a provisionable "disconnected" initial waiting delay (Tdinit), e.g., 15 seconds. Care MUST be taken to avoid synchronicity of the random number generation between multiple gateways and endpoints that would use the same algorithm. 2. The gateway then waits for either the end of this timer, the reception of a command for the endpoint from the Call Agent, or the detection of a local user activity for the endpoint, such as for example an off-hook transition. 3. When the "disconnected" timer elapses for the endpoint, when a command is received for the endpoint, or when local user activity is detected for the endpoint, the gateway initiates the "disconnected" procedure for the endpoint - if a disconnected procedure was already in progress for the endpoint, it is simply replaced by the new one. Furthermore, in the case of local user activity, a provisionable "disconnected" minimum waiting delay (Tdmin) MUST have elapsed since the endpoint became disconnected or the last time it ended the "disconnected" procedure in order to limit the rate at which the procedure is performed. If Tdmin has not passed, the endpoint simply proceeds to step 2 again, without affecting any disconnected procedure already in progress. 4. If the "disconnected" procedure still left the endpoint disconnected, the "disconnected" timer is then doubled, subject to a provisionable "disconnected" maximum waiting delay (Tdmax), e.g., 600 seconds, and the gateway proceeds with step 2 again (using a new transaction-id). The "disconnected" procedure is similar to the restart procedure in that it simply states that the endpoint MUST send a RestartInProgress command to the Call Agent informing it that the endpoint was disconnected. Furthermore, the endpoint MUST guarantee that the first non-audit message (non-audit command or response to non-audit command) that the Call Agent sees from this endpoint MUST inform the Call Agent that the endpoint is disconnected (unless the endpoint goes out-of-service). When a command (C) is received, this is achieved by sending a piggy-backed datagram with a "disconnected"
Top   ToC   RFC3435 - Page 144
   RestartInProgress command and the response to command C to the source
   address of command C as opposed to the current "notified entity".
   This piggy-backed RestartInProgress is not automatically
   retransmitted by the endpoint but simply relies on fate-sharing with
   the piggy-backed response to guarantee the in-order delivery
   requirement.  The Call Agent still sends a response to the piggy-
   backed RestartInProgress, however, as usual, the response may be
   lost.  In addition to the piggy-backed RestartInProgress command, a
   new "disconnected" procedure is triggered by the command received.
   This will lead to a non piggy-backed copy (i.e., same transaction) of
   the "disconnected" RestartInProgress command being sent reliably to
   the current "notified entity".

   When the Call Agent learns that the endpoint is disconnected, the
   Call Agent may then for instance decide to audit the endpoint, or
   simply clear all connections for the endpoint.  Note that each such
   "disconnected" procedure will result in a new RestartInProgress
   command, which will be subject to the normal retransmission
   procedures specified in Section 4.3.  At the end of the procedure,
   the endpoint may thus still be "disconnected".  Should the endpoint
   go out-of-service while being disconnected, it SHOULD send a "forced"
   RestartInProgress message as described in Section 2.3.12.

   The disconnected procedure is complete once a success response has
   been received.  Error responses are handled similarly to the restart
   procedure (Section 4.4.6).  If the "disconnected" procedure is to be
   initiated again following an error response, the rate-limiting timer
   considerations specified above still apply.

   Note, that if the RestartInProgress is piggybacked with the response
   (R) to a command received while being disconnected, then
   retransmission of this particular RestartInProgress does not require
   piggybacking of the response R.  However, while the endpoint is
   disconnected, resending the response R does require the
   RestartInProgress to be piggybacked with the response to ensure the
   in-order delivery of the two.

   If a set of disconnected endpoints have the same "notified entity",
   and the set of endpoints can be named with a wildcard, the gateway
   MAY replace the individual disconnected procedures with a suitably
   wildcarded disconnected procedure instead.  In that case, the Restart
   Delay for the wildcarded "disconnected" RestartInProgress command
   SHALL be the Restart Delay corresponding to the oldest disconnected
   procedure replaced.  Note that if only a subset of these endpoints
   subsequently have their "notified entity" changed and/or are no
   longer disconnected, then that wildcarded disconnected procedure can
   no longer be used.  The remaining individual disconnected procedures
   MUST then be resumed again.
Top   ToC   RFC3435 - Page 145
   A disconnected endpoint may wish to send a command (besides
   RestartInProgress) while it is disconnected.  Doing so will only
   succeed once the Call Agent is reachable again, which raises the
   question of what to do with such a command meanwhile.  At one
   extreme, the endpoint could drop the command right away, however that
   would not work very well when the Call Agent was in fact available,
   but the endpoint had not yet completed the "disconnected" procedure
   (consider for example the case where a NotificationRequest was just
   received which immediately resulted in a Notify being generated).  To
   prevent such scenarios, disconnected endpoints SHALL NOT blindly drop
   new commands to be sent for a period of T-MAX seconds after they
   receive a non-audit command.

   One way of satisfying this requirement is to employ a temporary
   buffering of commands to be sent, however in doing so, the endpoint
   MUST ensure, that it:

   * does not build up a long queue of commands to be sent,

   * does not swamp the Call Agent by rapidly sending too many commands
     once it is connected again.

   Buffering commands for T-MAX seconds and, once the endpoint is
   connected again, limiting the rate at which buffered commands are
   sent to one outstanding command per endpoint is considered acceptable
   (see also Section 4.4.8, especially if using wildcards).  If the
   endpoint is not connected within T-MAX seconds, but a "disconnected"
   procedure is initiated within T-MAX seconds, the endpoint MAY
   piggyback the buffered command(s) with that RestartInProgress.  Note,
   that once a command has been sent, regardless of whether it was
   buffered initially, or piggybacked earlier, retransmission of that
   command MUST cease T-MAX seconds after the initial send as described
   in Section 4.3.

   This specification purposely does not specify any additional behavior
   for a disconnected endpoint.  Vendors MAY for instance choose to
   provide silence, play reorder tone, or even enable a downloaded wav
   file to be played.

   The default value for Tdinit is 15 seconds, the default value for
   Tdmin, is 15 seconds, and the default value for Tdmax is 600 seconds.
Top   ToC   RFC3435 - Page 146

4.4.8 Load Control in General

The previous sections have described several MGCP mechanisms to deal with congestion and overload, namely: * the UDP retransmission strategy which adapts to network and call agent congestion on a per endpoint basis, * the guidelines on the ordering of commands which limit the number of commands issued in parallel, * the restart procedure which prevents flooding in case of a restart avalanche, and * the disconnected procedure which prevents flooding in case of a large number of disconnected endpoints. It is however still possible for a given set of endpoints, either on the same or different gateways, to issue one or more commands at a given point in time. Although it can be argued, that Call Agents should be sized to handle one message per served endpoint at any given point in time, this may not always be the case in practice. Similarly, gateways may not be able to handle a message for all of its endpoints at any given point in time. In general, such issues can be dealt with through the use of a credit-based mechanism, or by monitoring and automatically adapting to the observed behavior. We opt for the latter approach as follows. Conceptually, we assume that Call Agents and gateways maintain a queue of incoming transactions to be executed. Associated with this transaction queue is a high-water and a low-water mark. Once the queue length reaches the high-water mark, the entity SHOULD start issuing 101 provisional responses (transaction queued) until the queue length drops to the low-water mark. This applies to new transactions as well as to retransmissions. If the entity is unable to process any new transactions at this time, it SHOULD return error code 409 (processing overload). Furthermore, gateways SHOULD adjust the sending rate of new commands to a given Call Agent by monitoring the observed response times from that Call Agent to a *set* of endpoints. If the observed smoothed average response time suddenly rises significantly over some threshold, or the gateway receives a 101 (transaction queued) or 409 (overload) response, the gateway SHOULD adjust the sending rate of new commands to that Call Agent accordingly. The details of the smoothing average algorithm, the rate adjustments, and the thresholds involved are for further study, however they MUST be configurable.
Top   ToC   RFC3435 - Page 147
   Similarly, Call Agents SHOULD adjust the sending rate of new
   transactions to a given gateway by monitoring the observed response
   times from that gateway for a *set* of endpoints.  If the observed
   smoothed average response time suddenly rises significantly over some
   threshold, or the Call Agent receives a 101 (transaction queued) or
   409 (overloaded), the Call Agent SHOULD adjust the sending rate of
   new commands to that gateway accordingly.  The details of the
   smoothing average algorithm, the rate adjustments, and the thresholds
   involved are for further study, however they MUST be configurable.

5. Security Requirements

Any entity can send a command to an MGCP endpoint. If unauthorized entities could use the MGCP, they would be able to set-up unauthorized calls, or to interfere with authorized calls. We expect that MGCP messages will always be carried over secure Internet connections, as defined in the IP security architecture as defined in RFC 2401, using either the IP Authentication Header, defined in RFC 2402, or the IP Encapsulating Security Payload, defined in RFC 2406. The complete MGCP protocol stack would thus include the following layers: ------------------------------- | MGCP | |-------------------------------| | UDP | |-------------------------------| | IP security | | (authentication or encryption)| |-------------------------------| | IP | |-------------------------------| | transmission media | ------------------------------- Adequate protection of the connections will be achieved if the gateways and the Call Agents only accept messages for which IP security provided an authentication service. An encryption service will provide additional protection against eavesdropping, thus preventing third parties from monitoring the connections set up by a given endpoint. The encryption service will also be requested if the session descriptions are used to carry session keys, as defined in SDP.
Top   ToC   RFC3435 - Page 148
   These procedures do not necessarily protect against denial of service
   attacks by misbehaving gateways or misbehaving Call Agents.  However,
   they will provide an identification of these misbehaving entities,
   which should then be deprived of their authorization through
   maintenance procedures.

5.1 Protection of Media Connections

MGCP allows Call Agent to provide gateways with "session keys" that can be used to encrypt the audio messages, protecting against eavesdropping. A specific problem of packet networks is "uncontrolled barge-in". This attack can be performed by directing media packets to the IP address and UDP port used by a connection. If no protection is implemented, the packets will be decoded and the signals will be played on the "line side". A basic protection against this attack is to only accept packets from known sources, however this tends to conflict with RTP principles. This also has two inconveniences: it slows down connection establishment and it can be fooled by source spoofing: * To enable the address-based protection, the Call Agent must obtain the source address of the egress gateway and pass it to the ingress gateway. This requires at least one network round trip, and leaves us with a dilemma: either allow the call to proceed without waiting for the round trip to complete, and risk for example "clipping" a remote announcement, or wait for the full round trip and settle for slower call-set-up procedures. * Source spoofing is only effective if the attacker can obtain valid pairs of source and destination addresses and ports, for example by listening to a fraction of the traffic. To fight source spoofing, one could try to control all access points to the network. But this is in practice very hard to achieve. An alternative to checking the source address is to encrypt and authenticate the packets, using a secret key that is conveyed during the call set-up procedure. This will not slow down the call set-up, and provides strong protection against address spoofing.

6. Packages

As described in Section 2.1.6, packages are the preferred way of extending MGCP. In this section we describe the requirements associated with defining a package.
Top   ToC   RFC3435 - Page 149
   A package MUST have a unique package name defined.  The package name
   MUST be registered with the IANA, unless it starts with the
   characters "x-" or "x+" which are reserved for experimental packages.
   Please refer to Appendix C for IANA considerations.

   A package MUST also have a version defined which is simply a non-
   negative integer.  The default and initial version of a package is
   zero, the next version is one, etc.  New package versions MUST be
   completely backwards compatible, i.e., a new version of a package
   MUST NOT redefine or remove any of the extensions provided in an
   earlier version of the package.  If such a need arises, a new package
   name MUST be used instead.

   Packages containing signals of type time-out MAY indicate if the "to"
   parameter is supported for all the time-out signals in the package as
   well as the default rounding rules associated with these (see Section
   3.2.2.4).  If no such definition is provided, each time-out signal
   SHOULD provide these definitions.

   A package defines one or more of the following extensions:

   * Actions

   * BearerInformation

   * ConnectionModes

   * ConnectionParameters

   * DigitMapLetters

   * Events and Signals

   * ExtensionParameters

   * LocalConnectionOptions

   * ReasonCodes

   * RestartMethods

   * Return codes

   For each of the above types of extensions supported by the package,
   the package definition MUST contain a description of the extension as
   defined in the following sections.  Please note, that package
   extensions, just like any other extension, MUST adhere to the MGCP
   grammar.
Top   ToC   RFC3435 - Page 150

6.1 Actions

Extension Actions SHALL include: * The name and encoding of the extension action. * If the extension action takes any action parameters, then the name, encoding, and possible values of those parameters. * A description of the operation of the extension action. * A listing of the actions in this specification the extension can be combined with. If such a listing is not provided, it is assumed that the extension action cannot be combined with any other action in this specification. * If more than one extension action is defined in the package, then a listing of the actions in the package the extension can be combined with. If such a listing is not provided, it is assumed that the extension action cannot be combined with any other action in the package. Extension actions defined in two or more different packages SHOULD NOT be used simultaneously, unless very careful consideration to their potential interaction and side-effects has been given.

6.2 BearerInformation

BearerInformation extensions SHALL include: * The name and encoding of the BearerInformation extension. * The possible values and encoding of those values that can be assigned to the BearerInformation extension. * A description of the operation of the BearerInformation extension. As part of this description the default value (if any) if the extension is omitted in an EndpointConfiguration command MUST be defined. It may be necessary to make a distinction between the default value before and after the initial application of the parameter, for example if the parameter retains its previous value once specified, until explicitly altered. If default values are not described, then the extension parameter simply defaults to empty in all EndpointConfiguration commands. Note that the extension SHALL be included in the result for an AuditEndpoint command auditing the BearerInformation.
Top   ToC   RFC3435 - Page 151

6.3 ConnectionModes

Extension Connection Modes SHALL include: * The name and encoding of the extension connection mode. * A description of the operation of the extension connection mode. * A description of the interaction a connection in the extension connection mode will have with other connections in each of the modes defined in this specification. If such a description is not provided, the extension connection mode MUST NOT have any interaction with other connections on the endpoint. Extension connection modes SHALL NOT be included in the list of modes in a response to an AuditEndpoint for Capabilities, since the package will be reported in the list of packages.

6.4 ConnectionParameters

Extension Connection Parameters SHALL include: * The name and encoding of the connection parameter extension. * The possible values and encoding of those values that can be assigned to the connection parameter extension. * A description of how those values are derived. Note that the extension connection parameter MUST be included in the result for an AuditConnection command auditing the connection parameters.

6.5 DigitMapLetters

Extension Digit Map Letters SHALL include: * The name and encoding of the extension digit map letter(s). * A description of the meaning of the extension digit map letter(s). Note that extension DigitMapLetters in a digit map do not follow the normal naming conventions for extensions defined in packages. More specifically the package name and slash ("/") will not be part of the extension name, thereby forming a flat and limited name space with potential name clashing.
Top   ToC   RFC3435 - Page 152
   Therefore, a package SHALL NOT define a digit map letter extension
   whose encoding has already been used in another package.  If two
   packages have used the same encoding for a digit map letter
   extension, and those two packages are supported by the same endpoint,
   the result of using that digit map letter extension is undefined.

   Note that although an extension DigitMapLetter does not include the
   package name prefix and slash ("/") as part of the extension name
   within a digit map, the package name prefix and slash are included
   when the event code for the event that matched the DigitMapLetter is
   reported as an observed event.  In other words, the digit map just
   define the matching rule(s), but the event is still reported like any
   other event.

6.6 Events and Signals

The event/signal definition SHALL include the precise name of the event/signal (i.e., the code used in MGCP), a plain text definition of the event/signal, and, when appropriate, the precise definition of the corresponding events/signals, for example the exact frequencies of audio signals such as dial tones or DTMF tones. The package description MUST provide, for each event/signal, the following information: * The description of the event/signal and its purpose, which SHOULD include the actual signal that is generated by the client (e.g., xx ms FSK tone) as well as the resulting user observed result (e.g., Message Waiting light on/off). The event code used for the event/signal. * The detailed characteristics of the event/signal, such as for example frequencies and amplitude of audio signals, modulations and repetitions. Such details may be country specific. * The typical and maximum duration of the event/signal if applicable. * If the signal or event can be applied to a connection (across a media stream), it MUST be indicated explicitly. If no such indication is provided, it is assumed that the signal or event cannot be applied to a connection. For events, the following MUST be provided as well: * An indication if the event is persistent. By default, events are not persistent - defining events as being persistent is discouraged (see Appendix B for a preferred alternative). Note that persistent
Top   ToC   RFC3435 - Page 153
     events will automatically trigger a Notify when they occur, unless
     the Call Agent explicitly instructed the endpoint otherwise.  This
     not only violates the normal MGCP model, but also assumes the Call
     Agent supports the package in question.  Such an assumption is
     unlikely to hold in general.

   * An indication if there is an auditable event-state associated with
     the event.  By default, events do not have auditable event-states.

   * If event parameters are supported, it MUST be stated explicitly.
     The precise syntax and semantics of these MUST then be provided
     (subject to the grammar provided in Appendix A).  It SHOULD also be
     specified whether these parameters apply to RequestedEvents,
     ObservedEvents, DetectEvents and EventStates.  If not specified
     otherwise, it is assumed that:

     * they do not apply to RequestedEvents,

     * they do apply to ObservedEvents,

     * they apply in the same way to DetectEvents as they do to
       RequestedEvents for a given event parameter,

     * they apply in the same way to EventStates as they do to
       ObservedEvents for a given event parameter.

   * If the event is expected to be used in digit map matching, it
     SHOULD explicitly state so.  Note that only events with single
     letter or digit parameter codes can do this.  See Section 2.1.5 for
     further details.

   For signals, the following MUST be provided as well:

   * The type of signal (OO, TO, BR).

   * Time-Out signals SHOULD have an indication of the default time-out
     value.  In some cases, time-out values may be variable (if
     dependent on some action to complete such as out-pulsing digits).

   * If signal parameters are supported, it MUST be stated explicitly.
     The precise syntax and semantics of these MUST then be provided
     (subject to the grammar provided in Appendix A).

   * Time-Out signals may also indicate whether the "to" parameter is
     supported or not as well as what the rounding rules associated with
     them are.  If omitted from the signal definition, the package-wide
     definition is assumed (see Section 6).  If the package definition
     did not specify this, rounding rules default to the nearest non-
Top   ToC   RFC3435 - Page 154
     zero second, whereas support for the "to" parameter defaults to
     "no" for package version zero, and "yes" for package versions one
     and higher.

   The following format is RECOMMENDED for defining events and signals
   in conformance with the above:

    ------------------------------------------------------------------
   | Symbol  |   Definition               |  R  |   S     Duration    |
   |---------|----------------------------|-----|---------------------|
   |         |                            |     |                     |
   |         |                            |     |                     |
    ------------------------------------------------------------------

   where:

   * Symbol indicates the event code used for the event/signal, e.g.,
     "hd".

   * Definition gives a brief definition of the event/signal

   * R contains an "x" if the event can be detected or one or more of
     the following symbols:

     - "P" if the event is persistent.

     - "S" if the events is an event-state that may be audited.

     - "C" if the event can be detected on a connection.

   * S contains one of the following if it is a signal:

     - "OO" if the signal is On/Off signal.

     - "TO" if the signal is a Time-Out signal.

     - "BR" if the signal is a Brief signal.

   * S also contains:

     - "C" if the signal can be applied on a connection.

   The table SHOULD then be followed by a more comprehensive description
   of each event/signal defined.
Top   ToC   RFC3435 - Page 155

6.6.1 Default and Reserved Events

All packages that contain Time-Out type signals contain the operation failure ("of") and operation complete ("oc") events, irrespective of whether they are provided as part of the package description or not. These events are needed to support Time-Out signals and cannot be overridden in packages with Time-Out signals. They MAY be extended if necessary, however such practice is discouraged. If a package without Time-Out signals does contain definitions for the "oc" and "of" events, the event definitions provided in the package MAY over-ride those indicated here. Such practice is however discouraged and is purely allowed to avoid potential backwards compatibility problems. It is considered good practice to explicitly mention that the two events are supported in accordance with their default definitions, which are as follows: ------------------------------------------------------------------ | Symbol | Definition | R | S Duration | |---------|----------------------------|-----|---------------------| | oc | Operation Complete | x | | | of | Operation Failure | x | | ------------------------------------------------------------------ Operation complete (oc): The operation complete event is generated when the gateway was asked to apply one or several signals of type TO on the endpoint or connection, and one or more of those signals completed without being stopped by the detection of a requested event such as off-hook transition or dialed digit. The completion report should carry as a parameter the name of the signal that came to the end of its live time, as in: O: G/oc(G/rt) In this case, the observed event occurred because the "rt" signal in the "G" package timed out. If the reported signal was applied on a connection, the parameter supplied will include the name of the connection as well, as in: O: G/oc(G/rt@0A3F58) When the operation complete event is requested, it cannot be parameterized with any event parameters. When the package name is omitted (which is discouraged) as part of the signal name, the default package is assumed.
Top   ToC   RFC3435 - Page 156
   Operation failure (of):  The operation failure event is generated
   when the endpoint was asked to apply one or several signals of type
   TO on the endpoint or connection, and one or more of those signals
   failed prior to timing out.  The completion report should carry as a
   parameter the name of the signal that failed, as in:

      O: G/of(G/rt)

   In this case a failure occurred in producing the "rt" signal in the
   "G" package.

   When the reported signal was applied on a connection, the parameter
   supplied will include the name of the connection as well, as in:

      O: G/of(G/rt@0A3F58)

   When the operation failure event is requested, event parameters can
   not be specified.  When the package name is omitted (which is
   discouraged), the default package name is assumed.

6.7 ExtensionParameters

Extension parameter extensions SHALL include: * The name and encoding of the extension parameter. * The possible values and encoding of those values that can be assigned to the extension parameter. * For each of the commands defined in this specification, whether the extension parameter is Mandatory, Optional, or Forbidden in requests as well as responses. Note that extension parameters SHOULD NOT normally be mandatory. * A description of the operation of the extension parameter. As part of this description the default value (if any) if the extension is omitted in a command MUST be defined. It may be necessary to make a distinction between the default value before and after the initial application of the parameter, for example if the parameter retains its previous value once specified, until explicitly altered. If default values are not described, then the extension parameter simply defaults to empty in all commands. * Whether the extension can be audited in AuditEndpoint and/or AuditConnection as well as the values returned. If nothing is specified, then auditing of the extension parameter can only be done for AuditEndpoint, and the value returned SHALL be the current value for the extension. Note that this may be empty.


(next page on part 7)

Next Section