luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-04-21 06:39:17 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Change ‘DBus’ to ‘D-Bus’ in the GVariant Specification

Browse Source 
That’s how it’s meant to be formatted.

Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
This commit is contained in:
Philip Withnall 2022-11-02 11:21:02 +00:00
parent bf4bab98f7
commit 227bb51a74
1 changed files with 32 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
docs/reference/glib/gvariant-specification-1.0.rst
View File

@ -15,54 +15,54 @@ GVariant Specification 1.0
Types Types
***** *****
As per requirement, GVariant must be substantially compatible with the DBus message As per requirement, GVariant must be substantially compatible with the D-Bus message
bus system (as specified in [DBus]). bus system (as specified in [DBus]).
To this end, the type system used in GVariant is almost identical to that used by DBus. To this end, the type system used in GVariant is almost identical to that used by D-Bus.
Some very minimal changes were made, however, in order to provide for a better system Some very minimal changes were made, however, in order to provide for a better system
while still remaining highly compatible; specifically, every message that can by sent over while still remaining highly compatible; specifically, every message that can by sent over
DBus can be represented as a GVariant. D-Bus can be represented as a GVariant.
Some baggage has been carried in from DBus that would not otherwise have been present Some baggage has been carried in from D-Bus that would not otherwise have been present
in the type system if it were designed from scratch. The object path and signature types, in the type system if it were designed from scratch. The object path and signature types,
for example, are highly DBus-specific and would not be present in a general-purpose type for example, are highly D-Bus-specific and would not be present in a general-purpose type
system if it were to be created from scratch. system if it were to be created from scratch.
Differences from DBus Differences from D-Bus
===================== ======================
In order to increase conceptual clarity some limitations have been lifted, allowing calls In order to increase conceptual clarity some limitations have been lifted, allowing calls
to “never fail” instead of having to check for these special cases. to “never fail” instead of having to check for these special cases.
* Whereas DBus limits the maximum depth of container type nesting, GVariant makes * Whereas D-Bus limits the maximum depth of container type nesting, GVariant makes
no such limitations; nesting is supported to arbitrary depths. no such limitations; nesting is supported to arbitrary depths.
* Whereas DBus limits the maximum complexity of its messages by imposing a * Whereas D-Bus limits the maximum complexity of its messages by imposing a
limitation on the “signature string” to be no more than 255 characters, GVariant limitation on the “signature string” to be no more than 255 characters, GVariant
makes no such limitation; type strings of arbitrary length are supported, allowing makes no such limitation; type strings of arbitrary length are supported, allowing
for the creation of values with arbitrarily complex types. for the creation of values with arbitrarily complex types.
* Whereas DBus allows dictionary entry types to appear only as the element type of * Whereas D-Bus allows dictionary entry types to appear only as the element type of
an array type, GVariant makes no such limitation; dictionary entry types may exist an array type, GVariant makes no such limitation; dictionary entry types may exist
on their own or as children of any other type constructor. on their own or as children of any other type constructor.
* Whereas DBus requires structure types to contain at least one child type, GVariant * Whereas D-Bus requires structure types to contain at least one child type, GVariant
makes no such limitation; the unit type is a perfectly valid type in GVariant. makes no such limitation; the unit type is a perfectly valid type in GVariant.
Some of the limitations of DBus were imposed as security considerations (for example, Some of the limitations of D-Bus were imposed as security considerations (for example,
to bound the depth of recursion that may result from processing a message from an to bound the depth of recursion that may result from processing a message from an
untrusted sender). If GVariant is used in ways that are sensitive to these considerations untrusted sender). If GVariant is used in ways that are sensitive to these considerations
then programmers should employ checks for these cases upon entry of values into the then programmers should employ checks for these cases upon entry of values into the
program from an untrusted source. program from an untrusted source.
Additionally, DBus has no type constructor for expressing the concept of nullability [#f1]_. To Additionally, D-Bus has no type constructor for expressing the concept of nullability [#f1]_. To
this end, the Maybe type constructor (represented by m in type strings) has been added. this end, the Maybe type constructor (represented by m in type strings) has been added.
Some of these changes are under consideration for inclusion into DBus [#f2]_. Some of these changes are under consideration for inclusion into D-Bus [#f2]_.
.. [#f1] A “nullable type” is a type that, in addition to containing its normal range of values, also contains a .. [#f1] A “nullable type” is a type that, in addition to containing its normal range of values, also contains a
special value outside of that range, called ``NULL``, ``Nothing``, ``None`` or similar. In most languages with reference special value outside of that range, called ``NULL``, ``Nothing``, ``None`` or similar. In most languages with reference
or pointer types, these types are nullable. Some languages have the ability to have nullable versions of or pointer types, these types are nullable. Some languages have the ability to have nullable versions of
any type (for example, “``Maybe Int``” in Haskell and “``int? i;``” in C#). any type (for example, “``Maybe Int``” in Haskell and “``int? i;``” in C#).
.. [#f2] Considerable discussion has been made in face-to-face meetings and some discussion has also occured .. [#f2] Considerable discussion has been made in face-to-face meetings and some discussion has also occured
on the DBus mailing list: http://lists.freedesktop.org/archives/dbus/2007-August/008290.html on the D-Bus mailing list: http://lists.freedesktop.org/archives/dbus/2007-August/008290.html
Enumeration of Types Enumeration of Types
==================== ====================
@ -89,11 +89,11 @@ The Basic Types
of UTF-8 is expected and encouraged. of UTF-8 is expected and encouraged.
**Object Path** **Object Path**
A DBus object path, exactly as described in the DBus specification. A D-Bus object path, exactly as described in the D-Bus specification.
**Signature** **Signature**
A DBus signature string, exactly as described in the DBus specification. As this type A D-Bus signature string, exactly as described in the D-Bus specification. As this type
has been preserved solely for compatibility with DBus, all of the DBus restrictions has been preserved solely for compatibility with D-Bus, all of the D-Bus restrictions
on the range of values of this type apply (eg: nesting depth and maximum length on the range of values of this type apply (eg: nesting depth and maximum length
restrictions). restrictions).
@ -119,7 +119,7 @@ Container Types
The structure type constructor allows the creation of structure types corresponding The structure type constructor allows the creation of structure types corresponding
to the provided element types. These “structures” are actually closer to tuples in the to the provided element types. These “structures” are actually closer to tuples in the
sense that their fields are not named, but “structure” is used because that is what sense that their fields are not named, but “structure” is used because that is what
the DBus specification calls them. the D-Bus specification calls them.
The structure type constructor is the only type constructor that is variadic — any The structure type constructor is the only type constructor that is variadic — any
natural number of types may be given (including zero and one). natural number of types may be given (including zero and one).
@ -127,7 +127,7 @@ Container Types
**Dictionary entry** **Dictionary entry**
The dictionary entry type constructor allows the creation of a special sort of structure The dictionary entry type constructor allows the creation of a special sort of structure
which, when used as the element type of an array, implies that the content of the array which, when used as the element type of an array, implies that the content of the array
is a list of key/value pairs. For compatibility with DBus, this binary type constructor is a list of key/value pairs. For compatibility with D-Bus, this binary type constructor
requires a basic type as its first argument (which by convention is seen to be the key) requires a basic type as its first argument (which by convention is seen to be the key)
but any type is acceptable for the second argument (by convention, the value). but any type is acceptable for the second argument (by convention, the value).
@ -138,12 +138,12 @@ Container Types
Type Strings Type Strings
============ ============
Just as with DBus, a concise string representation is used to express types. Just as with D-Bus, a concise string representation is used to express types.
In GVariant, which deals directly with values as first order objects, a type string (by that In GVariant, which deals directly with values as first order objects, a type string (by that
name) is a string representing a single type. name) is a string representing a single type.
Contrast this with “signature strings” [#f3]_ in DBus, which apply to messages, and contain Contrast this with “signature strings” [#f3]_ in D-Bus, which apply to messages, and contain
zero or more types (corresponding to the arguments of the message). zero or more types (corresponding to the arguments of the message).
.. [#f3] Compare with the whence parameter to the ``lseek()`` system call. .. [#f3] Compare with the whence parameter to the ``lseek()`` system call.
@ -213,24 +213,24 @@ Serialisation Format
This chapter describes the serialisation format that is used by GVariant. This serialisation This chapter describes the serialisation format that is used by GVariant. This serialisation
format is newly developed and described for the first time here. format is newly developed and described for the first time here.
Why not DBus? Why not D-Bus?
============= ==============
Since GVariant is largely compatible with DBus, it would make sense to use the Since GVariant is largely compatible with D-Bus, it would make sense to use the
serialisation format of DBus (plus modifications where appropriate) as the serialisation serialisation format of D-Bus (plus modifications where appropriate) as the serialisation
format for GVariant. format for GVariant.
To do so, however, would conflict with a number of requirements that were established To do so, however, would conflict with a number of requirements that were established
for GVariant. for GVariant.
Most fundamentally, the requirements would be violated. DBus messages are encoded in such Most fundamentally, the requirements would be violated. D-Bus messages are encoded in such
a way that in order to fetch the 100th item out of an array you first have to iterate over a way that in order to fetch the 100th item out of an array you first have to iterate over
the first 99 items to discover where the 100th item lies. A side effect of this iteration the first 99 items to discover where the 100th item lies. A side effect of this iteration
would be a violation of the requirements. would be a violation of the requirements.
Additionally, using the DBus serialisation format with an API like that mandated by Additionally, using the D-Bus serialisation format with an API like that mandated by
the requirements would likely imply a violation of the requirements due to the fact that subparts the requirements would likely imply a violation of the requirements due to the fact that subparts
of DBus messages can change meaning when subjected to different starting alignments. of D-Bus messages can change meaning when subjected to different starting alignments.
This is discussed in more detail in `Simple Containment`_. This is discussed in more detail in `Simple Containment`_.
Notation Notation
@ -305,8 +305,8 @@ This property permits a container to be deconstructed into child values simply b
referencing a subsequence of the byte sequence of the container as the value of the referencing a subsequence of the byte sequence of the container as the value of the
child which is an effective way of satisfying the requirements. child which is an effective way of satisfying the requirements.
This property is not the case for the DBus serialisation format. In many cases (for This property is not the case for the D-Bus serialisation format. In many cases (for
example, arrays) the encoding of a child value of a DBus message will change depending example, arrays) the encoding of a child value of a D-Bus message will change depending
on the context in which that value appears. As an example: in the case of an array of on the context in which that value appears. As an example: in the case of an array of
doubles, should the value immediately preceding the array end on an offset that is an doubles, should the value immediately preceding the array end on an offset that is an
even multiple of 8 then the array will contain 4 padding bytes that it would not contain even multiple of 8 then the array will contain 4 padding bytes that it would not contain
@ -857,7 +857,7 @@ these problems then it is not in normal form.
byte then the default value is used. byte then the default value is used.
**Invalid Signature** **Invalid Signature**
If the serialised form of a signature string is not a valid DBus signature followed by If the serialised form of a signature string is not a valid D-Bus signature followed by
a zero byte then the default value is used. a zero byte then the default value is used.
**Wrong Size for Fixed Size Maybe** **Wrong Size for Fixed Size Maybe**