Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

Generic Remote Process Communication (RPC)


Data Structures

struct  osso_rpc_t

Typedefs

typedef gint( osso_rpc_cb_f )(const gchar *interface, const gchar *method, GArray *arguments, gpointer data, osso_rpc_t *retval)
typedef void( osso_rpc_async_f )(const gchar *interface, const gchar *method, osso_rpc_t *retval, gpointer data)

Functions

osso_return_t osso_rpc_run (osso_context_t *osso, const gchar *service, const gchar *object_path, const gchar *interface, const gchar *method, osso_rpc_t *retval, int argument_type,...)
osso_return_t osso_rpc_run_with_defaults (osso_context_t *osso, const gchar *application, const gchar *method, osso_rpc_t *retval, int argument_type,...)
osso_return_t osso_rpc_async_run (osso_context_t *osso, const gchar *service, const gchar *object_path, const gchar *interface, const gchar *method, osso_rpc_async_f *async_cb, gpointer data, int argument_type,...)
osso_return_t osso_rpc_async_run_with_defaults (osso_context_t *osso, const gchar *application, const gchar *method, osso_rpc_async_f *async_cb, gpointer data, int argument_type,...)
osso_return_t osso_rpc_set_cb_f (osso_context_t *osso, const gchar *service, const gchar *object_path, const gchar *interface, osso_rpc_cb_f *cb, gpointer data)
osso_return_t osso_rpc_set_default_cb_f (osso_context_t *osso, osso_rpc_cb_f *cb, gpointer data)
osso_return_t osso_rpc_unset_cb_f (osso_context_t *osso, const gchar *service, const gchar *object_path, const gchar *interface, osso_rpc_cb_f *cb, gpointer data)
osso_return_t osso_rpc_unset_default_cb_f (osso_context_t *osso, osso_rpc_cb_f *cb, gpointer data)
osso_return_t osso_rpc_get_timeout (osso_context_t *osso, gint *timeout)
osso_return_t osso_rpc_set_timeout (osso_context_t *osso, gint timeout)

Detailed Description

These functions provide a wrapper for DBUS messages.

Typedef Documentation

typedef void( osso_rpc_async_f)(const gchar *interface, const gchar *method, osso_rpc_t *retval, gpointer data)
 

This is the type for the asyncronous rpc return handler. This function is called when the asynchronous function returns.

Parameters:
interface The interface of the called method.
method The method that was called.
retval.The value that was returned.
data An application specific pointer.

typedef gint( osso_rpc_cb_f)(const gchar *interface, const gchar *method, GArray *arguments, gpointer data, osso_rpc_t *retval)
 

This is the type for the generic rpc handler. This function is called every time a method is requested on thr registered interface.

Parameters:
interface The interface that the method is called on.
method The method that is called.
arguments A GArray of osso_rpc_t structures.
retval The return value of the method. This should be set to DBUS_TYPE_INVALID for no reply.
data An application specific pointer.
Returns:
OSSO_OK if the function executed successfully. retval is set to DBUS_TYPE_INVALID for no reply. OSSO_ERROR, if an error occured, a dbus_error will be returned, and the retval should be of type DBUS_TYPE_STRING with an error message string as value.


Function Documentation

osso_return_t osso_rpc_async_run osso_context_t osso,
const gchar *  service,
const gchar *  object_path,
const gchar *  interface,
const gchar *  method,
osso_rpc_async_f async_cb,
gpointer  data,
int  argument_type,
  ...
 

This function sends a message to an other application, using D-BUS with asyncronous return value if needed. This function will try to activate the application that has registered the service with the D-BUS daemon, by using the D-BUS auto-activation feature.

