From 8873c90f99303f9cc308f15f8d03e637911f5b9e Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Tue, 18 Jan 2005 20:42:15 +0000 Subject: 2005-01-18 Havoc Pennington * Throughout, grand renaming to strip out the use of "service", just say "name" instead (or "bus name" when ambiguous). Did not change the internal code of the message bus itself, only the programmer-facing API and messages. * doc/dbus-specification.xml: further update the message bus section * bus/config-parser.c (all_are_equiv): fix bug using freed string in error case --- doc/TODO | 16 +- doc/dbus-specification.xml | 962 +++++++++++++++++++++------------------------ doc/dbus-tutorial.xml | 90 ++--- doc/diagram.png | Bin 0 -> 78762 bytes doc/diagram.svg | 590 +++++++++++++++++++++++++++ 5 files changed, 1104 insertions(+), 554 deletions(-) create mode 100644 doc/diagram.png create mode 100644 doc/diagram.svg (limited to 'doc') diff --git a/doc/TODO b/doc/TODO index c688583e..eac3e50b 100644 --- a/doc/TODO +++ b/doc/TODO @@ -1,5 +1,7 @@ Important for 1.0 === + + - change .service files to have Names=list rather than Name=string - How we will handle DCOP needs sorting out. Among other things, we need to check that service and service-ownership semantics map to DCOP @@ -38,18 +40,14 @@ Important for 1.0 (though they are kind of a pita to pass in as size_t with the varargs, so maybe not - what does glib do with g_object_get()?) - - rename the service thing. unique service names (":1") and well-known - ("org.foo.bar") should have different names probably; something like - "address" for the unique and "alias" for the well-known, or - "application id" for the unique and "common name" or "published - name" for the well-known; not sure yet. - - things are broken now when mixing endianness, because DBusMessage doesn't autoswap itself when you access a message of alternate endian. - add string array support back to append_args() + - auto-activate by default + Important for 1.0 GLib Bindings === @@ -71,6 +69,8 @@ Important for 1.0 GLib Bindings so it can figure out how to invoke the callback, or we have to rely on having introspection data. + - DBusGProxy doesn't emit "destroy" when it should + Might as Well for 1.0 === @@ -90,6 +90,10 @@ Might as Well for 1.0 Can Be Post 1.0 === + - The message bus internal code still says "service" for + "name", "base service" for "unique name", "activate" for + "start"; would be nice to clean up. + - Property list feature on message bus (list of properties associated with a connection). May also include message matching rules that involve the properties of the source or destination 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. + + D-BUS is designed for two specific use cases: + + + + A "system bus" for notifications from the system to user sessions, + and to allow the system to request input from user sessions. + + + + + 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 + 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. + + @@ -733,10 +757,11 @@ to return the reply despite this flag. - AUTO_ACTIVATION + AUTO_START 0x2 - This message automatically activates the - addressed service before the message is delivered. + This message automatically launches an owner + for the destination name before the message is delivered. + @@ -841,7 +866,7 @@ 6 STRING optional - The name of the service this message should be routed to. + The name of the connection this message should be routed to. Only used in combination with the message bus, see . @@ -850,8 +875,8 @@ 7 STRING optional - Sender service. The name of the base service that sent - this message. The message bus fills in this field; the field is + 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. @@ -877,8 +902,7 @@ There is a maximum name length - of 255 which applies to service, interface, and member - names. + of 255 which applies to bus names, interfaces, and members. Interface names @@ -907,15 +931,15 @@ - - Service names + + Bus names - 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. @@ -966,10 +990,11 @@ implementations must not require an interface field. - 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 DESTINATION field giving - the service to receive the message. + 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 + DESTINATION field giving the name of the connection + to receive the message. When an application handles a method call message, it is expected to @@ -1002,14 +1027,13 @@ flag and reply anyway. - If a message has the flag AUTO_ACTIVATION, then the addressed - service will be activated before the message is delivered, if - not already active. The message will be held until the service - is successfully activated or has failed to activate; in case - of failure, an activation error will be returned. 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 AUTO_START 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. Mapping method calls to native APIs @@ -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: - 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) - This means INTERFACE = org.freedesktop.DBus, MEMBER = ActivateService, + 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 @@ -1098,14 +1122,14 @@ In C++ that might end up looking like this: - 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); or equally valid, the return value could be done as an argument: - 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); 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 @@ Signals are written as follows: - org.freedesktop.DBus.ServiceLost (STRING service_name) + org.freedesktop.DBus.NameLost (STRING name) Signals don't specify "in" vs. "out" because only a single direction is possible. @@ -1988,42 +2012,6 @@ - - <literal>org.freedesktop.Props.Get</literal> - - [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] - - org.freedesktop.Props.Get (in STRING property_name, - out ANY_OR_NIL property_value) - - Message arguments: - - - - - Argument - Type - Description - - - - - 0 - in STRING - Name of the property to get - - - 1 - out ANY_OR_NIL - The value of the property. The type depends on the property. - - - - - - @@ -2032,188 +2020,316 @@ Message Bus Overview 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. - The message bus keeps track of a set of - services. A service is simply a name, such as - com.yoyodyne.Screensaver, which can be - owned by one or more of the connected - applications. The message bus itself always owns the special service - org.freedesktop.DBus. + 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 own the name. - Services may have secondary owners. 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, org.freedesktop.DBus. + 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. + + 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 + 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. + + + + 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. + + Messages may have a DESTINATION field (see ). When the message bus - receives a message, if the DESTINATION field is absent, the - message is taken to be a standard one-to-one message and interpreted - by the message bus itself. For example, sending - an org.freedesktop.Peer.Ping message with no - DESTINATION will cause the message bus itself to reply - to the ping immediately; the message bus would never make - this message visible to other applications. - - - If the DESTINATION field is present, then it indicates a - request for the message bus to route the message. In the usual case, - messages are routed to the owner of the named service. - Messages may also be broadcast - by sending them to the special service - org.freedesktop.DBus.Broadcast. Broadcast messages are - sent to all applications with message matching - rules that match the message. + linkend="message-protocol-header-fields"/>). If the + DESTINATION field is present, it specifies a message + recipient by name. Method calls and replies normally specify this field. + + + 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.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.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. If - org.freedesktop.Peer.Ping were sent to - org.freedesktop.DBus.Broadcast, then multiple applications - might receive the ping, and all would normally reply to it. + expected to reply to the ping. - - Message Bus Services + + Message Bus Names - 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 - org.freedesktop.DBus.Hello message. - This automatically-assigned service name is called - the application's base service. - 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 + org.freedesktop.DBus.Hello method call. This + automatically-assigned name is called the connection's unique + name. Unique names are never reused for two different + connections to the same bus. - 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. - 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. - - - An application can request additional service names to be associated - with it using the - org.freedesktop.DBus.AcquireService - message. [FIXME what service names are allowed; ASCII or unicode; - length limit; etc.] - - - [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 org.freedesktop.DBus.AcquireService - message. If an application specifies the - DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT flag, then all applications - trying to acquire the service will be put in a queue. When the - primary owner disconnects from the bus or removes ownership - from the service, the next application in the queue will be the - primary owner. If the DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT - flag is not specified, then the primary owner will lose - ownership whenever another application requests ownership of the - service. - - - 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. + + When a connection is closed, all the names that it owns are deleted (or + transferred to the next connection in the queue if any). + + + A connection can request additional names to be associated with it using + the org.freedesktop.DBus.RequestName message. describes the format of a valid + name. + + + + <literal>org.freedesktop.DBus.RequestName</literal> + + As a method: + + UINT32 RequestName (in STRING name, in UINT32 flags) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name to request + + + 1 + UINT32 + Flags + + + + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + UINT32 + Return value + + + + + + + This method call should be sent to + org.freedesktop.DBus 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: + + + + + + Conventional Name + Value + Description + + + + + DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT + 0x1 + + 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 org.freedesktop.DBus.NameOwnerChanged signal. + + + + DBUS_NAME_FLAG_REPLACE_EXISTING + 0x2 + + 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. + + + + + + + The return code can be one of the following values: + + + + + + Conventional Name + Value + Description + + + + + DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER + 1 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. + + + DBUS_REQUEST_NAME_REPLY_IN_QUEUE + 2 + The name already had an owner, DBUS_NAME_FLAG_REPLACE_EXISTING was not specified, and the current owner specified DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT. + + + DBUS_REQUEST_NAME_REPLY_EXISTS + 3 + The name already has an owner, and DBUS_NAME_FLAG_REPLACE_EXISTING was not specified. + + + DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER + 4 + The application trying to request ownership of a name is already the owner of it. + + + + + + + Message Bus Message Routing - When a message is received by the message bus, the message's - sndr header field MUST be set to the base service of - the application which sent the message. If the service already has - a sndr 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 + + + Message Bus Starting Services - [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 activation. + An application that can be started in this way is called a + service. - - - Message Bus Service Activation - Activation 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 org.freedesktop.TextEditor. + This implies a contract documented along with the name + org.freedesktop.TextEditor for which objects + the owner of that name will provide, and what interfaces those + objects will have. - To find an executable corresponding to a particular service, the bus - daemon looks for service description files. - 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 . + To find an executable corresponding to a particular name, the bus daemon + looks for service description files. Service + description files define a mapping from names to executables. Different + kinds of message bus will look for these files in different places, see + . - [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 - desktop - entries. 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. 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.
Example service description file # Sample service description file [D-BUS Service] - Name=org.gnome.ConfigurationDatabase + Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf; Exec=/usr/libexec/gconfd-2
- 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?] The executable launched will have the environment variable - DBUS_ACTIVATION_ADDRESS set to the address of the - message bus so it can connect and register the appropriate services. + DBUS_STARTER_ADDRESS set to the address of the + message bus so it can connect and request the appropriate names. The executable being launched may want to know whether the message bus - activating it is one of the well-known message buses (see ). To facilitate this, the bus MUST also set - the DBUS_ACTIVATION_BUS_TYPE environment variable if it is one + the DBUS_STARTER_BUS_TYPE environment variable if it is one of the well-known buses. The currently-defined values for this variable are system for the systemwide message bus, and session for the per-login-session message - bus. The activated executable must still connect to the address given - in DBUS_ACTIVATION_ADDRESS, but may assume that the + bus. The new executable must still connect to the address given + in DBUS_STARTER_ADDRESS, but may assume that the resulting connection is to the well-known bus. @@ -2262,7 +2378,7 @@ changes in the printer queue, and so forth. - The address of the login session message bus is given + 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 @@ -2284,9 +2400,8 @@ Message Bus Messages - The special message bus service org.freedesktop.DBus - responds to a number of messages, allowing applications to - interact with the message bus. + The special message bus name org.freedesktop.DBus + responds to a number of additional messages. @@ -2310,34 +2425,33 @@ 0 STRING - Name of the service assigned to the application + Unique name assigned to the connection - Before an application is able to send messages to other - applications it must send the - org.freedesktop.DBus.Hello 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 - org.freedesktop.DBus.Hello 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 org.freedesktop.DBus.Hello 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 + org.freedesktop.DBus.Hello message, it will be + disconnected from the bus. - 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). - - <literal>org.freedesktop.DBus.ListServices</literal> + + <literal>org.freedesktop.DBus.ListNames</literal> As a method: - STRING_ARRAY ListServices () + ARRAY of STRING ListNames () Reply arguments: @@ -2352,23 +2466,23 @@ 0 - STRING_ARRAY - Array of strings where each string is the name of a service + ARRAY of STRING + Array of strings where each string is a bus name - Returns a list of all existing services registered with the message bus. + Returns a list of all currently-owned names on the bus. - - <literal>org.freedesktop.DBus.ServiceExists</literal> + + <literal>org.freedesktop.DBus.NameHasOwner</literal> As a method: - BOOLEAN ServiceExists (in STRING service_name) + BOOLEAN NameHasOwner (in STRING name) Message arguments: @@ -2384,7 +2498,7 @@ 0 STRING - Name of the service + Name to check @@ -2403,23 +2517,23 @@ 0 BOOLEAN - Return value, true if the service exists + Return value, true if the name exists - Checks if a service with a specified name exists. + Checks if the specified name exists (currently has an owner). - - <literal>org.freedesktop.DBus.AcquireService</literal> + + <literal>org.freedesktop.DBus.NameOwnerChanged</literal> - As a method: + This is a signal: - UINT32 AcquireService (in STRING service_name) + NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner) Message arguments: @@ -2435,154 +2549,34 @@ 0 STRING - Name of the service + Name with a new owner 1 - UINT32 - Flags - - - - - Reply arguments: - - - - - Argument - Type - Description - - - - - 0 - UINT32 - Return value - - - - - - - Tries to become owner of a specific service. The flags - specified can be the following values logically ORed together: - - - - - - Identifier - Value - Description - - - - - DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT - 0x1 - - 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 org.freedesktop.DBus.ServiceLost message. - - - - DBUS_SERVICE_FLAGS_REPLACE_EXISTING - 0x2 - 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. - - - - - - [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: - - - - - - Identifier - Value - Description - - - - - DBUS_SERVICE_REPLY_PRIMARY_OWNER - 0x1 - The application is now the primary owner of the service. - - - DBUS_SERVICE_REPLY_IN_QUEUE - 0x2 - The service already has an owner which do not want to give up ownership and therefore the application has been put in a queue. - - - DBUS_SERVICE_REPLY_SERVICE_EXISTS - 0x4 - The service does already have a primary owner, and DBUS_SERVICE_FLAG_REPLACE_EXISTING was not specified when trying to acquire the service. - - - DBUS_SERVICE_REPLY_ALREADY_OWNER - 0x8 - The application trying to request ownership of the service is already the owner of it. + STRING + Old owner or empty string if none - - - - - - - <literal>org.freedesktop.DBus.ServiceAcquired</literal> - - As a method: - - ServiceAcquired (in STRING service_name) - - Message arguments: - - - - - Argument - Type - Description - - - - - 0 - STRING - Name of the service - - 1 - UINT32 - Flags + 2 + STRING + New owner or empty string if none - 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. - - <literal>org.freedesktop.DBus.ServiceLost</literal> + + <literal>org.freedesktop.DBus.NameLost</literal> - As a method: + This is a signal: - ServiceLost (in STRING service_name) + NameLost (STRING name) Message arguments: @@ -2598,28 +2592,24 @@ 0 STRING - Name of the service + Name which was lost - - 1 - UINT32 - Flags - - 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. - - <literal>org.freedesktop.DBus.ServiceOwnerChanged</literal> + + <literal>org.freedesktop.DBus.NameAcquired</literal> + This is a signal: - ServiceOwnerChanged (STRING service_name, STRING old_owner, STRING new_owner) + NameAcquired (STRING name) Message arguments: @@ -2635,37 +2625,24 @@ 0 STRING - Name of the service + Name which was acquired - - 1 - STRING - Base service of previous owner, empty string if the - service is newly created - - - 2 - STRING - Base service of new owner, empty string if the - service is no longer available - - 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. - - <literal>org.freedesktop.DBus.ActivateService</literal> + + <literal>org.freedesktop.DBus.StartServiceByName</literal> As a method: - UINT32 ActivateService (in STRING service_name, in UINT32 flags) + UINT32 StartServiceByName (in STRING name, in UINT32 flags) Message arguments: @@ -2681,7 +2658,7 @@ 0 STRING - Name of the service to activate + Name of the service to start 1 @@ -2710,15 +2687,12 @@ - Tries to launch the executable associated with a service. For more information, see . + Tries to launch the executable associated with a name. For more information, see . - [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] The return value can be one of the following values: - + @@ -2729,14 +2703,14 @@ - DBUS_ACTIVATION_REPLY_ACTIVATED - 0x0 - The service was activated successfully. + DBUS_START_REPLY_SUCCESS + 1 + The service was successfully started. - DBUS_ACTIVATION_REPLY_ALREADY_ACTIVE - 0x1 - The service is already active. + DBUS_START_REPLY_ALREADY_RUNNING + 2 + A connection already owns the given name. @@ -2745,12 +2719,12 @@ - - <literal>org.freedesktop.DBus.GetServiceOwner</literal> + + <literal>org.freedesktop.DBus.GetNameOwner</literal> As a method: - STRING GetServiceOwner (in STRING service_name) + STRING GetNameOwner (in STRING name) Message arguments: @@ -2766,7 +2740,7 @@ 0 STRING - Name of the service to query + Name to get the owner of @@ -2785,15 +2759,14 @@ 0 STRING - Return value, a base service name + Return value, a unique connection name - Returns the base service name of the primary owner of the - service in argument. If the requested service isn't active, - returns a - org.freedesktop.DBus.Error.ServiceHasNoOwner 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 + org.freedesktop.DBus.Error.NameHasNoOwner error. @@ -2818,7 +2791,7 @@ 0 STRING - Name of the connection/service to query + Name of the connection to query @@ -2848,31 +2821,6 @@ - - <literal>org.freedesktop.DBus.Error.NoMemory</literal> - - As a method: - - void NoMemory () - - - - Sent by the message bus when it can't process a message due to an out of memory failure. - - - - - <literal>org.freedesktop.DBus.Error.ServiceDoesNotExist</literal> - - As a method: - - void ServiceDoesNotExist (in STRING error) - - - - Sent by the message bus as a reply to a client that tried to send a message to a service that doesn't exist. - - @@ -2892,32 +2840,22 @@ This glossary defines some of the terms used in this specification. - Activation + Bus Name - The process of creating an owner for a particular service, - typically by launching an executable. - - - - - Base Service - - - 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). - - - - - Broadcast - - - A message sent to the special org.freedesktop.DBus.Broadcast - 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 com.yoyodyne.Screensaver + name might be used to send a message to a screensaver from Yoyodyne + Corporation. An application is said to own a + 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 + used to find applications that offer specific functionality. @@ -2937,9 +2875,20 @@ 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 - services. + names used for routing + messages. + + + + + Name + + + See . "Name" may + also be used to refer to some of the other names + in D-BUS, such as interface names. @@ -2947,9 +2896,9 @@ Namespace - 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. @@ -2957,73 +2906,80 @@ Object - Each application contains objects, - which have interfaces and - methods. Objects are referred to - by a name, called a path or - object reference. + Each application contains objects, which have + interfaces and + methods. Objects are referred to by a name, + called a path. - Path + One-to-One - - 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. + + 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). - One-to-One + Path - - An application talking directly to another application, without going through a message bus. + + 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. - Secondary service owner + + Queued Name Owner - 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. + Service - A service is simply a named list of applications. For example, the - hypothetical com.yoyodyne.Screensaver service might - accept messages that affect a screensaver from Yoyodyne Corporation. - An application is said to own a service if the - message bus has associated the application with the service name. - Services may also have secondary owners (see - ). + 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". - Service name + + Service Description Files - - 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. + + ".service files" tell the bus about service applications that can be + launched (see ). Most importantly they + provide a mapping from bus names to services that will request those + names when they start up. - Service Description Files + + Unique Connection Name - ".service files" tell the bus how to activate a particular service. - See + 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. diff --git a/doc/dbus-tutorial.xml b/doc/dbus-tutorial.xml index 6d1b7f3b..44f2f7ca 100644 --- a/doc/dbus-tutorial.xml +++ b/doc/dbus-tutorial.xml @@ -7,8 +7,8 @@
D-BUS Tutorial - Version 0.2 - 10 August 2004 + Version 0.3 + 18 January 2005 Havoc @@ -296,8 +296,8 @@ - - Services + + Bus Names Object paths, interfaces, and messages exist on the level of @@ -306,55 +306,55 @@ - Services, on the other hand, are a property of the message bus daemon. - A service is simply a name mapped to - some application connected to the message bus daemon. + Bus names, on the other hand, are a property of the message bus daemon. + The bus maintains a mapping from names to message bus connections. These names are used to specify the origin and destination of messages passing through the message bus. When a name is mapped - to a particular application, the application is said to - own that service. + to a particular application's connection, that application is said to + own that name. On connecting to the bus daemon, each application immediately owns a - special name called the base service. A base - service begins with a ':' (colon) character; no other services are - allowed to begin with that character. Base services are special because - each one is unique. They are created dynamically, and are never re-used - during the lifetime of the same bus daemon. You know that a given - base service name will have the same owner at all times. - An example of a base service name might be :34-907. + special name called the unique connection name. + A unique name begins with a ':' (colon) character; no other names are + allowed to begin with that character. Unique names are special because + they are created dynamically, and are never re-used during the lifetime + of the same bus daemon. You know that a given unique name will have the + same owner at all times. An example of a unique name might be + :34-907. The numbers after the colon have + no meaning other than their uniqueness. Applications may ask to own additional well-known - services. For example, you could write a specification to - define a service called com.mycompany.TextEditor. - Your definition could specify that to own this service, an application + names. For example, you could write a specification to + define a name called com.mycompany.TextEditor. + Your definition could specify that to own this name, an application should have an object at the path /com/mycompany/TextFileManager supporting the interface org.freedesktop.FileHandler. - Applications could then send messages to this service, + Applications could then send messages to this bus name, object, and interface to execute method calls. - You could think of the base service names as IP addresses, and the - well-known services as domain names. So + You could think of the unique names as IP addresses, and the + well-known names as domain names. So com.mycompany.TextEditor might map to something like :34-907 just as mycompany.com maps to something like 192.168.0.5. - Services have a second important use, other than routing messages. They + Names have a second important use, other than routing messages. They are used to track lifecycle. When an application exits (or crashes), its connection to the message bus will be closed by the operating system kernel. The message bus then sends out notification messages telling - remaining applications that the application's services have lost their + remaining applications that the application's names have lost their owner. By tracking these notifications, your application can reliably monitor the lifetime of other applications. @@ -408,12 +408,12 @@ method call on a particular object instance, a number of nested components have to be named: - Address -> [Service] -> Path -> Interface -> Method + Address -> [Bus Name] -> Path -> Interface -> Method - The service is in brackets to indicate that it's optional -- you only - provide a service name to route the method call to the right application + The bus name is in brackets to indicate that it's optional -- you only + provide a name to route the method call to the right application when using the bus daemon. If you have a direct connection to another - application, services aren't used; there's no bus daemon. + application, bus names aren't used; there's no bus daemon. @@ -455,8 +455,8 @@ main (int argc, char **argv) GError *error; DBusGProxy *proxy; DBusGPendingCall *call; - char **service_list; - int service_list_len; + char **name_list; + int name_list_len; int i; g_type_init (); @@ -472,24 +472,24 @@ main (int argc, char **argv) exit (1); } - /* Create a proxy object for the "bus driver" (service org.freedesktop.DBus) */ + /* Create a proxy object for the "bus driver" (name "org.freedesktop.DBus") */ - proxy = dbus_g_proxy_new_for_service (connection, - DBUS_SERVICE_ORG_FREEDESKTOP_DBUS, - DBUS_PATH_ORG_FREEDESKTOP_DBUS, - DBUS_INTERFACE_ORG_FREEDESKTOP_DBUS); + proxy = dbus_g_proxy_new_for_name (connection, + DBUS_SERVICE_ORG_FREEDESKTOP_DBUS, + DBUS_PATH_ORG_FREEDESKTOP_DBUS, + DBUS_INTERFACE_ORG_FREEDESKTOP_DBUS); - /* Call ListServices method */ + /* Call ListNames method */ - call = dbus_g_proxy_begin_call (proxy, "ListServices", DBUS_TYPE_INVALID); + call = dbus_g_proxy_begin_call (proxy, "ListNames", DBUS_TYPE_INVALID); error = NULL; if (!dbus_g_proxy_end_call (proxy, call, &error, DBUS_TYPE_ARRAY, DBUS_TYPE_STRING, - &service_list, &service_list_len, + &name_list, &name_list_len, DBUS_TYPE_INVALID)) { - g_printerr ("Failed to complete ListServices call: %s\n", + g_printerr ("Failed to complete ListNames call: %s\n", error->message); g_error_free (error); exit (1); @@ -497,17 +497,17 @@ main (int argc, char **argv) /* Print the results */ - g_print ("Services on the message bus:\n"); + g_print ("Names on the message bus:\n"); i = 0; - while (i < service_list_len) + while (i < name_list_len) { - g_assert (service_list[i] != NULL); - g_print (" %s\n", service_list[i]); + g_assert (name_list[i] != NULL); + g_print (" %s\n", name_list[i]); ++i; } - g_assert (service_list[i] == NULL); + g_assert (name_list[i] == NULL); - g_strfreev (service_list); + g_strfreev (name_list); return 0; } diff --git a/doc/diagram.png b/doc/diagram.png new file mode 100644 index 00000000..5cb84a99 Binary files /dev/null and b/doc/diagram.png differ diff --git a/doc/diagram.svg b/doc/diagram.svg new file mode 100644 index 00000000..193c5679 --- /dev/null +++ b/doc/diagram.svg @@ -0,0 +1,590 @@ + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + Application Process 1 + + DBusConnectionInstance + + C/C++/Python/etc.Object Instance + + Locate Objectvia Object Path + + Bindings Marshalto Method Call + + + Marshal MethodCall to Message + + + Bindings ProxyObject Instance + + Application Code + + IncomingCall + OutgoingCall + + + Bus Daemon Process + + Application Process 2 + Same Stuff as inProcess 1 + (Object Instance Has1 or More Interfaces) + + Socket(Bidirectional Message Stream) + + Socket(Bidirectional Message Stream) + + DBusConnectionInstance + + DBusConnectionInstance + + DBusConnectionInstance + + + Message Dispatcher + + if (message is signal) broadcastelse find destination named by message + + + + Destination Table + Connection 1Connection 2"The Session Manager""The Window Manager""The Screensaver""The Text Editor""The Hardware Directory""The Address Book""The Dictionary" + + + + + + -- cgit v1.2.1