Introduction to D-BUS

[Thiago Macieira]

Jeroen T. Vermeulen wrote:
>> Yes. However, a proper interface introspection will list the canonical
>> argument types. Whether the binding will accept other arguments or not
>> is purely up to the binding.
>
>So even if there are multiple methods of the same name in an interface,
>one of them is still the "canonical" one?

No, I meant methods with the same name across interfaces. Overloading of 
methods with the same name in the same object (whether in the same 
interface or not) is not interoperable.

An implementation should be able to call any method on a remote interface 
with any arbitrary argument list. But we've seen that implementing those 
methods isn't easy for some languages.

>> Yep, that's the empty interface name. The binding is required to
>> deliver the call if it can, but it can reject if it's ambiguous (or it
>> could deliver arbitrarily to one interface, if there's such a
>> difference).
>
>Then the binding is part of what the specification calls the
>"implementation," right?

Right. The libdbus library does the protocol stuff: alignment, endianness, 
connection, authentication, proper ordering, etc.

The binding is the thing that sits between the library and the user code. 
It's the one that is responsible for making libdbus easy for the user to 
use: generally it does that by mapping the D-Bus and libdbus concepts 
into the language's object, type and function calling system.

>> If you're using a well-defined interface introspection and you expect
>> interoperability, you follow rules like these:
>> * The callee MUST accept the correct parameter types.
>> * The callee MUST return the correct parameter types.
>> * If the input parameter types don't match, the callee MUST either
>> reject with an error or convert them (kinda obvious, but...)
>>
>> The caller MUST use the correct parameter types. Using of wrong types
>> results in undefined behaviour.
>
>I'm assuming that "correct" here is not necessarily the same as
>"canonical"...  So could I say that "well-defined interface
> introspection" is, in effect, an optional layer of specification for
> what bindings can and cannot do?

I mean this:

if the introspection says:
<interface name="com.example.Foo">
  <method name="Bar">
    <arg type="i" name="id" direction="in"/>
    <arg type="av" name="data" direction="in"/>
    <arg type="b" name="ok" direction="out"/>
    <arg type="av" name="data" direction="out"/>
  </method>
</interface>

Then the callee implementation MUST:
1) accept any calls to com.example.Foo.Bar with exactly two arguments: one 
INT32 and one ARRAY of VARIANT
2) always reply, by either:
  a) exactly two arguments, one of type BOOLEAN and one of type ARRAY of 
VARIANT
  b) an error message

An implementation could conceivably also allow (list not exhaustive):
* calls with one or more argument missing (e.g., create an empty array)
* calls with different argument types (e.g., it could convert a UINT16 to 
INT32, a ARRAY of STRING into ARRAY of VARIANT, etc.)
* calls with more, superfluous arguments (i.e., drop them)
* calls with badly-ordered argument list

I'd say that a conforming implementation should reject any such messages.

For the caller implementation, it:
1) MUST place calls with exactly two arguments: one INT32 and one ARRAY of 
VARIANT
2) SHOULD validate the return types and convert to error if the types 
mismatch (count or types)

Nothing of this sort is stated in the specification. This is just my 
thinking of how implementations intending to be interoperable should 
work.

>> Signals may also be overloaded (nothing in the spec or the library
>> prevents them from being so), but for semantic purposes, they should
>> share some commonality. I'd say that all overloads of the same signal
>> should be emitted at the same time, since they probably contain
>> different aspects of the same information.
>>
>> But the same applies:
>> * Signals MUST be emitted with the correct parameter types.
>
>And must all bindings be able to handle them in that case, and dispatch
>them to a listening program on their end?

That's a good question. We know that overloading of argument lists can 
cause some interoperability problems for method calls. I don't know about 
signals. The difference here is that you ask to listen to a specific 
signal, so the implementations may be able to filter the incoming 
messages to what they want.

The Qt binding is capable of listening to any signal as long as one part 
of the identification (service, object path, interface, signal name, 
argument signature) isn't a wildcard, except for the argument signature.

-- 
  Thiago Macieira  -  thiago (AT) macieira.info - thiago (AT) kde.org
    PGP/GPG: 0x6EF45358; fingerprint:
    E067 918B B660 DBD1 105C  966C 33F5 F005 6EF4 5358
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/dbus/attachments/20060829/b557d28a/attachment-0001.pgp