Parameters:
osso The library context as returned by osso_initialize.
service The service name of the target. e.g. com.nokia.application
object_path The object path of the target object.
interface The interface that the method belongs to.
method The method to call
async_cb A pointer to a function to be called when the method returns. If the call timeouts async_cb will be called with an error, generated by the D-BUS library. If this is NULL this function behaves just like osso_rpc_run, with the argument retval set to NULL. with the argument retval set to NULL.
data An application specific pointer that is given to the cb function.
argument_type The type of the first argument.
... The first argument value, and then a list of other arguments. See osso_rpc_run for more information.
Returns:
OSSO_OK if the message was sent. OSSO_INVALID if a parameter is invalid, and OSSO_ERROR if an error occurs (like failure to send the message)

osso_return_t osso_rpc_async_run_with_defaults osso_context_t osso,
const gchar *  application,
const gchar *  method,
osso_rpc_async_f async_cb,
gpointer  data,
int  argument_type,
  ...
 

This function sends a message to an other application, using D-BUS with asyncronous return value if needed. The service is defaulted to 'com.nokia.{application}', the object path is set to '/com/nokia/{application}' and the interface is defaulted to 'com.nokia.{application}'. This function will try to activate the application, by using the D-BUS auto-activation feature.

Parameters:
osso The library context as returned by osso_initialize.
application The name of the application to call the method on
method The method to call
async_cb A pointer to a function to be called when the method returns. If the call timeouts async_cb will be called with an error, generated by the D-BUS library. If this is NULL this function behaves just like osso_rpc_run_with_defaults, with the argument retval set to NULL.
data An application specific pointer that is given to the cb function.
argument_type The type of the first argument.
... The first argument value, and then a list of other arguments. See osso_rpc_run for more information.
Returns:
OSSO_OK if the message was sent. OSSO_INVALID if a parameter is invalid, and OSSO_ERROR if an error occurs (like failure to send the message)

osso_return_t osso_rpc_get_timeout osso_context_t osso,
gint *  timeout
 

Sets the timeout value used by rpc functions.

Parameters:
osso The library context as returned by osso_initialize.
timeout The new timeout value.
Returns:
OSSO_OK on success. OSSO_INVALID if osso is invalid

osso_return_t osso_rpc_run osso_context_t osso,
const gchar *  service,
const gchar *  object_path,
const gchar *  interface,
const gchar *  method,
osso_rpc_t retval,
int  argument_type,
  ...
 

This function sends a message to an other application, using D-BUS with syncronous return value if needed. This function will try to activate the application that has registered the service with the D-BUS daemon, by using the D-BUS auto-activation feature.

The variable arguments work in a type - value pairs. The type defines the value. If the type is G_TYPE_STRING, then the value is a pointer to a string. The list must end in a DBUS_TYPE_INVALID. The supported types are:

  • DBUS_TYPE_BOOLEAN
    • The value is a gboolean.
  • DBUS_TYPE_INT, DBUS_TYPE_UINT
    • The value is an int or an unsigned int.
  • DBUS_TYPE_DOUBLE
    • The value is a float.
  • DBUS_TYPE_STRING
    • The value is a pointer to a string.
    • If the pointer is NULL it is translated to a DBUS_TYPE_NIL.
  • DBUS_TYPE_NIL
    • No value, this represents a NULL type.
      Parameters:
      osso The library context as returned by osso_initialize.
      service The service name of the target. e.g. com.nokia.application
      object_path The object path of the target object.
      interface The interface that the method belongs to.
      method The method to call
      retval A pointer to a structure where the return value can be stored. If a reply is not interesting, or not desired, this can be set to NULL. When this is non null the call blocks for a while to wait for the return value. If the expected reply doesn't come within the timeout value set with the osso_rpc_set_timeout function, OSSO_ERROR will be returned and the retval variable will be set to OSSO_RPC_ERROR. If NULL is given the function returns when the message is sent.
      argument_type The type of the first argument.
      ... The first argument value, and then a list of other arguments. This list must end in a DBUS_TYPE_INVALID type.
      Returns:
      OSSO_OK if the message was sent. OSSO_INVALID if a parameter is invalid. If the remote method returns an error, or does not return anything, then OSSO_ERROR is returned, and retval is set to an error message. OSSO_ERROR is also returned if any other kind of error occures, like IO error.

