diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/TODO | 30 | ||||
| -rw-r--r-- | doc/dbus-specification.sgml | 624 |
2 files changed, 427 insertions, 227 deletions
@@ -23,9 +23,6 @@ (changing get_string to have an error return, and allowing a type error as a possible return) - - We might consider returning a "no such operation" error in dbus-connection.c - for unhandled messages. - - The convenience functions in dbus-bus.h should perhaps have the signatures that they would have if they were autogenerated stubs. e.g. the acquire service function. We should also evaluate @@ -69,3 +66,30 @@ files; they have to be in the toplevel file. when loading a child file, we could just init its DBusLimits from the parent, then after parsing copy its DBusLimits back to the parent + + - when making a method call, if the call serial were globally unique, + we could forward the call serial along with any method calls made + as a result of the first method call, and allow reentrancy that was + strictly part of the call stack of said method call. But I don't + really see how to do this without making the user pass around the + call serial to all method calls all the time, or disallowing + async calls. + + - the invalid messages in the test suite are all useless because + they are invalid for the wrong reasons due to protocol changes + + - I don't want to introduce DBusObject, but refcounting and object + data could still be factored out into an internal "base class" + perhaps. + + - modify the auth protocol to also support other initial-handshake + type of information + + - document the auth protocol as a set of states and transitions, and + then reimplement it in those terms + + - dbus_gproxy or dbus_g_proxy? + + - add dbus_message_has_path(), maybe has_member/interface + + - The OBJECT_PATH type is not documented in the spec. diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml index 4ab5291a..696c3f45 100644 --- a/doc/dbus-specification.sgml +++ b/doc/dbus-specification.sgml @@ -3,8 +3,8 @@ <article id="index"> <artheader> <title>D-BUS Specification</title> - <releaseinfo>Version 0.7</releaseinfo> - <date>26 March 2003</date> + <releaseinfo>Version 0.8</releaseinfo> + <date>06 September 2003</date> <authorgroup> <author> <firstname>Havoc</firstname> @@ -65,10 +65,10 @@ <para> D-BUS is <emphasis>easy to use</emphasis> because it works in terms of <firstterm>messages</firstterm> rather than byte streams, and - does not require users to understand any complex concepts such as a - new type system or elaborate APIs. Libraries implementing D-BUS - may choose to abstract messages as "method calls" (see - <xref linkend="message-conventions-method">). + automatically handles a lot of the hard IPC issues. Also, the D-BUS + library is designed to be wrapped in a way that lets developers use + their framework's existing object/type system, rather than learning + a new one specifically for IPC. </para> </listitem> </itemizedlist> @@ -83,11 +83,10 @@ forwards messages among them. </para> <para> - Things that D-BUS can be used for is for example notification of - system changes (notification of when a camera is plugged in to a - computer, or a new version of some software has been installed), - or desktop interoperablity, for example a file monitoring - service or a configuration service. + Uses of D-BUS include notification of system changes (notification of when + a camera is plugged in to a computer, or a new version of some software + has been installed), or desktop interoperablity, for example a file + monitoring service or a configuration service. </para> </sect1> @@ -135,6 +134,12 @@ </row> <row> <entry>1 byte</entry> + <entry>Type of message. Unknown types MUST be ignored. + Currently-defined types are described below. + </entry> + </row> + <row> + <entry>1 byte</entry> <entry>Bitwise OR of flags. Unknown flags MUST be ignored. Currently-defined flags are described below. </entry> @@ -149,12 +154,6 @@ </entry> </row> <row> - <entry>1 byte</entry> - <entry>A nul byte, reserved for future use. - Any value for this byte MUST be accepted. - </entry> - </row> - <row> <entry>4 bytes</entry> <entry>An unsigned 32-bit integer in the message's byte order, indicating the total length in bytes of @@ -172,9 +171,11 @@ <row> <entry>4 bytes</entry> <entry>The message's serial number, an unsigned 32-bit integer in - the message's byte order. Applications MUST NOT reuse the same - serial number for different messages more often than 32-bit - unsigned integer wraparound. Zero is not a valid serial number. + the message's byte order. The serial number is a cookie used to + identify message replies; thus all outstanding unreplied-to messages + from the same connection MUST have a different serial number. + Zero is not a valid serial number, but all other numbers are + allowed. </entry> </row> </tbody> @@ -182,19 +183,67 @@ </informaltable> </para> <para> - Flags that can appear in the second byte of the header: + Types that can appear in the second byte of the header: <informaltable> - <tgroup cols=2> + <tgroup cols=3> + <thead> + <row> + <entry>Conventional name</entry> + <entry>Decimal value</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>INVALID</entry> + <entry>0</entry> + <entry>This is an invalid type, if seen in a message + the connection should be dropped immediately.</entry> + </row> + <row> + <entry>METHOD_CALL</entry> + <entry>1</entry> + <entry>Method call.</entry> + </row> + <row> + <entry>METHOD_RETURN</entry> + <entry>2</entry> + <entry>Method reply with returned data.</entry> + </row> + <row> + <entry>ERROR</entry> + <entry>3</entry> + <entry>Error reply. If the first argument exists and is a + string, it is an error message.</entry> + </row> + <row> + <entry>SIGNAL</entry> + <entry>4</entry> + <entry>Signal emission.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + <para> + Flags that can appear in the third byte of the header: + <informaltable> + <tgroup cols=3> <thead> <row> + <entry>Conventional name</entry> <entry>Hex value</entry> <entry>Description</entry> </row> </thead> <tbody> <row> + <entry>NO_REPLY_EXPECTED</entry> <entry>0x1</entry> - <entry>This message is an error reply. If the first argument exists and is a string, it is an error message.</entry> + <entry>This message does not expect method return replies or + error replies; the reply can be omitted as an + optimization. However, it is compliant with this specification + to return the reply despite this flag.</entry> </row> </tbody> </tgroup> @@ -208,22 +257,21 @@ In addition to the required header information mentioned in <xref linkend="message-protocol-header-encoding">, the header may contain zero or more named - header fields. These fields are named to allow - future versions of this protocol specification to - add new fields; implementations must ignore fields - they do not understand. Implementations must not - invent their own header fields; only changes to + 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; only changes to this specification may introduce new header fields. </para> <para> - Header field names MUST consist of 4 non-nul bytes. The field name is - NOT nul terminated; it occupies exactly 4 bytes. Following the name, the - field MUST have a type code represented as a single unsigned byte, and - then a properly-aligned value of that type. See <xref - linkend="message-protocol-arguments"> for a description of how each type - is encoded. If an implementation sees a header field name that it does - not understand, it MUST ignore that field. + Header field names MUST consist of a single byte, possible values + of which are defined below. Following the name, the field MUST have + a type code represented as a single unsigned byte, and then a + properly-aligned value of that type. See <xref + linkend="message-protocol-arguments"> for a description of how each + type is encoded. If an implementation sees a header field name that + it does not understand, it MUST ignore that field. </para> <para> @@ -232,36 +280,68 @@ <tgroup cols=3> <thead> <row> - <entry>Name</entry> + <entry>Conventional Name</entry> + <entry>Decimal Value</entry> <entry>Type</entry> <entry>Description</entry> </row> </thead> <tbody> <row> - <entry>name</entry> + <entry>INVALID</entry> + <entry>0</entry> + <entry>INVALID</entry> + <entry>Not a valid field name (error if it appears in a message)</entry> + </row> + <row> + <entry>PATH</entry> + <entry>1</entry> + <entry>STRING</entry> + <entry>The object to send the message to; objects are identified by + a path, "/foo/bar"</entry> + </row> + <row> + <entry>INTERFACE</entry> + <entry>2</entry> + <entry>STRING</entry> + <entry>The interface to invoke a method call on, or + that a signal is emitted from. e.g. "org.freedesktop.Introspectable"</entry> + </row> + <row> + <entry>MEMBER</entry> + <entry>3</entry> + <entry>STRING</entry> + <entry>The member, either the method name or signal name. + e.g. "Frobate"</entry> + </row> + <row> + <entry>ERROR_NAME</entry> + <entry>4</entry> <entry>STRING</entry> - <entry>The name of the message, such as org.freedesktop.Peer.Ping</entry> + <entry>The name of the error that occurred, for errors</entry> </row> <row> - <entry>rply</entry> + <entry>REPLY_SERIAL</entry> + <entry>5</entry> <entry>UINT32</entry> <entry>The serial number of the message this message is a reply to. (The serial number is one of the mandatory header fields, see <xref linkend="message-protocol-header-encoding">.)</entry> </row> <row> - <entry>srvc</entry> + <entry>SERVICE</entry> + <entry>6</entry> <entry>STRING</entry> <entry>The name of the service this message should be routed to. Only used in combination with the message bus, see <xref linkend="message-bus">.</entry> </row> <row> - <entry>sndr</entry> + <entry>SENDER_SERVICE</entry> + <entry>7</entry> <entry>STRING</entry> - <entry>The name of the base service that sent this message. - The message bus fills in this field; the field is + <entry>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.</entry> </row> </tbody> @@ -277,10 +357,9 @@ buffer while keeping data types aligned, the total length of the header must be a multiple of 8 bytes. To achieve this, the header MUST be padded with nul bytes to align its total length on an 8-byte boundary. - The minimum number of padding bytes MUST be used. Because all possible - named fields use at least 8 bytes, implementations can distinguish - padding (which must be less than 8 bytes) from additional named fields - (which must be at least 8 bytes). + The minimum number of padding bytes MUST be used. Because zero is an + invalid field name, implementations can distinguish padding (which must be + zero initialized) from additional named fields. </para> </sect2> @@ -440,19 +519,228 @@ <sect2 id="message-protocol-names"> <title>Valid names</title> <para> - Messages and services have names with type STRING, meaning that - they must be valid UTF-8. However, there are also some - additional restrictions that apply to message and service names - specifically: - <itemizedlist> - <listitem><para>They must contain at least one '.' (period) character</para></listitem> - <listitem><para>They must not begin with a '.' (period) character</para></listitem> - <listitem><para>They must not exceed 256 bytes in length</para></listitem> - <listitem><para>They must be at least 1 byte in length</para></listitem> - </itemizedlist> - As a special exception, base service names (those beginning with a colon (':') character) - need not contain a period. + The various header fields of type STRING have some restrictions + on the string's format. + </para> + <sect3 id="message-protocol-names-service"> + <title>Service names</title> + <para> + Services have names with type STRING, meaning that + they must be valid UTF-8. However, there are also some + additional restrictions that apply to service names + specifically: + <itemizedlist> + <listitem><para>They must contain at least one '.' (period) character</para></listitem> + <listitem><para>They must not begin with a '.' (period) character</para></listitem> + <listitem><para>They must not exceed 256 bytes in length</para></listitem> + <listitem><para>They must be at least 1 byte in length</para></listitem> + </itemizedlist> + + As a special exception, base service names (those beginning with a colon + (':') character) need not contain a period. + </para> + <para> + FIXME really, shouldn't we ban basically everything non-alphanumeric + so the name will work in all programming languages? + </para> + </sect3> + <sect3 id="message-protocol-names-interface"> + <title>Interface names</title> + <para> + Interface names have the same restrictions as service names, + but do not have the special exception for names beginning with + a colon. + </para> + <para> + FIXME really, shouldn't we ban basically everything non-alphanumeric + so the name will work in all programming languages? + </para> + </sect3> + <sect3 id="message-protocol-names-method"> + <title>Method names</title> + <para> + Method names: + <itemizedlist> + <listitem><para>May not contain the '.' (period) character</para></listitem> + <listitem><para>Must not exceed 256 bytes in length</para></listitem> + <listitem><para>Must be at least 1 byte in length</para></listitem> + </itemizedlist> + </para> + <para> + FIXME really, shouldn't we ban basically everything non-alphanumeric + so the name will work in all programming languages? + </para> + </sect3> + <sect3 id="message-protocol-names-path"> + <title>Path names</title> + <para> + A 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. + </para> + </sect3> + <sect3 id="message-protocol-names-error"> + <title>Error names</title> + <para> + Error names have the same restrictions as interface names. + </para> + <para> + FIXME really, shouldn't we ban basically everything non-alphanumeric + so the name will work in all programming languages? + </para> + </sect3> + </sect2> + + <sect2 id="message-protocol-types"> + <title>Message types</title> + <para> + Each of the message types (METHOD_CALL, METHOD_RETURN, ERROR, and + SIGNAL) has its own expected usage conventions and header fields. </para> + <sect3 id="message-protocol-types-method"> + <title>Method Calls, Returns, and Errors</title> + <para> + Some messages invoke an operation on a remote object. These are + called method call messages and have the type tag METHOD_CALL. Such + messages map naturally to methods on objects in a typical program. + </para> + <para> + 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 + 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. + </para> + <para> + 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 + the service to receive the message. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <sect4 id="message-protocol-types-method-apis"> + <title>Mapping method calls to native APIs</title> + <para> + APIs for D-BUS may map method calls to a method call in a specific + programming language, such as C++, or may map a method call written + in an IDL to a D-BUS message. + </para> + <para> + 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 + "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" + argument. You can't pass things "by reference" over the wire, so + "inout" is purely an illusion of the in-process API. + </para> + <para> + Given a method with zero or one return values, followed by zero or more + arguments, where each argument may be "in", "out", or "inout", the + caller constructs a message by appending each "in" or "inout" argument, + in order. "out" arguments are not represented in the caller's message. + </para> + <para> + 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. + </para> + </sect4> + + </sect3> + + <sect3 id="message-protocol-types-signal"> + <title>Signal Emission</title> + <para> + 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 + the fully-qualified name of the signal. + </para> + </sect3> + + <sect3 id="message-protocol-types-notation"> + <title>Notation in this document</title> + <para> + This document uses a simple pseudo-IDL to describe particular method + calls and signals. Here is an example of a method call: + <programlisting> + org.freedesktop.DBus.ActivateService (in STRING service_name, in UINT32 flags, + out UINT32 resultcode) + </programlisting> + 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. + </para> + <para> + In C++ that might end up looking like this: + <programlisting> + unsigned int org::freedesktop::DBus::ActivateService (const char *service_name, + unsigned int flags); + </programlisting> + or equally valid, the return value could be done as an argument: + <programlisting> + void org::freedesktop::DBus::ActivateService (const char *service_name, + unsigned int flags, + unsigned int *resultcode); + </programlisting> + 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. + </para> + <para> + Signals are written as follows: + <programlisting> + org.freedesktop.DBus.ServiceLost (STRING service_name) + </programlisting> + Signals don't specify "in" vs. "out" because only + a single direction is possible. + </para> + <para> + 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. + </para> + <para> + It isn't especially encouraged to use this lame pseudo-IDL in actual + API implementations; you might use the native notation for the + language you're using, or you might use COM or CORBA IDL, for example. + </para> + </sect3> </sect2> </sect1> @@ -730,6 +1018,13 @@ </figure> </para> </sect2> + <sect2 id="auth-states"> + <title>Authentication state diagrams</title> + + <para> + WRITEME + </para> + </sect2> <sect2 id="auth-mechanisms"> <title>Authentication mechanisms</title> <para> @@ -905,161 +1200,35 @@ </para> </sect1> - <sect1 id="message-conventions"> - <title>Message Conventions</title> - <para> - This section documents conventions that are not essential to D-BUS - functionality, but should generally be followed in order to simplify - programmer's lives. - </para> - <sect2 id="message-conventions-naming"> - <title>Message Naming</title> - <para> - Messages are normally named in the form - "org.freedesktop.Peer.Ping", which has three - distinct components: - <variablelist> - <varlistentry> - <term>Namespace e.g. <literal>org.freedesktop</literal></term> - <listitem> - <para> - Message names have a Java-style namespace: a reversed domain - name. The components of the domain are normally lowercase. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Package or object e.g. <literal>Peer</literal></term> - <listitem> - <para> - The next part of the message name can be thought of as the name - of a singleton object, or as the name of a package of related - messages. More than one dot-separated component might be used - here. (Note that D-BUS does not define any idea of object - instances or object references.) The package or object name is - capitalized LikeThis. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Method or operation e.g. <literal>Ping</literal></term> - <listitem> - <para> - The final part of the message name is the most specific, and - should be a verb indicating an operation to be performed on the - object. The method or operation name is capitalized LikeThis. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - <para> - A reply to a message conventionally has the same name as the message - being replied to. When following method call conventions (see <xref - linkend="message-conventions-method">), this convention is mandatory, - because a message with multiple possible replies can't be mapped - to method call semantics without special-case code. - </para> - </sect2> - <sect2 id="message-conventions-method"> - <title>Method Call Mapping</title> - <para> - Some implementations of D-BUS may present an API that translates object - method calls into D-BUS messages. This document does not specify in - detail how such an API should look or work. However, it does specify how - message-based protocols should be designed to be friendly to such an - API. - </para> - <para> - Remember that D-BUS does not have object references or object instances. - So when one application sends the message - <literal>org.freedesktop.Peer.Ping</literal>, it sends it to another - application, not to any kind of sub-portion of that application. - However, a convenience API used within the recipient application may - route all messages that start with - <literal>org.freedesktop.Peer</literal> to a particular object instance, - and may invoke the <literal>Ping()</literal> method on said instance in - order to handle the message. This is a convenience API based on - method calls. - </para> - <para> - A "method call" consists of a message and, optionally, a reply to that - message. The name of the "method" is the last component of the message, - for example, <literal>org.freedesktop.Peer.Ping</literal> would map to - the method <literal>Ping()</literal> on some object. - </para> - <para> - Arguments to a method may be considered "in" (processed by the - recipient of the message), or "out" (returned to the sender of the - message in the reply). "inout" arguments are both sent and received, - i.e. the caller passes in a value which is modified. An "inout" argument - is equivalent to an "in" argument, followed by an "out" argument. - </para> - <para> - Given a method with zero or one return values, followed by zero or more - arguments, where each argument may be "in", "out", or "inout", the - caller constructs a message by appending each "in" or "inout" argument, - in order. "out" arguments are not represented in the caller's message. - </para> - <para> - 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. - </para> - <para> - The standard reply message MUST have the same name as the message being - replied to, and MUST set the "rply" header field to the serial - number of the message being replied to. - </para> - <para> - If an error occurs, an error reply may be sent in place of the standard - reply. Error replies can be identified by a special header flag, see - <xref linkend="message-protocol-header-encoding">. Error replies have a - name which reflects the type of error that occurred. Error replies would - generally be mapped to exceptions in a programming language. If an - error reply has a first argument, and that argument has type STRING, - then the argument must be an error message. - </para> - <para> - [FIXME discuss mapping of broadcast messages + matching rules - to signals and slots] - </para> - </sect2> - </sect1> - <sect1 id="standard-messages"> <title>Standard Peer-to-Peer Messages</title> <para> - In the following message definitions, "method call notation" is presented - in addition to simply listing the message names and arguments. The special - type name ANY means any type other than NIL, and the special type name - ANY_OR_NIL means any valid type. - [FIXME the messages here are just made up to illustrate the - format for defining them] + See <xref linkend="message-protocol-types-notation"> for details on + the notation used in this section. </para> <sect2 id="standard-messages-ping"> <title><literal>org.freedesktop.Peer.Ping</literal></title> <para> - As a method: <programlisting> - void Ping () + org.freedesktop.Peer.Ping () </programlisting> </para> <para> - On receipt of the message <literal>org.freedesktop.Peer.Ping</literal>, - an application should reply with - <literal>org.freedesktop.Peer.Ping</literal>. Neither the - message nor its reply have any arguments. - [FIXME the messages here are just made up to illustrate the - format for defining them] + On receipt of the METHOD_CALL + message <literal>org.freedesktop.Peer.Ping</literal>, an application + should do nothing other than reply with a METHOD_RETURN as usual. </para> </sect2> + <sect2 id="standard-messages-get-props"> <title><literal>org.freedesktop.Props.Get</literal></title> <para> - As a method: + [FIXME this is just a bogus made-up method that isn't implemented + or thought through, to save an example of table formatting for the + argument descriptions] <programlisting> - ANY_OR_NIL Get (in STRING property_name) + org.freedesktop.Props.Get (in STRING property_name, + out ANY_OR_NIL property_value) </programlisting> Message arguments: <informaltable> @@ -1074,37 +1243,18 @@ <tbody> <row> <entry>0</entry> - <entry>STRING</entry> + <entry>in STRING</entry> <entry>Name of the property to get</entry> </row> - </tbody> - </tgroup> - </informaltable> - Reply arguments: - <informaltable> - <tgroup cols=3> - <thead> - <row> - <entry>Argument</entry> - <entry>Type</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> <row> - <entry>0</entry> - <entry>ANY_OR_NIL</entry> + <entry>1</entry> + <entry>out ANY_OR_NIL</entry> <entry>The value of the property. The type depends on the property.</entry> </row> </tbody> </tgroup> </informaltable> </para> - <para> - - [FIXME the messages here are just made up to illustrate the - format for defining them] - </para> </sect2> </sect1> @@ -1132,18 +1282,18 @@ the new owner of the service. </para> <para> - Messages may have a <literal>srvc</literal> field (see <xref + Messages may have a <literal>SERVICE</literal> field (see <xref linkend="message-protocol-header-fields">). When the message bus - receives a message, if the <literal>srvc</literal> field is absent, the + receives a message, if the <literal>SERVICE</literal> field is absent, the message is taken to be a standard peer-to-peer message and interpreted by the message bus itself. For example, sending an <literal>org.freedesktop.Peer.Ping</literal> message with no - <literal>srvc</literal> will cause the message bus itself to reply + <literal>SERVICE</literal> will cause the message bus itself to reply to the ping immediately; the message bus would never make this message visible to other applications. </para> <para> - If the <literal>srvc</literal> field is present, then it indicates a + If the <literal>SERVICE</literal> 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 <firstterm>broadcast</firstterm> @@ -1154,7 +1304,7 @@ </para> <para> Continuing the <literal>org.freedesktop.Peer.Ping</literal> example, if - the ping message were sent with a <literal>srvc</literal> name of + the ping message were sent with a <literal>SERVICE</literal> name of <literal>com.yoyodyne.Screensaver</literal>, then the ping would be forwarded, and the Yoyodyne Corporation screensaver application would be expected to reply to the ping. If @@ -1967,6 +2117,32 @@ </para> </glossdef> </glossentry> + + <glossentry id="term-object"><glossterm>Object</glossterm> + <glossdef> + <para> + Each application contains <firstterm>objects</firstterm>, + which have <firstterm>interfaces</firstterm> and + <firstterm>methods</firstterm>. Objects are referred to + by a name, called a <firstterm>path</firstterm> or + <firstterm>object reference</firstterm>. + </para> + </glossdef> + </glossentry> + + <glossentry id="term-path"><glossterm>Path</glossterm> + <glossdef> + <para> + Object references (object names) in D-BUS are + organized into a filesystem-style hierarchy, so + each object is named by a path. As in LDAP, + there's no difference between "files" and "directories"; + a path can refer to an object, while still having + child objects below it. + </para> + </glossdef> + </glossentry> + <glossentry id="peer-to-peer"><glossterm>Peer-to-peer</glossterm> <glossdef> <para> |