Changeset 25877 in project for wiki/eggref/4/dbus

Timestamp:

02/08/12 12:08:15 (9 years ago)

Author:

Mario Domenech Goulart

Message:

dbus (wiki): semantic markup

File:

• wiki/eggref/4/dbus (modified) (4 diffs)

wiki/eggref/4/dbus

@@ -35 +35 @@
 === Requirements
 
-[[http://dbus.freedesktop.org/|libdbus and its headers]]; [[http://srfi.schemers.org/srfi-18/srfi-18.html|SRFI-18]]
+[[http://dbus.freedesktop.org/|libdbus and its headers]]
 
 
@@ -105 +105 @@
 === Exported functions
 
-dbus:make-context : glom together a bus, service, interface and path into an object that you can conveniently hold for later use.  The choices for bus are dbus:session-bus (which is the default if you don't specify it), dbus:system-bus and dbus:starter-bus.  The service, interface and path can be given as strings or symbols.  Symbols would be preferred; if you provide strings, dbus:make-context will convert them to symbols.  The default for path is "/" so if you don't need a hierarchical organization of "objects", you don't need to specify it.
-
-dbus:send : send a signal.
-
-dbus:make-sender : wrap dbus:send in a lambda, which you can then use like any local function.  The return value from the function thus created is not yet defined.  (Maybe should be #f or an error message?  or is it better to use exceptions when something cannot be sent?)
-
-dbus:call : call a remote method, wait for the reply, and receive the return values from the remote method, as a list.  Note that since this is a blocking call (it waits for the reply), it's not suitable for implementing the [[http://en.wikipedia.org/wiki/Actor_model|actor model]] or anything similarly lightweight/low-latency.
-
-dbus:make-method-proxy : wrap dbus:call in a lambda, which you can then use like any local function.  The return value from the function thus created will be the list of return values from the remote method.
-
-dbus:register-signal-handler : provide a handler to be called when the current process receives a DBus signal which matches the given context and the given signal name.  Start a SRFI-18 thread to poll for incoming signals (unless polling has been disabled on this bus).
-
-dbus:register-method : provide a handler (a method body) to be called when the current process receives a DBus message which matches the given context and the given method name.  Start a SRFI-18 thread to poll for incoming messages (unless polling has been disabled on this bus).
-
-dbus:enable-polling-thread! : enable or disable the polling thread for a particular bus, and set the polling interval in seconds
-
-dbus:poll-for-message : check once whether any incoming DBus message is waiting on a particular bus, and if so, dispatch it to the appropriate callback (which you have previously registered using dbus:register-method or dbus:register-signal-handler).  Returns #t if it received a message, #f if not.
-
-dbus:discover-services : get a list of service names available on a bus
-
-dbus:discover-api-xml : get the XML API "documentation" provided by the Introspectable interface of a service, if that interface is implemented
+<procedure>(dbus:make-context dbus:make-context #!key (bus dbus:session-bus) service interface (path "/"))</procedure>
+
+Glom together a bus, service, interface and path into an object that
+you can conveniently hold for later use.  The choices for bus are
+{{dbus:session-bus}} (which is the default if you don't specify it),
+{{dbus:system-bus}} and {{dbus:starter-bus}}.  The service, interface
+and path can be given as strings or symbols.  Symbols would be
+preferred; if you provide strings, {{dbus:make-context}} will convert
+them to symbols.  The default for path is "/" so if you don't need a
+hierarchical organization of "objects", you don't need to specify it.
+
+
+<procedure>(dbus:send context name . params)</procedure>
+
+Send a signal.
+
+
+<procedure>(dbus:call context name . params)</procedure>
+
+Call a remote method, wait for the reply, and receive the return
+values from the remote method, as a list.  Note that since this is a
+blocking call (it waits for the reply), it's not suitable for
+implementing the [[http://en.wikipedia.org/wiki/Actor_model|actor model]]
+or anything similarly lightweight/low-latency.
+
+
+<procedure>(dbus:make-method-proxy context name)</procedure>
+
+Wrap {{dbus:call}} in a lambda, which you can then use like any local
+function.  The return value from the function thus created will be the
+list of return values from the remote method.
+
+
+<procedure>(dbus:register-signal-handler context name msg-cb)</procedure>
+
+Provide a handler to be called when the current process receives a
+DBus signal which matches the given context and the given signal name.
+Start a SRFI-18 thread to poll for incoming signals (unless polling
+has been disabled on this bus).
+
+
+<procedure>(dbus:register-method context name msg-cb)</procedure>
+
+Provide a handler (a method body) to be called when the current
+process receives a DBus message which matches the given context and
+the given method name.  Start a SRFI-18 thread to poll for incoming
+messages (unless polling has been disabled on this bus).
+
+
+<procedure>(dbus:enable-polling-thread! #!key (bus dbus:session-bus) (enable #t) (interval default-polling-interval))</procedure>
+
+Enable or disable the polling thread for a particular bus, and set the
+polling interval in seconds
+
+
+<procedure>(dbus:poll-for-message #!key (bus dbus:session-bus) (timeout 0))</procedure>
+
+Check once whether any incoming DBus message is waiting on a
+particular bus, and if so, dispatch it to the appropriate callback
+(which you have previously registered using {{dbus:register-method}}
+or {{dbus:register-signal-handler}}).  Returns {{#t}} if it received a
+message, {{#f}} if not.
+
+
+<procedure>(dbus:discover-services #!key (bus dbus:session-bus))</procedure>
+
+Get a list of service names available on a bus
+
+
+<procedure>(dbus:discover-api-xml ctxt)</procedure>
+
+Get the XML API "documentation" provided by the Introspectable
+interface of a service, if that interface is implemented
+
 
 === Examples
@@ -133 +186 @@
 ==== Examples you can test with QT
 
-QT includes a DBUS remote-controlled car example.  E.g. it might be located in /usr/share/qt4/examples/qdbus/remotecontrolledcar/car depending on your distro.  If you run the car, you can cause the wheels of the car to turn to the right by doing this:
+QT includes a DBUS remote-controlled car example.  E.g. it might be located in {{/usr/share/qt4/examples/qdbus/remotecontrolledcar/car}} depending on your distro.  If you run the car, you can cause the wheels of the car to turn to the right by doing this:
 
 <enscript highlight=scheme>
@@ -165 +218 @@
 
 (let loop ()
-        (dbus:poll-for-message)
-        (loop))
-</enscript>
-
-dbus:register-method starts a polling loop the first time that it is called with a context specifying a particular bus.  (And if you register methods on multiple buses, there must be a polling thread for each.)  So you can then run the program above which does dbus:send, and you will see the appropriate printf statement execute asynchronously when the message is received.  However the polling thread is subject to the usual limitations of Chicken threads: if there is any blocking I/O, which is waiting for something, then all threads are blocked.  That means you should not use the readline egg for example, because the polling thread will be blocked between each time that you type something and hit Enter.
-
-If the polling thread doesn't work, and you would prefer to poll manually, you can call (dbus:enable-polling-thread! enable: #f) to stop the thread (or to prevent it from being started when you register a new method), and then call dbus:poll-for-message periodically.  Both of those functions can take an optional bus: parameter (which defaults to dbus:session-bus, naturally).  dbus:poll-for-message can also take an optional timeout: parameter (which is 0 by default, so that it is a non-blocking call).
+  (dbus:poll-for-message)
+  (loop))
+</enscript>
+
+{{dbus:register-method}} starts a polling loop the first time that it is called with a context specifying a particular bus.  (And if you register methods on multiple buses, there must be a polling thread for each.)  So you can then run the program above which does {{dbus:send}}, and you will see the appropriate printf statement execute asynchronously when the message is received.  However the polling thread is subject to the usual limitations of Chicken threads: if there is any blocking I/O, which is waiting for something, then all threads are blocked.  That means you should not use the readline egg for example, because the polling thread will be blocked between each time that you type something and hit Enter.
+
+If the polling thread doesn't work, and you would prefer to poll manually, you can call {{(dbus:enable-polling-thread! enable: #f)}} to stop the thread (or to prevent it from being started when you register a new method), and then call {{dbus:poll-for-message periodically}}.  Both of those functions can take an optional bus: parameter (which defaults to {{dbus:session-bus}}, naturally).  {{dbus:poll-for-message}} can also take an optional timeout: parameter (which is 0 by default, so that it is a non-blocking call).
 
 ==== Examples based on the DBus Tutorial