diff options
Diffstat (limited to 'doc/dbus-specification.xml')
| -rw-r--r-- | doc/dbus-specification.xml | 962 |
1 files changed, 459 insertions, 503 deletions
diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index f2c0146b..821c6011 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -96,6 +96,30 @@ monitoring service or a configuration service. </para> + <para> + D-BUS is designed for two specific use cases: + <itemizedlist> + <listitem> + <para> + A "system bus" for notifications from the system to user sessions, + and to allow the system to request input from user sessions. + </para> + </listitem> + <listitem> + <para> + A "session bus" used to implement desktop environments such as + GNOME and KDE. + </para> + </listitem> + </itemizedlist> + 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. D-BUS may turn out to be useful + in unanticipated applications, but future versions of this + spec and the reference implementation probably will not + incorporate features that interfere with the core use cases. + </para> + </sect1> <sect1 id="message-protocol"> @@ -733,10 +757,11 @@ to return the reply despite this flag.</entry> </row> <row> - <entry><literal>AUTO_ACTIVATION</literal></entry> + <entry><literal>AUTO_START</literal></entry> <entry>0x2</entry> - <entry>This message automatically activates the - addressed service before the message is delivered.</entry> + <entry>This message automatically launches an owner + for the destination name before the message is delivered. + </entry> </row> </tbody> </tgroup> @@ -841,7 +866,7 @@ <entry>6</entry> <entry><literal>STRING</literal></entry> <entry>optional</entry> - <entry>The name of the service this message should be routed to. + <entry>The name of the connection this message should be routed to. Only used in combination with the message bus, see <xref linkend="message-bus"/>.</entry> </row> @@ -850,8 +875,8 @@ <entry>7</entry> <entry><literal>STRING</literal></entry> <entry>optional</entry> - <entry>Sender service. The name of the base service that sent - this message. The message bus fills in this field; the field is + <entry>Unique name of the sending connection. + The message bus fills in this field so it is reliable; the field is only meaningful in combination with the message bus.</entry> </row> <row> @@ -877,8 +902,7 @@ </para> <para> There is a <firstterm>maximum name length</firstterm> - of 255 which applies to service, interface, and member - names. + of 255 which applies to bus names, interfaces, and members. </para> <sect3 id="message-protocol-names-interface"> <title>Interface names</title> @@ -907,15 +931,15 @@ </itemizedlist> </para> </sect3> - <sect3 id="message-protocol-names-service"> - <title>Service names</title> + <sect3 id="message-protocol-names-bus"> + <title>Bus names</title> <para> - Service names have the same restrictions as interface names, with a - special exception for base services. A base service name's first + Bus names have the same restrictions as interface names, with a + special exception for unique connection names. A unique name's first element must start with a colon (':') character. After the colon, any 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 + a digit. Bus names not starting with a colon have none of these exceptions and follow the same rules as interface names. </para> </sect3> @@ -966,10 +990,11 @@ implementations must not require an interface field. </para> <para> - Method call messages also include a <literal>PATH</literal> field indicating the - object to invoke the method on. If the call is passing through - a message bus, the message will also have a <literal>DESTINATION</literal> field giving - the service to receive the message. + Method call messages also include a <literal>PATH</literal> field + indicating the object to invoke the method on. If the call is passing + through a message bus, the message will also have a + <literal>DESTINATION</literal> field giving the name of the connection + to receive the message. </para> <para> When an application handles a method call message, it is expected to @@ -1002,14 +1027,13 @@ flag and reply anyway. </para> <para> - If a message has the flag <literal>AUTO_ACTIVATION</literal>, 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. 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. + If a message has the flag <literal>AUTO_START</literal> and the + destination name does not exist, then a program to own the destination + name will be started before the message is delivered. The message + will be held until the new program is successfully started or has + failed to start; in case of failure, an error will be returned. This + flag is only relevant in the context of a message bus, it is ignored + during one-to-one communication with no intermediate bus. </para> <sect4 id="message-protocol-types-method-apis"> <title>Mapping method calls to native APIs</title> @@ -1086,10 +1110,10 @@ 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) + org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags, + out UINT32 resultcode) </programlisting> - This means <literal>INTERFACE</literal> = org.freedesktop.DBus, <literal>MEMBER</literal> = ActivateService, + This means <literal>INTERFACE</literal> = org.freedesktop.DBus, <literal>MEMBER</literal> = StartServiceByName, <literal>METHOD_CALL</literal> arguments are <literal>STRING</literal> and <literal>UINT32</literal>, <literal>METHOD_RETURN</literal> argument is <literal>UINT32</literal>. Remember that the <literal>MEMBER</literal> field can't contain any '.' (period) characters so it's known that the last part of the name in @@ -1098,14 +1122,14 @@ <para> In C++ that might end up looking like this: <programlisting> - unsigned int org::freedesktop::DBus::ActivateService (const char *service_name, - unsigned int flags); + unsigned int org::freedesktop::DBus::StartServiceByName (const char *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); + void org::freedesktop::DBus::StartServiceByName (const char *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 @@ -1114,7 +1138,7 @@ <para> Signals are written as follows: <programlisting> - org.freedesktop.DBus.ServiceLost (STRING service_name) + org.freedesktop.DBus.NameLost (STRING name) </programlisting> Signals don't specify "in" vs. "out" because only a single direction is possible. @@ -1988,42 +2012,6 @@ </para> </sect2> - <sect2 id="standard-messages-get-props"> - <title><literal>org.freedesktop.Props.Get</literal></title> - <para> - [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> - org.freedesktop.Props.Get (in STRING property_name, - out ANY_OR_NIL property_value) - </programlisting> - Message arguments: - <informaltable> - <tgroup cols="3"> - <thead> - <row> - <entry>Argument</entry> - <entry>Type</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>0</entry> - <entry>in STRING</entry> - <entry>Name of the property to get</entry> - </row> - <row> - <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> - </sect2> </sect1> <sect1 id="message-bus"> @@ -2032,188 +2020,316 @@ <title>Message Bus Overview</title> <para> 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 one-to-one case. + Once connected, applications can exchange messages with other + applications that are also connected to the bus. </para> <para> - The message bus keeps track of a set of - <firstterm>services</firstterm>. A service is simply a name, such as - <literal>com.yoyodyne.Screensaver</literal>, which can be - <firstterm>owned</firstterm> by one or more of the connected - applications. The message bus itself always owns the special service - <literal>org.freedesktop.DBus</literal>. + In order to route messages among connections, the message bus keeps a + mapping from names to connections. Each connection has one + unique-for-the-lifetime-of-the-bus name automatically assigned. + Applications may request additional names for a connection. Additional + names are usually "well-known names" such as + "org.freedesktop.TextEditor". When a name is bound to a connection, + that connection is said to <firstterm>own</firstterm> the name. </para> <para> - Services may have <firstterm>secondary owners</firstterm>. Secondary owners - of a service are kept in a queue; if the primary owner of a service - disconnects, or releases the service, the next secondary owner becomes - the new owner of the service. + The bus itself owns a special name, <literal>org.freedesktop.DBus</literal>. + This name routes messages to the bus, allowing applications to make + administrative requests. For example, applications can ask the bus + to assign a name to a connection. </para> <para> + Each name may have <firstterm>queued owners</firstterm>. 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 + 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. + </para> + + <para> + This feature causes the right thing to happen if you start two text + editors for example; the first one may request "org.freedesktop.TextEditor", + and the second will be queued as a possible owner of that name. When + the first exits, the second will take over. + </para> + + <para> Messages may have a <literal>DESTINATION</literal> field (see <xref - linkend="message-protocol-header-fields"/>). When the message bus - receives a message, if the <literal>DESTINATION</literal> 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 <literal>org.freedesktop.Peer.Ping</literal> message with no - <literal>DESTINATION</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>DESTINATION</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> - by sending them to the special service - <literal>org.freedesktop.DBus.Broadcast</literal>. Broadcast messages are - sent to all applications with <firstterm>message matching - rules</firstterm> that match the message. + linkend="message-protocol-header-fields"/>). If the + <literal>DESTINATION</literal> field is present, it specifies a message + recipient by name. Method calls and replies normally specify this field. </para> + + <para> + Signals normally do not specify a destination; they are sent to all + applications with <firstterm>message matching rules</firstterm> that + match the message. + </para> + + <para> + When the message bus receives a method call, if the + <literal>DESTINATION</literal> 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 + <literal>org.freedesktop.Peer.Ping</literal> message with no + <literal>DESTINATION</literal> will cause the message bus itself to + reply to the ping immediately; the message bus will not make this + message visible to other applications. + </para> + <para> Continuing the <literal>org.freedesktop.Peer.Ping</literal> example, if the ping message were sent with a <literal>DESTINATION</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 - <literal>org.freedesktop.Peer.Ping</literal> were sent to - <literal>org.freedesktop.DBus.Broadcast</literal>, then multiple applications - might receive the ping, and all would normally reply to it. + expected to reply to the ping. </para> </sect2> - <sect2 id="message-bus-services"> - <title>Message Bus Services</title> + <sect2 id="message-bus-names"> + <title>Message Bus Names</title> <para> - A service is a name that identifies a certain application. Each - application connected to the message bus has at least one service name - assigned at connection time and returned in response to the - <literal>org.freedesktop.DBus.Hello</literal> message. - This automatically-assigned service name is called - the application's <firstterm>base service</firstterm>. - Base service names are unique and MUST never be reused for two different - applications. + Each connection has at least one name, assigned at connection time and + returned in response to the + <literal>org.freedesktop.DBus.Hello</literal> method call. This + automatically-assigned name is called the connection's <firstterm>unique + name</firstterm>. Unique names are never reused for two different + connections to the same bus. </para> <para> - Ownership of the base service is a prerequisite for interaction with - the message bus. It logically follows that the base service is always - the first service that an application comes to own, and the last - service that it loses ownership of. + 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. </para> <para> - Base service names must begin with the character ':' (ASCII colon - character); service names that are not base service names must not begin + Unique connection names must begin with the character ':' (ASCII colon + character); bus names that are not unique names must not begin with this character. (The bus must reject any attempt by an application - to manually create a service name beginning with ':'.) This restriction - categorically prevents "spoofing"; messages sent to a base service name - will always go to a single application instance and that instance only. - </para> - <para> - An application can request additional service names to be associated - with it using the - <literal>org.freedesktop.DBus.AcquireService</literal> - message. [FIXME what service names are allowed; ASCII or unicode; - length limit; etc.] - </para> - <para> - [FIXME this needs more detail, and should move the service-related message - descriptions up into this section perhaps] - Service ownership handling can be specified in the flags part - of the <literal>org.freedesktop.DBus.AcquireService</literal> - message. If an application specifies the - <literal>DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT</literal> 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 <literal>DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT</literal> - flag is not specified, then the primary owner will lose - ownership whenever another application requests ownership of the - service. - </para> - <para> - When a client disconnects from the bus, all the services that - the clients own are deleted, or in the case of a service that - prohibits replacement, ownership is transferred to the next - client in the queue, if any. + to manually request a name beginning with ':'.) This restriction + categorically prevents "spoofing"; messages sent to a unique name + will always go to the expected connection. </para> + <para> + When a connection is closed, all the names that it owns are deleted (or + transferred to the next connection in the queue if any). + </para> + <para> + A connection can request additional names to be associated with it using + the <literal>org.freedesktop.DBus.RequestName</literal> message. <xref + linkend="message-protocol-names-bus"/> describes the format of a valid + name. + </para> + + <sect3 id="bus-messages-request-name"> + <title><literal>org.freedesktop.DBus.RequestName</literal></title> + <para> + As a method: + <programlisting> + UINT32 RequestName (in STRING name, in UINT32 flags) + </programlisting> + Message arguments: + <informaltable> + <tgroup cols="3"> + <thead> + <row> + <entry>Argument</entry> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>0</entry> + <entry>STRING</entry> + <entry>Name to request</entry> + </row> + <row> + <entry>1</entry> + <entry>UINT32</entry> + <entry>Flags</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>UINT32</entry> + <entry>Return value</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + <para> + This method call should be sent to + <literal>org.freedesktop.DBus</literal> and asks the message bus to + assign the given name to the method caller. The flags argument + contains any of the following values logically ORed together: + + <informaltable> + <tgroup cols="3"> + <thead> + <row> + <entry>Conventional Name</entry> + <entry>Value</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT</entry> + <entry>0x1</entry> + <entry> + If the application succeeds in becoming the owner of the specified name, + then ownership of the name can't be transferred until the application + disconnects. If this flag is not set, then any application trying to become + the owner of the name will succeed and the previous owner will be + sent a <literal>org.freedesktop.DBus.NameOwnerChanged</literal> signal. + </entry> + </row> + <row> + <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry> + <entry>0x2</entry> + <entry> + Try to replace the current owner if there is one. If this + flag is not set the application will only become the owner of + the name if there is no current owner. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + + The return code can be one of the following values: + + <informaltable> + <tgroup cols="3"> + <thead> + <row> + <entry>Conventional Name</entry> + <entry>Value</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry> + <entry>1</entry> <entry>The caller is now the primary owner of + the name, replacing any previous owner. Either the name had no + owner before, or the caller specified + DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner did not + specify DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.</entry> + </row> + <row> + <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry> + <entry>2</entry> + <entry>The name already had an owner, DBUS_NAME_FLAG_REPLACE_EXISTING was not specified, and the current owner specified DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.</entry> + </row> + <row> + <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry> + <entry>3</entry> + <entry>The name already has an owner, and DBUS_NAME_FLAG_REPLACE_EXISTING was not specified.</entry> + </row> + <row> + <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry> + <entry>4</entry> + <entry>The application trying to request ownership of a name is already the owner of it.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </sect3> </sect2> + <sect2 id="message-bus-routing"> <title>Message Bus Message Routing</title> <para> - When a message is received by the message bus, the message's - <literal>sndr</literal> header field MUST be set to the base service of - the application which sent the message. If the service already has - a <literal>sndr</literal> field, the pre-existing field is replaced. - This rule means that a replies are always sent to the base service name, - i.e. to the same application that sent the message being replied to. + FIXME </para> + </sect2> + <sect2 id="message-bus-starting-services"> + <title>Message Bus Starting Services</title> <para> - [FIXME go into detail about broadcast, multicast, unicast, etc.] + The message bus can start applications on behalf of other applications. + In CORBA terms, this would be called <firstterm>activation</firstterm>. + An application that can be started in this way is called a + <firstterm>service</firstterm>. </para> - </sect2> - <sect2 id="message-bus-activation"> - <title>Message Bus Service Activation</title> <para> - <firstterm>Activation</firstterm> means to locate a service - owner for a service that is currently unowned. For now, it - means to launch an executable that will take ownership of - a particular service. + With D-BUS, starting a service is normally done by name. That is, + applications ask the message bus to start some program that will own a + well-known name, such as <literal>org.freedesktop.TextEditor</literal>. + This implies a contract documented along with the name + <literal>org.freedesktop.TextEditor</literal> for which objects + the owner of that name will provide, and what interfaces those + objects will have. </para> <para> - To find an executable corresponding to a particular service, the bus - daemon looks for <firstterm>service description files</firstterm>. - Service description files define a mapping from service names to - executables. Different kinds of message bus will look for these files - in different places, see <xref linkend="message-bus-types"/>. + To find an executable corresponding to a particular name, the bus daemon + looks for <firstterm>service description files</firstterm>. Service + description files define a mapping from names to executables. Different + kinds of message bus will look for these files in different places, see + <xref linkend="message-bus-types"/>. </para> <para> - [FIXME the file format should be much better specified than - "similar to .desktop entries" esp. since desktop entries are - already badly-specified. ;-)] Service description files have - the ".service" file extension. The message bus will only load - service description files ending with .service; all other - files will be ignored. The file format is similar to that of - <ulink + [FIXME the file format should be much better specified than "similar to + .desktop entries" esp. since desktop entries are already + badly-specified. ;-)] Service description files have the ".service" file + extension. The message bus will only load service description files + ending with .service; all other files will be ignored. The file format + is similar to that of <ulink url="http://www.freedesktop.org/standards/desktop-entry-spec/desktop-entry-spec.html">desktop - entries</ulink>. All service description files must be in - UTF-8 encoding. To ensure that there will be no name - collisions, service files must be namespaced using the same - mechanism as messages and service names. + entries</ulink>. All service description files must be in UTF-8 + encoding. To ensure that there will be no name collisions, service files + must be namespaced using the same mechanism as messages and service + names. <figure> <title>Example service description file</title> <programlisting> # Sample service description file [D-BUS Service] - Name=org.gnome.ConfigurationDatabase + Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf; Exec=/usr/libexec/gconfd-2 </programlisting> </figure> </para> <para> - When an application requests a service to be activated, the - bus daemon tries to find it in the list of activation - entries. It then tries to spawn the executable associated with - it. If this fails, it will report an error. [FIXME what - happens if two .service files offer the same service; what - kind of error is reported, should we have a way for the client - to choose one?] + When an application asks to start a service by name, the bus daemon tries to + find a service that will own that name. It then tries to spawn the + executable associated with it. If this fails, it will report an + error. [FIXME what happens if two .service files offer the same service; + what kind of error is reported, should we have a way for the client to + choose one?] </para> <para> The executable launched will have the environment variable - <literal>DBUS_ACTIVATION_ADDRESS</literal> set to the address of the - message bus so it can connect and register the appropriate services. + <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the + message bus so it can connect and request the appropriate names. </para> <para> The executable being launched may want to know whether the message bus - activating it is one of the well-known message buses (see <xref + starting it is one of the well-known message buses (see <xref linkend="message-bus-types"/>). To facilitate this, the bus MUST also set - the <literal>DBUS_ACTIVATION_BUS_TYPE</literal> environment variable if it is one + the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one of the well-known buses. The currently-defined values for this variable are <literal>system</literal> for the systemwide message bus, and <literal>session</literal> for the per-login-session message - bus. The activated executable must still connect to the address given - in <literal>DBUS_ACTIVATION_ADDRESS</literal>, but may assume that the + bus. The new executable must still connect to the address given + in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the resulting connection is to the well-known bus. </para> <para> @@ -2262,7 +2378,7 @@ changes in the printer queue, and so forth. </para> <para> - The address of the login session message bus is given + The address of the system message bus is given in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment variable. If that variable is not set, applications should try to connect to the well-known address @@ -2284,9 +2400,8 @@ <sect2 id="message-bus-messages"> <title>Message Bus Messages</title> <para> - The special message bus service <literal>org.freedesktop.DBus</literal> - responds to a number of messages, allowing applications to - interact with the message bus. + The special message bus name <literal>org.freedesktop.DBus</literal> + responds to a number of additional messages. </para> <sect3 id="bus-messages-hello"> @@ -2310,34 +2425,33 @@ <row> <entry>0</entry> <entry>STRING</entry> - <entry>Name of the service assigned to the application</entry> + <entry>Unique name assigned to the connection</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> - Before an application is able to send messages to other - applications it must send the - <literal>org.freedesktop.DBus.Hello</literal> message to the - message bus service. If an application tries to send a - message to another application, or a message to the message - bus service that isn't the - <literal>org.freedesktop.DBus.Hello</literal> message, it - will be disconnected from the bus. If a client wishes to - disconnect from the bus, it just has to disconnect from the - transport used. No de-registration message is necessary. + Before an application is able to send messages to other applications + it must send the <literal>org.freedesktop.DBus.Hello</literal> message + to the message bus to obtain a unique name. If an application without + a unique name tries to send a message to another application, or a + message to the message bus itself that isn't the + <literal>org.freedesktop.DBus.Hello</literal> message, it will be + disconnected from the bus. </para> <para> - The reply message contains the name of the application's base service. + There is no corresponding "disconnect" request; if a client wishes to + disconnect from the bus, it simply closes the socket (or other + communication channel). </para> </sect3> - <sect3 id="bus-messages-list-services"> - <title><literal>org.freedesktop.DBus.ListServices</literal></title> + <sect3 id="bus-messages-list-names"> + <title><literal>org.freedesktop.DBus.ListNames</literal></title> <para> As a method: <programlisting> - STRING_ARRAY ListServices () + ARRAY of STRING ListNames () </programlisting> Reply arguments: <informaltable> @@ -2352,23 +2466,23 @@ <tbody> <row> <entry>0</entry> - <entry>STRING_ARRAY</entry> - <entry>Array of strings where each string is the name of a service</entry> + <entry>ARRAY of STRING</entry> + <entry>Array of strings where each string is a bus name</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> - Returns a list of all existing services registered with the message bus. + Returns a list of all currently-owned names on the bus. </para> </sect3> - <sect3 id="bus-messages-service-exists"> - <title><literal>org.freedesktop.DBus.ServiceExists</literal></title> + <sect3 id="bus-messages-name-exists"> + <title><literal>org.freedesktop.DBus.NameHasOwner</literal></title> <para> As a method: <programlisting> - BOOLEAN ServiceExists (in STRING service_name) + BOOLEAN NameHasOwner (in STRING name) </programlisting> Message arguments: <informaltable> @@ -2384,7 +2498,7 @@ <row> <entry>0</entry> <entry>STRING</entry> - <entry>Name of the service</entry> + <entry>Name to check</entry> </row> </tbody> </tgroup> @@ -2403,23 +2517,23 @@ <row> <entry>0</entry> <entry>BOOLEAN</entry> - <entry>Return value, true if the service exists</entry> + <entry>Return value, true if the name exists</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> - Checks if a service with a specified name exists. + Checks if the specified name exists (currently has an owner). </para> </sect3> - <sect3 id="bus-messages-acquire-service"> - <title><literal>org.freedesktop.DBus.AcquireService</literal></title> + <sect3 id="bus-messages-name-owner-changed"> + <title><literal>org.freedesktop.DBus.NameOwnerChanged</literal></title> <para> - As a method: + This is a signal: <programlisting> - UINT32 AcquireService (in STRING service_name) + NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner) </programlisting> Message arguments: <informaltable> @@ -2435,154 +2549,34 @@ <row> <entry>0</entry> <entry>STRING</entry> - <entry>Name of the service</entry> + <entry>Name with a new owner</entry> </row> <row> <entry>1</entry> - <entry>UINT32</entry> - <entry>Flags</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>UINT32</entry> - <entry>Return value</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - <para> - Tries to become owner of a specific service. The flags - specified can be the following values logically ORed together: - - <informaltable> - <tgroup cols="3"> - <thead> - <row> - <entry>Identifier</entry> - <entry>Value</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT</entry> - <entry>0x1</entry> - <entry> - If the application succeeds in being the owner of the specified service, - then ownership of the service can't be transferred until the service - disconnects. If this flag is not set, then any application trying to become - the owner of the service will succeed and the previous owner will be - sent a <literal>org.freedesktop.DBus.ServiceLost</literal> message. - </entry> - </row> - <row> - <entry>DBUS_SERVICE_FLAGS_REPLACE_EXISTING</entry> - <entry>0x2</entry> - <entry>Try to replace the current owner if there is one. If this flag - is not set the application will only become the owner of the service if - there is no current owner.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - [FIXME if it's one of the following values, why are the values - done as flags instead of just 0, 1, 2, 3, 4] - The return value can be one of the following values: - - <informaltable> - <tgroup cols="3"> - <thead> - <row> - <entry>Identifier</entry> - <entry>Value</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>DBUS_SERVICE_REPLY_PRIMARY_OWNER</entry> - <entry>0x1</entry> - <entry>The application is now the primary owner of the service.</entry> - </row> - <row> - <entry>DBUS_SERVICE_REPLY_IN_QUEUE</entry> - <entry>0x2</entry> - <entry>The service already has an owner which do not want to give up ownership and therefore the application has been put in a queue.</entry> - </row> - <row> - <entry>DBUS_SERVICE_REPLY_SERVICE_EXISTS</entry> - <entry>0x4</entry> - <entry>The service does already have a primary owner, and DBUS_SERVICE_FLAG_REPLACE_EXISTING was not specified when trying to acquire the service.</entry> - </row> - <row> - <entry>DBUS_SERVICE_REPLY_ALREADY_OWNER</entry> - <entry>0x8</entry> - <entry>The application trying to request ownership of the service is already the owner of it.</entry> + <entry>STRING</entry> + <entry>Old owner or empty string if none</entry> </row> - </tbody> - </tgroup> - </informaltable> - </para> - </sect3> - <sect3 id="bus-messages-service-acquired"> - <title><literal>org.freedesktop.DBus.ServiceAcquired</literal></title> - <para> - As a method: - <programlisting> - ServiceAcquired (in STRING service_name) - </programlisting> - Message arguments: - <informaltable> - <tgroup cols="3"> - <thead> - <row> - <entry>Argument</entry> - <entry>Type</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>0</entry> - <entry>STRING</entry> - <entry>Name of the service</entry> - </row> <row> - <entry>1</entry> - <entry>UINT32</entry> - <entry>Flags</entry> + <entry>2</entry> + <entry>STRING</entry> + <entry>New owner or empty string if none</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> - This message is sent to a specific application when it becomes the - primary owner of a service. + This signal indicates that the owner of a name has changed. + It's also the signal to use to detect the appearance of + new names on the bus. </para> </sect3> - <sect3 id="bus-messages-service-lost"> - <title><literal>org.freedesktop.DBus.ServiceLost</literal></title> + <sect3 id="bus-messages-name-lost"> + <title><literal>org.freedesktop.DBus.NameLost</literal></title> <para> - As a method: + This is a signal: <programlisting> - ServiceLost (in STRING service_name) + NameLost (STRING name) </programlisting> Message arguments: <informaltable> @@ -2598,28 +2592,24 @@ <row> <entry>0</entry> <entry>STRING</entry> - <entry>Name of the service</entry> + <entry>Name which was lost</entry> </row> - <row> - <entry>1</entry> - <entry>UINT32</entry> - <entry>Flags</entry> - </row> </tbody> </tgroup> </informaltable> </para> <para> - This message is sent to a specific application when it loses primary - ownership of a service. + This signal is sent to a specific application when it loses + ownership of a name. </para> </sect3> - <sect3 id="bus-messages-service-owner-changed"> - <title><literal>org.freedesktop.DBus.ServiceOwnerChanged</literal></title> + <sect3 id="bus-messages-name-acquired"> + <title><literal>org.freedesktop.DBus.NameAcquired</literal></title> <para> + This is a signal: <programlisting> - ServiceOwnerChanged (STRING service_name, STRING old_owner, STRING new_owner) + NameAcquired (STRING name) </programlisting> Message arguments: <informaltable> @@ -2635,37 +2625,24 @@ <row> <entry>0</entry> <entry>STRING</entry> - <entry>Name of the service</entry> + <entry>Name which was acquired</entry> </row> - <row> - <entry>1</entry> - <entry>STRING</entry> - <entry>Base service of previous owner, empty string if the - service is newly created</entry> - </row> - <row> - <entry>2</entry> - <entry>STRING</entry> - <entry>Base service of new owner, empty string if the - service is no longer available</entry> - </row> </tbody> </tgroup> </informaltable> </para> <para> - This message is broadcast to all applications when a service has been - successfully registered on the message bus, has been deleted - or its primary owner has changed. + This signal is sent to a specific application when it gains + ownership of a name. </para> </sect3> - <sect3 id="bus-messages-activate-service"> - <title><literal>org.freedesktop.DBus.ActivateService</literal></title> + <sect3 id="bus-messages-start-service-by-name"> + <title><literal>org.freedesktop.DBus.StartServiceByName</literal></title> <para> As a method: <programlisting> - UINT32 ActivateService (in STRING service_name, in UINT32 flags) + UINT32 StartServiceByName (in STRING name, in UINT32 flags) </programlisting> Message arguments: <informaltable> @@ -2681,7 +2658,7 @@ <row> <entry>0</entry> <entry>STRING</entry> - <entry>Name of the service to activate</entry> + <entry>Name of the service to start</entry> </row> <row> <entry>1</entry> @@ -2710,15 +2687,12 @@ </tbody> </tgroup> </informaltable> - Tries to launch the executable associated with a service. For more information, see <xref linkend="message-bus-activation"/>. + Tries to launch the executable associated with a name. For more information, see <xref linkend="message-bus-starting-services"/>. - [FIXME need semantics in much more detail here; for example, - if I activate a service then send it a message, is the message - queued for the new service or is there a race] </para> <para> The return value can be one of the following values: - <informaltable> + <informaltable> <tgroup cols="3"> <thead> <row> @@ -2729,14 +2703,14 @@ </thead> <tbody> <row> - <entry>DBUS_ACTIVATION_REPLY_ACTIVATED</entry> - <entry>0x0</entry> - <entry>The service was activated successfully.</entry> + <entry>DBUS_START_REPLY_SUCCESS</entry> + <entry>1</entry> + <entry>The service was successfully started.</entry> </row> <row> - <entry>DBUS_ACTIVATION_REPLY_ALREADY_ACTIVE</entry> - <entry>0x1</entry> - <entry>The service is already active.</entry> + <entry>DBUS_START_REPLY_ALREADY_RUNNING</entry> + <entry>2</entry> + <entry>A connection already owns the given name.</entry> </row> </tbody> </tgroup> @@ -2745,12 +2719,12 @@ </sect3> - <sect3 id="bus-messages-get-service-owner"> - <title><literal>org.freedesktop.DBus.GetServiceOwner</literal></title> + <sect3 id="bus-messages-get-name-owner"> + <title><literal>org.freedesktop.DBus.GetNameOwner</literal></title> <para> As a method: <programlisting> - STRING GetServiceOwner (in STRING service_name) + STRING GetNameOwner (in STRING name) </programlisting> Message arguments: <informaltable> @@ -2766,7 +2740,7 @@ <row> <entry>0</entry> <entry>STRING</entry> - <entry>Name of the service to query</entry> + <entry>Name to get the owner of</entry> </row> </tbody> </tgroup> @@ -2785,15 +2759,14 @@ <row> <entry>0</entry> <entry>STRING</entry> - <entry>Return value, a base service name</entry> + <entry>Return value, a unique connection name</entry> </row> </tbody> </tgroup> </informaltable> - Returns the base service name of the primary owner of the - service in argument. If the requested service isn't active, - returns a - <literal>org.freedesktop.DBus.Error.ServiceHasNoOwner</literal> error. + Returns the unique connection name of the primary owner of the name + given. If the requested name doesn't have an owner, returns a + <literal>org.freedesktop.DBus.Error.NameHasNoOwner</literal> error. </para> </sect3> @@ -2818,7 +2791,7 @@ <row> <entry>0</entry> <entry>STRING</entry> - <entry>Name of the connection/service to query</entry> + <entry>Name of the connection to query</entry> </row> </tbody> </tgroup> @@ -2848,31 +2821,6 @@ </para> </sect3> - <sect3 id="bus-messages-out-of-memory"> - <title><literal>org.freedesktop.DBus.Error.NoMemory</literal></title> - <para> - As a method: - <programlisting> - void NoMemory () - </programlisting> - </para> - <para> - Sent by the message bus when it can't process a message due to an out of memory failure. - </para> - </sect3> - - <sect3 id="bus-messages-service-does-not-exist"> - <title><literal>org.freedesktop.DBus.Error.ServiceDoesNotExist</literal></title> - <para> - As a method: - <programlisting> - void ServiceDoesNotExist (in STRING error) - </programlisting> - </para> - <para> - Sent by the message bus as a reply to a client that tried to send a message to a service that doesn't exist. - </para> - </sect3> </sect2> </sect1> @@ -2892,32 +2840,22 @@ This glossary defines some of the terms used in this specification. </para> - <glossentry id="term-activation"><glossterm>Activation</glossterm> + <glossentry id="term-bus-name"><glossterm>Bus Name</glossterm> <glossdef> <para> - The process of creating an owner for a particular service, - typically by launching an executable. - </para> - </glossdef> - </glossentry> - - <glossentry id="term-base-service"><glossterm>Base Service</glossterm> - <glossdef> - <para> - The special service automatically assigned to an application by the - message bus. This service may never change owner, and the service - name will be unique (never reused during the lifetime of the - message bus). - </para> - </glossdef> - </glossentry> - - <glossentry id="term-broadcast"><glossterm>Broadcast</glossterm> - <glossdef> - <para> - A message sent to the special <literal>org.freedesktop.DBus.Broadcast</literal> - service; the message bus will forward the broadcast message - to all applications that have expressed interest in it. + The message bus maintains an association between names and + connections. (Normally, there's one connection per application.) A + bus name is simply an identifier used to locate connections. For + example, the hypothetical <literal>com.yoyodyne.Screensaver</literal> + name might be used to send a message to a screensaver from Yoyodyne + Corporation. An application is said to <firstterm>own</firstterm> a + name if the message bus has associated the application's connection + with the name. Names may also have <firstterm>queued + owners</firstterm> (see <xref linkend="term-queued-owner"/>). + The bus assigns a unique name to each connection, + see <xref linkend="term-unique-name"/>. Other names + can be thought of as "well-known names" and are + used to find applications that offer specific functionality. </para> </glossdef> </glossentry> @@ -2937,9 +2875,20 @@ <glossdef> <para> The message bus is a special application that forwards - or broadcasts messages between a group of applications + or routes messages between a group of applications connected to the message bus. It also manages - <firstterm>services</firstterm>. + <firstterm>names</firstterm> used for routing + messages. + </para> + </glossdef> + </glossentry> + + <glossentry id="term-name"><glossterm>Name</glossterm> + <glossdef> + <para> + See <xref linkend="term-bus-name"/>. "Name" may + also be used to refer to some of the other names + in D-BUS, such as interface names. </para> </glossdef> </glossentry> @@ -2947,9 +2896,9 @@ <glossentry id="namespace"><glossterm>Namespace</glossterm> <glossdef> <para> - Used to prevent collisions when defining message and service - names. The convention used is the same as Java uses for - defining classes: a reversed domain name. + Used to prevent collisions when defining new interfaces or bus + names. The convention used is the same one Java uses for defining + classes: a reversed domain name. </para> </glossdef> </glossentry> @@ -2957,73 +2906,80 @@ <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>. + 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>. </para> </glossdef> </glossentry> - <glossentry id="term-path"><glossterm>Path</glossterm> + <glossentry id="one-to-one"><glossterm>One-to-One</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> + An application talking directly to another application, without going + through a message bus. One-to-one connections may be "peer to peer" or + "client to server." The D-BUS protocol has no concept of client + vs. server after a connection has authenticated; the flow of messages + is symmetrical (full duplex). </para> </glossdef> </glossentry> - <glossentry id="one-to-one"><glossterm>One-to-One</glossterm> + <glossentry id="term-path"><glossterm>Path</glossterm> <glossdef> - <para> - An application talking directly to another application, without going through a message bus. + <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="term-secondary-owner"><glossterm>Secondary service owner</glossterm> + + <glossentry id="term-queued-owner"><glossterm>Queued Name Owner</glossterm> <glossdef> <para> - Each service has a primary owner; messages sent to the service name - go to the primary owner. However, certain services also maintain - a queue of secondary owners "waiting in the wings." If - the primary owner releases the service, then the first secondary - owner in the queue automatically becomes the primary owner. + Each bus name has a primary owner; messages sent to the name go to the + primary owner. However, certain names also maintain a queue of + secondary owners "waiting in the wings." If the primary owner releases + the name, then the first secondary owner in the queue automatically + becomes the new owner of the name. </para> </glossdef> </glossentry> + <glossentry id="term-service"><glossterm>Service</glossterm> <glossdef> <para> - A service is simply a named list of applications. For example, the - hypothetical <literal>com.yoyodyne.Screensaver</literal> service might - accept messages that affect a screensaver from Yoyodyne Corporation. - An application is said to <firstterm>own</firstterm> a service if the - message bus has associated the application with the service name. - Services may also have <firstterm>secondary owners</firstterm> (see - <xref linkend="term-secondary-owner"/>). + A service is an executable that can be launched by the bus daemon. + Services normally guarantee some particular features, for example they + may guarantee that they will request a specific name such as + "org.freedesktop.Screensaver", have a singleton object + "/org/freedesktop/Application", and that object will implement the + interface "org.freedesktop.ScreensaverControl". </para> </glossdef> </glossentry> - <glossentry id="term-service-name"><glossterm>Service name</glossterm> + + <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm> <glossdef> - <para> - The name used when referring to a service. If the service is - a base service it has a unique service name, for example - ":1-20", and otherwise it should be namespaced. + <para> + ".service files" tell the bus about service applications that can be + launched (see <xref linkend="term-service"/>). Most importantly they + provide a mapping from bus names to services that will request those + names when they start up. </para> </glossdef> </glossentry> - <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm> + + <glossentry id="term-unique-name"><glossterm>Unique Connection Name</glossterm> <glossdef> <para> - ".service files" tell the bus how to activate a particular service. - See <xref linkend="term-activation"/> + The special name automatically assigned to each connection by the + message bus. This name will never change owner, and will be unique + (never reused during the lifetime of the message bus). + It will begin with a ':' character. </para> </glossdef> </glossentry> |