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 inline MAddress aggregate(Input start, Input end) { typedef map 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]