From 3c8db267892bbce5c82d5060cef993dd54dc6ed4 Mon Sep 17 00:00:00 2001 From: Anders Carlsson Date: Mon, 17 Feb 2003 09:59:23 +0000 Subject: 2003-02-17 Anders Carlsson * bus/activation.c: (bus_activation_init), (child_setup), (bus_activation_activate_service): * bus/activation.h: * bus/main.c: (main): Set DBUS_ADDRESS environment variable. * dbus/dbus-errors.c: (dbus_set_error): Don't use va_copy since that's a C99 feature. * dbus/dbus-sysdeps.c: (_dbus_setenv), (do_exec), (_dbus_spawn_async): * dbus/dbus-sysdeps.h: Add child_setup_func to _dbus_spawn_async. * doc/dbus-specification.sgml: Update specification. * test/spawn-test.c: (setup_func), (main): Fix test. --- doc/dbus-specification.sgml | 496 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 491 insertions(+), 5 deletions(-) (limited to 'doc/dbus-specification.sgml') diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml index b54be17e..6412bf5b 100644 --- a/doc/dbus-specification.sgml +++ b/doc/dbus-specification.sgml @@ -698,15 +698,500 @@ responds to a number of messages, allowing applications to interact with the message bus. + + + <literal>org.freedesktop.DBus.Hello</literal> - - [document the messages here] + As a method: + + STRING Hello () + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the service assigned to the client + + + + + + + Before a client is able to send messages to other clients it + must send the org.freedesktop.DBus.Hello + message to the message bus service. If a client tries to send + a message to another client, or a message to the message bus + service that isn't the + org.freedesktop.DBus.Hello message, it will + be disconnected from the bus. + + + The reply message contains the name of the base service. Any + messages sent to the base service will be rereouted by the + message bus, delivering it to the client. + + + + <literal>org.freedesktop.DBus.ListServices</literal> + + As a method: + + STRING_ARRAY ListServices () + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING_ARRAY + Array of strings where each string is the name of a service + + + + + + + Returns a list of all existing services registered with the message bus. + + + + <literal>org.freedesktop.DBus.ServiceExists</literal> + + As a method: + + UINT32 ServiceExists (in STRING service_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the service + + + + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + UINT32 + Return value, 1 if the service exists and 0 otherwise + + + + + + + Checks if a service with a specified name exists. + + + + + <literal>org.freedesktop.DBus.AcquireService</literal> + + As a method: + + UINT32 AcquireService (in STRING service_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the service + + + 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 client 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 client 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 + Only become the owner of the service if there is no current owner. + + + + + + The return value can be one of the following values: + + + + + + Identifier + Value + Description + + + + + DBUS_SERVICE_REPLY_PRIMARY_OWNER + 0x1 + The client 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 client 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 client trying to request ownership of the service is already the owner of it. + + + + + + + + <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 + + + + + + + This message is sent to a specific client when it becomes the primary owner of a service. + + + + <literal>org.freedesktop.DBus.ServiceLost</literal> + + As a method: + + ServiceLost (in STRING service_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the service + + + 1 + UINT32 + Flags + + + + + + + This message is sent to a specific client when it loses primary ownership of a service. + + + + + <literal>org.freedesktop.DBus.ServiceCreated</literal> + + As a method: + + ServiceCreated (in STRING service_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the service + + + 1 + UINT32 + Flags + + + + + + + This message is broadcast to all clients when a service has been successfully registered on the message bus. + + + + + <literal>org.freedesktop.DBus.ServiceDeleted</literal> + + As a method: + + ServiceDeleted (in STRING service_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the service + + + 1 + UINT32 + Flags + + + + + + + This message is broadcast to all clients when a service has been deleted from the message bus. + + + + + <literal>org.freedesktop.DBus.ActivateService</literal> + + As a method: + + void ActivateService (in STRING service_name, in UINT32 flags) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the service to activate + + + 1 + UINT32 + Flags (currently not used) + + + + + + + Tries to launch the executable associated with a service. For more information, see the part on + + + + + Message Bus Services + + A service is a name that identifies a certain client. Each + client connected to the message bus has at least one service + name acquired through the + org.freedesktop.DBus.Hello message. In + addition, a client can request additional service names to be + associated with it using the + org.freedesktop.DBus.AcquireService + message. + + + Service ownership handling can be specified in the flags part + of the org.freedesktop.DBus.AcquireService + message. If a client specifies the + DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT flag, then all clients + 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 client 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 client requests ownership of the + service. Message Bus Service Activation - [document file format, filesystem locations, etc. for activation] + Activation is a way to launch executables that handle certain + services. The bus daemon looks in certain directories + (possibly different depending on if it's a system bus or a + message bus) for service description files. + + + 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. + +
+ Example service description file + + # Sample service description file + [D-BUS Service] + Name=org.gnome.ConfigurationDatabase + Exec=gconfd-2 + +
+ + + When a client 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. + + + The executable launched will have the environment variable + DBUS_ADDRESS set to the address of the + server so it can connect and register the appropriate services. @@ -730,16 +1215,17 @@ - + + Glossary This glossary defines some of the terms used in this specification. -- cgit