From 28ac50788469ae1ac617a600685d0769b450b3c8 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 25 Aug 2015 19:44:51 +0200 Subject: [PATCH 1/2] spec: trailing whitespace clean-up It's generally a good idea to avoid trailing whitespace in order to keep patchs minimal. While it's common to enforce such restrictions for C code, it's important for docbok XML files too. Hence, let's clean this up and remove all trailing whitespace currently in place. --- doc/dbus-specification.xml | 484 ++++++++++++++++++++++----------------------- 1 file changed, 242 insertions(+), 242 deletions(-) diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 1e0fe20..0468992 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -269,13 +269,13 @@ - A "session bus" used to implement desktop environments such as + A "session bus" used to implement desktop environments such as GNOME and KDE. - D-Bus is not intended to be a generic IPC system for any possible - application, and intentionally omits many features found in other + D-Bus is not intended to be a generic IPC system for any possible + application, and intentionally omits many features found in other IPC systems for this reason. @@ -283,7 +283,7 @@ At the same time, the bus daemons offer a number of features not found in other IPC systems, such as single-owner "bus names" (similar to X selections), on-demand startup of services, and security policies. - In many ways, these features are the primary motivation for developing + In many ways, these features are the primary motivation for developing D-Bus; other systems would have sufficed if IPC were the only goal. @@ -314,17 +314,17 @@ reference implementation's behavior. - Until this work is complete, any attempt to reimplement D-Bus will + Until this work is complete, any attempt to reimplement D-Bus will probably require looking at the reference implementation and/or asking - questions on the D-Bus mailing list about intended behavior. + questions on the D-Bus mailing list about intended behavior. Questions on the list are very welcome. - Nonetheless, this document should be a useful starting point and is + Nonetheless, this document should be a useful starting point and is to our knowledge accurate, though incomplete. - + @@ -405,7 +405,7 @@ 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 + the ASCII character 'i'. So the signature for a block of values containing a single INT32 would be: "i" @@ -413,7 +413,7 @@ A block of values containing two INT32 would have this signature: "ii" - + @@ -678,21 +678,21 @@ Container types - In addition to basic types, there are four container - types: STRUCT, ARRAY, VARIANT, + In addition to basic types, there are four container + types: STRUCT, ARRAY, VARIANT, and DICT_ENTRY. - 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 + So for example, a struct containing two integers would have this signature: "(ii)" - Structs can be nested, so for example a struct containing + Structs can be nested, so for example a struct containing an integer and another struct: "(i(ii))" @@ -704,7 +704,7 @@ 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 + but is useful in code that implements the protocol. This type code is specified to allow such code to interoperate in non-protocol contexts. @@ -721,7 +721,7 @@ "ai" - which is an array of 32-bit integers. But an array can be of any type, + which is an array of 32-bit integers. But an array can be of any type, such as this array-of-struct-with-two-int32-fields: "a(ii)" @@ -758,7 +758,7 @@ fields, and must not accept dict entries with non-basic-typed keys. A dict entry is always a key-value pair. - + The first field in the DICT_ENTRY is always the key. A message is considered corrupt if the same key occurs twice in the same @@ -767,7 +767,7 @@ - In most languages, an array of dict entry would be represented as a + In most languages, an array of dict entry would be represented as a map, hash table, or dict object. @@ -1113,9 +1113,9 @@ 8 STRING - A UINT32 indicating the string's - length in bytes excluding its terminating nul, followed by - non-nul string data of the given length, followed by a terminating nul + A UINT32 indicating the string's + length in bytes excluding its terminating nul, followed by + non-nul string data of the given length, followed by a terminating nul byte. @@ -1123,7 +1123,7 @@ OBJECT_PATH - Exactly the same as STRING except the + Exactly the same as STRING except the content must be a valid object path (see above). @@ -1131,7 +1131,7 @@ SIGNATURE - The same as STRING except the length is a single + 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 above). @@ -1141,7 +1141,7 @@ 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. @@ -1207,7 +1207,7 @@ information to figure out where to send the message and how to interpret it; the recipient interprets the body of the message. - + The body of the message is made up of zero or more arguments, which are typed values, such as an @@ -1231,7 +1231,7 @@ The length of the header must be a multiple of 8, allowing the body to begin on an 8-byte boundary when storing the entire message in a single - buffer. If the header does not naturally end on an 8-byte boundary + buffer. If the header does not naturally end on an 8-byte boundary up to 7 bytes of nul-initialized alignment padding must be added. @@ -1240,11 +1240,11 @@ - The maximum length of a message, including header, header alignment padding, + The maximum length of a message, including header, header alignment padding, and body is 2 to the 27th power or 134217728 (128 MiB). Implementations must not send or accept messages exceeding this size. - + The signature of the header is: @@ -1269,13 +1269,13 @@ 1st BYTE - Endianness flag; ASCII 'l' for little-endian - or ASCII 'B' for big-endian. Both header and body are + Endianness flag; ASCII 'l' for little-endian + or ASCII 'B' for big-endian. Both header and body are in this endianness. 2nd BYTE - Message type. Unknown types must be ignored. + Message type. Unknown types must be ignored. Currently-defined types are described below. @@ -1296,23 +1296,23 @@ 1st UINT32 - Length in bytes of the message body, starting - from the end of the header. The header ends after + 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 - The serial of this message, used as a cookie + The serial of this message, used as a cookie by the sender to identify the reply corresponding to this request. This must not be zero. - + 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 + variant is the field value. The message type determines which fields are required. @@ -1490,8 +1490,8 @@ 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 + (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 it must be ignored even though it has no meaning as of this version of the spec. @@ -1544,8 +1544,8 @@ STRING SIGNAL - The interface to invoke a method call on, or - that a signal is emitted from. Optional for + The interface to invoke a method call on, or + that a signal is emitted from. Optional for method calls, required for signals. The special interface org.freedesktop.DBus.Local is reserved; @@ -1583,7 +1583,7 @@ STRING optional The name of the connection this message is intended for. - Only used in combination with the message bus, see + Only used in combination with the message bus, see . @@ -1601,7 +1601,7 @@ SIGNATURE optional The signature of the message body. - If omitted, it is assumed to be the + If omitted, it is assumed to be the empty signature "" (i.e. the body must be 0-length). @@ -1633,23 +1633,23 @@ The various names in D-Bus messages have some restrictions. - There is a maximum name length - of 255 which applies to bus names, interfaces, and members. + There is a maximum name length + of 255 which applies to bus names, interfaces, and members. Interface names - 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 + 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: Interface names are composed of 1 or more elements separated by - a period ('.') character. All elements must contain at least + a period ('.') character. All elements must contain at least one character. - Each element must only contain the ASCII characters + Each element must only contain the ASCII characters "[A-Z][a-z][0-9]_" and must not begin with a digit. @@ -1698,7 +1698,7 @@ with the connection for its entire lifetime. A bus name is of type STRING, meaning that it must be valid UTF-8. However, there are also - some additional restrictions that apply to bus names + some additional restrictions that apply to bus names specifically: Bus names that start with a colon (':') @@ -1707,11 +1707,11 @@ Bus names are composed of 1 or more elements separated by - a period ('.') character. All elements must contain at least + a period ('.') character. All elements must contain at least one character. - Each element must only contain the ASCII characters + Each element must only contain the ASCII characters "[A-Z][a-z][0-9]_-". Only elements that are part of a unique connection name may begin with a digit, elements in other bus names must not begin with a digit. @@ -1848,26 +1848,26 @@ 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 - are the return value(s) or "out parameters" of the method call. - If the reply has type ERROR, then an "exception" has been thrown, - and the call fails; no return value will be provided. It makes + 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, + 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 - reply is required, so the caller will know the method + Even if a method call has no return values, a METHOD_RETURN + reply is required, so the caller will know the method was successfully processed. - The METHOD_RETURN or ERROR reply message must have the REPLY_SERIAL + 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, - 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). + 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 flag and reply anyway. @@ -1904,8 +1904,8 @@ in order. "out" arguments are not represented in the caller's message. - The recipient constructs a reply by appending first the return value - if any, then each "out" or "inout" argument, in order. + The recipient constructs a reply by appending first the return value + if any, then each "out" or "inout" argument, in order. "in" arguments are not represented in the reply message. @@ -1913,19 +1913,19 @@ exceptions. - In converting from native APIs to D-Bus, it is perhaps nice to - map D-Bus naming conventions ("FooBar") to native conventions - such as "fooBar" or "foo_bar" automatically. This is OK - as long as you can say that the native API is one that + In converting from native APIs to D-Bus, it is perhaps nice to + map D-Bus naming conventions ("FooBar") to native conventions + such as "fooBar" or "foo_bar" automatically. This is OK + as long as you can say that the native API is one that was specifically written for D-Bus. It makes the most sense - when writing object implementations that will be exported - over the bus. Object proxies used to invoke remote D-Bus + when writing object implementations that will be exported + over the bus. Object proxies used to invoke remote D-Bus objects probably need the ability to call any D-Bus method, and thus a magic name mapping like this could be a problem. This specification doesn't require anything of native API bindings; - the preceding is only a suggested convention for consistency + the preceding is only a suggested convention for consistency among bindings. @@ -1934,9 +1934,9 @@ Signal Emission - Unlike method calls, signal emissions have no replies. + 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 + 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. The INTERFACE header is required for signals, though it is optional for method calls. @@ -1946,14 +1946,14 @@ Errors - Messages of type ERROR are most commonly replies - to a METHOD_CALL, but may be returned in reply + 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 + 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 + 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. @@ -1963,13 +1963,13 @@ Notation in this document - This document uses a simple pseudo-IDL to describe particular method + This document uses a simple pseudo-IDL to describe particular method calls and signals. Here is an example of a method call: org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags, out UINT32 resultcode) - This means INTERFACE = org.freedesktop.DBus, MEMBER = StartServiceByName, + This means INTERFACE = org.freedesktop.DBus, MEMBER = StartServiceByName, 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 @@ -1983,12 +1983,12 @@ or equally valid, the return value could be done as an argument: - void org::freedesktop::DBus::StartServiceByName (const char *name, + void org::freedesktop::DBus::StartServiceByName (const char *name, unsigned int flags, unsigned int *resultcode); - It's really up to the API designer how they want to make - this look. You could design an API where the namespace wasn't used + It's really up to the API designer how they want to make + this look. You could design an API where the namespace wasn't used in C++, using STL or Qt, using varargs, or whatever you wanted. @@ -1996,7 +1996,7 @@ org.freedesktop.DBus.NameLost (STRING name) - Signals don't specify "in" vs. "out" because only + Signals don't specify "in" vs. "out" because only a single direction is possible. @@ -2009,7 +2009,7 @@ Invalid Protocol and Spec Extensions - + For security reasons, the D-Bus protocol should be strictly parsed and validated, with the exception of defined extension points. Any invalid @@ -2023,8 +2023,8 @@ - Generally speaking violations of the "must" requirements in this spec - should be considered possible attempts to exploit security, and violations + Generally speaking violations of the "must" requirements in this spec + should be considered possible attempts to exploit security, and violations of the "should" suggestions should be considered legitimate (though perhaps they should generate an error in some cases). @@ -2040,9 +2040,9 @@ - In the authentication protocol (see ) unknown - commands result in an ERROR rather than a disconnect. This enables - future extensions to the protocol. Commands starting with EXTENSION_ are + In the authentication protocol (see ) unknown + commands result in an ERROR rather than a disconnect. This enables + future extensions to the protocol. Commands starting with EXTENSION_ are reserved for third parties. @@ -2061,15 +2061,15 @@ Messages with an unknown type (something other than METHOD_CALL, METHOD_RETURN, - ERROR, SIGNAL) are ignored. - Unknown-type messages must still be well-formed in the same way - as the known messages, however. They still have the normal + ERROR, SIGNAL) are ignored. + Unknown-type messages must still be well-formed in the same way + as the known messages, however. They still have the normal header and body. - Header fields with an unknown or unexpected field code must be ignored, + Header fields with an unknown or unexpected field code must be ignored, though again they must still be well-formed. @@ -2129,7 +2129,7 @@ - Unofficial extensions to the command set must begin with the letters + Unofficial extensions to the command set must begin with the letters "EXTENSION_", to avoid conflicts with future official commands. For example, "EXTENSION_COM_MYDOMAIN_DO_STUFF". @@ -2145,15 +2145,15 @@ socket, and even on operating systems that do not require a byte to be sent in order to transmit credentials. The text protocol described in this document begins after the single nul byte. If the first byte - received from the client is not a nul byte, the server may disconnect + received from the client is not a nul byte, the server may disconnect that client. - A nul byte in any context other than the initial byte is an error; + A nul byte in any context other than the initial byte is an error; the protocol is ASCII-only. - The credentials sent along with the nul byte may be used with the + The credentials sent along with the nul byte may be used with the SASL mechanism EXTERNAL. @@ -2183,7 +2183,7 @@ REJECTED. - If authentication succeeds after exchanging DATA commands, + If authentication succeeds after exchanging DATA commands, an OK command must be sent to the client. @@ -2210,21 +2210,21 @@ DATA Command - The DATA command may come from either client or server, and simply - contains a hex-encoded block of data to be interpreted + The DATA command may come from either client or server, and simply + contains a hex-encoded block of data to be interpreted according to the SASL mechanism in use. - Some SASL mechanisms support sending an "empty string"; + Some SASL mechanisms support sending an "empty string"; FIXME we need some way to do this. BEGIN Command - The BEGIN command acknowledges that the client has received an + The BEGIN command acknowledges that the client has received an OK command from the server, and that the stream of messages - is about to begin. + is about to begin. The first octet received by the server after the \r\n of the BEGIN @@ -2242,8 +2242,8 @@ Optionally, the REJECTED command has a space-separated list of available auth mechanisms as arguments. If a server ever provides - a list of supported mechanisms, it must provide the same list - each time it sends a REJECTED message. Clients are free to + a list of supported mechanisms, it must provide the same list + each time it sends a REJECTED message. Clients are free to ignore all lists received after the first. @@ -2288,8 +2288,8 @@ If an ERROR is sent, the server or client that sent the error must continue as if the command causing the ERROR had never been - received. However, the the server or client receiving the error - should try something other than whatever caused the error; + received. However, the the server or client receiving the error + should try something other than whatever caused the error; if only canceling/rejecting the authentication. @@ -2353,7 +2353,7 @@ Authentication examples - +
Example of successful magic cookie authentication @@ -2459,16 +2459,16 @@ Authentication state diagrams - + - This section documents the auth protocol in terms of - a state machine for the client and the server. This is + This section documents the auth protocol in terms of + a state machine for the client and the server. This is probably the most robust way to implement the protocol. Client states - + To more precisely describe the interaction between the protocol state machine and the authentication mechanisms the @@ -2499,10 +2499,10 @@ - + Both RESP and CHALL may be empty. - + The Client starts by getting an initial response from the default mechanism and sends AUTH MECH RESP, or AUTH MECH if @@ -2512,7 +2512,7 @@ returns OK the client starts in state WaitingForOK. - + The client should keep track of available mechanisms and which it mechanisms it has already attempted. This list is @@ -2648,7 +2648,7 @@ Server states - + For the server MECH(RESP) means that the client response RESP was fed to the the mechanism MECH, which returns one of @@ -2750,7 +2750,7 @@ - + <emphasis>WaitingForData</emphasis> @@ -2846,7 +2846,7 @@ - + Authentication mechanisms @@ -2860,8 +2860,8 @@ The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client has the ability to read a private file owned by the user being authenticated. If the client can prove that it has access to a secret - cookie stored in this file, then the client is authenticated. - Thus the security of DBUS_COOKIE_SHA1 depends on a secure home + cookie stored in this file, then the client is authenticated. + Thus the security of DBUS_COOKIE_SHA1 depends on a secure home directory. @@ -2874,7 +2874,7 @@ - The client sends the username it would like to authenticate + The client sends the username it would like to authenticate as, hex-encoded. @@ -2920,13 +2920,13 @@ Cookies are stored in a user's home directory, in the directory - ~/.dbus-keyrings/. This directory must - not be readable or writable by other users. If it is, - clients and servers must ignore it. The directory + ~/.dbus-keyrings/. This directory must + not be readable or writable by other users. If it is, + clients and servers must ignore it. The directory contains cookie files named after the cookie context. - A cookie file contains one cookie per line. Each line + A cookie file contains one cookie per line. Each line has three space-separated fields: @@ -2944,7 +2944,7 @@ The cookie itself, a hex-encoded random block of bytes. The cookie - may be of any length, though obviously security increases + may be of any length, though obviously security increases as the length increases. @@ -2973,16 +2973,16 @@ Once the lockfile has been created, the server loads the cookie file. It should then delete any cookies that are old (the timeout can be fairly short), or more than a reasonable - time in the future (so that cookies never accidentally - become permanent, if the clock was set far into the future - at some point). If no recent keys remain, the + time in the future (so that cookies never accidentally + become permanent, if the clock was set far into the future + at some point). If no recent keys remain, the server may generate a new key. - The pruned and possibly added-to cookie file - must be resaved atomically (using a temporary + The pruned and possibly added-to cookie file + must be resaved atomically (using a temporary file which is rename()'d). @@ -2994,8 +2994,8 @@ - Clients need not lock the file in order to load it, - because servers are required to save the file atomically. + Clients need not lock the file in order to load it, + because servers are required to save the file atomically. @@ -3008,7 +3008,7 @@ Each value is escaped. - For example: + For example: unix:path=/tmp/dbus-test Which is the address to a unix socket with the path /tmp/dbus-test. @@ -3036,7 +3036,7 @@ - The set of optionally-escaped bytes is intended to preserve address + The set of optionally-escaped bytes is intended to preserve address readability and convenience. @@ -3051,7 +3051,7 @@ those two connections are equivalent post-connection but should have distinct UUIDs to distinguish the kinds of connection. - + The intent of the address UUID feature is to allow a client to avoid opening multiple identical connections to the same server, by allowing the @@ -3063,12 +3063,12 @@ - Note that the address key is guid even though the + Note that the address key is guid even though the rest of the API and documentation says "UUID," for historical reasons. - [FIXME clarify if attempting to connect to each is a requirement + [FIXME clarify if attempting to connect to each is a requirement or just a suggestion] When connecting to a server, multiple server addresses can be separated by a semi-colon. The library will then try to connect @@ -3110,28 +3110,28 @@ unix:path=/run/user/1234/bus. - + Transports [FIXME we need to specify in detail each transport and its possible arguments] - - Current transports include: unix domain sockets (including + + Current transports include: unix domain sockets (including abstract namespace on linux), launchd, systemd, TCP/IP, an executed subprocess and a debug/testing transport using in-process pipes. Future possible transports include one that tunnels over X11 protocol. - + Unix Domain Sockets - Unix domain sockets can be either paths in the file system or on Linux + Unix domain sockets can be either paths in the file system or on Linux kernels, they can be abstract which are similar to paths but do not show up in the file system. - When a socket is opened by the D-Bus library it truncates the path + When a socket is opened by the D-Bus library it truncates the path name right before the first trailing Nul byte. This is true for both normal paths and abstract paths. Note that this is a departure from previous versions of D-Bus that would create sockets with a fixed @@ -3153,8 +3153,8 @@ Server Address Format - - Unix domain socket addresses are identified by the "unix:" prefix + + Unix domain socket addresses are identified by the "unix:" prefix and support the following key/value pairs: @@ -3280,13 +3280,13 @@ TCP Sockets The tcp transport provides TCP/IP based connections between clients - located on the same or different hosts. + located on the same or different hosts. - Using tcp transport without any additional secure authentification mechanismus - over a network is unsecure. + Using tcp transport without any additional secure authentification mechanismus + over a network is unsecure. - + On Windows and most Unix platforms, the TCP stack is unable to transfer credentials over a TCP connection, so the EXTERNAL authentication mechanism does not work for this transport. @@ -3300,8 +3300,8 @@ Server Address Format - - TCP/IP socket addresses are identified by the "tcp:" prefix + + TCP/IP socket addresses are identified by the "tcp:" prefix and support the following key/value pairs: @@ -3333,9 +3333,9 @@ port (number) - The tcp port the server will open. A zero value let the server - choose a free port provided from the underlaying operating system. - libdbus is able to retrieve the real used port from the server. + The tcp port the server will open. A zero value let the server + choose a free port provided from the underlaying operating system. + libdbus is able to retrieve the real used port from the server. @@ -3387,8 +3387,8 @@ Server Address Format - - Nonce TCP/IP socket addresses uses the "nonce-tcp:" prefix + + Nonce TCP/IP socket addresses uses the "nonce-tcp:" prefix and support the following key/value pairs: @@ -3415,9 +3415,9 @@ port (number) - The tcp port the server will open. A zero value let the server - choose a free port provided from the underlaying operating system. - libdbus is able to retrieve the real used port from the server. + The tcp port the server will open. A zero value let the server + choose a free port provided from the underlaying operating system. + libdbus is able to retrieve the real used port from the server. @@ -3606,7 +3606,7 @@ UUIDs A working D-Bus implementation uses universally-unique IDs in two places. - First, each server address has a UUID identifying the address, + First, each server address has a UUID identifying the address, as described in . Second, each operating system kernel instance running a D-Bus client or server has a UUID identifying that kernel, retrieved by invoking the method @@ -3638,18 +3638,18 @@ of the UUID. - + Standard Interfaces - See for details on + See for details on the notation used in this section. There are some standard interfaces that may be useful across various D-Bus applications. <literal>org.freedesktop.DBus.Peer</literal> - The org.freedesktop.DBus.Peer interface + The org.freedesktop.DBus.Peer interface has two methods: org.freedesktop.DBus.Peer.Ping () @@ -3665,12 +3665,12 @@ On receipt of the METHOD_CALL message - org.freedesktop.DBus.Peer.GetMachineId, an application should - reply with a METHOD_RETURN containing a hex-encoded + org.freedesktop.DBus.Peer.GetMachineId, an application should + reply with a METHOD_RETURN containing a hex-encoded UUID representing the identity of the machine the process is running on. This UUID must be the same for all processes on a single system at least - until that system next reboots. It should be the same across reboots - if possible, but this is not always possible to implement and is not + until that system next reboots. It should be the same across reboots + if possible, but this is not always possible to implement and is not guaranteed. It does not matter which object path a GetMachineId is sent to. The reference implementation handles this method automatically. @@ -3679,11 +3679,11 @@ The UUID is intended to be per-instance-of-the-operating-system, so may represent a virtual machine running on a hypervisor, rather than a physical machine. Basically if two processes see the same UUID, they should also see the same - shared memory, UNIX domain sockets, process IDs, and other features that require + shared memory, UNIX domain sockets, process IDs, and other features that require a running OS kernel in common between the processes. - The UUID is often used where other programs might use a hostname. Hostnames + The UUID is often used where other programs might use a hostname. Hostnames can change without rebooting, however, or just be "localhost" - so the UUID is more robust. @@ -3713,8 +3713,8 @@ <literal>org.freedesktop.DBus.Properties</literal> - Many native APIs will have a concept of object properties - or attributes. These can be exposed via the + Many native APIs will have a concept of object properties + or attributes. These can be exposed via the org.freedesktop.DBus.Properties interface. @@ -3751,10 +3751,10 @@ see . - An empty string may be provided for the interface name; in this case, - if there are multiple properties on an object with the same name, - the results are undefined (picking one by according to an arbitrary - deterministic rule, or returning an error, are the reasonable + An empty string may be provided for the interface name; in this case, + if there are multiple properties on an object with the same name, + the results are undefined (picking one by according to an arbitrary + deterministic rule, or returning an error, are the reasonable possibilities). @@ -3904,10 +3904,10 @@ Introspection Data Format - As described in , - objects may be introspected at runtime, returning an XML string - that describes the object. The same XML format may be used in - other contexts as well, for example as an "IDL" for generating + As described in , + objects may be introspected at runtime, returning an XML string + that describes the object. The same XML format may be used in + other contexts as well, for example as an "IDL" for generating static language bindings. @@ -3954,39 +3954,39 @@ - If a child <node> has any sub-elements, then they + If a child <node> has any sub-elements, then they must represent a complete introspection of the child. - If a child <node> is empty, then it may or may + If a child <node> is empty, then it may or may not have sub-elements; the child must be introspected - in order to find out. The intent is that if an object + in order to find out. The intent is that if an object knows that its children are "fast" to introspect - it can go ahead and return their information, but + it can go ahead and return their information, but otherwise it can omit it. - The direction element on <arg> may be omitted, - in which case it defaults to "in" for method calls - and "out" for signals. Signals only allow "out" + The direction element on <arg> may be omitted, + in which case it defaults to "in" for method calls + and "out" for signals. Signals only allow "out" so while direction may be specified, it's pointless. - The possible directions are "in" and "out", + The possible directions are "in" and "out", unlike CORBA there is no "inout" - The possible property access flags are + The possible property access flags are "readwrite", "read", and "write" - Multiple interfaces can of course be listed for + Multiple interfaces can of course be listed for one <node>. @@ -4083,8 +4083,8 @@ Message Bus Overview - The message bus accepts connections from one or more applications. - Once connected, applications can exchange messages with other + The message bus accepts connections from one or more applications. + Once connected, applications can exchange messages with other applications that are also connected to the bus. @@ -4108,7 +4108,7 @@ Each name may have queued owners. When an application requests a name for a connection and the name is already in - use, the bus will optionally add the connection to a queue waiting for + use, the bus will optionally add the connection to a queue waiting for the name. If the current owner of the name disconnects or releases the name, the next connection in the queue will become the new owner. @@ -4116,7 +4116,7 @@ This feature causes the right thing to happen if you start two text editors for example; the first one may request "com.example.TextEditor", - and the second will be queued as a possible owner of that name. When + and the second will be queued as a possible owner of that name. When the first exits, the second will take over. @@ -4139,9 +4139,9 @@ connections to the same bus. - Ownership of a unique name is a prerequisite for interaction with - the message bus. It logically follows that the unique name is always - the first name that an application comes to own, and the last + Ownership of a unique name is a prerequisite for interaction with + the message bus. It logically follows that the unique name is always + the first name that an application comes to own, and the last one that it loses ownership of. @@ -4229,7 +4229,7 @@ If the method caller is currently the primary owner of the name, the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_DO_NOT_QUEUE - values are updated with the values from the new RequestName call, + values are updated with the values from the new RequestName call, and nothing further happens. @@ -4241,8 +4241,8 @@ invocation has the DBUS_NAME_FLAG_REPLACE_EXISTING flag, then the caller of RequestName replaces the current primary owner at the head of the queue and the current primary owner moves to the - second position in the queue. If the caller of RequestName was - in the queue previously its flags are updated with the values from + second position in the queue. If the caller of RequestName was + in the queue previously its flags are updated with the values from the new RequestName in addition to moving it to the head of the queue. @@ -4285,7 +4285,7 @@ automatically replace the new primary owner. In other words, DBUS_NAME_FLAG_REPLACE_EXISTING is not saved, it is only used at the time RequestName is called. This is deliberate to avoid an infinite loop - anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT + anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_REPLACE_EXISTING. @@ -4685,13 +4685,13 @@ if the security policy of the message bus allows it. - Match rules are added using the AddMatch bus method + Match rules are added using the AddMatch bus method (see ). Rules are - specified as a string of comma separated key/value pairs. - Excluding a key from the rule indicates a wildcard match. - For instance excluding the the member from a match rule but + specified as a string of comma separated key/value pairs. + Excluding a key from the rule indicates a wildcard match. + For instance excluding the the member from a match rule but adding a sender would let all messages from that sender through. - An example of a complete rule would be + An example of a complete rule would be "type='signal',sender='org.freedesktop.DBus',interface='org.freedesktop.DBus',member='Foo',path='/bar/foo',destination=':452345.34',arg2='bar'" @@ -4721,7 +4721,7 @@ . - The following table describes the keys that can be used to create + The following table describes the keys that can be used to create a match rule. @@ -4751,7 +4751,7 @@ An interface name (see ) Match messages sent over or to a particular interface. An example of an interface match is interface='org.freedesktop.Hal.Manager'. - If a message omits the interface header, it must not match any rule + If a message omits the interface header, it must not match any rule that specifies this key. @@ -4812,10 +4812,10 @@ arg[0, 1, 2, 3, ...] Any string - Arg matches are special and are used for further restricting the + Arg matches are special and are used for further restricting the match based on the arguments in the body of a message. Only arguments of type - STRING can be matched in this way. An example of an argument match - would be arg3='Foo'. Only argument indexes from 0 to 63 should be + STRING can be matched in this way. An example of an argument match + would be arg3='Foo'. Only argument indexes from 0 to 63 should be accepted. @@ -4927,7 +4927,7 @@ well-known name, such as com.example.TextEditor. This implies a contract documented along with the name com.example.TextEditor for which object - the owner of that name will provide, and what interfaces those + the owner of that name will provide, and what interfaces those objects will have. @@ -5067,9 +5067,9 @@ only by name. - Contrast this with a per-display scope. To achieve that, we would + Contrast this with a per-display scope. To achieve that, we would want a single bus spanning all sessions using a given display. - So we might set a _DBUS_DISPLAY_BUS_ADDRESS + So we might set a _DBUS_DISPLAY_BUS_ADDRESS property on screen 0 of the display, pointing to this bus. @@ -5078,7 +5078,7 @@ Well-known Message Bus Instances - Two standard message bus instances are defined here, along with how + Two standard message bus instances are defined here, along with how to locate them and where their service files live. @@ -5089,13 +5089,13 @@ session may interact with one another using this message bus. - The address of the login session message bus is given - in the DBUS_SESSION_BUS_ADDRESS environment - variable. If that variable is not set, applications may - also try to read the address from the X Window System root + The address of the login session message bus is given + in the DBUS_SESSION_BUS_ADDRESS environment + variable. If that variable is not set, applications may + also try to read the address from the X Window System root window property _DBUS_SESSION_BUS_ADDRESS. The root window property must have type STRING. - The environment variable should have precedence over the + The environment variable should have precedence over the root window property. The address of the login session message bus is given in the @@ -5335,19 +5335,19 @@ A computer may have a system message bus, accessible to all applications on the system. This message bus may be - used to broadcast system events, such as adding new hardware devices, + used to broadcast system events, such as adding new hardware devices, changes in the printer queue, and so forth. - The address of the system message bus is given - in the DBUS_SYSTEM_BUS_ADDRESS environment - variable. If that variable is not set, applications should try + The address of the system message bus is given + in the DBUS_SYSTEM_BUS_ADDRESS environment + variable. If that variable is not set, applications should try to connect to the well-known address unix:path=/var/run/dbus/system_bus_socket. - The D-Bus reference implementation actually honors the - $(localstatedir) configure option + The D-Bus reference implementation actually honors the + $(localstatedir) configure option for this address, on both client and server side. @@ -5428,7 +5428,7 @@ There is no corresponding "disconnect" request; if a client wishes to - disconnect from the bus, it simply closes the socket (or other + disconnect from the bus, it simply closes the socket (or other communication channel). @@ -5584,7 +5584,7 @@ This signal indicates that the owner of a name has changed. - It's also the signal to use to detect the appearance of + It's also the signal to use to detect the appearance of new names on the bus. @@ -6234,7 +6234,7 @@ - Adds a match rule to match messages going through the message bus (see ). + Adds a match rule to match messages going through the message bus (see ). If the bus does not have enough resources the org.freedesktop.DBus.Error.OOM error is returned. @@ -6265,7 +6265,7 @@ - Removes the first rule that matches (see ). + Removes the first rule that matches (see ). If the rule is not found the org.freedesktop.DBus.Error.MatchRuleNotFound error is returned. @@ -6297,9 +6297,9 @@ - Gets the unique ID of the bus. The unique ID here is shared among all addresses the - bus daemon is listening on (TCP, UNIX domain socket, etc.) and its format is described in - . Each address the bus is listening on also has its own unique + Gets the unique ID of the bus. The unique ID here is shared among all addresses the + bus daemon is listening on (TCP, UNIX domain socket, etc.) and its format is described in + . Each address the bus is listening on also has its own unique ID, as described in . The per-bus and per-address IDs are not related. There is also a per-machine ID, described in and returned by org.freedesktop.DBus.Peer.GetMachineId(). @@ -6428,9 +6428,9 @@ name if the message bus has associated the application's connection with the name. Names may also have queued owners (see ). - The bus assigns a unique name to each connection, - see . Other names - can be thought of as "well-known names" and are + The bus assigns a unique name to each connection, + see . Other names + can be thought of as "well-known names" and are used to find applications that offer specific functionality. @@ -6440,7 +6440,7 @@ - + Message @@ -6455,9 +6455,9 @@ Message Bus - The message bus is a special application that forwards + The message bus is a special application that forwards or routes messages between a group of applications - connected to the message bus. It also manages + connected to the message bus. It also manages names used for routing messages. @@ -6467,7 +6467,7 @@ Name - See . "Name" may + See . "Name" may also be used to refer to some of the other names in D-Bus, such as interface names. -- 2.4.3