osso_return_t osso_rpc_run_with_defaults osso_context_t osso,
const gchar *  application,
const gchar *  method,
osso_rpc_t retval,
int  argument_type,
  ...
 

This function is a wrapper for osso_rpc_run. It calls a remote method on the destination. The service is defaulted to 'com.nokia.{application}', the object path is set to '/com/nokia/{application}' and the interface is defaulted to 'com.nokia.{application}'. This function will try to activate the application, by using the D-BUS auto-activation feature.

Parameters:
osso The library context as returned by osso_initialize.
application The name of the application to call the method on
method The method to call
retval A pointer to a structure where the return value can be stored. If a reply is not interesting, or not desired, this can be set to NULL. When this is non null the call blocks for a while to wait for the return value. If the expected reply doesn't come within the timeout value set with the osso_rpc_set_timeout function, OSSO_ERROR will be returned and the retval variable will be set to OSSO_RPC_ERROR.
argument_type The type of the first argument.
... The first argument value, and then a list of other arguments. See osso_rpc_run for more information.
Returns:
OSSO_OK if the message was sent. OSSO_INVALID if a parameter is invalid. If the remote method returns an error, or does not return anything, then OSSO_ERROR is returned, and retval is set to an error message. OSSO_ERROR is also returned if any other kind of error occures, like IO error.

osso_return_t osso_rpc_set_cb_f osso_context_t osso,
const gchar *  service,
const gchar *  object_path,
const gchar *  interface,
osso_rpc_cb_f cb,
gpointer  data
 

This function registers a function to handle specific method calls with the given interface reachable by the give object path and service name.

Parameters:
osso The library context as returned by osso_initialize.
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.
cb The function that handles the method calls.
data An application specific pointer that is given to the cb function.
Returns:
OSSO_OK if the service could be set up. OSSO_INVALID if a parameter is invalid, and OSSO_ERROR if an error occurs (like IO)

osso_return_t osso_rpc_set_default_cb_f osso_context_t osso,
osso_rpc_cb_f cb,
gpointer  data
 

This function registers a function to handle specific method calls to the default service of 'com.nokia.{application}'.

Parameters:
osso The library context as returned by osso_initialize.
cb The function that handles the method calls.
data An application specific pointer that is given to the cb function.
Returns:
OSSO_OK if the new service was set up. OSSO_INVALID if a parameter is invalid, and OSSO_ERROR if an error occurs (like IO)

osso_return_t osso_rpc_set_timeout osso_context_t osso,
gint  timeout
 

Returns the current timeout value.

Parameters:
osso The library context as returned by osso_initialize.
timeout A pointer where to return the timeout value.
Returns:
OSSO_OK on success. OSSO_INVALID if osso is invalid

osso_return_t osso_rpc_unset_cb_f osso_context_t osso,
const gchar *  service,
const gchar *  object_path,
const gchar *  interface,
osso_rpc_cb_f cb,
gpointer  data
 

This function unregisters a function to handle specific method calls.

Parameters:
osso The library context as returned by osso_initialize.
service The service name to unregister. e.g. com.nokia.application
object_path The object path that this object has.
interface The interface that this object implements.
cb The function that was registered.
data The same pointer that was used with the osso_rpc_set_default_cb_f call
Returns:
OSSO_OK if the new service was set up. OSSO_INVALID if a parameter is invalid, and OSSO_ERROR if an error occurs (like IO)

osso_return_t osso_rpc_unset_default_cb_f osso_context_t osso,
osso_rpc_cb_f cb,
gpointer  data
 

This function unregisters a function to handle specific method calls.

Parameters:
osso The library context as returned by osso_initialize.
cb The function that was registered.
data The same pointer that was used with the osso_rpc_set_default_cb_f call
Returns:
OSSO_OK if the new service was set up. OSSO_INVALID if a parameter is invalid, and OSSO_ERROR if an error occurs (like IO)


Generated on Tue Aug 25 08:02:14 1970 for LibOSSO by doxygen 1.3.7