From 4fce285052c143296cd9e08a48de0175b5207853 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Tue, 18 Jan 2005 03:03:07 +0000 Subject: 2005-01-17 Havoc Pennington * dbus/dbus-types.h: remove 16-bit types since we don't use them ever * dbus/dbus-marshal-validate.c (_dbus_validate_path): disallow any "invalid name character" not only non-ASCII * doc/dbus-specification.xml: further update spec, message bus parts are still out-of-date but the marshaling etc. stuff is now accurate-ish --- doc/dbus-specification.xml | 656 ++++++++++++++++++++++----------------------- 1 file changed, 319 insertions(+), 337 deletions(-) (limited to 'doc/dbus-specification.xml') diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index b07f062f..f2c0146b 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -82,7 +82,7 @@ The base D-BUS protocol is a one-to-one (peer-to-peer or client-server) protocol, specified in . That is, it is a system for one application to talk to a single other - application. However, the primary intended application of D-BUS is the + application. However, the primary intended application of the protocol is the D-BUS message bus, specified in . The message bus is a special application that accepts connections from multiple other applications, and forwards @@ -138,13 +138,13 @@ - As a simple example, the type code for 32-bit integer (INT32) is + As a simple example, the type code for 32-bit integer (INT32) is the ASCII character 'i'. So the signature for a block of values - containing a single INT32 would be: + containing a single INT32 would be: "i" - A block of values containing two INT32 would have this signature: + A block of values containing two INT32 would have this signature: "ii" @@ -152,15 +152,15 @@ All basic types work like - INT32 in this example. To marshal and unmarshal + INT32 in this example. To marshal and unmarshal basic types, you simply read one value from the data block corresponding to each type code in the signature. In addition to basic types, there are three container - types: STRUCT, ARRAY, and VARIANT. + types: STRUCT, ARRAY, and VARIANT. - STRUCT has a type code, ASCII character 'r', but this type + STRUCT has a type code, ASCII character 'r', but this type code does not appear in signatures. Instead, ASCII characters '(' and ')' are used to mark the beginning and end of the struct. So for example, a struct containing two integers would have this @@ -177,9 +177,15 @@ type signature allows you to distinguish "(i(ii))" from "((ii)i)" or "(iii)" or "iii". + + + The STRUCT type code 'r' is not currently used in the D-BUS protocol, + but is useful in code that implements the protocol. This type code + is specified to allow such code to interoperate in non-protocol contexts. + - ARRAY has ASCII character 'a' as type code. The array type code must be + ARRAY has ASCII character 'a' as type code. The array type code must be followed by a single complete type. The single complete type following the array is the type of each array element. So the simple example is: @@ -226,8 +232,8 @@ - VARIANT has ASCII character 'v' as its type code. A marshaled value of - type VARIANT will have the signature of a single complete type as part + VARIANT has ASCII character 'v' as its type code. A marshaled value of + type VARIANT will have the signature of a single complete type as part of the value. This signature will be followed by a marshaled value of that type. @@ -238,66 +244,66 @@ - Type name + Conventional Name Code Description - INVALID + INVALID 0 (ASCII NUL) Not a valid type code, used to terminate signatures - BYTE + BYTE 121 (ASCII 'y') 8-bit unsigned integer - BOOLEAN + BOOLEAN 98 (ASCII 'b') - Boolean value, 0 is FALSE and 1 is TRUE. Everything else is invalid. + Boolean value, 0 is FALSE and 1 is TRUE. Everything else is invalid. - INT32 + INT32 105 (ASCII 'i') 32-bit signed integer - UINT32 + UINT32 117 (ASCII 'u') 32-bit unsigned integer - INT64 + INT64 120 (ASCII 'x') 64-bit signed integer - UINT64 + UINT64 116 (ASCII 't') 64-bit unsigned integer - DOUBLE + DOUBLE 100 (ASCII 'd') IEEE 754 double - STRING + STRING 115 (ASCII 's') UTF-8 string (must be valid UTF-8). Must be nul terminated. - OBJECT_PATH + OBJECT_PATH 111 (ASCII 'o') Name of an object instance - SIGNATURE + SIGNATURE 103 (ASCII 'g') A type signature - ARRAY + ARRAY 97 (ASCII 'a') Array - STRUCT + STRUCT 114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')') Struct - VARIANT + VARIANT 118 (ASCII 'v') Variant type (the type of the value is part of the value itself) @@ -343,47 +349,47 @@ - Type name + Conventional Name Encoding Alignment - INVALID + INVALID Not applicable; cannot be marshaled. N/A - BYTE + BYTE A single 8-bit byte. 1 - BOOLEAN - As for UINT32, but only 0 and 1 are valid values. + BOOLEAN + As for UINT32, but only 0 and 1 are valid values. 4 - INT32 + INT32 32-bit signed integer in the message's byte order. 4 - UINT32 + UINT32 32-bit unsigned integer in the message's byte order. 4 - INT64 + INT64 64-bit signed integer in the message's byte order. 8 - UINT64 + UINT64 64-bit unsigned integer in the message's byte order. 8 - DOUBLE + DOUBLE 64-bit IEEE 754 double in the message's byte order. 8 - STRING - A UINT32 indicating the string's + STRING + A UINT32 indicating the string's length in bytes excluding its terminating nul, followed by string data of the given length, followed by a terminating nul byte. @@ -392,35 +398,40 @@ 4 (for the length) - OBJECT_PATH - Exactly the same as STRING. + OBJECT_PATH + Exactly the same as STRING except the + content must be a valid object path (see below). 4 (for the length) - SIGNATURE - The same as STRING except the length is a single - byte (thus signatures have a maximum length of 255). + SIGNATURE + The same as STRING except the length is a single + byte (thus signatures have a maximum length of 255) + and the content must be a valid signature (see below). 1 - ARRAY + ARRAY - A UINT32 giving the length of the array data in bytes, followed by + A UINT32 giving the length of the array data in bytes, followed by alignment padding to the alignment boundary of the array element type, followed by each array element. The array length is from the end of the alignment padding to the end of the last element, i.e. it does not include the padding after the length, or any padding after the last element. + Arrays have a maximum length defined to be 2 to the 26th power or + 67108864. Implementations must not send or accept arrays exceeding this + length. 4 (for the length) - STRUCT + STRUCT A struct must start on an 8-byte boundary regardless of the type of the struct fields. The struct value consists of each @@ -431,9 +442,9 @@ 8 - VARIANT + VARIANT - A variant type has a marshaled SIGNATURE + A variant type has a marshaled SIGNATURE followed by a marshaled value with the type given in the signature. Unlike a message signature, the variant signature @@ -448,6 +459,110 @@ + + + Valid Object Paths + + + An object path is a name used to refer to an object instance. + Conceptually, each participant in a D-BUS message exchange may have + any number of object instances (think of C++ or Java objects) and each + such instance will have a path. Like a filesystem, the object + instances in an application form a hierarchical tree. + + + + The following rules define a valid object path. Implementations must + not send or accept messages with invalid object paths. + + + + The path may be of any length. + + + + + The path must begin with an ASCII '/' (integer 47) character, + and must consist of elements separated by slash characters. + + + + + Each element must only contain the ASCII characters + "[A-Z][a-z][0-9]_" + + + + + No element may be the empty string. + + + + + Multiple '/' characters cannot occur in sequence. + + + + + A trailing '/' character is not allowed unless the + path is the root path (a single '/' character). + + + + + + + + + + Valid Signatures + + An implementation must not send or accept invalid signatures. + Valid signatures will conform to the following rules: + + + + The signature ends with a nul byte. + + + + + The signature is a list of single complete types. + Arrays must have element types, and structs must + have both open and close parentheses. + + + + + Only type codes and open and close parentheses are + allowed in the signature. The STRUCT type code + is not allowed in signatures, because parentheses + are used instead. + + + + + The maximum depth of container type nesting is 32 array type + codes and 32 open parentheses. This implies that the maximum + total depth of recursion is 64, for an "array of array of array + of ... struct of struct of struct of ..." where there are 32 + array and 32 struct. + + + + + The maximum length of a signature is 255. + + + + + Signatures must be nul-terminated. + + + + + + @@ -469,6 +584,12 @@ The message body need not end on an 8-byte boundary. + + + The maximum length of a message, including header, header alignment padding, + and body is 2 to the 27th power or 134217728. Implementations must not + send or accept messages exceeding this size. + The signature of the header is: @@ -493,24 +614,25 @@ - 1st BYTE + 1st BYTE Endianness flag; ASCII 'l' for little-endian - or ASCII 'B' for big-endian. + or ASCII 'B' for big-endian. Both header and body are + in this endianness. - 2nd BYTE + 2nd BYTE Message type. Unknown types MUST be ignored. Currently-defined types are described below. - 3rd BYTE + 3rd BYTE Bitwise OR of flags. Unknown flags MUST be ignored. Currently-defined flags are described below. - 4th BYTE + 4th BYTE Major protocol version of the sending application. If the major protocol version of the receiving application does not match, the applications will not be able to communicate and the @@ -521,21 +643,21 @@ - 1st UINT32 + 1st UINT32 Length in bytes of the message body, starting from the end of the header. The header ends after its alignment padding to an 8-boundary. - 2nd UINT32 + 2nd UINT32 The serial of this message, used as a cookie by the sender to identify the reply corresponding to this request. - ARRAY of STRUCT of (BYTE,VARIANT) + ARRAY of STRUCT of (BYTE,VARIANT) An array of zero or more header fields where the byte is the field code, and the variant is the field value. The message type determines @@ -560,29 +682,29 @@ - INVALID + INVALID 0 This is an invalid type, if seen in a message the connection should be dropped immediately. - METHOD_CALL + METHOD_CALL 1 Method call. - METHOD_RETURN + METHOD_RETURN 2 Method reply with returned data. - ERROR + ERROR 3 Error reply. If the first argument exists and is a string, it is an error message. - SIGNAL + SIGNAL 4 Signal emission. @@ -603,7 +725,7 @@ - NO_REPLY_EXPECTED + NO_REPLY_EXPECTED 0x1 This message does not expect method return replies or error replies; the reply can be omitted as an @@ -611,7 +733,7 @@ to return the reply despite this flag. - AUTO_ACTIVATION + AUTO_ACTIVATION 0x2 This message automatically activates the addressed service before the message is delivered. @@ -625,8 +747,10 @@ Header Fields - A header must contain the required named header fields for the given - message type, and zero or more of any optional named header + The array at the end of the header contains header + fields, where each field is a 1-byte field code followed + by a field value. A header must contain the required header fields for + its message type, and zero or more of any optional header fields. Future versions of this protocol specification may add new fields. Implementations must ignore fields they do not understand. Implementations must not invent their own header fields; @@ -634,19 +758,29 @@ - Again, if an implementation sees a header field name that it does not - understand, it MUST ignore that field, as it will be part of a new - (but compatible) version of this specification. + Again, if an implementation sees a header field code that it does not + expect, it MUST ignore that field, as it will be part of a new + (but compatible) version of this specification. This also applies + to known header fields appearing in unexpected messages, for + example if a signal has a reply serial that should be ignored + even though it has no meaning as of this version of the spec. + + + + However, implementations must not send or accept known header fields + with the wrong type stored in the field value. So for example + a message with an INTERFACE field of type UINT32 would be considered + corrupt. - Here are the currently-defined named header fields: + Here are the currently-defined header fields: Conventional Name - Decimal Value + Decimal Code Type Required In Description @@ -654,26 +788,26 @@ - INVALID + INVALID 0 - INVALID + N/A not allowed Not a valid field name (error if it appears in a message) - PATH + PATH 1 - OBJECT_PATH - METHOD_CALL, SIGNAL + OBJECT_PATH + METHOD_CALL, SIGNAL The object to send a call to, or the object a signal is emitted from. - INTERFACE + INTERFACE 2 - STRING - SIGNAL + STRING + SIGNAL The interface to invoke a method call on, or that a signal is emitted from. Optional for @@ -681,53 +815,53 @@ - MEMBER + MEMBER 3 - STRING - METHOD_CALL, SIGNAL + STRING + METHOD_CALL, SIGNAL The member, either the method name or signal name. - ERROR_NAME + ERROR_NAME 4 - STRING - ERROR + STRING + ERROR The name of the error that occurred, for errors - REPLY_SERIAL + REPLY_SERIAL 5 - UINT32 - ERROR, METHOD_RETURN + UINT32 + ERROR, METHOD_RETURN The serial number of the message this message is a reply - to. (The serial number is the second UINT32 in the header.) + to. (The serial number is the second UINT32 in the header.) - DESTINATION + DESTINATION 6 - STRING + STRING optional The name of the service this message should be routed to. Only used in combination with the message bus, see . - SENDER + SENDER 7 - STRING + STRING optional Sender service. The name of the base service that sent this message. The message bus fills in this field; the field is only meaningful in combination with the message bus. - SIGNATURE + SIGNATURE 8 - SIGNATURE + SIGNATURE optional The signature of the message body. If omitted, it is assumed to be the - empty signature "" (i.e. the body is 0-length). + empty signature "" (i.e. the body must be 0-length). @@ -735,179 +869,21 @@ - - - Message Arguments - - The message body is made up of arguments. Each argument is a type code, - represented by a single unsigned byte, followed by the aligned value of - the argument in a type-dependent format. Alignment padding between the - typecode and the value is initialized to zero. - - - - - - - Type name - Code - Description - - - - - INVALID - 0 (ASCII NUL) - Not a valid type code (error if it appears in a message) - - NIL - 118 (ASCII 'v') - Marks a "void"/"unset"/"nonexistent"/"null" argument - - BYTE - 121 (ASCII 'y') - 8-bit unsigned integer - - BOOLEAN - 98 (ASCII 'b') - Boolean value, 0 is FALSE and 1 is TRUE. Everything else is invalid. - - INT32 - 105 (ASCII 'i') - 32-bit signed integer - - UINT32 - 117 (ASCII 'u') - 32-bit unsigned integer - - INT64 - 120 (ASCII 'x') - 64-bit signed integer - - UINT64 - 116 (ASCII 't') - 64-bit unsigned integer - - DOUBLE - 100 (ASCII 'd') - IEEE 754 double - - STRING - 115 (ASCII 's') - UTF-8 string (must be valid UTF-8). Must be zero terminated. - - CUSTOM - 99 (ASCII 'c') - A named byte array, used for custom types - - ARRAY - 97 (ASCII 'a') - Array - - DICT - 109 (ASCII 'm') - A dictionary of key/value pairs - - OBJECT_PATH - 111 (ASCII 'o') - Name of an object - - - - - - - The types are encoded as follows: - - - - - Type name - Encoding - - - - - INVALID - Not applicable; cannot be encoded. - - NIL - No data is encoded; the type code is followed immediately - by the type code of the next argument. - - BYTE - A byte. - - BOOLEAN - A byte, with valid values 0 and 1. - - INT32 - 32-bit signed integer in the message's byte order, aligned to 4-byte boundary. - - UINT32 - 32-bit unsigned integer in the message's byte order, aligned to 4-byte boundary. - - INT64 - 64-bit signed integer in the message's byte order, aligned to 8-byte boundary. - - UINT64 - 64-bit unsigned integer in the message's byte order, aligned to 8-byte boundary. - - DOUBLE - 64-bit IEEE 754 double in the message's byte order, aligned to 8-byte boundary. - - STRING - UINT32 aligned to 4-byte boundary indicating the string's - length in bytes excluding its terminating nul, followed by - string data of the given length, followed by a terminating nul - byte. - - - CUSTOM - A string (encoded as the STRING type above) giving the - name of the type followed by an UINT32 aligned to 4-byte boundary - indicating the data length in bytes, followed by the data. - The string has some restrictions on its content, see - . - - - ARRAY - A sequence of bytes giving the element type of the array, terminated - by a type different from ARRAY (just one byte for one-dimensional arrays, but - larger for multi-dimensional arrays), followed by an UINT32 (aligned to 4 bytes) - giving the length of the array data in bytes. This is followed by each array entry - encoded the way it would normally be encoded, except arrays, which are encoded - without the type information, since that is already declared above. Arrays containing - NIL are not allowed. - - - DICT - UINT32 giving the length of the dictionary data in bytes. - This is followed by a number of keyname/value pairs, where the - keyname is encoded as a STRING above, and the value is encoded - as a byte with typecode and how that type normally would be encoded - alone. - - - OBJECT_PATH - Encoded as if it were a STRING. - - - - - - - - Valid names + Valid Names The various names in D-BUS messages have some restrictions. + + There is a maximum name length + of 255 which applies to service, interface, and member + names. + Interface names - Interfaces have names with type STRING, meaning that + Interfaces have names with type STRING, meaning that they must be valid UTF-8. However, there are also some additional restrictions that apply to interface names specifically: @@ -927,8 +903,7 @@ They must not begin with a '.' (period) character. - They must not exceed 256 bytes in length. - They must be at least 1 byte in length. + They must not exceed the maximum name length. @@ -938,117 +913,103 @@ Service names have the same restrictions as interface names, with a special exception for base services. A base service name's first element must start with a colon (':') character. After the colon, any - characters in the range "[A-Z][a-z][0-9]_" may appear. Elements after + characters in "[A-Z][a-z][0-9]_" may appear. Elements after the first must follow the usual rules, except that they may start with a digit. Service names not starting with a colon have none of these exceptions and follow the same rules as interface names. - - Method names + + Member names - Method names: + Member (i.e. method or signal) names: Must only contain the ASCII characters "[A-Z][a-z][0-9]_" and may not begin with a digit. - Must not contain the '.' (period) character - Must not exceed 256 bytes in length - Must be at least 1 byte in length + Must not contain the '.' (period) character. + Must not exceed the maximum name length. + Must be at least 1 byte in length. - - Path names - - A path (type OBJECT_PATH) must begin with an ASCII '/' (slash) - character. Paths may not end with a slash character unless the path is - the one-byte string "/". Two slash characters may not appear adjacent - to one another (the empty string is not a valid "subdirectory"). Paths - may not exceed 256 bytes in length. - - Error names Error names have the same restrictions as interface names. - - Custom types - - Custom type names for values of type CUSTOM follow the same - restrictions as interface names. - - - Message types + Message Types - Each of the message types (METHOD_CALL, METHOD_RETURN, ERROR, and - SIGNAL) has its own expected usage conventions and header fields. + Each of the message types (METHOD_CALL, METHOD_RETURN, ERROR, and + SIGNAL) has its own expected usage conventions and header fields. + This section describes these conventions. - Method Calls, Returns, and Errors + Method Calls Some messages invoke an operation on a remote object. These are - called method call messages and have the type tag METHOD_CALL. Such + called method call messages and have the type tag METHOD_CALL. Such messages map naturally to methods on objects in a typical program. - A method call message is expected to have a MEMBER header field + A method call message is expected to have a MEMBER header field indicating the name of the method. Optionally, the message has an - INTERFACE field giving the interface the method is a part of. In the - absence of an INTERFACE field, if two interfaces on the same object have + INTERFACE field giving the interface the method is a part of. In the + absence of an INTERFACE field, if two interfaces on the same object have a method with the same name, it is undefined which of the two methods will be invoked. Implementations may also choose to return an error in this ambiguous case. However, if a method name is unique - implementations should not require an interface field. + implementations must not require an interface field. - Method call messages also include a PATH field indicating the + Method call messages also include a PATH field indicating the object to invoke the method on. If the call is passing through - a message bus, the message will also have a SERVICE field giving + a message bus, the message will also have a DESTINATION field giving the service to receive the message. When an application handles a method call message, it is expected to - return a reply. The reply is identified by a REPLY_SERIAL header field - indicating the serial number of the METHOD_CALL being replied to. The - reply can have one of two types; either METHOD_RETURN or ERROR. + return a reply. The reply is identified by a REPLY_SERIAL header field + indicating the serial number of the METHOD_CALL being replied to. The + reply can have one of two types; either METHOD_RETURN or ERROR. - If the reply has type METHOD_RETURN, the arguments to the reply message + If the reply has type METHOD_RETURN, the arguments to the reply message are the return value(s) or "out parameters" of the method call. - If the reply has type ERROR, then an "exception" has been thrown, + If the reply has type ERROR, then an "exception" has been thrown, and the call fails; no return value will be provided. It makes no sense to send multiple replies to the same method call. - Even if a method call has no return values, a METHOD_RETURN + Even if a method call has no return values, a METHOD_RETURN reply is expected, so the caller will know the method was successfully processed. - The METHOD_RETURN or ERROR reply message MUST have the REPLY_SERIAL - header field. If this field is missing, it should be treated as - a corrupt message. + The METHOD_RETURN or ERROR reply message must have the REPLY_SERIAL + header field. - If a METHOD_CALL message has the flag NO_REPLY_EXPECTED, + If a METHOD_CALL message has the flag NO_REPLY_EXPECTED, then as an optimization the application receiving the method call may choose to omit the reply message (regardless of - whether the reply would have been METHOD_RETURN or ERROR). - However, it is also acceptable to ignore the NO_REPLY_EXPECTED + whether the reply would have been METHOD_RETURN or ERROR). + However, it is also acceptable to ignore the NO_REPLY_EXPECTED flag and reply anyway. - If a message has the flag AUTO_ACTIVATION, then the addressed + If a message has the flag AUTO_ACTIVATION, then the addressed service will be activated before the message is delivered, if not already active. The message will be held until the service is successfully activated or has failed to activate; in case - of failure, an activation error will be returned. + of failure, an activation error will be returned. Activation + is only relevant in the context of a message bus, so this + flag is ignored for one-to-one communication with no + intermediate bus. Mapping method calls to native APIs @@ -1059,8 +1020,8 @@ In APIs of this nature, arguments to a method are often termed "in" - (which implies sent in the METHOD_CALL), or "out" (which implies - returned in the METHOD_RETURN). Some APIs such as CORBA also have + (which implies sent in the METHOD_CALL), or "out" (which implies + returned in the METHOD_RETURN). Some APIs such as CORBA also have "inout" arguments, which are both sent and received, i.e. the caller passes in a value which is modified. Mapped to D-BUS, an "inout" argument is equivalent to an "in" argument, followed by an "out" @@ -1078,6 +1039,15 @@ if any, then each "out" or "inout" argument, in order. "in" arguments are not represented in the reply message. + + Error replies are normally mapped to exceptions in languages that have + exceptions. + + + This specification doesn't require anything of native API bindings; + the preceding is only a suggested convention for consistency + among bindings. + @@ -1086,13 +1056,30 @@ Signal Emission Unlike method calls, signal emissions have no replies. - A signal emission is simply a single message of type SIGNAL. - It must have three header fields: PATH giving the object - the signal was emitted from, plus INTERFACE and MEMBER giving + A signal emission is simply a single message of type SIGNAL. + It must have three header fields: PATH giving the object + the signal was emitted from, plus INTERFACE and MEMBER giving the fully-qualified name of the signal. + + Errors + + Messages of type ERROR are most commonly replies + to a METHOD_CALL, but may be returned in reply + to any kind of message. The message bus for example + will return an ERROR in reply to a signal emission if + the bus does not have enough memory to send the signal. + + + An ERROR may have any arguments, but if the first + argument is a STRING, it must be an error message. + The error message may be logged or shown to the user + in some way. + + + Notation in this document @@ -1102,9 +1089,9 @@ org.freedesktop.DBus.ActivateService (in STRING service_name, in UINT32 flags, out UINT32 resultcode) - This means INTERFACE = org.freedesktop.DBus, MEMBER = ActivateService, - METHOD_CALL arguments are STRING and UINT32, METHOD_RETURN argument - is UINT32. Remember that the MEMBER field can't contain any '.' (period) + This means INTERFACE = org.freedesktop.DBus, MEMBER = ActivateService, + METHOD_CALL arguments are STRING and UINT32, METHOD_RETURN argument + is UINT32. Remember that the MEMBER field can't contain any '.' (period) characters so it's known that the last part of the name in the "IDL" is the member name. @@ -1132,11 +1119,6 @@ Signals don't specify "in" vs. "out" because only a single direction is possible. - - In this ad hoc notation, the special type name ANY means any type - other than NIL, and the special type name ANY_OR_NIL means any valid - type. - It isn't especially encouraged to use this lame pseudo-IDL in actual API implementations; you might use the native notation for the @@ -1987,7 +1969,7 @@ - Standard Peer-to-Peer Messages + Standard One-to-One Messages See for details on the notation used in this section. @@ -2000,9 +1982,9 @@ - On receipt of the METHOD_CALL + On receipt of the METHOD_CALL message org.freedesktop.Peer.Ping, an application - should do nothing other than reply with a METHOD_RETURN as usual. + should do nothing other than reply with a METHOD_RETURN as usual. @@ -2051,7 +2033,7 @@ The message bus accepts connections from one or more applications. Once connected, applications can send and receive messages from - the message bus, as in the peer-to-peer case. + the message bus, as in the one-to-one case. The message bus keeps track of a set of @@ -2068,18 +2050,18 @@ the new owner of the service. - Messages may have a SERVICE field (see DESTINATION field (see ). When the message bus - receives a message, if the SERVICE field is absent, the - message is taken to be a standard peer-to-peer message and interpreted + receives a message, if the DESTINATION field is absent, the + message is taken to be a standard one-to-one message and interpreted by the message bus itself. For example, sending an org.freedesktop.Peer.Ping message with no - SERVICE will cause the message bus itself to reply + DESTINATION will cause the message bus itself to reply to the ping immediately; the message bus would never make this message visible to other applications. - If the SERVICE field is present, then it indicates a + If the DESTINATION field is present, then it indicates a request for the message bus to route the message. In the usual case, messages are routed to the owner of the named service. Messages may also be broadcast @@ -2090,7 +2072,7 @@ Continuing the org.freedesktop.Peer.Ping example, if - the ping message were sent with a SERVICE name of + the ping message were sent with a DESTINATION name of com.yoyodyne.Screensaver, then the ping would be forwarded, and the Yoyodyne Corporation screensaver application would be expected to reply to the ping. If @@ -2139,11 +2121,11 @@ Service ownership handling can be specified in the flags part of the org.freedesktop.DBus.AcquireService message. If an application specifies the - DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT flag, then all applications + DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT flag, then all applications trying to acquire the service will be put in a queue. When the primary owner disconnects from the bus or removes ownership from the service, the next application in the queue will be the - primary owner. If the DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT + primary owner. If the DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT flag is not specified, then the primary owner will lose ownership whenever another application requests ownership of the service. @@ -2997,7 +2979,7 @@ - Peer-to-peer + One-to-One An application talking directly to another application, without going through a message bus. -- cgit