Changeset 25877 in project


Ignore:
Timestamp:
02/08/12 12:08:15 (8 years ago)
Author:
Mario Domenech Goulart
Message:

dbus (wiki): semantic markup

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/dbus

    r25876 r25877  
    3535=== Requirements
    3636
    37 [[http://dbus.freedesktop.org/|libdbus and its headers]]; [[http://srfi.schemers.org/srfi-18/srfi-18.html|SRFI-18]]
     37[[http://dbus.freedesktop.org/|libdbus and its headers]]
    3838
    3939
     
    105105=== Exported functions
    106106
    107 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.
    108 
    109 dbus:send : send a signal.
    110 
    111 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?)
    112 
    113 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.
    114 
    115 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.
    116 
    117 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).
    118 
    119 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).
    120 
    121 dbus:enable-polling-thread! : enable or disable the polling thread for a particular bus, and set the polling interval in seconds
    122 
    123 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.
    124 
    125 dbus:discover-services : get a list of service names available on a bus
    126 
    127 dbus:discover-api-xml : get the XML API "documentation" provided by the Introspectable interface of a service, if that interface is implemented
     107<procedure>(dbus:make-context dbus:make-context #!key (bus dbus:session-bus) service interface (path "/"))</procedure>
     108
     109Glom together a bus, service, interface and path into an object that
     110you can conveniently hold for later use.  The choices for bus are
     111{{dbus:session-bus}} (which is the default if you don't specify it),
     112{{dbus:system-bus}} and {{dbus:starter-bus}}.  The service, interface
     113and path can be given as strings or symbols.  Symbols would be
     114preferred; if you provide strings, {{dbus:make-context}} will convert
     115them to symbols.  The default for path is "/" so if you don't need a
     116hierarchical organization of "objects", you don't need to specify it.
     117
     118
     119<procedure>(dbus:send context name . params)</procedure>
     120
     121Send a signal.
     122
     123
     124<procedure>(dbus:call context name . params)</procedure>
     125
     126Call a remote method, wait for the reply, and receive the return
     127values from the remote method, as a list.  Note that since this is a
     128blocking call (it waits for the reply), it's not suitable for
     129implementing the [[http://en.wikipedia.org/wiki/Actor_model|actor model]]
     130or anything similarly lightweight/low-latency.
     131
     132
     133<procedure>(dbus:make-method-proxy context name)</procedure>
     134
     135Wrap {{dbus:call}} in a lambda, which you can then use like any local
     136function.  The return value from the function thus created will be the
     137list of return values from the remote method.
     138
     139
     140<procedure>(dbus:register-signal-handler context name msg-cb)</procedure>
     141
     142Provide a handler to be called when the current process receives a
     143DBus signal which matches the given context and the given signal name.
     144Start a SRFI-18 thread to poll for incoming signals (unless polling
     145has been disabled on this bus).
     146
     147
     148<procedure>(dbus:register-method context name msg-cb)</procedure>
     149
     150Provide a handler (a method body) to be called when the current
     151process receives a DBus message which matches the given context and
     152the given method name.  Start a SRFI-18 thread to poll for incoming
     153messages (unless polling has been disabled on this bus).
     154
     155
     156<procedure>(dbus:enable-polling-thread! #!key (bus dbus:session-bus) (enable #t) (interval default-polling-interval))</procedure>
     157
     158Enable or disable the polling thread for a particular bus, and set the
     159polling interval in seconds
     160
     161
     162<procedure>(dbus:poll-for-message #!key (bus dbus:session-bus) (timeout 0))</procedure>
     163
     164Check once whether any incoming DBus message is waiting on a
     165particular bus, and if so, dispatch it to the appropriate callback
     166(which you have previously registered using {{dbus:register-method}}
     167or {{dbus:register-signal-handler}}).  Returns {{#t}} if it received a
     168message, {{#f}} if not.
     169
     170
     171<procedure>(dbus:discover-services #!key (bus dbus:session-bus))</procedure>
     172
     173Get a list of service names available on a bus
     174
     175
     176<procedure>(dbus:discover-api-xml ctxt)</procedure>
     177
     178Get the XML API "documentation" provided by the Introspectable
     179interface of a service, if that interface is implemented
     180
    128181
    129182=== Examples
     
    133186==== Examples you can test with QT
    134187
    135 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:
     188QT 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:
    136189
    137190<enscript highlight=scheme>
     
    165218
    166219(let loop ()
    167         (dbus:poll-for-message)
    168         (loop))
    169 </enscript>
    170 
    171 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.
    172 
    173 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).
     220  (dbus:poll-for-message)
     221  (loop))
     222</enscript>
     223
     224{{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.
     225
     226If 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).
    174227
    175228==== Examples based on the DBus Tutorial
Note: See TracChangeset for help on using the changeset viewer.