Remote Procedure Calls (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)
typedef void	osso_rpc_argfill (DBusMessage *msg, void *data)
typedef void	osso_rpc_retval_free_f (osso_rpc_t *retval)
Functions
void	osso_rpc_free_val (osso_rpc_t *rpc)
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_argfill (osso_context_t *osso, const gchar *service, const gchar *object_path, const gchar *interface, const gchar *method, osso_rpc_t *retval, osso_rpc_argfill *argfill, gpointer argfill_data)
osso_return_t	osso_rpc_run_system (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_system_with_argfill (osso_context_t *osso, const gchar *service, const gchar *object_path, const gchar *interface, const gchar *method, osso_rpc_t *retval, osso_rpc_argfill *argfill, gpointer argfill_data)
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_argfill (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, osso_rpc_argfill *argfill, gpointer argfill_data)
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_with_free (osso_context_t *osso, const gchar *service, const gchar *object_path, const gchar *interface, osso_rpc_cb_f *cb, gpointer data, osso_rpc_retval_free_f *retval_free)
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_with_free (osso_context_t *osso, osso_rpc_cb_f *cb, gpointer data, osso_rpc_retval_free_f *retval_free)
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 wrappers for D-BUS message passing.

---

Typedef Documentation

typedef void osso_rpc_argfill(DBusMessage *msg, void *data)

This is the type of the function used with osso_rpc_run_with_argfill, osso_rpc_run_system_with_argfill, and osso_rpc_async_run_with_argfill to append the arguments to the D-Bus message msg.

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 value callback function. This function is called when the asynchronous function returns.

Parameters:

	interface	The interface of the remote object.
	method	The RPC function that was called.
	retval	The value that was returned. The structure pointed to by retval and its contents are only valid until the callback returns.
	data	An application specific pointer specified when the callback was registered.

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 function. This function is called every time a method is requested on the 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. This array and the osso_rpc_t values in it are only valid until the callback returns.
	retval	The return value of the method. This should be set to DBUS_TYPE_INVALID for no reply. See osso_rpc_set_cb_f and osso_rpc_free_val for how the memory associated with retval is managed.
	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.

typedef void osso_rpc_retval_free_f(osso_rpc_t *retval)

The type for functions that free the contents of a osso_rpc_t structure that is used as a retval with an RPC callback. See osso_rpc_set_cb_f_with_free.

---

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 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.

Parameters:

	osso	The library context as returned by osso_initialize.
	service	The service name of the other application, e.g. com.nokia.application.
	object_path	The object path of the target object.
	interface	The interface that the RPC function belongs to.
	method	The RPC function to call.
	async_cb	A pointer to a function to be called when the call returns. If the call times out, 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.
	data	Arbitrary application specific pointer that will be passed to the callback and ignored by Libosso.
	argument_type	The type of the first argument.
	...	The first argument value, and then a type-value list of other arguments. The list must be terminated with DBUS_TYPE_INVALID type. See osso_rpc_run for more information.

Returns:

OSSO_OK on success, OSSO_INVALID if a parameter is invalid, and OSSO_ERROR if an error occurred. the message)

osso_return_t osso_rpc_async_run_with_argfill	(	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,
		osso_rpc_argfill *	argfill,
		gpointer	argfill_data
	)

This function is like osso_rpc_async_run but instead of passing the arguments for the DBUS message as a variable length argument list, you provide a function in the argfill parameter that will provide the arguments. The argfill function is called with the DBusMessage object that is going to be sent and should append all arguments to that object with dbus_message_append_args, or similar.

The parameter argfill_data will be passed to argfill.

WARNING: Using this function is not recommended, because it will make your program more dependent on the DBus API due to the appending of arguments to a DBusMessage.

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 calls an RPC function for the default service of an other application. This call is non-blocking; a callback function is registered for the return value of the called RPC function. 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.

Parameters:

	osso	The library context as returned by osso_initialize.
	application	The name of the application providing the service.
	method	The RPC function to call.
	async_cb	A pointer to a function to be called when the RPC call returns. If the call times out, async_cb will be called with an error generated by the D-BUS library. If this parameter is NULL, this function behaves just like osso_rpc_run_with_defaults, with the retval argument 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 type-value list of other arguments. The list must be terminated with DBUS_TYPE_INVALID type. 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)

void osso_rpc_free_val

(

osso_rpc_t *

rpc

)

This function frees the contents of the osso_rpc_t structure pointed to by rpc. (It does not free the structure itself.) You need to call this for structures filled by osso_rpc_run and related functions.

This function will call g_free to free the memory pointed to by rpc->value.s when rpc->type is DBUS_TYPE_STRING. This guarantee allows you to use this function as the retval_free parameter for osso_rpc_set_cb_f, etc, when you get that string from g_strdup, g_strdup_printf, etc.

Parameters:

rpc

The structure whose contents is to be freed.

osso_return_t osso_rpc_get_timeout	(	osso_context_t *	osso,
		gint *	timeout
	)

Sets the timeout value used by the RPC functions.

Parameters:

	osso	The library context as returned by osso_initialize.
	timeout	The new timeout value.

Returns:

OSSO_OK on success, and OSSO_INVALID on invalid parameter.

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 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.

