The ``osso`` package
======================

Using ``Rpc``
-------------

These methods provide wrappers for D-BUS message passing.

Methods
-------
*rpc_run*

  This function calls an RPC function of an other application.
  This call is blocking. If the application providing the
  function is not already running, it will be started by the
  D-BUS auto-activation mechanism.

  ``osso.Rpc.rpc_run(service, object_path, interface, method,
  rpc_args = (), wait_reply = False, system_bus = False)``

  - ``service:     The service name of the remote service,
    e.g. "com.nokia.application".``
  - ``object_path: The object path of the remote object.``
  - ``interface:   The interface that the RPC function belongs
    to.``
  - ``method:      The RPC function to call.``
  - ``rpc_args (optional):   Tuple containing the RPC arguments,
    if it has any. No arguments are sent by default.``
  - ``wait_reply (optional): Whether a reply (return value) is
    being expected or not. Default value is False.``
  - ``system_bus (optional): Whether the RPC call should be sent
    on the system bus or not. Default value is False.``

*rpc_run_with_defaults*

  This method is a wrapper for osso.Context.rpc_run. It calls
  an RPC function of an other application. This call is blocking.
  The service name of the other application is "com.nokia.A",
  where A is the application parameter passed to this function.
  Similarly, the object path is "/com/nokia/A", and the interface
  "com.nokia.A". If the application providing the service is not
  already running, it will be started by the D-BUS auto-activation
  mechanism.

  ``osso.Rpc.rpc_run_with_defaults(application, method,
  rpc_args = (), wait_reply = False)``

  - ``application: The name of the remote application.``
  - ``method:      The RPC function to call.``
  - ``rpc_args (optional):   Tuple containing the RPC arguments,
    if it has any. No arguments are sent by default.``
  - ``wait_reply (optional): Whether a reply (return value) is
    being expected or not. Default value is False.``

*rpc_async_run*

  This method calls an RPC function of an other application.
  This call is non-blocking; a callback function is registered
  for the return value of the called RPC function. If the
  application providing the service is not already running,
  it will be started by the D-BUS auto-activation mechanism.

  ``osso.Rpc.rpc_async_run(service, object_path, interface,
  method, callback, user_data = None, rpc_args = ())``

  - ``service: The service name of the remote service, e.g.
    "com.nokia.application".``
  - ``object_path: The object path of the remote object.``
  - ``interface: The interface that the RPC function belongs to.``
  - ``method:    The RPC function to call.``
  - ``callback:  A a function to be called when the call returns.
    If the call times out, callback will be called with an error
    generated by the D-BUS library. If this is None, this method
    behaves just like osso.Context.rpc_run, with wait_reply set
    to False.``
  - ``user_data (optional): Arbitrary application specific
    object that will be passed to the callback and ignored by
    LibOSSO.``
  - ``rpc_args (optional): Tuple containing the RPC arguments,
    if it has any. No arguments are sent by default.``

*rpc_async_run_with_defaults*

  ``osso.Rpc.rpc_async_run_with_defaults(application, method,
  callback, user_data = None, rpc_args = ())``

  - ``application: The name of the remote application.``
  - ``method:      The RPC function to call.``
  - ``callback:    A function to be called when the call returns.
    If the call times out, callback will be called with an error
    generated by the D-BUS library. If this is None, this method
    behaves just like osso.Context.rpc_run, with wait_reply set
    to False.``
  - ``user_data (optional): Arbitrary application specific
    object that will be passed to the callback and ignored by
    LibOSSO.``
  - ``rpc_args (optional):  Tuple containing the RPC arguments,
    if it has any. No arguments are sent by default.``

*set_rpc_callback*

  This method registers/unregisters a callback function for
  handling RPC calls to a given object of a service.

  The callback function will receive the following parameters:
  interface, method, arguments and user_data (in that order).

  ``osso.Rpc.set_rpc_callback(service, object_path, interface,
  callback, user_data = None)``

  - ``service:     The service name to set up, e.g.
    "com.nokia.application".``
  - ``object_path: The object path that this object has.``
  - ``interface:   The interface that this object implements.``
  - ``callback:    The function to register. Use None to
    unregister.``
  - ``user_data (optional): Arbitrary application specific object
    that will be passed to the callback and ignored by LibOSSO.``

*set_rpc_default_callback*

  This method registers a callback function for handling RPC
  calls to the default service of the application. The default
  service is "com.nokia.A", where A is the application's name
  as given in the constructor.

  The callback function will receive the following parameters:
  interface, method, arguments and user_data (in that order).

  ``osso.Rpc.set_rpc_default_callback(callback, user_data = None)``

  - ``callback:	The function to register. Use None to unregister.``
  - ``user_data (optional): Arbitrary application specific object
    that will be passed to the callback and ignored by LibOSSO.``

*get_rpc_timeout*

  Return the timeout value used by RPC methods.

  ``osso.Rpc.get_rpc_timeout()``

  - ``Returns: Timeout value used by RPC methods.``

*set_rpc_timeout*

  Sets the timeout value used by RPC methods.

  ``osso.Rpc.set_rpc_timeout(timeout)``

  - ``timeout: Timeout value used by RPC methods.``

Example
-------
**TODO**
