From 3e6b351f189f89af76fe1fd6e63a5171fae18284 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Mon, 11 Apr 2011 16:53:03 +0100 Subject: Imported Upstream version 1.5.0 --- doc/dbus-specification.html | 139 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 110 insertions(+), 29 deletions(-) (limited to 'doc/dbus-specification.html') diff --git a/doc/dbus-specification.html b/doc/dbus-specification.html index 59dfbb35..10738cda 100644 --- a/doc/dbus-specification.html +++ b/doc/dbus-specification.html @@ -6,7 +6,8 @@             <>
          

Sven Herzberg

Imendio AB


            
-          

Version 0.15

Revision History
Revision currentcommit log
Revision 0.153 November 2010
Revision 0.1412 May 2010
Revision 0.1323 Dezember 2009
Revision 0.127 November, 2006
Revision 0.116 February 2005
Revision 0.1028 January 2005
Revision 0.97 Januar 2005
Revision 0.806 September 2003
First released document.

Table of Contents

Introduction
Protocol and Specification Stability
Message Protocol
Type Signatures
Marshaling (Wire Format)
Message Format
Valid Names
Message Types
Invalid Protocol and Spec Extensions
Authentication Protocol
Protocol Overview
Special credentials-passing nul byte
AUTH command
CANCEL Command
DATA Command
BEGIN Command
REJECTED Command
OK Command
ERROR Command
NEGOTIATE_UNIX_FD Command
AGREE_UNIX_FD Command
Future Extensions
Authentication examples
Authentication state diagrams
Authentication mechanisms
Server Addresses
Transports
Unix Domain Sockets
launchd
TCP Sockets
Nonce-secured TCP Sockets
Meta Transports
Autolaunch
Naming Conventions
UUIDs
Standard Interfaces
org.freedesktop.DBus.Peer
org.freedesktop.DBus.Introspectable
org.freedesktop.DBus.Properties
Introspection Data Format
Message Bus Specification
Message Bus Overview
Message Bus Names
Message Bus Message Routing
Message Bus Starting Services
Well-known Message Bus Instances
Message Bus Messages
Glossary

Introduction

+          

Version 0.16

Revision History
Revision currentcommit log
Revision 0.1611 April 2011
add path_namespace, arg0namespace; argNpath matches object + paths
Revision 0.153 November 2010
Revision 0.1412 May 2010
Revision 0.1323 Dezember 2009
Revision 0.127 November, 2006
Revision 0.116 February 2005
Revision 0.1028 January 2005
Revision 0.97 Januar 2005
Revision 0.806 September 2003
First released document.

Table of Contents

Introduction
Protocol and Specification Stability
Message Protocol
Type Signatures
Marshaling (Wire Format)
Message Format
Valid Names
Message Types
Invalid Protocol and Spec Extensions
Authentication Protocol
Protocol Overview
Special credentials-passing nul byte
AUTH command
CANCEL Command
DATA Command
BEGIN Command
REJECTED Command
OK Command
ERROR Command
NEGOTIATE_UNIX_FD Command
AGREE_UNIX_FD Command
Future Extensions
Authentication examples
Authentication state diagrams
Authentication mechanisms
Server Addresses
Transports
Unix Domain Sockets
launchd
TCP Sockets
Nonce-secured TCP Sockets
Meta Transports
Autolaunch
Naming Conventions
UUIDs
Standard Interfaces
org.freedesktop.DBus.Peer
org.freedesktop.DBus.Introspectable
org.freedesktop.DBus.Properties
Introspection Data Format
Message Bus Specification
Message Bus Overview
Message Bus Names
Message Bus Message Routing
Message Bus Starting Services
Well-known Message Bus Instances
Message Bus Messages
Glossary

Introduction

D-Bus is a system for low-latency, low-overhead, easy to use interprocess communication (IPC). In more detail:

  • @@ -899,14 +900,14 @@ commands may be introduced both before, and after authentication, i.e. both before and after the OK command.

Authentication examples

-

Figure 1. Example of successful magic cookie authentication

+        
Figure 1. Example of successful magic cookie authentication
             (MAGIC_COOKIE is a made up mechanism)
 
             C: AUTH MAGIC_COOKIE 3138363935333137393635383634
             S: OK 1234deadbeef
             C: BEGIN
           


-        
Figure 2. Example of finding out mechanisms then picking one
+        
Figure 2. Example of finding out mechanisms then picking one
             C: AUTH
             S: REJECTED KERBEROS_V4 SKEY
             C: AUTH SKEY 7ab83f32ee
@@ -915,14 +916,14 @@
             S: OK 1234deadbeef
             C: BEGIN
           


