idnits 2.17.1 draft-ietf-mmusic-mbus-guidelines-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 29 instances of too long lines in the document, the longest one being 10 characters in excess of 72. ** There are 152 instances of lines with control characters in the document. ** The abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 46 instances of lines with non-RFC2606-compliant FQDNs in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 171: '...ion profile defintion SHOULD contain a...' RFC 2119 keyword, line 205: '... Each parameter SHOULD be associated ...' RFC 2119 keyword, line 209: '...f the same type) SHOULD be declared by...' RFC 2119 keyword, line 212: '...sts the type of each element SHOULD be...' RFC 2119 keyword, line 215: '...arameter list is allowed, it SHOULD be...' (68 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: 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. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 14, 2001) is 8472 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-06) exists of draft-ietf-mmusic-mbus-transport-04 ** Downref: Normative reference to an Informational draft: draft-ietf-mmusic-mbus-transport (ref. '1') ** Obsolete normative reference: RFC 1889 (ref. '2') (Obsoleted by RFC 3550) Summary: 12 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group Kutscher 3 Internet-Draft TZI, Universitaet Bremen 4 Expires: August 15, 2001 February 14, 2001 6 The Message Bus: Guidelines for Application Profile Writers 7 draft-ietf-mmusic-mbus-guidelines-00.txt 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance with 12 all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as 17 Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six 20 months and may be updated, replaced, or obsoleted by other documents 21 at any time. It is inappropriate to use Internet-Drafts as reference 22 material or to cite them other than as "work in progress." 24 To view the entire list of Internet-Draft Shadow Directories, see 25 http://www.ietf.org/shadow.html. 27 This Internet-Draft will expire on August 15, 2001. 29 Copyright Notice 31 Copyright (C) The Internet Society (2001). All Rights Reserved. 33 Abstract 35 This memo defines a list of conventions for terminology, algorithms 36 and procedures for interaction models that are useful for 37 applications using the Message Bus (Mbus) [1]. These conventions are 38 intended as guidelines for designers of Mbus application profiles 39 and Mbus implementations/applications. 41 Version Info 43 $Revision: 2.17 $ 45 $Date: 2001/02/14 14:55:07 $ 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . 5 50 2. Terminology . . . . . . . . . . . . . . . . . . . . . 6 51 3. General Mbus Command Definition Conventions . . . . . 7 52 3.1 Conventions for parameter encoding . . . . . . . . . . 7 53 3.2 Parameter Specification for Mbus Commands . . . . . . 7 54 3.2.1 Optional parameters . . . . . . . . . . . . . . . . . 8 55 3.2.1.1 Example of a Definition of an Optional Parameter List 9 56 3.2.1.2 Example for an Mbus Command with an Optional Parameter 9 57 4. Usage of Mbus Addresses . . . . . . . . . . . . . . . 10 58 4.1 Example of a Specification of an Addressing Scheme . . 11 59 5. Mbus Command Classes . . . . . . . . . . . . . . . . . 12 60 5.1 Remote Commands . . . . . . . . . . . . . . . . . . . 13 61 5.1.1 Example for a Command Definition . . . . . . . . . . . 13 62 5.1.2 Example for an Mbus Interaction . . . . . . . . . . . 14 63 5.2 RPC-style Commands . . . . . . . . . . . . . . . . . . 14 64 5.2.1 Invoking Remote Procedures . . . . . . . . . . . . . . 14 65 5.2.2 Returning Results from Remote Procedure Calls . . . . 15 66 5.2.3 Example for a Command Definition . . . . . . . . . . . 16 67 5.2.4 Example for an Mbus Interaction . . . . . . . . . . . 17 68 5.2.5 RPC Communication with Multiple Entities . . . . . . . 17 69 5.2.5.1 Anycast . . . . . . . . . . . . . . . . . . . . . . . 17 70 5.2.5.1.1 Example for an Mbus Interaction . . . . . . . . . . . 18 71 5.2.5.2 One RPC, more than one Result Command . . . . . . . . 19 72 5.2.5.2.1 Example for an Mbus Interaction . . . . . . . . . . . 20 73 5.2.5.3 one RPC, coordinated result . . . . . . . . . . . . . 20 74 5.2.5.3.1 Example for an Mbus Interaction . . . . . . . . . . . 21 75 5.3 Transactions . . . . . . . . . . . . . . . . . . . . . 21 76 5.3.1 Example for a Command Definition . . . . . . . . . . . 23 77 5.3.2 Example for an Mbus Interaction I . . . . . . . . . . 24 78 5.3.3 Example for an Mbus Interaction II . . . . . . . . . . 25 79 5.4 Inspection/Modification of Properties . . . . . . . . 25 80 5.4.1 Example for a Command Definition . . . . . . . . . . . 27 81 5.4.2 Example for an Mbus Interaction I . . . . . . . . . . 28 82 5.4.3 Example for an Mbus Interaction II . . . . . . . . . . 28 83 5.4.4 Example for an Mbus Interaction III . . . . . . . . . 28 84 5.5 Event Notifications . . . . . . . . . . . . . . . . . 30 85 5.5.1 Example for a Command Definition . . . . . . . . . . . 30 86 5.5.2 Example for an Mbus Interaction . . . . . . . . . . . 30 87 5.6 Contexts . . . . . . . . . . . . . . . . . . . . . . . 31 88 5.6.1 Example for a Command Definition . . . . . . . . . . . 31 89 5.6.2 Example for an Mbus Interaction . . . . . . . . . . . 33 90 5.7 Status Signaling . . . . . . . . . . . . . . . . . . . 33 91 5.7.1 Example of a Definition of Status Symbols . . . . . . 34 92 6. Mbus service models . . . . . . . . . . . . . . . . . 35 93 6.1 No Control . . . . . . . . . . . . . . . . . . . . . . 36 94 6.1.1 mbus.register . . . . . . . . . . . . . . . . . . . . 37 95 6.1.2 mbus.deregister . . . . . . . . . . . . . . . . . . . 37 96 6.1.3 mbus.registered . . . . . . . . . . . . . . . . . . . 38 97 6.1.4 mbus.get-registered . . . . . . . . . . . . . . . . . 39 98 6.2 Tight Control . . . . . . . . . . . . . . . . . . . . 39 99 6.3 Exclusive Tight Control . . . . . . . . . . . . . . . 39 100 7. Algorithms . . . . . . . . . . . . . . . . . . . . . . 41 101 7.1 Aggregation of Mbus Addresses . . . . . . . . . . . . 41 102 7.2 Expansion of Mbus Group Addresses . . . . . . . . . . 41 103 8. Definition of Constants . . . . . . . . . . . . . . . 42 104 References . . . . . . . . . . . . . . . . . . . . . . 43 105 Author's Address . . . . . . . . . . . . . . . . . . . 43 106 A. Examples for Application Profiles . . . . . . . . . . 44 107 A.1 Mbus Profile for RTP applications . . . . . . . . . . 44 108 A.1.1 Configuring a RTP engine . . . . . . . . . . . . . . . 44 109 A.1.1.1 rtp.set-attributes . . . . . . . . . . . . . . . . . . 44 110 A.1.1.2 Controlling a RTP engine . . . . . . . . . . . . . . . 45 111 A.1.1.2.1 rtp.source.mute . . . . . . . . . . . . . . . . . . . 45 112 A.1.1.3 Events generated by a RTP engine . . . . . . . . . . . 45 113 A.1.1.3.1 rtp.source.exists . . . . . . . . . . . . . . . . . . 45 114 A.1.1.3.2 rtp.source.left . . . . . . . . . . . . . . . . . . . 46 115 A.1.1.3.3 rtp.source.attributes . . . . . . . . . . . . . . . . 46 116 A.1.1.3.4 rtp.source.reception . . . . . . . . . . . . . . . . . 47 117 A.1.1.3.5 rtp.source.packet.loss . . . . . . . . . . . . . . . . 47 118 A.1.1.3.6 rtp.source.active . . . . . . . . . . . . . . . . . . 48 119 A.1.1.3.7 rtp.source.inactive . . . . . . . . . . . . . . . . . 48 120 A.1.1.3.8 rtp.source.packet.duration . . . . . . . . . . . . . . 48 121 A.1.1.3.9 rtp.source.codec . . . . . . . . . . . . . . . . . . . 49 122 A.1.1.3.10 rtp.source.playout . . . . . . . . . . . . . . . . . . 49 123 Full Copyright Statement . . . . . . . . . . . . . . . 50 125 1. Introduction 127 [1] specifies the Mbus transport protocol. This includes the basic 128 protocol behaviour, representation of PDUs and PDU elements and 129 operational aspects, such as Mbus configuration. This base 130 specification can be used to implement the Mbus protocol. Specific 131 Mbus command sets are not defined in this specification -- they are 132 expected to be defined in application specific documents. 134 This document builds on the basic transport specification and tries 135 to give useful recommendations for writers of Mbus application 136 profiles in the following areas: 138 Terminology: We propose common Mbus related terms in order to unify 139 the terminology used in Mbus application profiles. 141 Algorithms: A set of algorithms are given that are useful for Mbus 142 implementors. 144 Notation Conventions: We propose a set of conventions that can be 145 used for writing Mbus application profiles, such as 146 recommendations how to specify the characteristics of an Mbus 147 command etc. 149 Representation Conventions: Building upon the representation of 150 values given in the Mbus transport specification we define 151 additional representations for more complex data types. 153 Interaction Models: The transport specification essentially defines 154 one interaction model for the Mbus: Message passing (with support 155 for group communication). In this document we propose conventions 156 for additional interaction models that can be implemented with 157 the basic Mbus message passing mechanisms. 159 2. Terminology 161 This section defines some Mbus related terms. 163 Application profile: A specification of Mbus commands, their 164 semantics and characteristics for a specific application context. 166 Fully qualified Mbus address: A unique, fully qualified Mbus address 167 that denominates exactly one concrete existing Mbus entity at a 168 given time and can thus not be expanded further. 170 Addressing scheme: A set of Mbus address key and possible address 171 values. An Mbus application profile defintion SHOULD contain a 172 specification of a corresponding addressing scheme. 174 3. General Mbus Command Definition Conventions 176 This section gives some general recommendations how to specify Mbus 177 commands and their parameter lists and how to represent certain data 178 types using Mbus parameter types. 180 3.1 Conventions for parameter encoding 182 This section list some useful conventions for encoding values of 183 commonly used parameter types. 185 pair: A pair is a list that has exactly two elements, not 186 necessarily of the same type. 188 map: A map is a list of pairs where the first element of all pairs 189 (the keys) is of type T1 and the second element of all pairs 190 (values) is of type T2. A key value may occur only once. T1 and 191 T2 may be equal. The map is specified as "map of (T1,T2)". 193 MbusAddressElement: A Mbus address element is represented as a pair 194 of strings: The first element represent the address element key 195 and the second element represents the address element value. 197 MbusAddress: A Mbus address is represented as a list of 198 MbusAddressElements, a map of (string,string). 200 3.2 Parameter Specification for Mbus Commands 202 This section lists some guidelines how parameters of Mbus commands 203 should be specified in Mbus application profiles. 205 1. Each parameter SHOULD be associated with a well-defined Mbus 206 parameter type, i.e., one of the types specified in [1]. 208 2. Homogeneous lists (i.e. lists that contain elements that are all 209 of the same type) SHOULD be declared by specifying the element 210 type, for example "list of string". 212 3. For heterogeneous lists the type of each element SHOULD be 213 specified. 215 4. In the case an optional parameter list is allowed, it SHOULD be 216 the last parameter and a list of the potential parameters and 217 their name tags SHOULD be given. 219 See Section 3.2.1 for recommendations how to specify and use 220 optional parameters. 222 3.2.1 Optional parameters 224 Some Mbus command argument lists may be of variable length, i.e., 225 some parameters may be optional. The following conventions are 226 proposed for optional parameters: 228 o An argument list can have elements that are "optional argument 229 lists". The elements of those lists are pairs: Each first element 230 is of type String and represents a name for an optional 231 parameter. Each second element is the value and can be of 232 arbitrary type. This allows applications to process optional 233 parameters independent of their order even when some parameters 234 are missing. 236 o A command specification may have a set of predefined optional 237 parameters. In a command definition, these SHOULD be declared by 238 listing the names and type definitions. If applicable, naming 239 conventions for further parameters SHOULD be specified, for 240 example to distinguish different classes of optional parameters. 242 o If a command definition requires optional parameters it SHOULD 243 provide exactly one optional parameters list. It is RECOMMENDED 244 that the optional parameter list be the last element of the 245 command's parameter list, as shown in Section 3.2.1.2. 247 3.2.1.1 Example of a Definition of an Optional Parameter List 249 tools.foo.bar 250 Remote command (reliable/unreliable) 252 Parameters: 253 p1: string 254 p1 is the value for... 256 p2: int 257 p2 is the number of... 259 p3: list of string 260 a list of names for... 262 Optional Parameters: 263 p4: string 264 the optional name of... 266 p5: string 267 the optional number of... 269 3.2.1.2 Example for an Mbus Command with an Optional Parameter 271 Entity A: --------- 273 "mbus/1.0" 42 65454365 U (app:foo module:gui id:4711-1@192.168.1.1) \ 274 (app:foo module:engine) () 275 tools.foo.bar ("gg" 17 ("a" "b") ("p5" 42)) 277 4. Usage of Mbus Addresses 279 Mbus addresses are lists of arbitrary key/value pairs and every Mbus 280 entity can choose its own Mbus address. Target Mbus addresses can be 281 partly qualified to allow for group addressing or selecting 282 receivers by certain application specific key elements that 283 represent a certain application or service type. Except for the 284 mandatory id-element the Mbus transport specification [1] does not 285 define any other elements and it is suggested that Mbus application 286 profile definitions specify a set of useful address element names 287 and values for a specific application context. 289 Example of a fully qualified Mbus address and three partly qualified 290 Mbus addresses: 292 (conf:test media:audio module:engine app:rat id:4711-1@192.168.1.1) 293 (media:audio module:engine) 294 (module:engine) 295 () 297 These address elements might be used to offer a particular service 298 to other entities and to disambiguate entities sufficiently. Address 299 elements might also be used to express membership of a certain Mbus 300 address group. When it is known that an entity will always send 301 certain messages to a specific address group, an entity will have to 302 provide the corresponding address elements (with proper keys and 303 values) to become a member of that group. This depicts the following 304 uses of Mbus address elements: 306 1. to signal affiliation to an application context 308 2. to offer a certain service 310 3. to receive messages for a certain subgroup (to "tune" to a 311 specific sub-channel on the Mbus) 313 It is possible that for a given application context not every 314 address element is to be used by every involved Mbus entity. Instead 315 some elements (or values) might be reserved for use by "service 316 providing entities" while others might be required in order to 317 receive messages that are addressed to a certain subgroup. 319 Moreover it should be noted that it may make sense for entities to 320 adopt more than one command profile and thus make use of more than 321 one addressing scheme. An entity could provide all address elements 322 that are required by command profile A and additionally provide all 323 the required element for profile B. 325 In the following a list of guidelines is presented how to specify an 326 Mbus addressing scheme for an Mbus profile definition. 328 A Mbus profile definition SHOULD be a sufficiently self-contained 329 specification of Mbus commands for a particular application area 330 together with a specification of an addressing model for Mbus 331 entities that are supposed to implement or use the commands. It 332 SHOULD be clear which commands belong to an application profile 333 definition and what addressing conventions are to be considered. 335 The following specifies how addressing conventions SHOULD be 336 defined: 338 1. List the address element keys that are used. 340 2. List (or describe) the set of legal values for each element key 341 and explain the semantics (if applicable). 343 3. Name the services (or mandatory commands) that an entity 344 providing certain address element keys/values must 345 provide/understand. 347 4. Give examples for complete Mbus addresses using the defined 348 address elements. 350 5. For each command that is specified in the profile definition 351 explain the relation to the address elements. ("This command is 352 sent to the group xy." or "This command must be understood by 353 every entity that provides the address element xy:z.") 355 4.1 Example of a Specification of an Addressing Scheme 357 TBD 359 5. Mbus Command Classes 361 The general semantic model for Mbus commands is that commands are 362 sent as payload of messages from one peer to another receiving 363 (group of) peer(s) in order to trigger some kind of operation on the 364 receiving side. On a low level of abstraction every Mbus command can 365 be modeled like this. However on a higher level of abstraction some 366 classes of commands can be identified that are used to implement 367 specific Mbus communication scenarios. The following list decribes 368 these command classes briefly: 370 Remote commands: Remote commands are used to trigger an asynchronous 371 operation on the target system. The command has a name that is 372 associated with a certain operation on the receiving side and can 373 be sent together with a list of arguments (that can be empty) 374 that are interpreted by the receiver. The name and the type 375 definition of the command are specified in application semantics 376 definition document. See Section 5.1 for a detailed discussion of 377 generic remote commands. 379 RPC-style commands: RPC-commands allow to associate an operation at 380 an remote entity with an Mbus command and SHOULD be used when a 381 caller expects a result message from the callee that can return 382 result parameters of the remote procedure/function call. 383 Different types of RPC-commands are defined in this 384 specification. See Section 5.2 for a detailed discussion of 385 RPC-style commands. 387 Transactions: Transaction-style commands are similar to remote 388 commands because they are also used to trigger a remote 389 operation. Additionally transactions are used in scenarios where 390 the caller is interested in how/whether the remote operation has 391 been performed. In general, characteristics of transactions are 392 atomicity (recoverability), consistency, isolation 393 (serializability) and durability. This specification defines 394 procedures for atomic transactions. Consistency, isolation and 395 durability are to be provided by the Mbus application themselves. 396 See Section 5.3 for a detailed discussion of transactions. 398 Properties: Obtaining the value of a named property of another Mbus 399 entity is a variant of an RPC-style command: One command is sent 400 that represent a query and one command is returned to the caller 401 that contains the value. Setting the value of a named variable is 402 a simple remote command with a parameter for the new value. See 403 Section 5.4 for a detailed discussion of commands related to 404 property inspection and manipulation. 406 Event notification: An entity that frequently sends messages to 407 inform other entities of certain events sends a command for each 408 state change (or after a certain interval) to a (group of) 409 receiver(s). These commands are similar to the simple remote 410 commands because they are also sent asynchronously. See Section 411 5.5 for a detailed discussion of event notification. 413 Contexts: Instead of short time interactions between entities that 414 can be accomplished by RPCs and other command classes contexts 415 allow for more persistent relationships between entities. 416 Contexts are scopes for coherent commands that are to be 417 exchanged within a long-term interaction. Contexts provide the 418 service of assigning a name to an interaction context that allows 419 to disambiguate Mbus interactions that use the same commands but 420 refer to different contexts at the same time. See Section 5.6 for 421 a detailed discussion of contexts. 423 The following sections specify useful procedures that SHOULD be 424 considered when defining Mbus command sets that contain commands of 425 the aforementioned classes: 427 5.1 Remote Commands 429 Simple remote commands (that do not belong to any of the other 430 classes) require no special procedures or conventions besides the 431 general recommendations for Mbus command definitions: They SHOULD be 432 defined in a self-contained profile definition, their applicability, 433 the command name and the command arguments SHOULD be documented like 434 proposed in Section 3.2. 436 5.1.1 Example for a Command Definition 438 tools.foo.bar 439 Remote command (reliable/unreliable) 441 Parameters: 442 p1: string 443 p1 is the value for... 445 p2: int 446 p2 is the number of... 448 p3: list of string 449 a list of names for... 451 Optional parameters: none 453 5.1.2 Example for an Mbus Interaction 455 Entity A: 456 --------- 458 "mbus/1.0" 42 65454365 U (app:foo module:gui id:4711-1@192.168.1.1) \ 459 (app:foo module:engine) () 460 tools.foo.bar ("gg" 17 ("a" "b")) 462 Entity B: 463 --------- 465 "mbus/1.0" 42 65454365 U (app:foo module:engine id:4712-1@192.168.1.1) \ 466 (app:foo module:gui id:4711-1@192.168.1.1) () 467 tools.foo.ok () 469 5.2 RPC-style Commands 471 RPC-style commands are implemented by a command-pair: One command 472 (with arguments) for triggering the remote procedure call and one 473 command for the result. There are RPCs for Mbus "point-to-point" 474 communication and RPC for Mbus group communications. The following 475 conventions are proposed: 477 5.2.1 Invoking Remote Procedures 479 o No restriction is imposed on the command name. The class of the 480 command ("RPC") SHOULD be mentioned in the command definition. 482 o The first argument of a RPC command SHOULD be a map of 483 (string,string) (see Section 3.1) and contain meta information. 484 The map SHOULD contain an element with the key "ID". The 485 corresponding value is an arbitrary RPC ID that SHOULD be unique 486 for the calling entity. For point-to-point RPCs (see Section 487 5.2.5 for RPCs to groups of entities) the meta information map 488 SHOULD also contain an element with key "RPC-TYPE" and value 489 "UNICAST". It is RECOMMENDED that unicast RPCs be sent using 490 reliable Mbus messages. Multicast RPCs are defined in Section 491 5.2.5. 493 o The second argument of a RPC command is of type list and contains 494 an arbitrary number of RPC parameters. The syntax and the 495 semantics of this list SHOULD be defined in the definition of the 496 RPC command. 498 5.2.2 Returning Results from Remote Procedure Calls 500 o The names of commands for returning RPC result are constructed 501 using the name of the trigger command and appending the string 502 ".return". 504 o The first argument of a RPC return command is a map of 505 (string,string) for meta information that contains the following 506 information: 508 The original RPC ID that has been generated by the calling 509 entity; 511 Another element with the key of "RPC-STATUS" SHOULD have one 512 of the following values: 514 OK: The procedure has been called. 516 UNKNOWN: No operation is associated with the RPC command. The 517 command is unknown to the callee. 519 The RPC-STATUS parameter is used to signal the generic RPC 520 status and can be used to acknowledge the call of the 521 specified RPC. 523 o The second argument of a RPC return command is of type list and 524 contains a list of return parameters. It is RECOMMENDED that the 525 first element of this list be of type list, containing 526 application specific status information. 528 o The second element SHOULD be of type list and contain further 529 application specific return parameters. The syntax and the 530 semantics of this list SHOULD be defined in the definition of the 531 RPC command. 533 o The application specific status information list SHOULD contain: 535 An identifier (type symbol) that signals the general result 536 (successful or unsuccessful operation) of the RPC. The 537 possible values are "OK" and "FAILED". 539 An identifier (type symbol) that represents the application 540 specific result status of the procedure call. The set of 541 symbols SHOULD be specified in the definition of the RPC. 543 A textual description of the status (type string). 545 If the general result of the RPC is "FAILED" the further 546 parameters may be omitted although they have been specified in 547 the RPC definition. 549 5.2.3 Example for a Command Definition 551 The meta information list (for ID and RPC-TYPE) and the application 552 status list does not have to be provided in RPC command definitions. 554 tools.foo.bar 555 RPC 557 p1: string 558 p1 is the value for... 560 p2: int 561 p2 is the number of... 563 p3: list of string 564 a list of names for... 566 optional parameters: none 568 The following application specific result states are defined: 570 BAR_COMPLETED The bar operation has been called successfully. 571 NO_SUCH_P1 The p1 parameter is invalid. 572 FOO_CRASH The foo module crashed during the execution of bar. 574 return parameters: 576 r1: int 577 the value of... 579 5.2.4 Example for an Mbus Interaction 581 Entity A: 582 --------- 584 "mbus/1.0" 42 65454365 R (app:foo module:gui id:4711-1@192.168.1.1) \ 585 (app:foo module:engine id:4712-1@192.168.1.1) () 586 tools.foo.bar ((("ID" "123") ("RPC-TYPE" "UNICAST")) \ 587 ("gg" 17 ("a" "b"))) 589 Entity B: 590 --------- 592 "mbus/1.0" 57 65454366 U (app:foo module:engine id:4712-1@192.168.1.1) \ 593 (app:foo module:gui id:4711-1@192.168.1.1) () 594 tools.foo.bar.return ((("ID" "123") ("RPC-STATUS" "OK")) \ 595 ((OK BAR_COMPLETED "Success!") (1))) 597 5.2.5 RPC Communication with Multiple Entities 599 Different scenarios for RPCs that are addressed to groups of 600 entities are defined: 602 anycast 603 A sender sends an RPC message to a group of entities and wants 604 exactly one of the entities to perform the operation and return 605 results. 607 one RPC, more than one result command 608 A sender sends an RPC message to a group of entities and wants 609 each entity to perform the operation and to return a result. 611 one RPC, coordinated result 612 A sender sends a RPC message to a group of entities and expects 613 each entity to perform the operation but only one result messages 614 that represents all results of the addressed group. 616 5.2.5.1 Anycast 618 The following conventions are proposed for anycast RPCs: 620 The sender uses a group address as the Mbus target address of the 621 RPC message using unreliable Mbus message transport. 623 The command meta-information list SHOULD provide an entry with 624 key "RPC-TYPE" and value "ANYCAST". 626 Those of the receiving entities that want to respond to the RPC 627 and are able to perform the requested operation return a 628 "standby" command in order to signal their disposition to provide 629 the service. The name of the command is the RPC command name 630 concatenated with ".standby". The first argument is again a 631 meta-information list that contains the original RPC-ID. The 632 target address of this command is an aggregate of the sender 633 address and the target addres of the RPC und MUST therefore be 634 sent unreliably. See Section 7.1 for a description of an address 635 aggregation algorithm. 637 After a timeout T_anycast (Section 8) the entity that originally 638 sent the RPC message selects one of the entities that answered 639 with a "standby" command and sends it the RPC again (in a new 640 message). This message MUST be sent using reliable Mbus message 641 transport. The meta-information list of the command contains an 642 additional entry with a key "REFERENCE". The value is the 643 sequence number of the received standby message. 645 The entity that receives the second RPC message now operates as 646 specified for the regular unicast RPC case. 648 5.2.5.1.1 Example for an Mbus Interaction 650 Entity A: 651 --------- 653 "mbus/1.0" 42 65454365 U (app:foo module:gui id:4711-1@192.168.1.1) \ 654 (module:engine) () 655 tools.foo.bar ((("ID" "123") ("RPC-TYPE" "ANYCAST")) ("gg" 17 ("a" "b"))) 657 Entity B: 658 --------- 660 "mbus/1.0" 57 65454366 U (app:foo module:engine id:4712-1@192.168.1.1) \ 661 () () 662 tools.foo.bar.standby ((("ID" "123"))) 664 Entity C: 665 --------- 667 "mbus/1.0" 83 65454366 U (app:xy module:engine id:4713-1@192.168.1.1) \ 668 () () 669 tools.foo.bar.standby ((("ID" "123"))) 671 Entity A: 672 --------- 673 "mbus/1.0" 43 65454367 U (app:foo module:gui id:4711-1@192.168.1.1) \ 674 (app:xy module:engine id:4713-1@192.168.1.1) () 675 tools.foo.bar ((("ID" "123") ("RPC-TYPE" "ANYCAST") ("REFERENCE" 83)) \ 676 ("gg" 17 ("a" "b"))) 678 Entity C: 679 --------- 681 "mbus/1.0" 84 65454368 U (app:xy module:engine id:4713-1@192.168.1.1) \ 682 (app:foo module:gui id:4711-1@192.168.1.1) () 683 tools.foo.bar.return ((("ID" "123") ("RPC-STATUS" "OK")) \ 684 ((OK BAR_COMPLETED "Success!") (1))) 686 5.2.5.2 One RPC, more than one Result Command 688 The following conventions are proposed for RPCs that are sent to a 689 group of entities where each entity responds independently: 691 The sender uses a group address as the Mbus target address of the 692 RPC message. 694 The command meta-information list SHOULD provide an entry with 695 key "RPC-TYPE" and value "MULTICAST". 697 The sending entity sends the RPC in a message addressed to an 698 Mbus address group using unreliable Mbus message transport and 699 calculates the set of real Mbus addresses (see Section 2) of the 700 entities that are enclosed in the destination address group. See 701 Section 7.2 for an algorithm for expanding Mbus group addresses 702 to real Mbus addresses. 704 The receiving entities operate as specified for the regular 705 unicast RPC case, i.e. they try perform the operation and report 706 the results to the sender of the RPC. The destination address of 707 the result message MUST be the address of the RPC's sender. The 708 message MUST be sent reliably. 710 After an application dependent timeout the entity that originally 711 sent the RPC evaluates the received results: If all entities 712 return a RPC-STATUS of "OK" the RPC can be considered successful. 713 The procedure of how return parameters are gathered, collapsed 714 and presented to the user is application/implementation specific. 716 5.2.5.2.1 Example for an Mbus Interaction 718 Entity A: 719 --------- 721 "mbus/1.0" 42 65454365 U (app:foo module:gui id:4711-1@192.168.1.1) \ 722 (module:engine) () 723 tools.foo.bar ((("ID" "123") ("RPC-TYPE" "MULTICAST")) ("gg" 17 ("a" "b"))) 725 Entity B: 726 --------- 728 "mbus/1.0" 57 65454366 U (app:foo module:engine id:4712-1@192.168.1.1) \ 729 (app:foo module:gui id:4711-1@192.168.1.1) () 730 tools.foo.bar.return ((("ID" "123") ("RPC-STATUS" "OK")) \ 731 ((OK BAR_COMPLETED "Success!") (1))) 733 Entity C: 734 --------- 736 "mbus/1.0" 83 65454366 U (app:xy module:engine id:4713-1@192.168.1.1) \ 737 (app:foo module:gui id:4711-1@192.168.1.1) () 738 tools.foo.bar.return ((("ID" "123") ("RPC-STATUS" "OK")) \ 739 ((OK BAR_COMPLETED "Success!") (2))) 741 5.2.5.3 one RPC, coordinated result 743 The following conventions are proposed for RPCs that are sent to a 744 group of entities where each entity performs the operation but only 745 one result messages that represents all results of the addressed 746 group is sent to the original sender of the RPC: 748 The sender uses a group address as the Mbus target address of the 749 RPC message. 751 The command meta-information list SHOULD provide an entry with 752 key "RPC-TYPE" and value "COORDINATED". 754 The sending entity sends the RPC in a message addressed to an 755 Mbus address group using unreliable Mbus message transport. 757 The receiving entities try to perform the operation and then send 758 intermediate result commands to the RPC destination group. After 759 a timeout T_Coordination one entity aggregates all intermediate 760 results and sends an aggregated RPC-result message to the 761 original sender. The coordination process and the procedure how 762 to decide which entity reports the gathered results is yet TBD. 764 :-( 766 5.2.5.3.1 Example for an Mbus Interaction 768 Entity A: 769 --------- 771 "mbus/1.0" 42 65454365 U (app:foo module:gui id:4711-1@192.168.1.1) \ 772 (module:engine) () 773 tools.foo.bar ((("ID" "123") ("RPC-TYPE" "COORDINATED")) ("gg" 17 ("a" "b"))) 775 TBD... 777 5.3 Transactions 779 Transactions are implemented by defining a command that triggers an 780 operation and an additional acknowledgement command that is sent 781 after the operation has completed (or failed). Acknowledgement 782 commands MUST refer to the initial trigger command and this relation 783 is expressed by a special reference parameter that is generated by 784 the caller. Note that the acknowledgement command is different from 785 acknowledgments on the Mbus transport level: Those only ensure that 786 messages are really received by the addressees, whereas transaction 787 acknowledgments inform the original caller about the result of a 788 certain operation that the callee should have performed upon 789 reception of the transaction command. 791 Transaction commands are only allowed for unicast messages, they may 792 not be sent to address groups. They MUST be sent using reliable Mbus 793 messages. Senders of transaction commands are called clients, 794 receivers of transaction commands are called servers. 796 After a sender (a client) has initiated a transaction with the 797 respective transaction command (see below) it may abort (rollback) 798 the transaction with a dedicated command (see below) or finally 799 commit the transaction using another dedicated command. 801 It should be noted that means for concurrency control, e.g., to 802 achieve consistency in the presence of parallel transactions, have 803 to be provided by the application itself and is not part of these 804 conventions. 806 The following conventions for transaction commands are proposed: 808 o There are no restrictions on naming transaction commands. Any 809 command in an Mbus command hierarchy can be used for triggering 810 transactions. The class of the command ("TRANSACTION") SHOULD be 811 mentioned in the command definition. 813 o The first argument of a transaction command SHOULD be a map of 814 (string,string) (see Section 3.1) and contain meta information. 815 The map SHOULD contain an element with the key "ID". The 816 corresponding value is an arbitrary transaction ID that SHOULD be 817 unique for the calling entity. 819 o The second argument of a transaction command is of type list and 820 contains an arbitrary number of transaction parameters. The 821 syntax and the semantics of this list SHOULD be defined in the 822 definition of the transaction command. 824 o After a transaction command has been sent the sender can either 825 cancel or commit the transaction: A transaction cancel command 826 has the original transaction command name plus an appended 827 ".cancel" as a command name and the original transaction id as a 828 meta information parameter. A receiver SHOULD cancel or rollback 829 any actions initiated by the original transaction message after 830 receiving a transaction cancellation and delete any state related 831 to the transaction. A transaction commit command has the original 832 transaction command name plus an appended ".commit" as a command 833 name and the original transaction id as a meta information 834 parameter. A receicing entity SHOULD finish outstanding action 835 initiated by the original transaction command after receiving a 836 transaction commit command and delete any state related to the 837 transaction. After a commit has been received cancel commands for 838 the corresponding transaction MUST NOT be honoured anymore. 840 o After receiving a transaction command an entity responds with an 841 acknowledgement. Acknowledgment command names are constructed 842 using the name of the trigger command and appending the string 843 ".ack". The first argument of a transaction acknowledgement 844 command is of type "String" and contains the original transaction 845 ID that has been generated by the calling entity. Any action that 846 is performed MUST be reversible and SHOULD only be executed in 847 non-reversible way after a commit command has been received for 848 the corresponding transaction. If a cancel command for the 849 corresponding transaction has been received before a commit 850 command the entity SHOULD rollback any performed actions. 852 o The second argument of a transaction acknowledgement command is 853 of type "Symbol" and can have one of the following values: 855 OK: The transaction was successful. 857 UNKNOWN: No operation is associated with the transaction command. 858 The command is unknown to the callee. 860 FAILED: The transaction could not be performed successfully. 862 CANCELLED: The transaction has been cancelled. 864 o Further information about the transaction status can be supplied 865 optionally and can be passed in a common optional command list 866 (see Section 3.2.1). 868 o After a server has received a commit command for a transaction it 869 SHOULD respond with an additional acknowledgement command. For 870 clarity the command name for this command is composed of the name 871 of the original command and an appended ".completed". The 872 parameters are the same as for the first acknowledgement. 874 5.3.1 Example for a Command Definition 876 The meta information list (for the transaction ID) does not have to 877 be provided in transaction command definitions. 879 tools.foo.bar 880 TRANSACTION 882 Parameters: 884 p1: string 885 p1 is the value for... 887 p2: int 888 p2 is the number of... 890 p3: list of string 891 a list of names for... 893 Optional parameters: none 895 5.3.2 Example for an Mbus Interaction I 897 Entity A: 898 --------- 900 "mbus/1.0" 42 65454365 R (app:foo module:gui id:4711-1@192.168.1.1) \ 901 (app:foo module:engine id:4712-1@192.168.1.1) () 902 tools.foo.bar ((("ID" "123")) ("gg" 17 ("a" "b"))) 904 Entity B: 905 --------- 907 "mbus/1.0" 57 65454366 U (app:foo module:engine id:4712-1@192.168.1.1) \ 908 (app:foo module:gui id:4711-1@192.168.1.1) () 909 tools.foo.bar.ack ("123" OK) 911 Entity A: 912 --------- 914 "mbus/1.0" 43 65454367 R (app:foo module:gui id:4711-1@192.168.1.1) \ 915 (app:foo module:engine id:4712-1@192.168.1.1) () 916 tools.foo.bar.commit ((("ID" "123"))) 918 Entity B: 919 --------- 921 "mbus/1.0" 58 65454368 U (app:foo module:engine id:4712-1@192.168.1.1) \ 922 (app:foo module:gui id:4711-1@192.168.1.1) () 923 tools.foo.bar.completed ("123" OK) 925 5.3.3 Example for an Mbus Interaction II 927 Entity A: 928 --------- 930 "mbus/1.0" 42 65454365 R (app:foo module:gui id:4711-1@192.168.1.1) \ 931 (app:foo module:engine id:4712-1@192.168.1.1) () 932 tools.foo.bar ((("ID" "123")) ("gg" 17 ("a" "b"))) 934 Entity B: 935 --------- 937 "mbus/1.0" 57 65454366 U (app:foo module:engine id:4712-1@192.168.1.1) \ 938 (app:foo module:gui id:4711-1@192.168.1.1) () 939 tools.foo.bar.ack ("123" OK) 941 Entity A: 942 --------- 944 "mbus/1.0" 43 65454367 R (app:foo module:gui id:4711-1@192.168.1.1) \ 945 (app:foo module:engine id:4712-1@192.168.1.1) () 946 tools.foo.bar.cancel ((("ID" "123"))) 948 Entity B: 949 --------- 951 "mbus/1.0" 58 65454368 U (app:foo module:engine id:4712-1@192.168.1.1) \ 952 (app:foo module:gui id:4711-1@192.168.1.1) () 953 tools.foo.bar.completed ("123" CANCELLED) 955 5.4 Inspection/Modification of Properties 957 Obtaining the value of a named property of another entity is 958 achieved by using a set of RPC-style commands (see Section 5.2): 959 RPCs are defined for setting, obtaining and "watching" values of 960 properties. The following conventions are proposed: 962 o No restriction is imposed on the property's name. Entities can 963 use any command to transmit a new value for a certain property. 964 The Mbus command name is the property name. In a profile 965 definition a property SHOULD be classified as ("PROPERTY") which 966 means that it is possible for other entities to set/retrieve its 967 value (see below). Additionally the type of the property SHOULD 968 be specified using the syntax specified in Section 3.2. 970 o In order to obtain the value of a certain property that is 971 managed by another Mbus entity a module sends a "get-request" RPC 972 to the respective entity. The command name of this RPC is 973 composed of the property name and ".get". The RPC argument list 974 is empty. Upon receiving a get-request an entity hosting the 975 property returns a RPC result command to the requesting entity. 976 The (only) RPC argument is the current value. Application 977 specific status values (Section 5.2) for the return command of a 978 get-RPC are: 980 OK: Property exists. 982 NO_SUCH_PROPERTY: The requested property does not exist. 984 o In order to change the value of a certain property that is 985 managed by another Mbus entity a module sends a "set-request" RPC 986 to the respective entity. The command name of this RPC is 987 composed of the property name and ".set". The (only) RPC argument 988 is the new value. Upon receiving a set-request an entity hosting 989 the property changes the value and returns a RPC result command 990 to the requesting entity. The (only) RPC argument is the new 991 value. Application specific status values (Section 5.2) for the 992 return command of a set-RPC are: 994 OK: Property exists and has been updated. 996 NO_SUCH_PROPERTY: The requested property does not exist. 998 o Besides get-requests clients can also use "watch-requests" to 999 obtain the value of properties. watch-requests can be sent if an 1000 entity wants to be informed about any updates to the property 1001 value. The RPC command name of this request is composed of the 1002 variable name and ".watch". The RPC argument list is empty. Upon 1003 receiving a watch-request an entity that hosts the property adds 1004 the originating entity to a list of subscribers for the property 1005 variable and will further on send an update to all list members 1006 when the value of the property changes. The current value of the 1007 property is sent to the originator of the watch-request in a RPC 1008 return command. The updates are event notificatons as specified 1009 in Section 5.5, i.e., simple Mbus commands with the property name 1010 as the command name and the current value as the only parameter. 1011 Application specific status values (Section 5.2) for the return 1012 command of a watch-RPC are: 1014 OK: Property exists and the requesting entity has been added to 1015 the list of subscribers. 1017 NO_SUCH_PROPERTY: The requested property does not exist. 1019 o A subscriber of a property can also send an "unwatch-request" RPC 1020 to unsubscribe. The command name of this request is composed of 1021 the property name and ".unwatch". The argument list is empty. The 1022 RPC return command also requires no further RPC parameter. 1023 Application specific status values (Section 5.2) for the return 1024 command of a uwatch-RPC are: 1026 OK: Property exists and the requesting entity has been removed 1027 from the list of subscribers. 1029 NO_SUCH_PROPERTY: The requested property does not exist. 1031 NOT_SUBSCRIBED The requesting entity is not on the list of 1032 subcribers for this property. 1034 Entities that have been declared to provide a property, e.g., in a 1035 profile definition, SHOULD support all aforementioned requests. 1037 All requests related to properties MUST be send as unicast RPCs. 1039 Notes: 1040 Requests for non-existing properties result in a RPC-UNKNOWN error 1041 (see Section 5.2). 1043 5.4.1 Example for a Command Definition 1045 The RPC commands for the different property request do not have to 1046 be specified. 1048 tools.foo.bar 1049 PROPERTY 1051 type: string 1053 5.4.2 Example for an Mbus Interaction I 1055 Entity A: 1056 --------- 1058 "mbus/1.0" 42 65454365 R (app:foo module:gui id:4711-1@192.168.1.1) \ 1059 (app:foo module:engine id:4712-1@192.168.1.1) () 1060 tools.foo.bar.get ((("ID" "123") ("RPC-TYPE" "UNICAST"))) 1062 Entity B: 1063 --------- 1065 "mbus/1.0" 57 65454366 U (app:foo module:engine id:4712-1@192.168.1.1) \ 1066 (app:foo module:gui id:4711-1@192.168.1.1) () 1067 tools.foo.bar.get.return ((("ID" "123") ("RPC-STATUS" "OK")) \ 1068 ((OK OK "") ("the value"))) 1070 5.4.3 Example for an Mbus Interaction II 1072 Entity A: 1073 --------- 1075 "mbus/1.0" 42 65454365 R (app:foo module:gui id:4711-1@192.168.1.1) \ 1076 (app:foo module:engine id:4712-1@192.168.1.1) () 1077 tools.foo.bar.set ((("ID" "123") ("RPC-TYPE" "UNICAST")) \ 1078 ((OK OK "") ("the value"))) 1080 Entity B: 1081 --------- 1083 "mbus/1.0" 57 65454366 U (app:foo module:engine id:4712-1@192.168.1.1) \ 1084 (app:foo module:gui id:4711-1@192.168.1.1) () 1085 tools.foo.bar.set.return ((("ID" "123") ("RPC-STATUS" "OK")) \ 1086 ((OK OK "") ("new value"))) 1088 5.4.4 Example for an Mbus Interaction III 1090 Entity A: 1091 --------- 1093 "mbus/1.0" 42 65454365 R (app:foo module:gui id:4711-1@192.168.1.1) \ 1094 (app:foo module:engine id:4712-1@192.168.1.1) () 1095 tools.foo.bar.watch ((("ID" "123") ("RPC-TYPE" "UNICAST"))) 1097 Entity B: 1098 --------- 1099 "mbus/1.0" 57 65454366 R (app:foo module:engine id:4712-1@192.168.1.1) \ 1100 (app:foo module:gui id:4711-1@192.168.1.1) () 1101 tools.foo.bar.watch.return ((("ID" "123") ("RPC-STATUS" "OK")) \ 1102 ((OK OK "") ("the value"))) 1104 Entity C: 1105 --------- 1107 "mbus/1.0" 82 65454367 R (app:bar module:engine id:4713-1@192.168.1.1) \ 1108 (app:foo module:engine id:4712-1@192.168.1.1) () 1109 tools.foo.bar.set ((("ID" "345") ("RPC-TYPE" "UNICAST")) \ 1110 ((OK OK "") ("new value"))) 1112 Entity B: 1113 --------- 1115 "mbus/1.0" 58 65454368 R (app:foo module:engine id:4712-1@192.168.1.1) \ 1116 (app:bar module:engine id:4713-1@192.168.1.1) () 1117 tools.foo.bar.set.return ((("ID" "345") ("RPC-STATUS" "OK")) \ 1118 ((OK OK "") ("new value"))) 1120 Entity B: 1121 --------- 1123 "mbus/1.0" 59 65454369 U (app:foo module:engine id:4712-1@192.168.1.1) \ 1124 (app:foo module:gui id:4711-1@192.168.1.1) () 1125 tools.foo.bar ("new value") 1127 Entity A: 1128 --------- 1130 "mbus/1.0" 43 65454370 R (app:foo module:gui id:4711-1@192.168.1.1) \ 1131 (app:foo module:engine id:4712-1@192.168.1.1) () 1132 tools.foo.bar.unwatch ((("ID" "124") ("RPC-TYPE" "UNICAST"))) 1134 Entity B: 1135 --------- 1137 "mbus/1.0" 60 65454371 R (app:foo module:engine id:4712-1@192.168.1.1) \ 1138 (app:foo module:gui id:4711-1@192.168.1.1) () 1139 tools.foo.bar.unwatch.return ((("ID" "123") ("RPC-STATUS" "OK"))) 1141 5.5 Event Notifications 1143 There are different usage scenarios for events that origin at a 1144 certain entity and need to be signaled to other entities. An event 1145 notification is an Mbus command with an arbitrary argument list that 1146 is sent (eventually, maybe periodically) to a group of entities. The 1147 following conventions are proposed: 1149 o No restriction is imposed on the name of the notification 1150 command. In a profile definition a command SHOULD be classified 1151 as ("EVENT NOTIFICATION"). 1153 o A command that is classified as an event notification SHOULD also 1154 be associated with a default target address that is used when the 1155 notification command is sent. 1157 See Section 6 for conventions of how to subscribe to and how to 1158 redirect event notifications. 1160 5.5.1 Example for a Command Definition 1162 tools.foo.bar 1163 EVENT NOTIFICATION 1165 default target address: (app:xy module:gui) 1167 Parameters: 1168 p1: string 1169 p1 is the value for... 1171 p2: int 1172 p2 is the number of... 1174 p3: list of string 1175 a list of names for... 1177 5.5.2 Example for an Mbus Interaction 1179 Entity A: 1180 --------- 1182 "mbus/1.0" 42 65454365 U (app:foo module:gui id:4711-1@192.168.1.1) \ 1183 (app:xy module:gui) () 1184 tools.foo.bar ("gg" 17 ("a" "b")) 1186 5.6 Contexts 1188 RPCs can be used to trigger a remote operation with the possibility 1189 to obtain results from a single operation thus representing a short 1190 time interaction between two or more Mbus entities. Sometimes there 1191 is the need for more persistent interaction relations between 1192 entities, for example, when a series of commands all refer to the 1193 same context. The command category "contexts" allows for expressing 1194 a long-term relationship between commands that are exchanged by Mbus 1195 entities. 1197 The model that is used here is the concept of a specific context in 1198 which a sequence of Mbus commands are exchanged that relate to each 1199 other and are originated by entities of a group of Mbus entities. 1200 The context that provides a scope for Mbus commands is identified by 1201 a unique id that is used in all commands belonging to the context. 1203 Contexts can start to exist (they can be created) and cease to exist 1204 (destructed). Mbus commands for context creation and destruction 1205 will be defined below. 1207 Only certain specified commands are valid within a context. An Mbus 1208 context definition specifies these commands and their semantics. 1209 Context commands are either RPC commands (see Section 5.2) or event 1210 notifications that provide the context-id in the meta information 1211 parameter (key="CONTEXT-ID"). The subsequent argument of a context 1212 command is of type list and contains an arbitrary number of 1213 parameters. The syntax and the semantics of this list SHOULD be 1214 specified in the definition of the command. 1216 The name of a context is an Mbus command prefix. Command names for 1217 construction and destruction commands as well as other context 1218 commands are derived from the context name by appending a dot and 1219 the name of the method. The name of the construction command is 1220 CONTEXT_NAME.create and the name of the destruction command is 1221 CONTEXT_NAME.delete. Both are "simple" Mbus commands (remote 1222 commands) with one parameter: the context-id as a parameter of type 1223 string. 1225 CONTEXT_NAME.create and CONTEXT_NAME.delete can be sent to single 1226 Mbus entities as well as to group of entities using a Mbus group 1227 address. It is RECOMMENDED that context-creation/deletion messages 1228 to single entities be sent reliable. Only the creator of a context 1229 (the entity that has sent the CONTEXT_NAME.create message) SHOULD 1230 delete the corresponding context. 1232 5.6.1 Example for a Command Definition 1234 The meta information list (for the context ID and eventual RPC or 1235 transaction IDs) does not have to be provided in each command 1236 definition in the context definition. 1238 Context "conf.call-ctrl.call" 1239 ------------------------ 1241 About: This context definition comprehends commands that can be used 1242 for a "call context". The following commands may refer 1243 to different contexts that represent different calls. 1245 The following commands are defined in this context: 1247 conf.call-ctrl.call.setup 1248 RPC 1250 Parameters: 1252 caller: string 1253 identifies the caller 1255 callee: string 1256 identifies the callee 1258 Optional Parameters: none 1260 conf.call-ctrl.call.disconnected 1261 EVENT NOTIFICATION 1263 default target address: (app:controller) 1265 Parameters: 1267 reason: string 1268 the reason for the disconnection 1270 Optional Parameters: none 1272 5.6.2 Example for an Mbus Interaction 1274 Entity A: 1275 --------- 1277 "mbus/1.0" 42 65454365 U (app:controller module:engine id:4711-1@192.168.1.1) \ 1278 (app:call-ctrl module:engine id:4712-1@192.168.1.1) () 1279 conf.call-ctrl.call.create ("345") 1281 Entity A: 1282 --------- 1284 "mbus/1.0" 43 65454366 R (app:controller module:gui id:4711-1@192.168.1.1) \ 1285 (app:call-ctrl module:engine id:4712-1@192.168.1.1) () 1286 conf.call-ctrl.call.setup ((("ID" "123") ("CONTEXT-ID" "345")) \ 1287 ("joe@foo.bar" "bob@foo.bar")) 1289 Entity B: 1290 --------- 1292 "mbus/1.0" 57 65454380 U (app:call-ctrl module:engine id:4712-1@192.168.1.1) \ 1293 (app:controller) () 1294 conf.call-ctrl.call.disconnected ((("CONTEXT-ID" "345")) ("hangup")) 1296 Entity A: 1297 --------- 1299 "mbus/1.0" 44 65454385 U (app:controller module:engine id:4711-1@192.168.1.1) \ 1300 (app:call-ctrl module:engine id:4712-1@192.168.1.1) () 1301 conf.call-ctrl.call.delete ("345") 1303 5.7 Status Signaling 1305 In order to notify other entities of status events asynchronously, 1306 each Mbus entity SHOULD send such events using the "mbus.status" 1307 command. This command is an event notification as specified in 1308 Section 5.5 and can thus also be given a default target address. 1310 As specified in Section 5.5 the default target address of this 1311 message can be redirected using the "mbus.register" command defined 1312 in Section 6.1.1. 1314 mbus.status 1315 EVENT NOTIFICATION 1317 Parameters: 1318 class: symbol 1319 An identifier for the class of the status message. 1320 Predefined identifiers are: 1322 INFO: for informational messages 1323 WARNING: for warnings 1324 ERROR: for error reports 1326 Application profiles can also define new status 1327 message classes. 1329 sym: symbol 1330 An identifier for the status message. Application 1331 profile definitions SHOULD enumerate the possible 1332 status symbols (and their textual description, see 1333 below). 1335 descr: string 1336 A textual description for the status message. 1338 Optional Parameters: none 1340 To be discussed (FIXME): Should mbus.status only be used top-level 1341 or with arbitrary prefixes? 1343 5.7.1 Example of a Definition of Status Symbols 1345 TBD 1347 6. Mbus service models 1349 In general, the Mbus is a communication channel for message passing 1350 within a group of modules. Mbus implementations provide mechanisms 1351 to enable applications modules to pass messages to other modules. 1352 From an application point of view the goal of using the Mbus is 1353 using certain services of other entities (or providing these 1354 services). 1356 Each Mbus entity can provide a number of different services: It may 1357 perform certain operations for other entities that are triggered by 1358 the reception of Mbus commands or it may notify one or more entities 1359 of events. 1361 In the simplest case, an entity will simply receive Mbus messages 1362 and perform the operations that are denominated by the commands that 1363 are contained in the messages. Sometimes, however, entities will 1364 only process certain commands if they are are received from an 1365 entity that has registered as a client, e.g. a controller, before. 1366 Entities that are remote-controlled via their Mbus interface could 1367 restrict the number of controlling entities to one (at a time) in 1368 order to ensure consistency. Also, there could be event 1369 notifications that are sent to a certain dedicated controller only, 1370 as well as there can be notifications that can be sent to a group of 1371 receivers, each of which having subscribed to this event source 1372 before. Again, in simple scenarios, entities may just broadcast all 1373 event notifications to the whole Mbus. 1375 It is proposed that all commands, variables, event notifications 1376 that an entity may send or receive in a specific application context 1377 be subsumed in a common Mbus command set definition. Service models 1378 that apply to such a set of Mbus commands SHOULD be specified as 1379 well. 1381 In the following the different service models (control relation 1382 classes) are described in detail and a list of conventions and 1383 recommendations is presented that SHOULD be considered when writing 1384 Mbus command definitions. 1386 Different classes of control relations are defined: 1388 o no control 1390 o tight control 1392 o exclusive tight control 1394 These different classes of control relations are usually applied to 1395 a command set that is implemented by some Mbus entities. It is 1396 suggested that a control relation type is assigned to command sets 1397 in the command set definition. 1399 The motivation for defining different service models is to 1400 accommodate different applications with different requirements 1401 concerning flexibility and the level of control for their Mbus 1402 communication. 1404 The next sections specify the semantics and implications of the 1405 individual control classes: 1407 6.1 No Control 1409 "no control" means that entities do not require a special control 1410 relation with another entity to be established in order to accept 1411 commands from it. All Mbus commands, variables etc. of the 1412 respective command set can be used directly and there is no 1413 regulation of the number of entities that may interact using the 1414 respective commands at a time. 1416 A command set that is classified as "no control" may contain 1417 commands for unsolicited event notification or even RPC-style 1418 commands that can be sent by an entity conforming to a specific Mbus 1419 command set definition. These Mbus commands that are originated by a 1420 conforming entity may be addressed to a default target address. 1421 There may be a default target address for all commands of a command 1422 definition set but each command may be associated to a specific 1423 default target address. It is RECOMMENDED that commands of the "no 1424 control" class that may be sent without prior solicitation, such as 1425 event notifications, are assigned a default target address. 1427 The default target address that an entity sends unsolicited commands 1428 to may be changed by other entities. Entities may add themselves to 1429 a list of clients/controllers that is maintained by another service 1430 providing entity. The effect of having the service providing entity 1431 add another entity to a list of clients is that the default target 1432 address is no longer used but the respective messages are directed 1433 to the client entity. If more than one entity tries to add itself to 1434 the target address list it is up to the application to allow or deny 1435 this. Generally, entities of the "no control" class are expected to 1436 accept multiple clients. When multiple clients are present each 1437 message that would otherwise just be sent to the default target 1438 address is sent either to a Mbus group address that uniquely 1439 represents the registered clients or is sent independently to all 1440 clients. Clients may also deregister. When all clients have 1441 deregistered the entity SHOULD use the default target address for 1442 the respective command again. 1444 The changing of the default target address is called redirection. 1446 Redirection may take place on single commands or a complete command 1447 set. If a command or a command set use a default target address that 1448 can be redirected by clients it SHOULD be marked as "REDIRECTABLE" 1449 and the default target address SHOULD be given. 1451 Redirection commands belong to the class of RPC-commands. The 1452 following commands are defined (see Section 3.1 for parameter type 1453 definitions): 1455 6.1.1 mbus.register 1457 RPC 1459 Parameters: 1461 command: string 1462 Name of the Mbus command (or command set prefix, MUST be 1463 specified absolutely) 1465 addr: MbusAddress 1466 Mbus address that should be registered. 1468 Optional Parameters: none 1470 Description: This command is sent by an interested client entity to 1471 a service providing entity in order to change its default target 1472 address for the given command (prefix). 1474 Application specific return values 1476 OK: The client has been added to the address list. 1478 NO_SUCH_COMMAND: The command (prefix) that has been given in the 1479 request is unknown. 1481 DENIED: The requesting entity is denied to register the given 1482 command (prefix). 1484 Return parameters: 1486 addr-list: list of MbusAddress 1487 the new list of registered clients. 1489 6.1.2 mbus.deregister 1491 RPC 1493 Parameters: 1495 command: string 1496 Name of the Mbus command (or command set prefix, MUST be 1497 specified absolutely) 1499 addr: MbusAddress 1500 Mbus address that should be deregistered. 1502 Optional Parameters: none 1504 Description: This command is sent by a registered client entity to a 1505 service providing entity in order to deregister from a command or 1506 service subscription. 1508 Application specific return values 1510 OK: The client has been removed from the address list. 1512 NO_SUCH_COMMAND: The command (prefix) that has been given in the 1513 request is unknown. 1515 NOT_REGISTERED: The given address has not been registered before 1516 for the command (prefix). 1518 Return parameters: 1520 add-list: list of MbusAddress 1521 the new list of registered clients. 1523 6.1.3 mbus.registered 1525 EVENT NOTIFICATION 1527 Parameters: 1529 string command: Name of the Mbus command (or command set prefix) 1531 list of MbusAddress add-list: Current list of registered clients 1533 Description: This notification is sent by a service providing entity 1534 after a new client has registered for a command (prefix). The 1535 second parameter contains the new list of registered clients for 1536 the given command. The notfication SHOULD be sent to the old list 1537 of clients (or to the default target address if no other clients 1538 have registered before). 1540 6.1.4 mbus.get-registered 1542 RPC 1544 Parameters: 1546 command: string 1547 Name of the Mbus command (or command set prefix) 1549 Optional Parameters: none 1551 Description: This command can be used in order to obtain the current 1552 list of registered clients for the specified command (prefix). 1554 Application specific return values 1556 OK: The list of registered clients is provided. 1558 NO_SUCH_COMMAND: The command (prefix) that has been given in the 1559 request is unknown. 1561 Return parameters: 1563 addr-list: list of MbusAddress 1564 the list of registered clients. 1566 6.2 Tight Control 1568 An entity that requires "tight control" for some or all of its Mbus 1569 controllable resources will only accept commands from an entity that 1570 has established a control relationship before. This means that Mbus 1571 commands, variables etc. can only be used by another entity after it 1572 has registered itself as a "controller" at the entity that provides 1573 the resources. Upon this registration the controlled entity adds the 1574 new controller's Mbus address to a controller-address-list that is 1575 used for authorization and for sending event notifications etc. 1576 Another complementary de-registration command enables entitites to 1577 end the control relationship. Again, there is no regulation of the 1578 number of entities that may register themselves as a controller at a 1579 time. 1581 Entities that conform to a command set definition marked as "tight 1582 control" SHOULD not send commands or event notifications to a 1583 default target address for resources of that set. 1585 6.3 Exclusive Tight Control 1587 "Exclusive tight control" has the same semantics as "tight control", 1588 except for the number of controllers at a time: An entity that 1589 provides an Mbus command set that has been marked as requiring 1590 exclusive tight control will only accept one controller at a timer 1591 and reject register requests once a control relation with another 1592 entity has been established. 1594 When a register request is received while another entity is 1595 currently registered as a controller the receicing entity SHOULD 1596 return the value "DENIED" (see Section 6.1.1. 1598 7. Algorithms 1600 7.1 Aggregation of Mbus Addresses 1602 The following algorithm can be used to aggregate an arbitrary number 1603 of Mbus addresses: (FIX this example code) 1605 template 1606 inline MAddress aggregate(Input start, Input end) 1607 { 1608 typedef map elements; 1609 elements ae; 1610 int count=0; 1611 MAddress res; 1613 // get all address elements: 1614 for(;start!=end;start++) { 1615 count++; 1616 for(MAddress::Const_Iterator ai(*start); ai; ++ai) { 1617 ae[*ai]++; // count occurence of AddressElements 1618 } 1619 } 1620 // keep all Elements that occured in every Address: 1621 elements::const_iterator ei; 1622 for(ei=ae.begin();ei!=ae.end();ei++) { 1623 if(ei->second==count) { 1624 res.setElement(ei->first.key(),ei->first.val()); 1625 } 1626 } 1627 return res; 1628 } 1630 7.2 Expansion of Mbus Group Addresses 1632 The following algorithm can be used to expand an Mbus group address 1633 to the set of real Mbus addresses enclosed within the group address. 1635 TBD 1637 8. Definition of Constants 1639 The following constants are defined: 1641 T_anycast: N_r * T_r (see [1]) 1643 T_Coordindation: 2 * N_r * T_r (see [1]) 1645 References 1647 [1] Ott, J., Perkins, C. and D. Kutscher, "A Message Bus for Local 1648 Coordination", Internet Draft 1649 draft-ietf-mmusic-mbus-transport-04.txt, February 2001. 1651 [2] Schulzrinne, H., Casner, S., Frederick, R. and V. Jacobsen, 1652 "RTP: A Transport Protocol for Real-Time Applications", RFC 1653 1889, January 1996. 1655 Author's Address 1657 Dirk Kutscher 1658 TZI, Universitaet Bremen 1659 Bibliothekstr. 1 1660 Bremen 28359 1661 Germany 1663 Phone: +49.421.218-7595 1664 Fax: +49.421.218-7000 1665 EMail: dku@tzi.org 1667 Appendix A. Examples for Application Profiles 1669 A.1 Mbus Profile for RTP applications 1671 This needs to be updated. 1673 The following commands are used to provide information about an RTP 1674 [2] media source. Each source in media sessions is identified by its 1675 SSRC (not by the CNAME, since this would not be unique). Correlation 1676 to CNAMEs for cross-media references (eg: for lip- synchronization) 1677 has to be done by receiving entities. 1679 The purpose of this Mbus profile is to provide a mechanism that 1680 allows for controlling RTP engine. RTP engines are entities that use 1681 an RTP protocol stack to send and receive RTP/RTCP data. This Mbus 1682 profile provide control commands to configure RTP engine and 1683 notification commands to notify interested engine of RTP events. 1685 All commands of this set conform to the control class "exclusive 1686 tight control". The default destination address for event 1687 notifications is (). 1689 It is suggested that RTP engines that support these commands, i.e. 1690 that can be controlled by the RPCs listed below and that can 1691 generate the event notifications, provide the following address 1692 element in their Mbus addresses: 1693 (module:engine) 1695 For all commands, event notifications that carry a SSRC value, the 1696 value is represented as a string in hexadecimal notation. 1698 A.1.1 Configuring a RTP engine 1700 The following commands are used to configure a RTP engine. 1702 A.1.1.1 rtp.set-attributes 1704 rtp.set-attributes (attribute-list) 1705 RPC 1707 This command is used to configure the SSRC and SDES parameters of a 1708 RTP engine. 1710 Parameters: 1712 attribute-list: map of (String,String) 1713 A map containing configuration information. The first element of 1714 each pair is the name of the attribute and the second element of 1715 each pair is the value of the attribute. The following attribute 1716 names are defined: 1718 SSRC: The SSRC value to be used by the RTP engine. 1720 NAME: The name of the participant. 1722 PHONE: The phone number of the participant. 1724 LOC: The geographic location of the participant. 1726 TOOL: The application/tool name of the participant. 1728 NOTE: The notice/status item. 1730 CNAME: The canonical end-point identifier for the participant. 1732 If other attribute names than those listed are used they are to 1733 be interpreted as PRIV SDES items (see [2]). 1735 A.1.1.2 Controlling a RTP engine 1737 The following commands are used to control a RTP engine during a RTP 1738 session. 1740 A.1.1.2.1 rtp.source.mute 1742 rtp.source.mute (ssrc muteState) 1743 RPC 1745 The command indicates that a source is to be muted/ unmuted. 1747 Parameters: 1749 ssrc: string 1750 The SSRC value of the participant to be muted/unmuted. 1752 muteState: Integer 1753 The value of the muteState parameter is 0 to indicate unmuted, 1754 and 1 to indicate muted. 1756 A.1.1.3 Events generated by a RTP engine 1758 The following commands are used by a RTP engine to signal source 1759 specific events during a RTP session. 1761 A.1.1.3.1 rtp.source.exists 1763 rtp.source.exists (ssrc validityTime) 1764 EVENT NOTIFICATION 1765 The rtp.source.exists command is sent by a media engine to assert 1766 that a particular source is present in a session. 1768 Parameters: 1770 ssrc: string 1771 The ssrc of the source this event notification refers to. 1773 validityTime: Integer 1774 The validityTime parameter is the time for which that source 1775 should be considered valid, in seconds. If another 1776 rtp.source.exists command has not been received for that source 1777 within this time period, the source is implicitly timed out. The 1778 validityTime SHOULD be three times the RTCP reporting interval 1779 for that session. 1781 A.1.1.3.2 rtp.source.left 1783 rtp.source.left (ssrc) 1784 EVENT NOTIFICATION 1786 The rtp.source.left command is used to indicate that a source has 1787 left the session. 1789 Parameters: 1791 ssrc: string 1792 The ssrc of the source this event notification refers to. 1794 A.1.1.3.3 rtp.source.attributes 1796 rtp.source.attributes (ssrc attribute-list) 1797 EVENT NOTIFICATION 1799 This event notification is used to pass RTCP SDES information of 1800 other sources from a media engine to a user interface. 1802 Parameters: 1804 ssrc: string 1805 The ssrc of the source this event notification refers to. 1807 attribute-list: map of (String,String) 1808 A map containing the SDES information. The first element of each 1809 pair is the name of the attribute and the second element of each 1810 pair is the value of the attribute. The same attributes as for 1811 rtp.set-attributes (Appendix A.1.1.1) are defined (except for 1812 SSRC). 1814 A.1.1.3.4 rtp.source.reception 1816 rtp.source.reception (ssrc packetsRecv packetsLost packetsMisordered 1817 jitter validityTime) 1818 EVENT NOTIFICATION 1820 This command is used to pass RTCP RR information from a media engine 1821 to a user interface. The total number of packets received, lost and 1822 misordered are sent, together with the network timing jitter in 1823 milliseconds and a validity time for this report in seconds. 1825 Parameters: 1827 ssrc: string 1828 The ssrc of the source this event notification refers to. 1830 packetsRecv: Integer 1831 Total number of received packets. 1833 packetsLost: Integer 1834 Total number of lost packets. 1836 packetsMisordered: Integer 1837 Total number of misordered packets. 1839 jitter: Integer 1840 Observed jitter in milliseconds. 1842 validityTime: Integer 1843 Validity time in seconds for this report. 1845 A.1.1.3.5 rtp.source.packet.loss 1847 rtp.source.packet.loss (dest_ssrc src_ssrc% validityTime) 1848 EVENT NOTIFICATION 1850 Sent by a media engine to indicate the instantaneous packet loss 1851 observed between two sources. The validityTime for this report is in 1852 milliseconds. 1854 Parameters: 1856 dest_ssrc: string 1857 The ssrc of the receiving participant. 1859 src_ssrc: string 1860 The ssrc of the sending participant. 1862 validityTime: Integer 1863 The validityTime for this report is in milliseconds. 1865 A.1.1.3.6 rtp.source.active 1867 rtp.source.active (ssrc validityTime) 1868 EVENT NOTIFICATION 1870 The rtp.source.active notification indicates that a source is 1871 transmitting data into the session. The validityTime field indicates 1872 the period for which this source should be considered active, in 1873 milliseconds. 1875 Parameters: 1877 ssrc: string 1878 The ssrc of the source this event notification refers to. 1880 validityTime: Integer 1881 The validityTime field indicates the period for which this source 1882 should be considered active, in milliseconds. 1884 A.1.1.3.7 rtp.source.inactive 1886 rtp.source.inactive (ssrc) 1887 EVENT NOTIFICATION 1889 The rtp.source.active notifications indicates that a source has 1890 stopped transmitting data into the session. 1892 Parameters: 1894 ssrc: string 1895 The ssrc of the source this event notification refers to. 1897 A.1.1.3.8 rtp.source.packet.duration 1899 rtp.source.packet.duration (ssrc packetDuration) 1900 EVENT NOTIFICATION 1902 Sent by a media engine to indicate the duration, in milliseconds, of 1903 packets received from a source. This may be used to control the 1904 duration of packets sent by a media engine, if sent to that engine 1905 with the cname of the engine. 1907 Parameters: 1909 ssrc: string 1910 The ssrc of the source this event notification refers to. 1912 packetDuration: Integer 1913 The duration, in milliseconds, of packets received from a source. 1915 A.1.1.3.9 rtp.source.codec 1917 rtp.source.codec (ssrc codec) 1918 EVENT NOTIFICATION 1920 Sent by a media engine to indicate the codec in use by a source. 1922 Parameters: 1924 ssrc: string 1925 The ssrc of the source this event notification refers to. 1927 codec: String 1928 The codec name. 1930 A.1.1.3.10 rtp.source.playout 1932 rtp.source.playout (ssrc playoutDelay) 1933 EVENT NOTIFICATION 1935 Sent by a media engine to indicate the playout delay, in 1936 milliseconds, for a source (that is, end-to-end time from capture to 1937 playout). This allows for lip-synchronization between audio and 1938 video streams. 1940 Parameters: 1942 ssrc: string 1943 The ssrc of the source this event notification refers to. 1945 playoutDelay: Integer 1946 playout delay, in milliseconds. 1948 Full Copyright Statement 1950 Copyright (C) The Internet Society (2001). All Rights Reserved. 1952 This document and translations of it may be copied and furnished to 1953 others, and derivative works that comment on or otherwise explain it 1954 or assist in its implmentation may be prepared, copied, published 1955 and distributed, in whole or in part, without restriction of any 1956 kind, provided that the above copyright notice and this paragraph 1957 are included on all such copies and derivative works. However, this 1958 document itself may not be modified in any way, such as by removing 1959 the copyright notice or references to the Internet Society or other 1960 Internet organizations, except as needed for the purpose of 1961 developing Internet standards in which case the procedures for 1962 copyrights defined in the Internet Standards process must be 1963 followed, or as required to translate it into languages other than 1964 English. 1966 The limited permissions granted above are perpetual and will not be 1967 revoked by the Internet Society or its successors or assigns. 1969 This document and the information contained herein is provided on an 1970 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1971 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1972 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1973 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1974 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1976 Acknowledgement 1978 Funding for the RFC editor function is currently provided by the 1979 Internet Society.