X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fdbus-specification.xml;h=7280cf1768611b037b8168796e3e2031fddfb5a6;hb=b080ba1eab764b79edb62afcfc61794f410a5591;hp=183ef5b792fd8490b6547120cb9616d39125ff80;hpb=b6b15f052f880963dc7261a0fc9c509d211b6d32;p=platform%2Fupstream%2Fdbus.git diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 183ef5b..7280cf1 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -6,8 +6,8 @@
D-Bus Specification - Version 0.17 - (not final) + Version 0.19 + UNRELEASED Havoc @@ -49,6 +49,26 @@ + + Simon + McVittie + + Collabora Ltd. +
+ simon.mcvittie@collabora.co.uk +
+ + + + David + Zeuthen + + Red Hat, Inc. +
+ davidz@redhat.com +
+ + @@ -58,6 +78,20 @@ + 0.18 + 29 July 2011 + smcv + define eavesdropping, unicast, broadcast; add eavesdrop + match keyword; promote type system to a top-level section + + + 0.17 + 1 June 2011 + smcv/davidz + define ObjectManager; reserve extra pseudo-type-codes used + by GVariant + + 0.16 11 April 2011 @@ -237,27 +271,13 @@ - - Message Protocol - - - A message consists of a - header and a body. If you - think of a message as a package, the header is the address, and the body - contains the package contents. The message delivery system uses the header - 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 - integer or a byte array. - + + Type System - Both header and body use the same type system and format for - serializing data. Each type of value has a wire format. + D-Bus has a type system, in which values of various types can be + serialized into a sequence of bytes referred to as the + wire format in a standard way. Converting a value from some other representation into the wire format is called marshaling and converting it back from the wire format is unmarshaling. @@ -816,6 +836,31 @@ + + + + Message Protocol + + + A message consists of a + header and a body. If you + think of a message as a package, the header is the address, and the body + contains the package contents. The message delivery system uses the header + 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 + integer or a byte array. + + + + Both header and body use the D-Bus type + system and format for serializing data. + + Message Format @@ -3347,39 +3392,10 @@ - Messages may have a DESTINATION field (see ). If the - DESTINATION field is present, it specifies a message - recipient by name. Method calls and replies normally specify this field. - The message bus must send messages (of any type) with the - DESTINATION field set to the specified recipient, - regardless of whether the recipient has set up a match rule matching - the message. - - - - Signals normally do not specify a destination; they are sent to all - applications with message matching rules that - match the message. - - - - When the message bus receives a method call, if the - DESTINATION field is absent, the call is taken to be - a standard one-to-one message and interpreted by the message bus - itself. For example, sending an - org.freedesktop.DBus.Peer.Ping message with no - DESTINATION will cause the message bus itself to - reply to the ping immediately; the message bus will not make this - message visible to other applications. - - - - Continuing the org.freedesktop.DBus.Peer.Ping example, if - 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. + Applications may send unicast messages to + a specific recipient or to the message bus itself, or + broadcast messages to all interested recipients. + See for details. @@ -3813,20 +3829,122 @@ Message Bus Message Routing + + + Messages may have a DESTINATION field (see ), resulting in a + unicast message. If the + DESTINATION field is present, it specifies a message + recipient by name. Method calls and replies normally specify this field. + The message bus must send messages (of any type) with the + DESTINATION field set to the specified recipient, + regardless of whether the recipient has set up a match rule matching + the message. + + - FIXME + When the message bus receives a signal, if the + DESTINATION field is absent, it is considered to + be a broadcast signal, and is sent to all + applications with message matching rules that + match the message. Most signal messages are broadcasts. + + + Unicast signal messages (those with a DESTINATION + field) are not commonly used, but they are treated like any unicast + message: they are delivered to the specified receipient, + regardless of its match rules. One use for unicast signals is to + avoid a race condition in which a signal is emitted before the intended + recipient can call to + receive that signal: if the signal is sent directly to that recipient + using a unicast message, it does not need to add a match rule at all, + and there is no race condition. Another use for unicast signals, + on message buses whose security policy prevents eavesdropping, is to + send sensitive information which should only be visible to one + recipient. + + + + When the message bus receives a method call, if the + DESTINATION field is absent, the call is taken to be + a standard one-to-one message and interpreted by the message bus + itself. For example, sending an + org.freedesktop.DBus.Peer.Ping message with no + DESTINATION will cause the message bus itself to + reply to the ping immediately; the message bus will not make this + message visible to other applications. + + + + Continuing the org.freedesktop.DBus.Peer.Ping example, if + 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. + + + + Message bus implementations may impose a security policy which + prevents certain messages from being sent or received. + When a message cannot be sent or received due to a security + policy, the message bus should send an error reply, unless the + original message had the NO_REPLY flag. + + + + Eavesdropping + + Receiving a unicast message whose DESTINATION + indicates a different recipient is called + eavesdropping. On a message bus which acts as + a security boundary (like the standard system bus), the security + policy should usually prevent eavesdropping, since unicast messages + are normally kept private and may contain security-sensitive + information. + + + + Eavesdropping is mainly useful for debugging tools, such as + the dbus-monitor tool in the reference + implementation of D-Bus. Tools which eavesdrop on the message bus + should be careful to avoid sending a reply or error in response to + messages intended for a different client. + + + + Clients may attempt to eavesdrop by adding match rules + (see ) containing + the eavesdrop='true' match. If the message bus' + security policy does not allow eavesdropping, the match rule can + still be added, but will not have any practical effect. For + compatibility with older message bus implementations, if adding such + a match rule results in an error reply, the client may fall back to + adding the same rule with the eavesdrop match + omitted. + + + Match Rules - An important part of the message bus routing protocol is match - rules. Match rules describe what messages can be sent to a client - based on the contents of the message. When a message is routed - through the bus it is compared to clients' match rules. If any - of the rules match, the message is dispatched to the client. - If none of the rules match the message never leaves the bus. This - is an effective way to control traffic over the bus and to make sure - only relevant message need to be processed by the client. + An important part of the message bus routing protocol is match + rules. Match rules describe the messages that should be sent to a + client, based on the contents of the message. Broadcast signals + are only sent to clients which have a suitable match rule: this + avoids waking up client processes to deal with signals that are + not relevant to that client. + + + Messages that list a client as their DESTINATION + do not need to match the client's match rules, and are sent to that + client regardless. As a result, match rules are mainly used to + receive a subset of broadcast signals. + + + Match rules can also be used for eavesdropping + (see ), + if the security policy of the message bus allows it. Match rules are added using the AddMatch bus method @@ -4004,6 +4122,28 @@ + + eavesdrop + 'true', 'false' + Since D-Bus 1.5.6, match rules do not + match messages which have a DESTINATION + field unless the match rule specifically + requests this + (see ) + by specifying eavesdrop='true' + in the match rule. eavesdrop='false' + restores the default behaviour. Messages are + delivered to their DESTINATION + regardless of match rules, so this match does not + affect normal delivery of unicast messages. + If the message bus has a security policy which forbids + eavesdropping, this match may still be used without error, + but will not have any practical effect. + In older versions of D-Bus, this match was not allowed + in match rules, and all match rules behaved as if + eavesdrop='true' had been used. + +