-        
Figure 3. Example of client sends unknown command then falls back to regular auth
+        
Figure 3. Example of client sends unknown command then falls back to regular auth
             C: FOOBAR
             S: ERROR
             C: AUTH MAGIC_COOKIE 3736343435313230333039
             S: OK 1234deadbeef
             C: BEGIN
           


-        
Figure 4. Example of server doesn't support initial auth mechanism
+        
Figure 4. Example of server doesn't support initial auth mechanism
             C: AUTH MAGIC_COOKIE 3736343435313230333039
             S: REJECTED KERBEROS_V4 SKEY
             C: AUTH SKEY 7ab83f32ee
@@ -931,7 +932,7 @@
             S: OK 1234deadbeef
             C: BEGIN
           


-        
Figure 5. Example of wrong password or the like followed by successful retry
+        
Figure 5. Example of wrong password or the like followed by successful retry
             C: AUTH MAGIC_COOKIE 3736343435313230333039
             S: REJECTED KERBEROS_V4 SKEY
             C: AUTH SKEY 7ab83f32ee
@@ -944,7 +945,7 @@
             S: OK 1234deadbeef
             C: BEGIN
           


-        
Figure 6. Example of skey cancelled and restarted
+        
Figure 6. Example of skey cancelled and restarted
             C: AUTH MAGIC_COOKIE 3736343435313230333039
             S: REJECTED KERBEROS_V4 SKEY
             C: AUTH SKEY 7ab83f32ee
@@ -957,7 +958,7 @@
             S: OK 1234deadbeef
             C: BEGIN
           


-        
Figure 7. Example of successful magic cookie authentication with successful negotiation of Unix FD passing
+        
Figure 7. Example of successful magic cookie authentication with successful negotiation of Unix FD passing
             (MAGIC_COOKIE is a made up mechanism)
 
             C: AUTH MAGIC_COOKIE 3138363935333137393635383634
@@ -966,7 +967,7 @@
             S: AGREE_UNIX_FD
             C: BEGIN
           


-        
Figure 8. Example of successful magic cookie authentication with unsuccessful negotiation of Unix FD passing
+        
Figure 8. Example of successful magic cookie authentication with unsuccessful negotiation of Unix FD passing
             (MAGIC_COOKIE is a made up mechanism)
 
             C: AUTH MAGIC_COOKIE 3138363935333137393635383634
@@ -1244,7 +1245,7 @@
                 fails, the lock fails. Servers should retry for a reasonable
                 period of time, then they may choose to delete an existing lock
                 to keep users from having to manually delete a stale
