Network Working Group Kutscher
Internet-Draft TZI, Universitaet Bremen
Expires: August 15, 2001 February 14, 2001
The Message Bus: Guidelines for Application Profile Writers
draft-ietf-mmusic-mbus-guidelines-00.txt
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other documents
at any time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
To view the entire list of Internet-Draft Shadow Directories, see
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 15, 2001.
Copyright Notice
Copyright (C) The Internet Society (2001). All Rights Reserved.
Abstract
This memo defines a list of conventions for terminology, algorithms
and procedures for interaction models that are useful for
applications using the Message Bus (Mbus) [1]. These conventions are
intended as guidelines for designers of Mbus application profiles
and Mbus implementations/applications.
Version Info
$Revision: 2.17 $
$Date: 2001/02/14 14:55:07 $
Kutscher Expires August 15, 2001 [Page 1]
Internet-Draft Mbus Guidelines February 2001
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . 6
3. General Mbus Command Definition Conventions . . . . . 7
3.1 Conventions for parameter encoding . . . . . . . . . . 7
3.2 Parameter Specification for Mbus Commands . . . . . . 7
3.2.1 Optional parameters . . . . . . . . . . . . . . . . . 8
3.2.1.1 Example of a Definition of an Optional Parameter List 9
3.2.1.2 Example for an Mbus Command with an Optional Parameter 9
4. Usage of Mbus Addresses . . . . . . . . . . . . . . . 10
4.1 Example of a Specification of an Addressing Scheme . . 11
5. Mbus Command Classes . . . . . . . . . . . . . . . . . 12
5.1 Remote Commands . . . . . . . . . . . . . . . . . . . 13
5.1.1 Example for a Command Definition . . . . . . . . . . . 13
5.1.2 Example for an Mbus Interaction . . . . . . . . . . . 14
5.2 RPC-style Commands . . . . . . . . . . . . . . . . . . 14
5.2.1 Invoking Remote Procedures . . . . . . . . . . . . . . 14
5.2.2 Returning Results from Remote Procedure Calls . . . . 15
5.2.3 Example for a Command Definition . . . . . . . . . . . 16
5.2.4 Example for an Mbus Interaction . . . . . . . . . . . 17
5.2.5 RPC Communication with Multiple Entities . . . . . . . 17
5.2.5.1 Anycast . . . . . . . . . . . . . . . . . . . . . . . 17
5.2.5.1.1 Example for an Mbus Interaction . . . . . . . . . . . 18
5.2.5.2 One RPC, more than one Result Command . . . . . . . . 19
5.2.5.2.1 Example for an Mbus Interaction . . . . . . . . . . . 20
5.2.5.3 one RPC, coordinated result . . . . . . . . . . . . . 20
5.2.5.3.1 Example for an Mbus Interaction . . . . . . . . . . . 21
5.3 Transactions . . . . . . . . . . . . . . . . . . . . . 21
5.3.1 Example for a Command Definition . . . . . . . . . . . 23
5.3.2 Example for an Mbus Interaction I . . . . . . . . . . 24
5.3.3 Example for an Mbus Interaction II . . . . . . . . . . 25
5.4 Inspection/Modification of Properties . . . . . . . . 25
5.4.1 Example for a Command Definition . . . . . . . . . . . 27
5.4.2 Example for an Mbus Interaction I . . . . . . . . . . 28
5.4.3 Example for an Mbus Interaction II . . . . . . . . . . 28
5.4.4 Example for an Mbus Interaction III . . . . . . . . . 28
5.5 Event Notifications . . . . . . . . . . . . . . . . . 30
5.5.1 Example for a Command Definition . . . . . . . . . . . 30
5.5.2 Example for an Mbus Interaction . . . . . . . . . . . 30
5.6 Contexts . . . . . . . . . . . . . . . . . . . . . . . 31
5.6.1 Example for a Command Definition . . . . . . . . . . . 31
5.6.2 Example for an Mbus Interaction . . . . . . . . . . . 33
5.7 Status Signaling . . . . . . . . . . . . . . . . . . . 33
5.7.1 Example of a Definition of Status Symbols . . . . . . 34
6. Mbus service models . . . . . . . . . . . . . . . . . 35
6.1 No Control . . . . . . . . . . . . . . . . . . . . . . 36
6.1.1 mbus.register . . . . . . . . . . . . . . . . . . . . 37
6.1.2 mbus.deregister . . . . . . . . . . . . . . . . . . . 37
Kutscher Expires August 15, 2001 [Page 2]
Internet-Draft Mbus Guidelines February 2001
6.1.3 mbus.registered . . . . . . . . . . . . . . . . . . . 38
6.1.4 mbus.get-registered . . . . . . . . . . . . . . . . . 39
6.2 Tight Control . . . . . . . . . . . . . . . . . . . . 39
6.3 Exclusive Tight Control . . . . . . . . . . . . . . . 39
7. Algorithms . . . . . . . . . . . . . . . . . . . . . . 41
7.1 Aggregation of Mbus Addresses . . . . . . . . . . . . 41
7.2 Expansion of Mbus Group Addresses . . . . . . . . . . 41
8. Definition of Constants . . . . . . . . . . . . . . . 42
References . . . . . . . . . . . . . . . . . . . . . . 43
Author's Address . . . . . . . . . . . . . . . . . . . 43
A. Examples for Application Profiles . . . . . . . . . . 44
A.1 Mbus Profile for RTP applications . . . . . . . . . . 44
A.1.1 Configuring a RTP engine . . . . . . . . . . . . . . . 44
A.1.1.1 rtp.set-attributes . . . . . . . . . . . . . . . . . . 44
A.1.1.2 Controlling a RTP engine . . . . . . . . . . . . . . . 45
A.1.1.2.1 rtp.source.mute . . . . . . . . . . . . . . . . . . . 45
A.1.1.3 Events generated by a RTP engine . . . . . . . . . . . 45
A.1.1.3.1 rtp.source.exists . . . . . . . . . . . . . . . . . . 45
A.1.1.3.2 rtp.source.left . . . . . . . . . . . . . . . . . . . 46
A.1.1.3.3 rtp.source.attributes . . . . . . . . . . . . . . . . 46
A.1.1.3.4 rtp.source.reception . . . . . . . . . . . . . . . . . 47
A.1.1.3.5 rtp.source.packet.loss . . . . . . . . . . . . . . . . 47
A.1.1.3.6 rtp.source.active . . . . . . . . . . . . . . . . . . 48
A.1.1.3.7 rtp.source.inactive . . . . . . . . . . . . . . . . . 48
A.1.1.3.8 rtp.source.packet.duration . . . . . . . . . . . . . . 48
A.1.1.3.9 rtp.source.codec . . . . . . . . . . . . . . . . . . . 49
A.1.1.3.10 rtp.source.playout . . . . . . . . . . . . . . . . . . 49
Full Copyright Statement . . . . . . . . . . . . . . . 50
Kutscher Expires August 15, 2001 [Page 3]
Internet-Draft Mbus Guidelines February 2001
1. Introduction
[1] specifies the Mbus transport protocol. This includes the basic
protocol behaviour, representation of PDUs and PDU elements and
operational aspects, such as Mbus configuration. This base
specification can be used to implement the Mbus protocol. Specific
Mbus command sets are not defined in this specification -- they are
expected to be defined in application specific documents.
This document builds on the basic transport specification and tries
to give useful recommendations for writers of Mbus application
profiles in the following areas:
Terminology: We propose common Mbus related terms in order to unify
the terminology used in Mbus application profiles.
Algorithms: A set of algorithms are given that are useful for Mbus
implementors.
Notation Conventions: We propose a set of conventions that can be
used for writing Mbus application profiles, such as
recommendations how to specify the characteristics of an Mbus
command etc.
Representation Conventions: Building upon the representation of
values given in the Mbus transport specification we define
additional representations for more complex data types.
Interaction Models: The transport specification essentially defines
one interaction model for the Mbus: Message passing (with support
for group communication). In this document we propose conventions
for additional interaction models that can be implemented with
the basic Mbus message passing mechanisms.
Kutscher Expires August 15, 2001 [Page 4]
Internet-Draft Mbus Guidelines February 2001
2. Terminology
This section defines some Mbus related terms.
Application profile: A specification of Mbus commands, their
semantics and characteristics for a specific application context.
Fully qualified Mbus address: A unique, fully qualified Mbus address
that denominates exactly one concrete existing Mbus entity at a
given time and can thus not be expanded further.
Addressing scheme: A set of Mbus address key and possible address
values. An Mbus application profile defintion SHOULD contain a
specification of a corresponding addressing scheme.
Kutscher Expires August 15, 2001 [Page 5]
Internet-Draft Mbus Guidelines February 2001
3. General Mbus Command Definition Conventions
This section gives some general recommendations how to specify Mbus
commands and their parameter lists and how to represent certain data
types using Mbus parameter types.
3.1 Conventions for parameter encoding
This section list some useful conventions for encoding values of
commonly used parameter types.
pair: A pair is a list that has exactly two elements, not
necessarily of the same type.
map: A map is a list of pairs where the first element of all pairs
(the keys) is of type T1 and the second element of all pairs
(values) is of type T2. A key value may occur only once. T1 and
T2 may be equal. The map is specified as "map of (T1,T2)".
MbusAddressElement: A Mbus address element is represented as a pair
of strings: The first element represent the address element key
and the second element represents the address element value.
MbusAddress: A Mbus address is represented as a list of
MbusAddressElements, a map of (string,string).
3.2 Parameter Specification for Mbus Commands
This section lists some guidelines how parameters of Mbus commands
should be specified in Mbus application profiles.
1. Each parameter SHOULD be associated with a well-defined Mbus
parameter type, i.e., one of the types specified in [1].
2. Homogeneous lists (i.e. lists that contain elements that are all
of the same type) SHOULD be declared by specifying the element
type, for example "list of string".
3. For heterogeneous lists the type of each element SHOULD be
specified.
4. In the case an optional parameter list is allowed, it SHOULD be
the last parameter and a list of the potential parameters and
their name tags SHOULD be given.
See Section 3.2.1 for recommendations how to specify and use
optional parameters.
Kutscher Expires August 15, 2001 [Page 6]
Internet-Draft Mbus Guidelines February 2001
3.2.1 Optional parameters
Some Mbus command argument lists may be of variable length, i.e.,
some parameters may be optional. The following conventions are
proposed for optional parameters:
o An argument list can have elements that are "optional argument
lists". The elements of those lists are pairs: Each first element
is of type String and represents a name for an optional
parameter. Each second element is the value and can be of
arbitrary type. This allows applications to process optional
parameters independent of their order even when some parameters
are missing.
o A command specification may have a set of predefined optional
parameters. In a command definition, these SHOULD be declared by
listing the names and type definitions. If applicable, naming
conventions for further parameters SHOULD be specified, for
example to distinguish different classes of optional parameters.
o If a command definition requires optional parameters it SHOULD
provide exactly one optional parameters list. It is RECOMMENDED
that the optional parameter list be the last element of the
command's parameter list, as shown in Section 3.2.1.2.
Kutscher Expires August 15, 2001 [Page 7]
Internet-Draft Mbus Guidelines February 2001
3.2.1.1 Example of a Definition of an Optional Parameter List
tools.foo.bar
Remote command (reliable/unreliable)
Parameters:
p1: string
p1 is the value for...
p2: int
p2 is the number of...
p3: list of string
a list of names for...
Optional Parameters:
p4: string
the optional name of...
p5: string
the optional number of...
3.2.1.2 Example for an Mbus Command with an Optional Parameter
Entity A: ---------
"mbus/1.0" 42 65454365 U (app:foo module:gui id:4711-1@192.168.1.1) \
(app:foo module:engine) ()
tools.foo.bar ("gg" 17 ("a" "b") ("p5" 42))
Kutscher Expires August 15, 2001 [Page 8]
Internet-Draft Mbus Guidelines February 2001
4. Usage of Mbus Addresses
Mbus addresses are lists of arbitrary key/value pairs and every Mbus
entity can choose its own Mbus address. Target Mbus addresses can be
partly qualified to allow for group addressing or selecting
receivers by certain application specific key elements that
represent a certain application or service type. Except for the
mandatory id-element the Mbus transport specification [1] does not
define any other elements and it is suggested that Mbus application
profile definitions specify a set of useful address element names
and values for a specific application context.
Example of a fully qualified Mbus address and three partly qualified
Mbus addresses:
(conf:test media:audio module:engine app:rat id:4711-1@192.168.1.1)
(media:audio module:engine)
(module:engine)
()
These address elements might be used to offer a particular service
to other entities and to disambiguate entities sufficiently. Address
elements might also be used to express membership of a certain Mbus
address group. When it is known that an entity will always send
certain messages to a specific address group, an entity will have to
provide the corresponding address elements (with proper keys and
values) to become a member of that group. This depicts the following
uses of Mbus address elements:
1. to signal affiliation to an application context
2. to offer a certain service
3. to receive messages for a certain subgroup (to "tune" to a
specific sub-channel on the Mbus)
It is possible that for a given application context not every
address element is to be used by every involved Mbus entity. Instead
some elements (or values) might be reserved for use by "service
providing entities" while others might be required in order to
receive messages that are addressed to a certain subgroup.
Moreover it should be noted that it may make sense for entities to
adopt more than one command profile and thus make use of more than
one addressing scheme. An entity could provide all address elements
that are required by command profile A and additionally provide all
the required element for profile B.
In the following a list of guidelines is presented how to specify an
Kutscher Expires August 15, 2001 [Page 9]
Internet-Draft Mbus Guidelines February 2001
Mbus addressing scheme for an Mbus profile definition.
A Mbus profile definition SHOULD be a sufficiently self-contained
specification of Mbus commands for a particular application area
together with a specification of an addressing model for Mbus
entities that are supposed to implement or use the commands. It
SHOULD be clear which commands belong to an application profile
definition and what addressing conventions are to be considered.
The following specifies how addressing conventions SHOULD be
defined:
1. List the address element keys that are used.
2. List (or describe) the set of legal values for each element key
and explain the semantics (if applicable).
3. Name the services (or mandatory commands) that an entity
providing certain address element keys/values must
provide/understand.
4. Give examples for complete Mbus addresses using the defined
address elements.
5. For each command that is specified in the profile definition
explain the relation to the address elements. ("This command is
sent to the group xy." or "This command must be understood by
every entity that provides the address element xy:z.")
4.1 Example of a Specification of an Addressing Scheme
TBD
Kutscher Expires August 15, 2001 [Page 10]
Internet-Draft Mbus Guidelines February 2001
5. Mbus Command Classes
The general semantic model for Mbus commands is that commands are
sent as payload of messages from one peer to another receiving
(group of) peer(s) in order to trigger some kind of operation on the
receiving side. On a low level of abstraction every Mbus command can
be modeled like this. However on a higher level of abstraction some
classes of commands can be identified that are used to implement
specific Mbus communication scenarios. The following list decribes
these command classes briefly:
Remote commands: Remote commands are used to trigger an asynchronous
operation on the target system. The command has a name that is
associated with a certain operation on the receiving side and can
be sent together with a list of arguments (that can be empty)
that are interpreted by the receiver. The name and the type
definition of the command are specified in application semantics
definition document. See Section 5.1 for a detailed discussion of
generic remote commands.
RPC-style commands: RPC-commands allow to associate an operation at
an remote entity with an Mbus command and SHOULD be used when a
caller expects a result message from the callee that can return
result parameters of the remote procedure/function call.
Different types of RPC-commands are defined in this
specification. See Section 5.2 for a detailed discussion of
RPC-style commands.
Transactions: Transaction-style commands are similar to remote
commands because they are also used to trigger a remote
operation. Additionally transactions are used in scenarios where
the caller is interested in how/whether the remote operation has
been performed. In general, characteristics of transactions are
atomicity (recoverability), consistency, isolation
(serializability) and durability. This specification defines
procedures for atomic transactions. Consistency, isolation and
durability are to be provided by the Mbus application themselves.
See Section 5.3 for a detailed discussion of transactions.
Properties: Obtaining the value of a named property of another Mbus
entity is a variant of an RPC-style command: One command is sent
that represent a query and one command is returned to the caller
that contains the value. Setting the value of a named variable is
a simple remote command with a parameter for the new value. See
Section 5.4 for a detailed discussion of commands related to
property inspection and manipulation.
Event notification: An entity that frequently sends messages to
inform other entities of certain events sends a command for each
Kutscher Expires August 15, 2001 [Page 11]
Internet-Draft Mbus Guidelines February 2001
state change (or after a certain interval) to a (group of)
receiver(s). These commands are similar to the simple remote
commands because they are also sent asynchronously. See Section
5.5 for a detailed discussion of event notification.
Contexts: Instead of short time interactions between entities that
can be accomplished by RPCs and other command classes contexts
allow for more persistent relationships between entities.
Contexts are scopes for coherent commands that are to be
exchanged within a long-term interaction. Contexts provide the
service of assigning a name to an interaction context that allows
to disambiguate Mbus interactions that use the same commands but
refer to different contexts at the same time. See Section 5.6 for
a detailed discussion of contexts.
The following sections specify useful procedures that SHOULD be
considered when defining Mbus command sets that contain commands of
the aforementioned classes:
5.1 Remote Commands
Simple remote commands (that do not belong to any of the other
classes) require no special procedures or conventions besides the
general recommendations for Mbus command definitions: They SHOULD be
defined in a self-contained profile definition, their applicability,
the command name and the command arguments SHOULD be documented like
proposed in Section 3.2.
5.1.1 Example for a Command Definition
tools.foo.bar
Remote command (reliable/unreliable)
Parameters:
p1: string
p1 is the value for...
p2: int
p2 is the number of...
p3: list of string
a list of names for...
Optional parameters: none
Kutscher Expires August 15, 2001 [Page 12]
Internet-Draft Mbus Guidelines February 2001
5.1.2 Example for an Mbus Interaction
Entity A:
---------
"mbus/1.0" 42 65454365 U (app:foo module:gui id:4711-1@192.168.1.1) \
(app:foo module:engine) ()
tools.foo.bar ("gg" 17 ("a" "b"))
Entity B:
---------
"mbus/1.0" 42 65454365 U (app:foo module:engine id:4712-1@192.168.1.1) \
(app:foo module:gui id:4711-1@192.168.1.1) ()
tools.foo.ok ()
5.2 RPC-style Commands
RPC-style commands are implemented by a command-pair: One command
(with arguments) for triggering the remote procedure call and one
command for the result. There are RPCs for Mbus "point-to-point"
communication and RPC for Mbus group communications. The following
conventions are proposed:
5.2.1 Invoking Remote Procedures
o No restriction is imposed on the command name. The class of the
command ("RPC") SHOULD be mentioned in the command definition.
o The first argument of a RPC command SHOULD be a map of
(string,string) (see Section 3.1) and contain meta information.
The map SHOULD contain an element with the key "ID". The
corresponding value is an arbitrary RPC ID that SHOULD be unique
for the calling entity. For point-to-point RPCs (see Section
5.2.5 for RPCs to groups of entities) the meta information map
SHOULD also contain an element with key "RPC-TYPE" and value
"UNICAST". It is RECOMMENDED that unicast RPCs be sent using
reliable Mbus messages. Multicast RPCs are defined in Section
5.2.5.
o The second argument of a RPC command is of type list and contains
an arbitrary number of RPC parameters. The syntax and the
semantics of this list SHOULD be defined in the definition of the
RPC command.
Kutscher Expires August 15, 2001 [Page 13]
Internet-Draft Mbus Guidelines February 2001
5.2.2 Returning Results from Remote Procedure Calls
o The names of commands for returning RPC result are constructed
using the name of the trigger command and appending the string
".return".
o The first argument of a RPC return command is a map of
(string,string) for meta information that contains the following
information:
The original RPC ID that has been generated by the calling
entity;
Another element with the key of "RPC-STATUS" SHOULD have one
of the following values:
OK: The procedure has been called.
UNKNOWN: No operation is associated with the RPC command. The
command is unknown to the callee.
The RPC-STATUS parameter is used to signal the generic RPC
status and can be used to acknowledge the call of the
specified RPC.
o The second argument of a RPC return command is of type list and
contains a list of return parameters. It is RECOMMENDED that the
first element of this list be of type list, containing
application specific status information.
o The second element SHOULD be of type list and contain further
application specific return parameters. The syntax and the
semantics of this list SHOULD be defined in the definition of the
RPC command.
o The application specific status information list SHOULD contain:
An identifier (type symbol) that signals the general result
(successful or unsuccessful operation) of the RPC. The
possible values are "OK" and "FAILED".
An identifier (type symbol) that represents the application
specific result status of the procedure call. The set of
symbols SHOULD be specified in the definition of the RPC.
A textual description of the status (type string).
If the general result of the RPC is "FAILED" the further
parameters may be omitted although they have been specified in
Kutscher Expires August 15, 2001 [Page 14]
Internet-Draft Mbus Guidelines February 2001
the RPC definition.
5.2.3 Example for a Command Definition
The meta information list (for ID and RPC-TYPE) and the application
status list does not have to be provided in RPC command definitions.
tools.foo.bar
RPC
p1: string
p1 is the value for...
p2: int
p2 is the number of...
p3: list of string
a list of names for...
optional parameters: none
The following application specific result states are defined:
BAR_COMPLETED The bar operation has been called successfully.
NO_SUCH_P1 The p1 parameter is invalid.
FOO_CRASH The foo module crashed during the execution of bar.
return parameters:
r1: int
the value of...
Kutscher Expires August 15, 2001 [Page 15]
Internet-Draft Mbus Guidelines February 2001
5.2.4 Example for an Mbus Interaction
Entity A:
---------
"mbus/1.0" 42 65454365 R (app:foo module:gui id:4711-1@192.168.1.1) \
(app:foo module:engine id:4712-1@192.168.1.1) ()
tools.foo.bar ((("ID" "123") ("RPC-TYPE" "UNICAST")) \
("gg" 17 ("a" "b")))
Entity B:
---------
"mbus/1.0" 57 65454366 U (app:foo module:engine id:4712-1@192.168.1.1) \
(app:foo module:gui id:4711-1@192.168.1.1) ()
tools.foo.bar.return ((("ID" "123") ("RPC-STATUS" "OK")) \
((OK BAR_COMPLETED "Success!") (1)))
5.2.5 RPC Communication with Multiple Entities
Different scenarios for RPCs that are addressed to groups of
entities are defined:
anycast
A sender sends an RPC message to a group of entities and wants
exactly one of the entities to perform the operation and return
results.
one RPC, more than one result command
A sender sends an RPC message to a group of entities and wants
each entity to perform the operation and to return a result.
one RPC, coordinated result
A sender sends a RPC message to a group of entities and expects
each entity to perform the operation but only one result messages
that represents all results of the addressed group.
5.2.5.1 Anycast
The following conventions are proposed for anycast RPCs:
The sender uses a group address as the Mbus target address of the
RPC message using unreliable Mbus message transport.
The command meta-information list SHOULD provide an entry with
key "RPC-TYPE" and value "ANYCAST".
Those of the receiving entities that want to respond to the RPC
Kutscher Expires August 15, 2001 [Page 16]
Internet-Draft Mbus Guidelines February 2001
and are able to perform the requested operation return a
"standby" command in order to signal their disposition to provide
the service. The name of the command is the RPC command name
concatenated with ".standby". The first argument is again a
meta-information list that contains the original RPC-ID. The
target address of this command is an aggregate of the sender
address and the target addres of the RPC und MUST therefore be
sent unreliably. See Section 7.1 for a description of an address
aggregation algorithm.
After a timeout T_anycast (Section 8) the entity that originally
sent the RPC message selects one of the entities that answered
with a "standby" command and sends it the RPC again (in a new
message). This message MUST be sent using reliable Mbus message
transport. The meta-information list of the command contains an
additional entry with a key "REFERENCE". The value is the
sequence number of the received standby message.
The entity that receives the second RPC message now operates as
specified for the regular unicast RPC case.
5.2.5.1.1 Example for an Mbus Interaction
Entity A:
---------
"mbus/1.0" 42 65454365 U (app:foo module:gui id:4711-1@192.168.1.1) \
(module:engine) ()
tools.foo.bar ((("ID" "123") ("RPC-TYPE" "ANYCAST")) ("gg" 17 ("a" "b")))
Entity B:
---------
"mbus/1.0" 57 65454366 U (app:foo module:engine id:4712-1@192.168.1.1) \
() ()
tools.foo.bar.standby ((("ID" "123")))
Entity C:
---------
"mbus/1.0" 83 65454366 U (app:xy module:engine id:4713-1@192.168.1.1) \
() ()
tools.foo.bar.standby ((("ID" "123")))
Entity A:
---------
Kutscher Expires August 15, 2001 [Page 17]
Internet-Draft Mbus Guidelines February 2001
"mbus/1.0" 43 65454367 U (app:foo module:gui id:4711-1@192.168.1.1) \
(app:xy module:engine id:4713-1@192.168.1.1) ()
tools.foo.bar ((("ID" "123") ("RPC-TYPE" "ANYCAST") ("REFERENCE" 83)) \
("gg" 17 ("a" "b")))
Entity C:
---------
"mbus/1.0" 84 65454368 U (app:xy module:engine id:4713-1@192.168.1.1) \
(app:foo module:gui id:4711-1@192.168.1.1) ()
tools.foo.bar.return ((("ID" "123") ("RPC-STATUS" "OK")) \
((OK BAR_COMPLETED "Success!") (1)))
5.2.5.2 One RPC, more than one Result Command
The following conventions are proposed for RPCs that are sent to a
group of entities where each entity responds independently:
The sender uses a group address as the Mbus target address of the
RPC message.
The command meta-information list SHOULD provide an entry with
key "RPC-TYPE" and value "MULTICAST".
The sending entity sends the RPC in a message addressed to an
Mbus address group using unreliable Mbus message transport and
calculates the set of real Mbus addresses (see Section 2) of the
entities that are enclosed in the destination address group. See
Section 7.2 for an algorithm for expanding Mbus group addresses
to real Mbus addresses.
The receiving entities operate as specified for the regular
unicast RPC case, i.e. they try perform the operation and report
the results to the sender of the RPC. The destination address of
the result message MUST be the address of the RPC's sender. The
message MUST be sent reliably.
After an application dependent timeout the entity that originally
sent the RPC evaluates the received results: If all entities
return a RPC-STATUS of "OK" the RPC can be considered successful.
The procedure of how return parameters are gathered, collapsed
and presented to the user is application/implementation specific.
Kutscher Expires August 15, 2001 [Page 18]
Internet-Draft Mbus Guidelines February 2001
5.2.5.2.1 Example for an Mbus Interaction
Entity A:
---------
"mbus/1.0" 42 65454365 U (app:foo module:gui id:4711-1@192.168.1.1) \
(module:engine) ()
tools.foo.bar ((("ID" "123") ("RPC-TYPE" "MULTICAST")) ("gg" 17 ("a" "b")))
Entity B:
---------
"mbus/1.0" 57 65454366 U (app:foo module:engine id:4712-1@192.168.1.1) \
(app:foo module:gui id:4711-1@192.168.1.1) ()
tools.foo.bar.return ((("ID" "123") ("RPC-STATUS" "OK")) \
((OK BAR_COMPLETED "Success!") (1)))
Entity C:
---------
"mbus/1.0" 83 65454366 U (app:xy module:engine id:4713-1@192.168.1.1) \
(app:foo module:gui id:4711-1@192.168.1.1) ()
tools.foo.bar.return ((("ID" "123") ("RPC-STATUS" "OK")) \
((OK BAR_COMPLETED "Success!") (2)))
5.2.5.3 one RPC, coordinated result
The following conventions are proposed for RPCs that are sent to a
group of entities where each entity performs the operation but only
one result messages that represents all results of the addressed
group is sent to the original sender of the RPC:
The sender uses a group address as the Mbus target address of the
RPC message.
The command meta-information list SHOULD provide an entry with
key "RPC-TYPE" and value "COORDINATED".
The sending entity sends the RPC in a message addressed to an
Mbus address group using unreliable Mbus message transport.
The receiving entities try to perform the operation and then send
intermediate result commands to the RPC destination group. After
a timeout T_Coordination one entity aggregates all intermediate
results and sends an aggregated RPC-result message to the
original sender. The coordination process and the procedure how
to decide which entity reports the gathered results is yet TBD.
Kutscher Expires August 15, 2001 [Page 19]
Internet-Draft Mbus Guidelines February 2001
:-(
5.2.5.3.1 Example for an Mbus Interaction
Entity A:
---------
"mbus/1.0" 42 65454365 U (app:foo module:gui id:4711-1@192.168.1.1) \
(module:engine) ()
tools.foo.bar ((("ID" "123") ("RPC-TYPE" "COORDINATED")) ("gg" 17 ("a" "b")))
TBD...
5.3 Transactions
Transactions are implemented by defining a command that triggers an
operation and an additional acknowledgement command that is sent
after the operation has completed (or failed). Acknowledgement
commands MUST refer to the initial trigger command and this relation
is expressed by a special reference parameter that is generated by
the caller. Note that the acknowledgement command is different from
acknowledgments on the Mbus transport level: Those only ensure that
messages are really received by the addressees, whereas transaction
acknowledgments inform the original caller about the result of a
certain operation that the callee should have performed upon
reception of the transaction command.
Transaction commands are only allowed for unicast messages, they may
not be sent to address groups. They MUST be sent using reliable Mbus
messages. Senders of transaction commands are called clients,
receivers of transaction commands are called servers.
After a sender (a client) has initiated a transaction with the
respective transaction command (see below) it may abort (rollback)
the transaction with a dedicated command (see below) or finally
commit the transaction using another dedicated command.
It should be noted that means for concurrency control, e.g., to
achieve consistency in the presence of parallel transactions, have
to be provided by the application itself and is not part of these
conventions.
The following conventions for transaction commands are proposed:
o There are no restrictions on naming transaction commands. Any
command in an Mbus command hierarchy can be used for triggering
transactions. The class of the command ("TRANSACTION") SHOULD be
mentioned in the command definition.
Kutscher Expires August 15, 2001 [Page 20]
Internet-Draft Mbus Guidelines February 2001
o The first argument of a transaction command SHOULD be a map of
(string,string) (see Section 3.1) and contain meta information.
The map SHOULD contain an element with the key "ID". The
corresponding value is an arbitrary transaction ID that SHOULD be
unique for the calling entity.
o The second argument of a transaction command is of type list and
contains an arbitrary number of transaction parameters. The
syntax and the semantics of this list SHOULD be defined in the
definition of the transaction command.
o After a transaction command has been sent the sender can either
cancel or commit the transaction: A transaction cancel command
has the original transaction command name plus an appended
".cancel" as a command name and the original transaction id as a
meta information parameter. A receiver SHOULD cancel or rollback
any actions initiated by the original transaction message after
receiving a transaction cancellation and delete any state related
to the transaction. A transaction commit command has the original
transaction command name plus an appended ".commit" as a command
name and the original transaction id as a meta information
parameter. A receicing entity SHOULD finish outstanding action
initiated by the original transaction command after receiving a
transaction commit command and delete any state related to the
transaction. After a commit has been received cancel commands for
the corresponding transaction MUST NOT be honoured anymore.
o After receiving a transaction command an entity responds with an
acknowledgement. Acknowledgment command names are constructed
using the name of the trigger command and appending the string
".ack". The first argument of a transaction acknowledgement
command is of type "String" and contains the original transaction
ID that has been generated by the calling entity. Any action that
is performed MUST be reversible and SHOULD only be executed in
non-reversible way after a commit command has been received for
the corresponding transaction. If a cancel command for the
corresponding transaction has been received before a commit
command the entity SHOULD rollback any performed actions.
o The second argument of a transaction acknowledgement command is
of type "Symbol" and can have one of the following values:
OK: The transaction was successful.
UNKNOWN: No operation is associated with the transaction command.
The command is unknown to the callee.
FAILED: The transaction could not be performed successfully.
Kutscher Expires August 15, 2001 [Page 21]
Internet-Draft Mbus Guidelines February 2001
CANCELLED: The transaction has been cancelled.
o Further information about the transaction status can be supplied
optionally and can be passed in a common optional command list
(see Section 3.2.1).
o After a server has received a commit command for a transaction it
SHOULD respond with an additional acknowledgement command. For
clarity the command name for this command is composed of the name
of the original command and an appended ".completed". The
parameters are the same as for the first acknowledgement.
5.3.1 Example for a Command Definition
The meta information list (for the transaction ID) does not have to
be provided in transaction command definitions.
tools.foo.bar
TRANSACTION
Parameters:
p1: string
p1 is the value for...
p2: int
p2 is the number of...
p3: list of string
a list of names for...
Optional parameters: none
Kutscher Expires August 15, 2001 [Page 22]
Internet-Draft Mbus Guidelines February 2001
5.3.2 Example for an Mbus Interaction I
Entity A:
---------
"mbus/1.0" 42 65454365 R (app:foo module:gui id:4711-1@192.168.1.1) \
(app:foo module:engine id:4712-1@192.168.1.1) ()
tools.foo.bar ((("ID" "123")) ("gg" 17 ("a" "b")))
Entity B:
---------
"mbus/1.0" 57 65454366 U (app:foo module:engine id:4712-1@192.168.1.1) \
(app:foo module:gui id:4711-1@192.168.1.1) ()
tools.foo.bar.ack ("123" OK)
Entity A:
---------
"mbus/1.0" 43 65454367 R (app:foo module:gui id:4711-1@192.168.1.1) \
(app:foo module:engine id:4712-1@192.168.1.1) ()
tools.foo.bar.commit ((("ID" "123")))
Entity B:
---------
"mbus/1.0" 58 65454368 U (app:foo module:engine id:4712-1@192.168.1.1) \
(app:foo module:gui id:4711-1@192.168.1.1) ()
tools.foo.bar.completed ("123" OK)
Kutscher Expires August 15, 2001 [Page 23]
Internet-Draft Mbus Guidelines February 2001
5.3.3 Example for an Mbus Interaction II
Entity A:
---------
"mbus/1.0" 42 65454365 R (app:foo module:gui id:4711-1@192.168.1.1) \
(app:foo module:engine id:4712-1@192.168.1.1) ()
tools.foo.bar ((("ID" "123")) ("gg" 17 ("a" "b")))
Entity B:
---------
"mbus/1.0" 57 65454366 U (app:foo module:engine id:4712-1@192.168.1.1) \
(app:foo module:gui id:4711-1@192.168.1.1) ()
tools.foo.bar.ack ("123" OK)
Entity A:
---------
"mbus/1.0" 43 65454367 R (app:foo module:gui id:4711-1@192.168.1.1) \
(app:foo module:engine id:4712-1@192.168.1.1) ()
tools.foo.bar.cancel ((("ID" "123")))
Entity B:
---------
"mbus/1.0" 58 65454368 U (app:foo module:engine id:4712-1@192.168.1.1) \
(app:foo module:gui id:4711-1@192.168.1.1) ()
tools.foo.bar.completed ("123" CANCELLED)
5.4 Inspection/Modification of Properties
Obtaining the value of a named property of another entity is
achieved by using a set of RPC-style commands (see Section 5.2):
RPCs are defined for setting, obtaining and "watching" values of
properties. The following conventions are proposed:
o No restriction is imposed on the property's name. Entities can
use any command to transmit a new value for a certain property.
The Mbus command name is the property name. In a profile
definition a property SHOULD be classified as ("PROPERTY") which
means that it is possible for other entities to set/retrieve its
value (see below). Additionally the type of the property SHOULD
be specified using the syntax specified in Section 3.2.
o In order to obtain the value of a certain property that is
Kutscher Expires August 15, 2001 [Page 24]
Internet-Draft Mbus Guidelines February 2001
managed by another Mbus entity a module sends a "get-request" RPC
to the respective entity. The command name of this RPC is
composed of the property name and ".get". The RPC argument list
is empty. Upon receiving a get-request an entity hosting the
property returns a RPC result command to the requesting entity.
The (only) RPC argument is the current value. Application
specific status values (Section 5.2) for the return command of a
get-RPC are:
OK: Property exists.
NO_SUCH_PROPERTY: The requested property does not exist.
o In order to change the value of a certain property that is
managed by another Mbus entity a module sends a "set-request" RPC
to the respective entity. The command name of this RPC is
composed of the property name and ".set". The (only) RPC argument
is the new value. Upon receiving a set-request an entity hosting
the property changes the value and returns a RPC result command
to the requesting entity. The (only) RPC argument is the new
value. Application specific status values (Section 5.2) for the
return command of a set-RPC are:
OK: Property exists and has been updated.
NO_SUCH_PROPERTY: The requested property does not exist.
o Besides get-requests clients can also use "watch-requests" to
obtain the value of properties. watch-requests can be sent if an
entity wants to be informed about any updates to the property
value. The RPC command name of this request is composed of the
variable name and ".watch". The RPC argument list is empty. Upon
receiving a watch-request an entity that hosts the property adds
the originating entity to a list of subscribers for the property
variable and will further on send an update to all list members
when the value of the property changes. The current value of the
property is sent to the originator of the watch-request in a RPC
return command. The updates are event notificatons as specified
in Section 5.5, i.e., simple Mbus commands with the property name
as the command name and the current value as the only parameter.
Application specific status values (Section 5.2) for the return
command of a watch-RPC are:
OK: Property exists and the requesting entity has been added to
the list of subscribers.
NO_SUCH_PROPERTY: The requested property does not exist.
o A subscriber of a property can also send an "unwatch-request" RPC
Kutscher Expires August 15, 2001 [Page 25]
Internet-Draft Mbus Guidelines February 2001
to unsubscribe. The command name of this request is composed of
the property name and ".unwatch". The argument list is empty. The
RPC return command also requires no further RPC parameter.
Application specific status values (Section 5.2) for the return
command of a uwatch-RPC are:
OK: Property exists and the requesting entity has been removed
from the list of subscribers.
NO_SUCH_PROPERTY: The requested property does not exist.
NOT_SUBSCRIBED The requesting entity is not on the list of
subcribers for this property.
Entities that have been declared to provide a property, e.g., in a
profile definition, SHOULD support all aforementioned requests.
All requests related to properties MUST be send as unicast RPCs.
Notes:
Requests for non-existing properties result in a RPC-UNKNOWN error
(see Section 5.2).
5.4.1 Example for a Command Definition
The RPC commands for the different property request do not have to
be specified.
tools.foo.bar
PROPERTY
type: string
Kutscher Expires August 15, 2001 [Page 26]
Internet-Draft Mbus Guidelines February 2001
5.4.2 Example for an Mbus Interaction I
Entity A:
---------
"mbus/1.0" 42 65454365 R (app:foo module:gui id:4711-1@192.168.1.1) \
(app:foo module:engine id:4712-1@192.168.1.1) ()
tools.foo.bar.get ((("ID" "123") ("RPC-TYPE" "UNICAST")))
Entity B:
---------
"mbus/1.0" 57 65454366 U (app:foo module:engine id:4712-1@192.168.1.1) \
(app:foo module:gui id:4711-1@192.168.1.1) ()
tools.foo.bar.get.return ((("ID" "123") ("RPC-STATUS" "OK")) \
((OK OK "") ("the value")))
5.4.3 Example for an Mbus Interaction II
Entity A:
---------
"mbus/1.0" 42 65454365 R (app:foo module:gui id:4711-1@192.168.1.1) \
(app:foo module:engine id:4712-1@192.168.1.1) ()
tools.foo.bar.set ((("ID" "123") ("RPC-TYPE" "UNICAST")) \
((OK OK "") ("the value")))
Entity B:
---------
"mbus/1.0" 57 65454366 U (app:foo module:engine id:4712-1@192.168.1.1) \
(app:foo module:gui id:4711-1@192.168.1.1) ()
tools.foo.bar.set.return ((("ID" "123") ("RPC-STATUS" "OK")) \
((OK OK "") ("new value")))
5.4.4 Example for an Mbus Interaction III
Entity A:
---------
"mbus/1.0" 42 65454365 R (app:foo module:gui id:4711-1@192.168.1.1) \
(app:foo module:engine id:4712-1@192.168.1.1) ()
tools.foo.bar.watch ((("ID" "123") ("RPC-TYPE" "UNICAST")))
Entity B:
---------
Kutscher Expires August 15, 2001 [Page 27]
Internet-Draft Mbus Guidelines February 2001
"mbus/1.0" 57 65454366 R (app:foo module:engine id:4712-1@192.168.1.1) \
(app:foo module:gui id:4711-1@192.168.1.1) ()
tools.foo.bar.watch.return ((("ID" "123") ("RPC-STATUS" "OK")) \
((OK OK "") ("the value")))
Entity C:
---------
"mbus/1.0" 82 65454367 R (app:bar module:engine id:4713-1@192.168.1.1) \
(app:foo module:engine id:4712-1@192.168.1.1) ()
tools.foo.bar.set ((("ID" "345") ("RPC-TYPE" "UNICAST")) \
((OK OK "") ("new value")))
Entity B:
---------
"mbus/1.0" 58 65454368 R (app:foo module:engine id:4712-1@192.168.1.1) \
(app:bar module:engine id:4713-1@192.168.1.1) ()
tools.foo.bar.set.return ((("ID" "345") ("RPC-STATUS" "OK")) \
((OK OK "") ("new value")))
Entity B:
---------
"mbus/1.0" 59 65454369 U (app:foo module:engine id:4712-1@192.168.1.1) \
(app:foo module:gui id:4711-1@192.168.1.1) ()
tools.foo.bar ("new value")
Entity A:
---------
"mbus/1.0" 43 65454370 R (app:foo module:gui id:4711-1@192.168.1.1) \
(app:foo module:engine id:4712-1@192.168.1.1) ()
tools.foo.bar.unwatch ((("ID" "124") ("RPC-TYPE" "UNICAST")))
Entity B:
---------
"mbus/1.0" 60 65454371 R (app:foo module:engine id:4712-1@192.168.1.1) \
(app:foo module:gui id:4711-1@192.168.1.1) ()
tools.foo.bar.unwatch.return ((("ID" "123") ("RPC-STATUS" "OK")))
Kutscher Expires August 15, 2001 [Page 28]
Internet-Draft Mbus Guidelines February 2001
5.5 Event Notifications
There are different usage scenarios for events that origin at a
certain entity and need to be signaled to other entities. An event
notification is an Mbus command with an arbitrary argument list that
is sent (eventually, maybe periodically) to a group of entities. The
following conventions are proposed:
o No restriction is imposed on the name of the notification
command. In a profile definition a command SHOULD be classified
as ("EVENT NOTIFICATION").
o A command that is classified as an event notification SHOULD also
be associated with a default target address that is used when the
notification command is sent.
See Section 6 for conventions of how to subscribe to and how to
redirect event notifications.
5.5.1 Example for a Command Definition
tools.foo.bar
EVENT NOTIFICATION
default target address: (app:xy module:gui)
Parameters:
p1: string
p1 is the value for...
p2: int
p2 is the number of...
p3: list of string
a list of names for...
5.5.2 Example for an Mbus Interaction
Entity A:
---------
"mbus/1.0" 42 65454365 U (app:foo module:gui id:4711-1@192.168.1.1) \
(app:xy module:gui) ()
tools.foo.bar ("gg" 17 ("a" "b"))
Kutscher Expires August 15, 2001 [Page 29]
Internet-Draft Mbus Guidelines February 2001
5.6 Contexts
RPCs can be used to trigger a remote operation with the possibility
to obtain results from a single operation thus representing a short
time interaction between two or more Mbus entities. Sometimes there
is the need for more persistent interaction relations between
entities, for example, when a series of commands all refer to the
same context. The command category "contexts" allows for expressing
a long-term relationship between commands that are exchanged by Mbus
entities.
The model that is used here is the concept of a specific context in
which a sequence of Mbus commands are exchanged that relate to each
other and are originated by entities of a group of Mbus entities.
The context that provides a scope for Mbus commands is identified by
a unique id that is used in all commands belonging to the context.
Contexts can start to exist (they can be created) and cease to exist
(destructed). Mbus commands for context creation and destruction
will be defined below.
Only certain specified commands are valid within a context. An Mbus
context definition specifies these commands and their semantics.
Context commands are either RPC commands (see Section 5.2) or event
notifications that provide the context-id in the meta information
parameter (key="CONTEXT-ID"). The subsequent argument of a context
command is of type list and contains an arbitrary number of
parameters. The syntax and the semantics of this list SHOULD be
specified in the definition of the command.
The name of a context is an Mbus command prefix. Command names for
construction and destruction commands as well as other context
commands are derived from the context name by appending a dot and
the name of the method. The name of the construction command is
CONTEXT_NAME.create and the name of the destruction command is
CONTEXT_NAME.delete. Both are "simple" Mbus commands (remote
commands) with one parameter: the context-id as a parameter of type
string.
CONTEXT_NAME.create and CONTEXT_NAME.delete can be sent to single
Mbus entities as well as to group of entities using a Mbus group
address. It is RECOMMENDED that context-creation/deletion messages
to single entities be sent reliable. Only the creator of a context
(the entity that has sent the CONTEXT_NAME.create message) SHOULD
delete the corresponding context.
5.6.1 Example for a Command Definition
The meta information list (for the context ID and eventual RPC or
Kutscher Expires August 15, 2001 [Page 30]
Internet-Draft Mbus Guidelines February 2001
transaction IDs) does not have to be provided in each command
definition in the context definition.
Context "conf.call-ctrl.call"
------------------------
About: This context definition comprehends commands that can be used
for a "call context". The following commands may refer
to different contexts that represent different calls.
The following commands are defined in this context:
conf.call-ctrl.call.setup
RPC
Parameters:
caller: string
identifies the caller
callee: string
identifies the callee
Optional Parameters: none
conf.call-ctrl.call.disconnected
EVENT NOTIFICATION
default target address: (app:controller)
Parameters:
reason: string
the reason for the disconnection
Optional Parameters: none
Kutscher Expires August 15, 2001 [Page 31]
Internet-Draft Mbus Guidelines February 2001
5.6.2 Example for an Mbus Interaction
Entity A:
---------
"mbus/1.0" 42 65454365 U (app:controller module:engine id:4711-1@192.168.1.1) \
(app:call-ctrl module:engine id:4712-1@192.168.1.1) ()
conf.call-ctrl.call.create ("345")
Entity A:
---------
"mbus/1.0" 43 65454366 R (app:controller module:gui id:4711-1@192.168.1.1) \
(app:call-ctrl module:engine id:4712-1@192.168.1.1) ()
conf.call-ctrl.call.setup ((("ID" "123") ("CONTEXT-ID" "345")) \
("joe@foo.bar" "bob@foo.bar"))
Entity B:
---------
"mbus/1.0" 57 65454380 U (app:call-ctrl module:engine id:4712-1@192.168.1.1) \
(app:controller) ()
conf.call-ctrl.call.disconnected ((("CONTEXT-ID" "345")) ("hangup"))
Entity A:
---------
"mbus/1.0" 44 65454385 U (app:controller module:engine id:4711-1@192.168.1.1) \
(app:call-ctrl module:engine id:4712-1@192.168.1.1) ()
conf.call-ctrl.call.delete ("345")
5.7 Status Signaling
In order to notify other entities of status events asynchronously,
each Mbus entity SHOULD send such events using the "mbus.status"
command. This command is an event notification as specified in
Section 5.5 and can thus also be given a default target address.
As specified in Section 5.5 the default target address of this
message can be redirected using the "mbus.register" command defined
in Section 6.1.1.
Kutscher Expires August 15, 2001 [Page 32]
Internet-Draft Mbus Guidelines February 2001
mbus.status
EVENT NOTIFICATION
Parameters:
class: symbol
An identifier for the class of the status message.
Predefined identifiers are:
INFO: for informational messages
WARNING: for warnings
ERROR: for error reports
Application profiles can also define new status
message classes.
sym: symbol
An identifier for the status message. Application
profile definitions SHOULD enumerate the possible
status symbols (and their textual description, see
below).
descr: string
A textual description for the status message.
Optional Parameters: none
To be discussed (FIXME): Should mbus.status only be used top-level
or with arbitrary prefixes?
5.7.1 Example of a Definition of Status Symbols
TBD
Kutscher Expires August 15, 2001 [Page 33]
Internet-Draft Mbus Guidelines February 2001
6. Mbus service models
In general, the Mbus is a communication channel for message passing
within a group of modules. Mbus implementations provide mechanisms
to enable applications modules to pass messages to other modules.
From an application point of view the goal of using the Mbus is
using certain services of other entities (or providing these
services).
Each Mbus entity can provide a number of different services: It may
perform certain operations for other entities that are triggered by
the reception of Mbus commands or it may notify one or more entities
of events.
In the simplest case, an entity will simply receive Mbus messages
and perform the operations that are denominated by the commands that
are contained in the messages. Sometimes, however, entities will
only process certain commands if they are are received from an
entity that has registered as a client, e.g. a controller, before.
Entities that are remote-controlled via their Mbus interface could
restrict the number of controlling entities to one (at a time) in
order to ensure consistency. Also, there could be event
notifications that are sent to a certain dedicated controller only,
as well as there can be notifications that can be sent to a group of
receivers, each of which having subscribed to this event source
before. Again, in simple scenarios, entities may just broadcast all
event notifications to the whole Mbus.
It is proposed that all commands, variables, event notifications
that an entity may send or receive in a specific application context
be subsumed in a common Mbus command set definition. Service models
that apply to such a set of Mbus commands SHOULD be specified as
well.
In the following the different service models (control relation
classes) are described in detail and a list of conventions and
recommendations is presented that SHOULD be considered when writing
Mbus command definitions.
Different classes of control relations are defined:
o no control
o tight control
o exclusive tight control
These different classes of control relations are usually applied to
a command set that is implemented by some Mbus entities. It is
Kutscher Expires August 15, 2001 [Page 34]
Internet-Draft Mbus Guidelines February 2001
suggested that a control relation type is assigned to command sets
in the command set definition.
The motivation for defining different service models is to
accommodate different applications with different requirements
concerning flexibility and the level of control for their Mbus
communication.
The next sections specify the semantics and implications of the
individual control classes:
6.1 No Control
"no control" means that entities do not require a special control
relation with another entity to be established in order to accept
commands from it. All Mbus commands, variables etc. of the
respective command set can be used directly and there is no
regulation of the number of entities that may interact using the
respective commands at a time.
A command set that is classified as "no control" may contain
commands for unsolicited event notification or even RPC-style
commands that can be sent by an entity conforming to a specific Mbus
command set definition. These Mbus commands that are originated by a
conforming entity may be addressed to a default target address.
There may be a default target address for all commands of a command
definition set but each command may be associated to a specific
default target address. It is RECOMMENDED that commands of the "no
control" class that may be sent without prior solicitation, such as
event notifications, are assigned a default target address.
The default target address that an entity sends unsolicited commands
to may be changed by other entities. Entities may add themselves to
a list of clients/controllers that is maintained by another service
providing entity. The effect of having the service providing entity
add another entity to a list of clients is that the default target
address is no longer used but the respective messages are directed
to the client entity. If more than one entity tries to add itself to
the target address list it is up to the application to allow or deny
this. Generally, entities of the "no control" class are expected to
accept multiple clients. When multiple clients are present each
message that would otherwise just be sent to the default target
address is sent either to a Mbus group address that uniquely
represents the registered clients or is sent independently to all
clients. Clients may also deregister. When all clients have
deregistered the entity SHOULD use the default target address for
the respective command again.
The changing of the default target address is called redirection.
Kutscher Expires August 15, 2001 [Page 35]
Internet-Draft Mbus Guidelines February 2001
Redirection may take place on single commands or a complete command
set. If a command or a command set use a default target address that
can be redirected by clients it SHOULD be marked as "REDIRECTABLE"
and the default target address SHOULD be given.
Redirection commands belong to the class of RPC-commands. The
following commands are defined (see Section 3.1 for parameter type
definitions):
6.1.1 mbus.register
RPC
Parameters:
command: string
Name of the Mbus command (or command set prefix, MUST be
specified absolutely)
addr: MbusAddress
Mbus address that should be registered.
Optional Parameters: none
Description: This command is sent by an interested client entity to
a service providing entity in order to change its default target
address for the given command (prefix).
Application specific return values
OK: The client has been added to the address list.
NO_SUCH_COMMAND: The command (prefix) that has been given in the
request is unknown.
DENIED: The requesting entity is denied to register the given
command (prefix).
Return parameters:
addr-list: list of MbusAddress
the new list of registered clients.
6.1.2 mbus.deregister
RPC
Parameters:
Kutscher Expires August 15, 2001 [Page 36]
Internet-Draft Mbus Guidelines February 2001
command: string
Name of the Mbus command (or command set prefix, MUST be
specified absolutely)
addr: MbusAddress
Mbus address that should be deregistered.
Optional Parameters: none
Description: This command is sent by a registered client entity to a
service providing entity in order to deregister from a command or
service subscription.
Application specific return values
OK: The client has been removed from the address list.
NO_SUCH_COMMAND: The command (prefix) that has been given in the
request is unknown.
NOT_REGISTERED: The given address has not been registered before
for the command (prefix).
Return parameters:
add-list: list of MbusAddress
the new list of registered clients.
6.1.3 mbus.registered
EVENT NOTIFICATION
Parameters:
string command: Name of the Mbus command (or command set prefix)
list of MbusAddress add-list: Current list of registered clients
Description: This notification is sent by a service providing entity
after a new client has registered for a command (prefix). The
second parameter contains the new list of registered clients for
the given command. The notfication SHOULD be sent to the old list
of clients (or to the default target address if no other clients
have registered before).
Kutscher Expires August 15, 2001 [Page 37]
Internet-Draft Mbus Guidelines February 2001
6.1.4 mbus.get-registered
RPC
Parameters:
command: string
Name of the Mbus command (or command set prefix)
Optional Parameters: none
Description: This command can be used in order to obtain the current
list of registered clients for the specified command (prefix).
Application specific return values
OK: The list of registered clients is provided.
NO_SUCH_COMMAND: The command (prefix) that has been given in the
request is unknown.
Return parameters:
addr-list: list of MbusAddress
the list of registered clients.
6.2 Tight Control
An entity that requires "tight control" for some or all of its Mbus
controllable resources will only accept commands from an entity that
has established a control relationship before. This means that Mbus
commands, variables etc. can only be used by another entity after it
has registered itself as a "controller" at the entity that provides
the resources. Upon this registration the controlled entity adds the
new controller's Mbus address to a controller-address-list that is
used for authorization and for sending event notifications etc.
Another complementary de-registration command enables entitites to
end the control relationship. Again, there is no regulation of the
number of entities that may register themselves as a controller at a
time.
Entities that conform to a command set definition marked as "tight
control" SHOULD not send commands or event notifications to a
default target address for resources of that set.
6.3 Exclusive Tight Control
"Exclusive tight control" has the same semantics as "tight control",
except for the number of controllers at a time: An entity that
Kutscher Expires August 15, 2001 [Page 38]
Internet-Draft Mbus Guidelines February 2001
provides an Mbus command set that has been marked as requiring
exclusive tight control will only accept one controller at a timer
and reject register requests once a control relation with another
entity has been established.
When a register request is received while another entity is
currently registered as a controller the receicing entity SHOULD
return the value "DENIED" (see Section 6.1.1.
Kutscher Expires August 15, 2001 [Page 39]
Internet-Draft Mbus Guidelines February 2001
7. Algorithms
7.1 Aggregation of Mbus Addresses
The following algorithm can be used to aggregate an arbitrary number
of Mbus addresses: (FIX this example code)
template <class Input>
inline MAddress aggregate(Input start, Input end)
{
typedef map<MAddressElement,int> elements;
elements ae;
int count=0;
MAddress res;
// get all address elements:
for(;start!=end;start++) {
count++;
for(MAddress::Const_Iterator ai(*start); ai; ++ai) {
ae[*ai]++; // count occurence of AddressElements
}
}
// keep all Elements that occured in every Address:
elements::const_iterator ei;
for(ei=ae.begin();ei!=ae.end();ei++) {
if(ei->second==count) {
res.setElement(ei->first.key(),ei->first.val());
}
}
return res;
}
7.2 Expansion of Mbus Group Addresses
The following algorithm can be used to expand an Mbus group address
to the set of real Mbus addresses enclosed within the group address.
TBD
Kutscher Expires August 15, 2001 [Page 40]
Internet-Draft Mbus Guidelines February 2001
8. Definition of Constants
The following constants are defined:
T_anycast: N_r * T_r (see [1])
T_Coordindation: 2 * N_r * T_r (see [1])
Kutscher Expires August 15, 2001 [Page 41]
Internet-Draft Mbus Guidelines February 2001
References
[1] Ott, J., Perkins, C. and D. Kutscher, "A Message Bus for Local
Coordination", Internet Draft
draft-ietf-mmusic-mbus-transport-04.txt, February 2001.
[2] Schulzrinne, H., Casner, S., Frederick, R. and V. Jacobsen,
"RTP: A Transport Protocol for Real-Time Applications", RFC
1889, January 1996.
Author's Address
Dirk Kutscher
TZI, Universitaet Bremen
Bibliothekstr. 1
Bremen 28359
Germany
Phone: +49.421.218-7595
Fax: +49.421.218-7000
EMail: dku@tzi.org
Kutscher Expires August 15, 2001 [Page 42]
Internet-Draft Mbus Guidelines February 2001
Appendix A. Examples for Application Profiles
A.1 Mbus Profile for RTP applications
This needs to be updated.
The following commands are used to provide information about an RTP
[2] media source. Each source in media sessions is identified by its
SSRC (not by the CNAME, since this would not be unique). Correlation
to CNAMEs for cross-media references (eg: for lip- synchronization)
has to be done by receiving entities.
The purpose of this Mbus profile is to provide a mechanism that
allows for controlling RTP engine. RTP engines are entities that use
an RTP protocol stack to send and receive RTP/RTCP data. This Mbus
profile provide control commands to configure RTP engine and
notification commands to notify interested engine of RTP events.
All commands of this set conform to the control class "exclusive
tight control". The default destination address for event
notifications is ().
It is suggested that RTP engines that support these commands, i.e.
that can be controlled by the RPCs listed below and that can
generate the event notifications, provide the following address
element in their Mbus addresses:
(module:engine)
For all commands, event notifications that carry a SSRC value, the
value is represented as a string in hexadecimal notation.
A.1.1 Configuring a RTP engine
The following commands are used to configure a RTP engine.
A.1.1.1 rtp.set-attributes
rtp.set-attributes (attribute-list)
RPC
This command is used to configure the SSRC and SDES parameters of a
RTP engine.
Parameters:
attribute-list: map of (String,String)
A map containing configuration information. The first element of
each pair is the name of the attribute and the second element of
each pair is the value of the attribute. The following attribute
Kutscher Expires August 15, 2001 [Page 43]
Internet-Draft Mbus Guidelines February 2001
names are defined:
SSRC: The SSRC value to be used by the RTP engine.
NAME: The name of the participant.
PHONE: The phone number of the participant.
LOC: The geographic location of the participant.
TOOL: The application/tool name of the participant.
NOTE: The notice/status item.
CNAME: The canonical end-point identifier for the participant.
If other attribute names than those listed are used they are to
be interpreted as PRIV SDES items (see [2]).
A.1.1.2 Controlling a RTP engine
The following commands are used to control a RTP engine during a RTP
session.
A.1.1.2.1 rtp.source.mute
rtp.source.mute (ssrc muteState)
RPC
The command indicates that a source is to be muted/ unmuted.
Parameters:
ssrc: string
The SSRC value of the participant to be muted/unmuted.
muteState: Integer
The value of the muteState parameter is 0 to indicate unmuted,
and 1 to indicate muted.
A.1.1.3 Events generated by a RTP engine
The following commands are used by a RTP engine to signal source
specific events during a RTP session.
A.1.1.3.1 rtp.source.exists
rtp.source.exists (ssrc validityTime)
EVENT NOTIFICATION
Kutscher Expires August 15, 2001 [Page 44]
Internet-Draft Mbus Guidelines February 2001
The rtp.source.exists command is sent by a media engine to assert
that a particular source is present in a session.
Parameters:
ssrc: string
The ssrc of the source this event notification refers to.
validityTime: Integer
The validityTime parameter is the time for which that source
should be considered valid, in seconds. If another
rtp.source.exists command has not been received for that source
within this time period, the source is implicitly timed out. The
validityTime SHOULD be three times the RTCP reporting interval
for that session.
A.1.1.3.2 rtp.source.left
rtp.source.left (ssrc)
EVENT NOTIFICATION
The rtp.source.left command is used to indicate that a source has
left the session.
Parameters:
ssrc: string
The ssrc of the source this event notification refers to.
A.1.1.3.3 rtp.source.attributes
rtp.source.attributes (ssrc attribute-list)
EVENT NOTIFICATION
This event notification is used to pass RTCP SDES information of
other sources from a media engine to a user interface.
Parameters:
ssrc: string
The ssrc of the source this event notification refers to.
attribute-list: map of (String,String)
A map containing the SDES information. The first element of each
pair is the name of the attribute and the second element of each
pair is the value of the attribute. The same attributes as for
rtp.set-attributes (Appendix A.1.1.1) are defined (except for
SSRC).
Kutscher Expires August 15, 2001 [Page 45]
Internet-Draft Mbus Guidelines February 2001
A.1.1.3.4 rtp.source.reception
rtp.source.reception (ssrc packetsRecv packetsLost packetsMisordered
jitter validityTime)
EVENT NOTIFICATION
This command is used to pass RTCP RR information from a media engine
to a user interface. The total number of packets received, lost and
misordered are sent, together with the network timing jitter in
milliseconds and a validity time for this report in seconds.
Parameters:
ssrc: string
The ssrc of the source this event notification refers to.
packetsRecv: Integer
Total number of received packets.
packetsLost: Integer
Total number of lost packets.
packetsMisordered: Integer
Total number of misordered packets.
jitter: Integer
Observed jitter in milliseconds.
validityTime: Integer
Validity time in seconds for this report.
A.1.1.3.5 rtp.source.packet.loss
rtp.source.packet.loss (dest_ssrc src_ssrc% validityTime)
EVENT NOTIFICATION
Sent by a media engine to indicate the instantaneous packet loss
observed between two sources. The validityTime for this report is in
milliseconds.
Parameters:
dest_ssrc: string
The ssrc of the receiving participant.
src_ssrc: string
The ssrc of the sending participant.
validityTime: Integer
Kutscher Expires August 15, 2001 [Page 46]
Internet-Draft Mbus Guidelines February 2001
The validityTime for this report is in milliseconds.
A.1.1.3.6 rtp.source.active
rtp.source.active (ssrc validityTime)
EVENT NOTIFICATION
The rtp.source.active notification indicates that a source is
transmitting data into the session. The validityTime field indicates
the period for which this source should be considered active, in
milliseconds.
Parameters:
ssrc: string
The ssrc of the source this event notification refers to.
validityTime: Integer
The validityTime field indicates the period for which this source
should be considered active, in milliseconds.
A.1.1.3.7 rtp.source.inactive
rtp.source.inactive (ssrc)
EVENT NOTIFICATION
The rtp.source.active notifications indicates that a source has
stopped transmitting data into the session.
Parameters:
ssrc: string
The ssrc of the source this event notification refers to.
A.1.1.3.8 rtp.source.packet.duration
rtp.source.packet.duration (ssrc packetDuration)
EVENT NOTIFICATION
Sent by a media engine to indicate the duration, in milliseconds, of
packets received from a source. This may be used to control the
duration of packets sent by a media engine, if sent to that engine
with the cname of the engine.
Parameters:
ssrc: string
The ssrc of the source this event notification refers to.
Kutscher Expires August 15, 2001 [Page 47]
Internet-Draft Mbus Guidelines February 2001
packetDuration: Integer
The duration, in milliseconds, of packets received from a source.
A.1.1.3.9 rtp.source.codec
rtp.source.codec (ssrc codec)
EVENT NOTIFICATION
Sent by a media engine to indicate the codec in use by a source.
Parameters:
ssrc: string
The ssrc of the source this event notification refers to.
codec: String
The codec name.
A.1.1.3.10 rtp.source.playout
rtp.source.playout (ssrc playoutDelay)
EVENT NOTIFICATION
Sent by a media engine to indicate the playout delay, in
milliseconds, for a source (that is, end-to-end time from capture to
playout). This allows for lip-synchronization between audio and
video streams.
Parameters:
ssrc: string
The ssrc of the source this event notification refers to.
playoutDelay: Integer
playout delay, in milliseconds.
Kutscher Expires August 15, 2001 [Page 48]
Internet-Draft Mbus Guidelines February 2001
Full Copyright Statement
Copyright (C) The Internet Society (2001). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implmentation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph
are included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFC editor function is currently provided by the
Internet Society.
Kutscher Expires August 15, 2001 [Page 49]
