norisatir/go-dbus — pull request #3 by bmatsuo (2012-01-11 07:35:27+00:00)
Title: Objectify API

Description
========

This patch will alter the top level API. It would be prudent to **discuss it before merging** into the master repository. The test code in the patch is altered for the new API, as is the README example.

Aside from these changes, I refactored the test code in [dbus_test.go](https://github.com/bmatsuo/go-dbus/blob/objectify-api/dbus_test.go) while I was fixing API calls. It's now a table-driven test that allows more method-call tests to be written.

I've also introduced two new types which I discuss at the bottom of this document.

Please look everything over and give me your feedback. An important part of this should process be planning for future changes the API needs (there are certainly a few).

Thanks.

Changes
=======

Changes to the existing API affect the *Connection interface. *Object and *Interface have new methods, but otherwise function the same way.

Connection.Interface
------------------------------

The Connection.Interface method is now Object.Interface. The method did not rely on the connection. Using it as a *Connection method only made things more cumbersome.

Method calls and signal emitting
-----------------------------------------------

The way methods/signals are called/emitted has changed. A method/signal is obtained from *Interface, using method Method/Signal. This object is then passed to the *Connection method Call/Emit (formerly CallMethod/EmitSignal) along with a list of arguments. The new Call/Emit API is outlined in [the updated README](https://github.com/bmatsuo/go-dbus/tree/objectify-api#readme).

Signal handling
----------------------

The Connection.AddSignalHandler method has been renamed Connection.Handle. It is slightly more ambiguous. It could be renamed Connection.HandleSignal. I think a more appropriate solution might be let it be named Connection.Handle, but make its argument a 'SignalHandler'. I don't think this type exists (not publicly). But a simple wrapper could take care of that.

New types
---------------

Finally, there are new types Method and Signal. These types combine *Interface objects with MethodData/SignalData objects. This solution is probably not ideal. The MethodData and SignalData types should probably not be exported (either before this request is merged, or sometime in the near future).