-                lock. [1]
+                lock. [1]
               
  • 
                 Once the lockfile has been created, the server loads the cookie
                 file. It should then delete any cookies that are old (the
@@ -1959,21 +1960,101 @@
                   If a message omits the interface header, it must not match any rule 
                   that specifies this key.memberAny valid method or signal nameMatches messages which have the give method or signal name. An example of
                   a member match is member='NameOwnerChanged'pathAn object path (see the section called “Valid Object Paths”)Matches messages which are sent from or to the given object. An example of a
-                  path match is path='/org/freedesktop/Hal/Manager'destinationA unique name (see Unique Connection Name)Matches messages which are being sent to the given unique name. An
+                  path match is path='/org/freedesktop/Hal/Manager'path_namespaceAn object path
+                    
    
+                      Matches messages which are sent from or to an
+                      object for which the object path is either the
+                      given value, or that value followed by one or
+                      more path components.
+                    
    
+
+                    
    
+                      For example,
+                      path_namespace='/com/example/foo'
+                      would match signals sent by
+                      /com/example/foo
+                      or by
+                      /com/example/foo/bar,
+                      but not by
+                      /com/example/foobar.
+                    
    
+
+                    
    
+                      Using both path and
+                      path_namespace in the same match
+                      rule is not allowed.
+                    
    
+
+                    
    
+                      
+                        This match key was added in version 0.16 of the
+                        D-Bus specification and implemented by the bus
+                        daemon in dbus 1.5.0 and later.
+                      
+                    
    
+                destinationA unique name (see Unique Connection Name)Matches messages which are being sent to the given unique name. An
                   example of a destination match is destination=':1.0'arg[0, 1, 2, 3, ...]Any stringArg matches are special and are used for further restricting the 
-                  match based on the arguments in the body of a message.  As of this time
-                  only string arguments can be matched.  An example of an argument match 
+                  match based on the arguments in the body of a message. Only arguments of type
+                  STRING can be matched in this way. An example of an argument match 
                   would be arg3='Foo'. Only argument indexes from 0 to 63 should be 
-                  accepted.arg[0, 1, 2, 3, ...]pathAny stringArgument path matches provide a specialised form of wildcard
-                  matching for path-like namespaces. As with normal argument matches,
-                  if the argument is exactly equal to the string given in the match
-                  rule then the rule is satisfied. Additionally, there is also a
-                  match when either the string given in the match rule or the
-                  appropriate message argument ends with '/' and is a prefix of the
-                  other. An example argument path match is arg0path='/aa/bb/'. This
-                  would match messages with first arguments of '/', '/aa/',
-                  '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match
-                  messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.
    • 
+                  accepted.arg[0, 1, 2, 3, ...]pathAny string
+                    
    Argument path matches provide a specialised form of wildcard matching for
+                      path-like namespaces. They can match arguments whose type is either STRING or
+                      OBJECT_PATH. As with normal argument matches,
+                      if the argument is exactly equal to the string given in the match
+                      rule then the rule is satisfied. Additionally, there is also a
+                      match when either the string given in the match rule or the
+                      appropriate message argument ends with '/' and is a prefix of the
+                      other. An example argument path match is arg0path='/aa/bb/'. This
+                      would match messages with first arguments of '/', '/aa/',
+                      '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match
+                      messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.
    
+
+                    
    This is intended for monitoring “directories” in file system-like
+                      hierarchies, as used in the dconf configuration
+                      system. An application interested in all nodes in a particular hierarchy would
+                      monitor arg0path='/ca/example/foo/'. Then the service could
+                      emit a signal with zeroth argument "/ca/example/foo/bar" to
+                      represent a modification to the “bar” property, or a signal with zeroth
+                      argument "/ca/example/" to represent atomic modification of
+                      many properties within that directory, and the interested application would be
+                      notified in both cases.
    
+                    
    
+                      
+                        This match key was added in version 0.12 of the
+                        D-Bus specification, implemented for STRING
+                        arguments by the bus daemon in dbus 1.2.0 and later,
+                        and implemented for OBJECT_PATH arguments in dbus 1.5.0
+                        and later.
+                      
+                    
    
+                  arg0namespaceLike a bus name, except that the string is not
+                    required to contain a '.' (period)
+                    
    Match messages whose first argument is of type STRING, and is a bus name
+                      or interface name within the specified namespace. This is primarily intended
+                      for watching name owner changes for a group of related bus names, rather than
+                      for a single name or all name changes.
    
+
+                    
    Because every valid interface name is also a valid
+                      bus name, this can also be used for messages whose
+                      first argument is an interface name.
    
+
+                    
    For example, the match rule
+                      member='NameOwnerChanged',arg0namespace='com.example.backend'
+                      matches name owner changes for bus names such as
+                      com.example.backend.foo,
+                      com.example.backend.foo.bar, and
+                      com.example.backend itself.
    
+
+                    
    See also the section called “org.freedesktop.DBus.NameOwnerChanged”.
    
+                    
    
+                      
+                        This match key was added in version 0.16 of the
+                        D-Bus specification and implemented by the bus
+                        daemon in dbus 1.5.0 and later.
+                      
+                    
    
+                  
    
         
    Message Bus Starting Services
    
         The message bus can start applications on behalf of other applications.
         In CORBA terms, this would be called activation.
@@ -2010,7 +2091,7 @@
 
         
    • General syntax
    • Comment format
    
 
-        
    Figure 9. Example service description file
    +        
    Figure 9. Example service description file
                 # Sample service description file
             [D-BUS Service]
             Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;
@@ -2180,7 +2261,7 @@
             allowing another process to set the selection between the
             verification and the setting (e.g., by using XGrabServer /
             XungrabServer).
-          
    
+          
    
             [FIXME specify location of .service files, probably using
             DESKTOP_DIRS etc. from basedir specification, though login session
             bus is not really desktop-specific]
@@ -2195,7 +2276,7 @@
           variable. If that variable is not set, applications should try 
           to connect to the well-known address
           unix:path=/var/run/dbus/system_bus_socket.
-          [2]
+          [2]
         
    
           [FIXME specify location of system bus .service files]
         
    Message Bus Messages
    
@@ -2380,7 +2461,7 @@
         There is also a per-machine ID, described in the section called “org.freedesktop.DBus.Peer” and returned
         by org.freedesktop.DBus.Peer.GetMachineId().
         For a desktop session bus, the bus ID can be used as a way to uniquely identify a user's session.
-        
    Glossary
    
+        
    Glossary
    
       This glossary defines some of the terms used in this specification.
     
    Bus Name
    
           The message bus maintains an association between names and
@@ -2454,10 +2535,10 @@
           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.
-        

    [1] Lockfiles are used instead of real file
+        

    [1] Lockfiles are used instead of real file
                 locking fcntl() because real locking
                 implementations are still flaky on network
-                filesystems.
    [2] 
+                filesystems.
    [2] 
               The D-Bus reference implementation actually honors the 
               $(localstatedir) configure option 
               for this address, on both client and server side.
-- 
cgit v1.2.3