The variable arguments work in a type-value pairs. The type argument defines the type of the following 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_INT32, DBUS_TYPE_UINT32
  • 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.

    Parameters:

    	osso	The library context as returned by osso_initialize.
    	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.
    	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 to wait for the return value. If the expected reply does not come within the RPC 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 immediately after the call has been initiated (D-BUS message sent). You should call osso_rpc_free_val for this structure when it is no longer needed.
    	argument_type	The type of the first argument.
    	...	The first argument value, and then a type-value list of other arguments. This list must end in a DBUS_TYPE_INVALID type.

    Returns:

    OSSO_OK on success, 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 occurs, such as an IO error.

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

See osso_rpc_run. The RPC call is sent on the system bus instead

osso_return_t osso_rpc_run_system_with_argfill	(	osso_context_t *	osso,
		const gchar *	service,
		const gchar *	object_path,
		const gchar *	interface,
		const gchar *	method,
		osso_rpc_t *	retval,
		osso_rpc_argfill *	argfill,
		gpointer	argfill_data
	)

osso_return_t osso_rpc_run_with_argfill	(	osso_context_t *	osso,
		const gchar *	service,
		const gchar *	object_path,
		const gchar *	interface,
		const gchar *	method,
		osso_rpc_t *	retval,
		osso_rpc_argfill *	argfill,
		gpointer	argfill_data
	)

This function is like osso_rpc_run but instead of passing the arguments for the DBUS message as a variable length argument list, you provide a function in the argfill parameter that will provide the arguments. The argfill function is called with the DBusMessage object that is going to be sent and should append all arguments to that object with dbus_message_append_args, or similar.

The parameter argfill_data will be passed to argfill.

WARNING: Using this function is not recommended, because it will make your program more dependent on the DBus API due to the appending of arguments to a DBusMessage.

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 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.

Parameters:

	osso	The library context as returned by osso_initialize.
	application	The name of the remote application.
	method	The RPC function to call.
	retval	A pointer to a structure where the return value can be stored. If the application does not want to handle the reply, this can be set to NULL. When this is non-NULL, the call blocks to wait for the return value. If the expected reply does not come within the RPC 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. You should call osso_rpc_free_val for this structure when it is no longer needed.
	argument_type	The type of the first argument.
	...	The first argument value, and then a type-value list of other arguments. The list must be terminated with DBUS_TYPE_INVALID type. 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
	)

Equivalent to osso_rpc_set_cb_f_with_free when passing NULL for retval_free.

osso_return_t osso_rpc_set_cb_f_with_free	(	osso_context_t *	osso,
		const gchar *	service,
		const gchar *	object_path,
		const gchar *	interface,
		osso_rpc_cb_f *	cb,
		gpointer	data,
		osso_rpc_retval_free_f *	retval_free
	)

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

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 to register.
	data	Arbitrary application specific pointer that will be passed to the callback and ignored by Libosso.
	retval_free	A function that is called with the osso_rpc_t structure that has been filled by cb when that structure is no longer needed by libosso. In particular, you should pass osso_rpc_free_val here when you set retval->value.s to a string that should be freed with g_free. Likewise, you should pass NULL here when you set retval->value.s to a string that should not be freed.

Returns:

OSSO_OK on success, OSSO_INVALID if a parameter is invalid, and OSSO_ERROR if an error occurred.

osso_return_t osso_rpc_set_default_cb_f	(	osso_context_t *	osso,
		osso_rpc_cb_f *	cb,
		gpointer	data
	)

Equivalent to osso_rpc_set_default_cb_f_with_free when passing NULL for retval_free.

osso_return_t osso_rpc_set_default_cb_f_with_free	(	osso_context_t *	osso,
		osso_rpc_cb_f *	cb,
		gpointer	data,
		osso_rpc_retval_free_f *	retval_free
	)

This function 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 to osso_initialize.

Parameters:

	osso	The library context as returned by osso_initialize.
	cb	The function to register.
	data	Arbitrary application specific pointer that will be passed to the callback and ignored by Libosso.
	retval_free	As for osso_rpc_set_cb_f.

Returns:

OSSO_OK on success, OSSO_INVALID if a parameter is invalid, and OSSO_ERROR if an error occurred.

osso_return_t osso_rpc_set_timeout	(	osso_context_t *	osso,
		gint	timeout
	)

Returns the current RPC 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, and OSSO_INVALID on invalid parameter.

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 an RPC callback function.

Parameters:

	osso	The library context as returned by osso_initialize.
	service	The service name to unregister.
	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_cb_f call.

Returns:

OSSO_OK on success, OSSO_INVALID if a parameter is invalid, and OSSO_ERROR if an error occurred.

osso_return_t osso_rpc_unset_default_cb_f	(	osso_context_t *	osso,
		osso_rpc_cb_f *	cb,
		gpointer	data
	)

This function unregisters an RPC callback function for the default service.

Parameters:

	osso	The library context as returned by osso_initialize.
	cb	The RPC function to unregister.
	data	The same pointer that was used with the osso_rpc_set_default_cb_f call.

Returns:

OSSO_OK on success, OSSO_INVALID if a parameter is invalid, and OSSO_ERROR if an error occurred.