Tutorial notes

[Matthew Johnson]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Sat, 19 Aug 2006, Jeroen T. Vermeulen wrote:

> I've been trying to work my way through the D-BUS Tutorial as a complete
> newbie, though with some basic understanding of what it and systems like
> it do (plus some experience with GLib, knowledge of Python, and a
> conceptual overview of CORBA and such).  So far I've come across various
> problems with the text that I've been asked to post here.

I've been there and done that. I was trying to use the low-level
bindings. Have you read my low-level tutorial and Java documentation? I
realise you aren't planning to write in these bindings but looking at
your questions I *hope* I may have done a bit better in explaining them.
Certainly some of your questions are specific to the glib or python
bindings (for example proxies. The Java bindings *do* feature proxies,
but only internally. You get references to interfaces, you don't know
about the implementation).

http://www.matthew.ath.cx/misc/dbus for the low-level tutorial
http://www.matthew.ath.cx/projects/dbus-doc/dbus-java/ for the java (or
replace the last '/' with '.pdf' for the non-html version).

> What follows is the list I have now.  It's not complete since I've
> switched to reading the Specification instead, which is more
> newbie-friendly.  I hope these notes will be useful in improving the text.

The fact that the Specification is more newbie-friendly than the
tutorial says a lot (specs are meant to be technically accurate and
detailed, tutorials are meant to be newbie-friendly). Thanks a lot for
these questions, this is exactly what we need before the 1.0 release.

> * Signal

A signal is a DBus message which can be emitted from a program and
received by any other program which is listening for that type of
signal.

> * Proxy

A binding-specific notion of a 'fake' local object which provides the
same methods as a remote object and when called passes them on to the
remote object (glib and python experts reply if this is wrong for you)

> * Service

The term service is being deprecated. Any process connected to the bus
can export objects which can have methods called on them, and any
process can request well-known bus names. A service used to refer to any
process which had a well-known name and exported objects.

> * Bus driver

???

> * Introspection XML file

The interfaces, objects, methods and signals which are available from a
process connected to the bus can be found via introspection. The
Introspectable.Introspect() method should be implemented by any object
exported on the bus. This will return the data in XML format (format
specified in the Specification). If you save this in a file it can be
used to generate headers for the various language bindings (glib
requires this, Java you can do so optionally, qt either requires or
provides it optionally).

> * Type signature

Again, this is only relevant in some bindings. Each thing which can be
serialized onto the bus as an argument to a call or signal has a type.
This is included in the message as a type signature. For an int32 them
signature is 'i'. For an array of string it is 'as'. For a struct
containing two ints, a map of uint23=>array of double and a string it's
'(iia{uad}s)' and so on. In Java you don't have to care about this. In
some of the other languages you have to decorate the functions with
their type signature.

> Compare this to "objects:" by far most things in the tutorial that I would
> call objects in programming practice are not objects in d-bus terms.  I'll
> be using d-bus in Python, which has its own objects, but for that I gather
> I'm expected to dive into glib as well, with its own, different and more
> restrictive notion of an object.  So what, essentially, *is* an object as
> the term is used here?  It's "an instance, not a type."  Thank you, that
> part I knew.

DBus is modelled as a program having a series of objects (as
conventionally defined as you like), and you can export some of them on
the bus; that is to say, a remote process can call some or all of it's
methods. When you export an object you give it a unique path on your
connection to be referred to.

It's actually implemented as message passing, where the messages are
just (objectpath,interface,method) tuples, but the idea is that you are
calling the interface.method method on the object exported on
objectpath. 'Communication Endpoint' is a reasonable description of
this, but conceptually DBus is meant to be about exporting objects (The
Java bindings map this directly onto Java's object model)

> As it is, I don't even have a word to set an object in the d-bus sense
> apart from the other things called object!  At least glib has GObject.

Again, this is very binding-specific. In the low-level bindings of
course there are no objects. In Java terms they really are just normal
objects that happen to have implemented a particular interface and been
exported.

> Objects may be poorly named, but they're explained.  Not so for proxies:
> the closest thing to an explanation of what proxies do (though not quite
> their first mention) is in the first sample C program, where a proxy to a
> bus is created.  There follows a paragraph called "Program initialization"
> that describes this, but it's not made clear whether it describes general
> practice or just the given example--are we *always* supposed to create a
> proxy to a bus after connecting to it?  Or is that just what this example
> happens to do?  If so, why?

I'll leave all this to the glib experts, since I assume that's what it's
written in. (and having tried to write in the glib bindings, no knowing
glib, I really don't like them. I assume they are what all good glib
programmers are used to though).

> But there is another problem: when names are introduced, there is no
> mention of the fact that names are also given to a lot of other kinds of
> objects (excuse me, entities).  Then later it turns out there are also
> "bus names" which are described as "a property of the message bus daemon."
> I think the wording there is exceedingly unfortunate: "bus names" are,
> from what we see further down, not names of buses.  Instead, they turn out
> to be names of connections.

That is badly phrased. As I said above, we are trying to phase out the
word 'service' so as not to imply that some connections to the bus are
'special' and can export things while others can't. The phrase which we
are using instead of 'service names' is 'bus names'.

> On the point of glib
>
> Also with the Python examples

Again, I'll leave these to the experts.

> That's about it.  I realize I'm being difficult.  Then again, in my
> experience one of the hardest things in the world is to take something you
> already know and see it with the eyes of one who doesn't.  That's why I
> hope a newbie's view can be useful.

No, absolutely be as difficult and picky as you like, it would be really
good to have this clear by 1.0. Also, when you do understand it, please
do contribute to the docs.

HTH,

Matt

- -- 
Matthew Johnson
http://www.matthew.ath.cx/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Made with pgp4pine 1.76

iD8DBQFE5tS9pldmHVvob7kRAjgoAJ9PNdjLNeXUc+1fnSbkKt3MntosfwCgzf7g
dZ9t67+dIILDLqbF59hkr0k=
=gtzN
-----END PGP SIGNATURE-----