diff options
author | Chengwei Yang <chengwei.yang@intel.com> | 2013-12-06 11:15:12 +0800 |
---|---|---|
committer | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2014-01-06 16:07:22 +0000 |
commit | eeae8a6b1ca7375213ba06d311e10108794f21c3 (patch) | |
tree | 0c0b72e7509e365634d97944536cf80d24af710b /doc | |
parent | 15a5b2637c73d8f6d30acf1517b00182f215eb35 (diff) | |
download | dbus-eeae8a6b1ca7375213ba06d311e10108794f21c3.tar.gz |
DBus Spec: replace tab with 8 spaces
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=72301
Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/dbus-specification.xml | 426 |
1 files changed, 213 insertions, 213 deletions
diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index d1b8d473..5043849f 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -10,44 +10,44 @@ <date>(not yet released)</date> <authorgroup> <author> - <firstname>Havoc</firstname> - <surname>Pennington</surname> - <affiliation> - <orgname>Red Hat, Inc.</orgname> - <address> - <email>hp@pobox.com</email> - </address> - </affiliation> + <firstname>Havoc</firstname> + <surname>Pennington</surname> + <affiliation> + <orgname>Red Hat, Inc.</orgname> + <address> + <email>hp@pobox.com</email> + </address> + </affiliation> </author> <author> - <firstname>Anders</firstname> - <surname>Carlsson</surname> - <affiliation> - <orgname>CodeFactory AB</orgname> - <address> + <firstname>Anders</firstname> + <surname>Carlsson</surname> + <affiliation> + <orgname>CodeFactory AB</orgname> + <address> <email>andersca@codefactory.se</email> </address> - </affiliation> + </affiliation> </author> <author> - <firstname>Alexander</firstname> - <surname>Larsson</surname> - <affiliation> - <orgname>Red Hat, Inc.</orgname> - <address> + <firstname>Alexander</firstname> + <surname>Larsson</surname> + <affiliation> + <orgname>Red Hat, Inc.</orgname> + <address> <email>alexl@redhat.com</email> </address> - </affiliation> + </affiliation> </author> <author> - <firstname>Sven</firstname> - <surname>Herzberg</surname> - <affiliation> - <orgname>Imendio AB</orgname> - <address> + <firstname>Sven</firstname> + <surname>Herzberg</surname> + <affiliation> + <orgname>Imendio AB</orgname> + <address> <email>sven@imendio.com</email> </address> - </affiliation> + </affiliation> </author> <author> <firstname>Simon</firstname> @@ -765,14 +765,14 @@ <entry>0 (ASCII NUL)</entry> <entry>Not a valid type code, used to terminate signatures</entry> </row><row> - <entry><literal>BYTE</literal></entry> - <entry>121 (ASCII 'y')</entry> - <entry>8-bit unsigned integer</entry> + <entry><literal>BYTE</literal></entry> + <entry>121 (ASCII 'y')</entry> + <entry>8-bit unsigned integer</entry> + </row><row> + <entry><literal>BOOLEAN</literal></entry> + <entry>98 (ASCII 'b')</entry> + <entry>Boolean value, 0 is <literal>FALSE</literal> and 1 is <literal>TRUE</literal>. Everything else is invalid.</entry> </row><row> - <entry><literal>BOOLEAN</literal></entry> - <entry>98 (ASCII 'b')</entry> - <entry>Boolean value, 0 is <literal>FALSE</literal> and 1 is <literal>TRUE</literal>. Everything else is invalid.</entry> - </row><row> <entry><literal>INT16</literal></entry> <entry>110 (ASCII 'n')</entry> <entry>16-bit signed integer</entry> @@ -780,7 +780,7 @@ <entry><literal>UINT16</literal></entry> <entry>113 (ASCII 'q')</entry> <entry>16-bit unsigned integer</entry> - </row><row> + </row><row> <entry><literal>INT32</literal></entry> <entry>105 (ASCII 'i')</entry> <entry>32-bit signed integer</entry> @@ -788,7 +788,7 @@ <entry><literal>UINT32</literal></entry> <entry>117 (ASCII 'u')</entry> <entry>32-bit unsigned integer</entry> - </row><row> + </row><row> <entry><literal>INT64</literal></entry> <entry>120 (ASCII 'x')</entry> <entry>64-bit signed integer</entry> @@ -1109,7 +1109,7 @@ <entry> 8 </entry> - </row><row> + </row><row> <entry><literal>VARIANT</literal></entry> <entry> The marshaled <literal>SIGNATURE</literal> of a single @@ -1119,7 +1119,7 @@ <entry> 1 (alignment of the signature) </entry> - </row><row> + </row><row> <entry><literal>DICT_ENTRY</literal></entry> <entry> Identical to STRUCT. @@ -1136,7 +1136,7 @@ file descriptor in the array of file descriptors that accompany the message.</entry> <entry>4</entry> - </row> + </row> </tbody> </tgroup> </informaltable> @@ -1528,12 +1528,12 @@ </para> </listitem> - <listitem><para>Interface names must contain at least one '.' (period) + <listitem><para>Interface names must contain at least one '.' (period) character (and thus at least two elements). </para></listitem> - <listitem><para>Interface names must not begin with a '.' (period) character.</para></listitem> - <listitem><para>Interface names must not exceed the maximum name length.</para></listitem> + <listitem><para>Interface names must not begin with a '.' (period) character.</para></listitem> + <listitem><para>Interface names must not exceed the maximum name length.</para></listitem> </itemizedlist> </para> @@ -1592,12 +1592,12 @@ </para> </listitem> - <listitem><para>Bus names must contain at least one '.' (period) + <listitem><para>Bus names must contain at least one '.' (period) character (and thus at least two elements). </para></listitem> - <listitem><para>Bus names must not begin with a '.' (period) character.</para></listitem> - <listitem><para>Bus names must not exceed the maximum name length.</para></listitem> + <listitem><para>Bus names must not begin with a '.' (period) character.</para></listitem> + <listitem><para>Bus names must not exceed the maximum name length.</para></listitem> </itemizedlist> </para> <para> @@ -1635,12 +1635,12 @@ <para> Member (i.e. method or signal) names: <itemizedlist> - <listitem><para>Must only contain the ASCII characters + <listitem><para>Must only contain the ASCII characters "[A-Z][a-z][0-9]_" and may not begin with a digit.</para></listitem> - <listitem><para>Must not contain the '.' (period) character.</para></listitem> - <listitem><para>Must not exceed the maximum name length.</para></listitem> - <listitem><para>Must be at least 1 byte in length.</para></listitem> + <listitem><para>Must not contain the '.' (period) character.</para></listitem> + <listitem><para>Must not exceed the maximum name length.</para></listitem> + <listitem><para>Must be at least 1 byte in length.</para></listitem> </itemizedlist> </para> @@ -1984,23 +1984,23 @@ Commands from the client to the server are as follows: <itemizedlist> - <listitem><para>AUTH [mechanism] [initial-response]</para></listitem> - <listitem><para>CANCEL</para></listitem> - <listitem><para>BEGIN</para></listitem> - <listitem><para>DATA <data in hex encoding></para></listitem> - <listitem><para>ERROR [human-readable error explanation]</para></listitem> - <listitem><para>NEGOTIATE_UNIX_FD</para></listitem> - </itemizedlist> + <listitem><para>AUTH [mechanism] [initial-response]</para></listitem> + <listitem><para>CANCEL</para></listitem> + <listitem><para>BEGIN</para></listitem> + <listitem><para>DATA <data in hex encoding></para></listitem> + <listitem><para>ERROR [human-readable error explanation]</para></listitem> + <listitem><para>NEGOTIATE_UNIX_FD</para></listitem> + </itemizedlist> From server to client are as follows: <itemizedlist> - <listitem><para>REJECTED <space-separated list of mechanism names></para></listitem> - <listitem><para>OK <GUID in hex></para></listitem> - <listitem><para>DATA <data in hex encoding></para></listitem> - <listitem><para>ERROR</para></listitem> - <listitem><para>AGREE_UNIX_FD</para></listitem> - </itemizedlist> + <listitem><para>REJECTED <space-separated list of mechanism names></para></listitem> + <listitem><para>OK <GUID in hex></para></listitem> + <listitem><para>DATA <data in hex encoding></para></listitem> + <listitem><para>ERROR</para></listitem> + <listitem><para>AGREE_UNIX_FD</para></listitem> + </itemizedlist> </para> <para> Unofficial extensions to the command set must begin with the letters @@ -2230,18 +2230,18 @@ <para> <figure> - <title>Example of successful magic cookie authentication</title> - <programlisting> + <title>Example of successful magic cookie authentication</title> + <programlisting> (MAGIC_COOKIE is a made up mechanism) C: AUTH MAGIC_COOKIE 3138363935333137393635383634 S: OK 1234deadbeef C: BEGIN </programlisting> - </figure> + </figure> <figure> - <title>Example of finding out mechanisms then picking one</title> - <programlisting> + <title>Example of finding out mechanisms then picking one</title> + <programlisting> C: AUTH S: REJECTED KERBEROS_V4 SKEY C: AUTH SKEY 7ab83f32ee @@ -2250,20 +2250,20 @@ S: OK 1234deadbeef C: BEGIN </programlisting> - </figure> + </figure> <figure> - <title>Example of client sends unknown command then falls back to regular auth</title> - <programlisting> + <title>Example of client sends unknown command then falls back to regular auth</title> + <programlisting> C: FOOBAR S: ERROR C: AUTH MAGIC_COOKIE 3736343435313230333039 S: OK 1234deadbeef C: BEGIN </programlisting> - </figure> + </figure> <figure> - <title>Example of server doesn't support initial auth mechanism</title> - <programlisting> + <title>Example of server doesn't support initial auth mechanism</title> + <programlisting> C: AUTH MAGIC_COOKIE 3736343435313230333039 S: REJECTED KERBEROS_V4 SKEY C: AUTH SKEY 7ab83f32ee @@ -2272,10 +2272,10 @@ S: OK 1234deadbeef C: BEGIN </programlisting> - </figure> + </figure> <figure> - <title>Example of wrong password or the like followed by successful retry</title> - <programlisting> + <title>Example of wrong password or the like followed by successful retry</title> + <programlisting> C: AUTH MAGIC_COOKIE 3736343435313230333039 S: REJECTED KERBEROS_V4 SKEY C: AUTH SKEY 7ab83f32ee @@ -2288,10 +2288,10 @@ S: OK 1234deadbeef C: BEGIN </programlisting> - </figure> + </figure> <figure> - <title>Example of skey cancelled and restarted</title> - <programlisting> + <title>Example of skey cancelled and restarted</title> + <programlisting> C: AUTH MAGIC_COOKIE 3736343435313230333039 S: REJECTED KERBEROS_V4 SKEY C: AUTH SKEY 7ab83f32ee @@ -2304,10 +2304,10 @@ S: OK 1234deadbeef C: BEGIN </programlisting> - </figure> + </figure> <figure> - <title>Example of successful magic cookie authentication with successful negotiation of Unix FD passing</title> - <programlisting> + <title>Example of successful magic cookie authentication with successful negotiation of Unix FD passing</title> + <programlisting> (MAGIC_COOKIE is a made up mechanism) C: AUTH MAGIC_COOKIE 3138363935333137393635383634 @@ -2316,10 +2316,10 @@ S: AGREE_UNIX_FD C: BEGIN </programlisting> - </figure> + </figure> <figure> - <title>Example of successful magic cookie authentication with unsuccessful negotiation of Unix FD passing</title> - <programlisting> + <title>Example of successful magic cookie authentication with unsuccessful negotiation of Unix FD passing</title> + <programlisting> (MAGIC_COOKIE is a made up mechanism) C: AUTH MAGIC_COOKIE 3138363935333137393635383634 @@ -2328,7 +2328,7 @@ S: ERROR C: BEGIN </programlisting> - </figure> + </figure> </para> </sect2> <sect2 id="auth-states"> @@ -2997,17 +2997,17 @@ <title>Unix Domain Sockets</title> <para> Unix domain sockets can be either paths in the file system or on Linux - kernels, they can be abstract which are similar to paths but - do not show up in the file system. + kernels, they can be abstract which are similar to paths but + do not show up in the file system. </para> <para> When a socket is opened by the D-Bus library it truncates the path - name right before the first trailing Nul byte. This is true for both - normal paths and abstract paths. Note that this is a departure from - previous versions of D-Bus that would create sockets with a fixed - length path name. Names which were shorter than the fixed length - would be padded by Nul bytes. + name right before the first trailing Nul byte. This is true for both + normal paths and abstract paths. Note that this is a departure from + previous versions of D-Bus that would create sockets with a fixed + length path name. Names which were shorter than the fixed length + would be padded by Nul bytes. </para> <para> Unix domain sockets are not available on Windows. @@ -3846,38 +3846,38 @@ <para> Method, interface, property, and signal elements may have "annotations", which are generic key/value pairs of metadata. - They are similar conceptually to Java's annotations and C# attributes. + They are similar conceptually to Java's annotations and C# attributes. Well-known annotations: </para> <informaltable> <tgroup cols="3"> - <thead> - <row> - <entry>Name</entry> - <entry>Values (separated by ,)</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>org.freedesktop.DBus.Deprecated</entry> - <entry>true,false</entry> - <entry>Whether or not the entity is deprecated; defaults to false</entry> - </row> - <row> - <entry>org.freedesktop.DBus.GLib.CSymbol</entry> - <entry>(string)</entry> - <entry>The C symbol; may be used for methods and interfaces</entry> - </row> - <row> - <entry>org.freedesktop.DBus.Method.NoReply</entry> - <entry>true,false</entry> - <entry>If set, don't expect a reply to the method call; defaults to false.</entry> - </row> - <row> - <entry>org.freedesktop.DBus.Property.EmitsChangedSignal</entry> - <entry>true,invalidates,false</entry> - <entry> + <thead> + <row> + <entry>Name</entry> + <entry>Values (separated by ,)</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>org.freedesktop.DBus.Deprecated</entry> + <entry>true,false</entry> + <entry>Whether or not the entity is deprecated; defaults to false</entry> + </row> + <row> + <entry>org.freedesktop.DBus.GLib.CSymbol</entry> + <entry>(string)</entry> + <entry>The C symbol; may be used for methods and interfaces</entry> + </row> + <row> + <entry>org.freedesktop.DBus.Method.NoReply</entry> + <entry>true,false</entry> + <entry>If set, don't expect a reply to the method call; defaults to false.</entry> + </row> + <row> + <entry>org.freedesktop.DBus.Property.EmitsChangedSignal</entry> + <entry>true,invalidates,false</entry> + <entry> <para> If set to <literal>false</literal>, the <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal> @@ -3902,8 +3902,8 @@ interface element. </para> </entry> - </row> - </tbody> + </row> + </tbody> </tgroup> </informaltable> </sect1> @@ -4016,11 +4016,11 @@ <entry>STRING</entry> <entry>Name to request</entry> </row> - <row> - <entry>1</entry> - <entry>UINT32</entry> - <entry>Flags</entry> - </row> + <row> + <entry>1</entry> + <entry>UINT32</entry> + <entry>Flags</entry> + </row> </tbody> </tgroup> </informaltable> @@ -4131,10 +4131,10 @@ </row> </thead> <tbody> - <row> - <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry> - <entry>0x1</entry> - <entry> + <row> + <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry> + <entry>0x1</entry> + <entry> If an application A specifies this flag and succeeds in becoming the owner of the name, and another application B @@ -4148,11 +4148,11 @@ application A as the owner. </entry> - </row> - <row> - <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry> - <entry>0x2</entry> - <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 @@ -4161,11 +4161,11 @@ the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT. </entry> - </row> - <row> - <entry>DBUS_NAME_FLAG_DO_NOT_QUEUE</entry> - <entry>0x4</entry> - <entry> + </row> + <row> + <entry>DBUS_NAME_FLAG_DO_NOT_QUEUE</entry> + <entry>0x4</entry> + <entry> Without this flag, if an application requests a name that is already owned, the application will be placed in a queue to @@ -4178,10 +4178,10 @@ became the name owner. </entry> - </row> - </tbody> - </tgroup> - </informaltable> + </row> + </tbody> + </tgroup> + </informaltable> The return code can be one of the following values: @@ -4195,41 +4195,41 @@ </row> </thead> <tbody> - <row> + <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 specified + <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 specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT.</entry> - </row> - <row> - <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry> - <entry>2</entry> + </row> + <row> + <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry> + <entry>2</entry> - <entry>The name already had an owner, + <entry>The name already had an owner, DBUS_NAME_FLAG_DO_NOT_QUEUE was not specified, and either the current owner did not specify DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the requesting application did not specify DBUS_NAME_FLAG_REPLACE_EXISTING. </entry> - </row> - <row> - <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry> <entry>3</entry> - <entry>The name already has an owner, - DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either - DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the - current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not - specified by the requesting application.</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> + </row> + <row> + <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry> <entry>3</entry> + <entry>The name already has an owner, + DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either + DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the + current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not + specified by the requesting application.</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> @@ -4302,7 +4302,7 @@ </row> </thead> <tbody> - <row> + <row> <entry>DBUS_RELEASE_NAME_REPLY_RELEASED</entry> <entry>1</entry> <entry>The caller has released his claim on the given name. Either the caller was the primary owner of @@ -4310,21 +4310,21 @@ waiting in the queue for the name, or the caller was waiting in the queue for the name and has now been removed from the queue.</entry> - </row> - <row> - <entry>DBUS_RELEASE_NAME_REPLY_NON_EXISTENT</entry> - <entry>2</entry> - <entry>The given name does not exist on this bus.</entry> - </row> - <row> - <entry>DBUS_RELEASE_NAME_REPLY_NOT_OWNER</entry> - <entry>3</entry> - <entry>The caller was not the primary owner of this name, + </row> + <row> + <entry>DBUS_RELEASE_NAME_REPLY_NON_EXISTENT</entry> + <entry>2</entry> + <entry>The given name does not exist on this bus.</entry> + </row> + <row> + <entry>DBUS_RELEASE_NAME_REPLY_NOT_OWNER</entry> + <entry>3</entry> + <entry>The caller was not the primary owner of this name, and was also not waiting in the queue to own this name.</entry> - </row> - </tbody> - </tgroup> - </informaltable> + </row> + </tbody> + </tgroup> + </informaltable> </para> </sect3> @@ -4486,7 +4486,7 @@ <sect3 id="message-bus-routing-match-rules"> <title>Match Rules</title> <para> - An important part of the message bus routing protocol is match + An important part of the message bus routing protocol is match rules. Match rules describe the messages that should be sent to a client, based on the contents of the message. Broadcast signals are only sent to clients which have a suitable match rule: this @@ -4773,14 +4773,14 @@ and <literal>Exec</literal> (the command to be executed). <figure> - <title>Example service description file</title> - <programlisting> + <title>Example service description file</title> + <programlisting> # Sample service description file [D-BUS Service] Name=com.example.ConfigurationDatabase Exec=/usr/bin/sample-configd </programlisting> - </figure> + </figure> </para> <para> @@ -5362,16 +5362,16 @@ <entry>STRING</entry> <entry>Name with a new owner</entry> </row> - <row> - <entry>1</entry> - <entry>STRING</entry> - <entry>Old owner or empty string if none</entry> - </row> - <row> - <entry>2</entry> - <entry>STRING</entry> - <entry>New owner or empty string if none</entry> - </row> + <row> + <entry>1</entry> + <entry>STRING</entry> + <entry>Old owner or empty string if none</entry> + </row> + <row> + <entry>2</entry> + <entry>STRING</entry> + <entry>New owner or empty string if none</entry> + </row> </tbody> </tgroup> </informaltable> @@ -5471,11 +5471,11 @@ <entry>STRING</entry> <entry>Name of the service to start</entry> </row> - <row> - <entry>1</entry> - <entry>UINT32</entry> - <entry>Flags (currently not used)</entry> - </row> + <row> + <entry>1</entry> + <entry>UINT32</entry> + <entry>Flags (currently not used)</entry> + </row> </tbody> </tgroup> </informaltable> @@ -5513,7 +5513,7 @@ </row> </thead> <tbody> - <row> + <row> <entry>DBUS_START_REPLY_SUCCESS</entry> <entry>1</entry> <entry>The service was successfully started.</entry> @@ -5970,8 +5970,8 @@ </tgroup> </informaltable> Adds a match rule to match messages going through the message bus (see <xref linkend='message-bus-routing-match-rules'/>). - If the bus does not have enough resources the <literal>org.freedesktop.DBus.Error.OOM</literal> - error is returned. + If the bus does not have enough resources the <literal>org.freedesktop.DBus.Error.OOM</literal> + error is returned. </para> </sect3> <sect3 id="bus-messages-remove-match"> @@ -6001,8 +6001,8 @@ </tgroup> </informaltable> Removes the first rule that matches (see <xref linkend='message-bus-routing-match-rules'/>). - If the rule is not found the <literal>org.freedesktop.DBus.Error.MatchRuleNotFound</literal> - error is returned. + If the rule is not found the <literal>org.freedesktop.DBus.Error.MatchRuleNotFound</literal> + error is returned. </para> </sect3> @@ -6146,7 +6146,7 @@ <glossentry id="one-to-one"><glossterm>One-to-One</glossterm> <glossdef> - <para> + <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 @@ -6186,7 +6186,7 @@ Services normally guarantee some particular features, for example they may guarantee that they will request a specific name such as "com.example.Screensaver", have a singleton object - "/com/example/Application", and that object will implement the + "/com/example/Application", and that object will implement the interface "com.example.Screensaver.Control". </para> </glossdef> |