eripc.h

Go to the documentation of this file.

#ifndef _ERIPC_
#define _ERIPC_

/**
 * @defgroup eripc Inter-Process Communication Library
 * @{
 * @file eripc.h
 * @brief Public header for liberipc.
 */
 
/*
 * This file is part of liberipc.
 *
 * liberipc is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 2 of the License, or
 * (at your option) any later version.
 *
 * liberipc is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */

/**
 * Copyright (C) 2008 iRex Technologies B.V. 
 * All rights reserved.
 *
 * Based on code found in libosso library by Kimmo Hämäläinen <kimmo.hamalainen@nokia.com>
 */

#include <glib.h>

G_BEGIN_DECLS

typedef enum {
    ERIPC_ERROR_SUCCESS =  0,   /* success (not an error) */
    ERIPC_ERROR_INVALID,        /* invalid arguments */ 
    ERIPC_ERROR_OOM,            /* out of memory */
    ERIPC_ERROR,                /* generic error code */
    ERIPC_ERROR_TIMEOUT,        /* timeout happened */
} eripc_error_t;

typedef enum {
    ERIPC_TYPE_INVALID = 0,
    ERIPC_TYPE_BOOL,
    ERIPC_TYPE_BYTE,
    ERIPC_TYPE_INT,
    ERIPC_TYPE_UINT,
    ERIPC_TYPE_DOUBLE,
    ERIPC_TYPE_STRING,
    ERIPC_TYPE_DATA
} eripc_data_t;

typedef enum {
    ERIPC_BUS_IRRELEVANT = 0,
    ERIPC_BUS_SYSTEM,
    ERIPC_BUS_SESSION,
    ERIPC_BUS_BOTH
} eripc_bus_t;
 
typedef enum { 
    ERIPC_EVENT_NONE = 0,               /* non-event, event type is not relevant */
    ERIPC_EVENT_MESSAGE,                /* message received */
    ERIPC_EVENT_SIGNAL,                 /* signal received */
    ERIPC_EVENT_MESSAGE_OR_SIGNAL,      /* message or signal received */
    ERIPC_EVENT_REPLY,                  /* reply received */
    ERIPC_EVENT_ERROR,                  /* error reply received */
    ERIPC_EVENT_REPLY_OR_ERROR,         /* reply or error received */
} eripc_event_t;

typedef struct _eripc_context_t eripc_context_t;

typedef struct {
  int type;             /* type of argument */
  int data_len;         /* only used with ERIPC_TYPE_DATA to tell
                           the length of the data */
  union {
    int b;              /* ERIPC_TYPE_BOOL */
    char by;            /* ERIPC_TYPE_BYTE */
    int i;              /* ERIPC_TYPE_INT */
    unsigned int u;     /* ERIPC_TYPE_UINT */
    double d;           /* ERIPC_TYPE_DOUBLE */
    char *s;            /* ERIPC_TYPE_STRING */
    void *data;         /* ERIPC_TYPE_DATA */
  } value;
} eripc_arg_t;

typedef struct {
        const char *service;    /* service name or NULL */
        const char *path;       /* object path or NULL */
        const char *interface;  /* interface name or NULL */
        const char *name;       /* name of message/signal or NULL */

        /* Received event type, in case it is one of the
         * pre-defined events */
        eripc_event_t event_type;

        /* Message bus type. The type may be ERIPC_BUS_IRRELEVANT
         * for e.g. pre-defined events. */
        eripc_bus_t bus_type;

        /* This can be an ID string of the reply or a received message. */
        const char *message_id;

        /* Received error message, or NULL */
        const char *error;

        /* Array of arguments (coming or going), terminating to
         * argument of type #ERIPC_TYPE_INVALID. args is NULL if the
         * message has no arguments.
         * Note that this is ignored in case of a vararg function. */
        const eripc_arg_t *args;
    
        /* Pointer to the DBus message related ot this event */
        char *dbus_message;
} eripc_event_info_t;

/**
 * This is the type for the callback handlers of events and messages.
 *
 * This function is called when the asynchronous function returns a 
 * reply or when a registered event occurs.
 *
 * @param context IPC context returned by #eripc_init.
 * @param info Structure specifying the type of event and its arguments.
 * @param user_data Optional user data passed when the handler was 
                    registered.
 */
typedef void (eripc_handler_t)(eripc_context_t *context,
                               const eripc_event_info_t *info,
                               void *user_data);

typedef struct osso_af_context_t osso_context_t;


/**********************************/
/*          FUNCTIONS             */
/**********************************/

void *eripc_get_system_connection (eripc_context_t *context);
void *eripc_get_session_connection (eripc_context_t *context);

/**
 * This function initialises the library, connects to both the D-Bus session
 * and system busses, integrates with the GLib main loop, and
 * initialises the library for use. #eripc_init should be called
 * only once by the program.
 * @param program_name The name of the program.
 * This name forms the last part of the default (D-Bus) service name of the
 * program. Note that the D-Bus service name will be
 * 'com.irexnet.program_name', where 'program_name' is the value you gave as 
 * the parameter.  The only valid characters that the name may contain are 
 * letters a-z and the underscore '_'.
 * However, you can give a name such as 'org.foo.bar' to
 * have 'bar' as your program's name and 'org.foo.bar' as the D-Bus service
 * name.
 * @param program_version The version string of the application. This will
 * be used to determine if a saved UI state is still valid for the program.
 * @param context The GLib main loop context to connect to, or NULL for
 * the default context.
 * @return A context to use in later calls to this library, or NULL if an
 * error happened.
 */
eripc_context_t *eripc_init(const char *program_name,
                            const char *program_version,
                            GMainContext *context);

/**
 * This function registers a handler for a signal.
 *
 * @param context IPC context returned by #eripc_init.
 * @param handler The handler function to call when the event happens.
 * @param user_data Optional user data to pass to the handler when it
 *                  is called.
 * @param bus_type The bus type (session or system bus).
 * @param source Interface name to receive signal/message from.
 * @param signal_name Name of the signal.
 * @param handler_id Return location for the handler ID, which is used
 *                   to unregister the handler.
 *
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_set_signal_handler(eripc_context_t *context,
                                       eripc_handler_t *handler,
                                       void *user_data,
                                       eripc_bus_t bus_type,
                                       const char *source,
                                       const char *signal_name,
                                       int *handler_id);

/**
 * This function registers a handler for a message.
 *
 * @param context IPC context returned by #eripc_init.
 * @param handler The handler function to call when the event happens.
 * @param user_data Optional user data to pass to the handler when it
 *                  is called.
 * @param bus_type The bus type (session or system bus).
 * @param source Interface name of message to receive.
 * @param message_name Name of the message/method.
 * @param handler_id Return location for the handler ID, which is used
 *                   to unregister the handler.
 *
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_set_message_handler(eripc_context_t *context,
                                        eripc_handler_t *handler,
                                        void *user_data,
                                        eripc_bus_t bus_type,
                                        const char *source,
                                        const char *message_name,
                                        int *handler_id);

/**
 * This function registers a custom handler for event, message, or signal.
 *
 * @param context IPC context returned by #eripc_init.
 * @param info Structure specifying the type of events to handle.
 * @param handler The handler function to call when the event happens.
 * @param user_data Optional user data to pass to the handler when it
 *                  is called.
 * @param handler_id Return location for the handler ID, which is used
 *                   to unregister the handler.
 *
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_set_event_handler(eripc_context_t *context,
                                      const eripc_event_info_t *info,
                                      eripc_handler_t *handler,
                                      void *user_data,
                                      int *handler_id);

/**
 * This function unregisters a handler for event, message, or signal.
 *
 * @param context IPC context returned by #eripc_init.
 * @param handler_id Handler to unregister. The handler will not be
 *                   called after it has been successfully unregistered.
 *
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_unset_handler(eripc_context_t *context,
                                        int handler_id);


/**
 * Returns the current RPC timeout value.
 * @param context IPC context returned by #eripc_init.
 * @param timeout A pointer where to return the timeout value in milliseconds.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_get_timeout (eripc_context_t *context, int *timeout);

/**
 * Sets the timeout value used by the RPC functions.
 * @param context IPC context returned by #eripc_init.
 * @param timeout The new timeout value in milliseconds.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_set_timeout(eripc_context_t *context, int timeout);

/**
 * This function sends a variable message and registers a reply handler.
 * 
 * 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 
 * ERIPC_TYPE_INVALID. The supported types are:
 *  - ERIPC_TYPE_BOOL
 *    - The value is a gboolean.
 *  - ERIPC_TYPE_BYTE, ERIPC_TYPE_INT, ERIPC_TYPE_UINT
 *    - The value is an byte, int or an unsigned int.
 *  - ERIPC_TYPE_DOUBLE
 *    - The value is a float.
 *  - ERIPC_TYPE_STRING
 *    - The value is a pointer to a string.
 *  - ERIPC_TYPE_DATA
 *    - Two values are expected: first an integer indicating length of 
 *      the data block (e.g. array), second a pointer to the data block.
 *
 * @param context IPC context returned by #eripc_init.
 * @param reply_handler The handler function to call when a reply is
 *                      returned. Set to NULL for no reply.
 * @param user_data Optional user data to pass to the handler when it
 *                  is called.
 * @param bus_type The bus type (session or system bus).
 * @param destination Interface name to send message to.
 * @param message_name Name of the message/method to call.
 * @param arg_type The type of the first argument.
 * @param ... The first argument value, and then a type-value list of other
 * arguments. This list must end in a #ERIPC_TYPE_INVALID type.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_send_varargs(eripc_context_t *context,
                                 eripc_handler_t *reply_handler,
                                 const void *user_data,
                                 eripc_bus_t bus_type,
                                 const char *destination,
                                 const char *message_name,
                                 eripc_data_t arg_type, ...);

/**
 * This function sends a string message and registers a reply handler.
 * 
 * Instead of the variable arguments of #eripc_send_varargs, this
 * function has single string as argument. 
 *
 * @param context IPC context returned by #eripc_init.
 * @param reply_handler The handler function to call when a reply is
 *                      returned. Set to NULL for no reply.
 * @param user_data Optional user data to pass to the handler when it
 *                  is called.
 * @param bus_type The bus type (session or system bus).
 * @param destination Interface name to send message to.
 * @param message_name Name of the message/method to call.
 * @param string The argument string.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_send_string(eripc_context_t *context,
                                eripc_handler_t *reply_handler,
                                const void *user_data,
                                eripc_bus_t bus_type,
                                const char *destination,
                                const char *message_name,
                                const char *string);

/**
 * This function sends an integer message and registers a reply handler.
 * 
 * Instead of the variable arguments of #eripc_send_varargs, this
 * function has single integer as argument. 
 *
 * @param context IPC context returned by #eripc_init.
 * @param reply_handler The handler function to call when a reply is
 *                      returned. Set to NULL for no reply.
 * @param user_data Optional user data to pass to the handler when it
 *                  is called.
 * @param bus_type The bus type (session or system bus).
 * @param destination Interface name to send message to.
 * @param message_name Name of the message/method to call.
 * @param value The argument value.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_send_int(eripc_context_t *context,
                             eripc_handler_t *reply_handler,
                             const void *user_data,
                             eripc_bus_t bus_type,
                             const char *destination,
                             const char *message_name,
                             int value);

/**
 * This function sends a boolean message and registers a reply handler.
 * 
 * Instead of the variable arguments of #eripc_send_varargs, this
 * function has single boolean as argument. 
 *
 * @param context IPC context returned by #eripc_init.
 * @param reply_handler The handler function to call when a reply is
 *                      returned. Set to NULL for no reply.
 * @param user_data Optional user data to pass to the handler when it
 *                  is called.
 * @param bus_type The bus type (session or system bus).
 * @param destination Interface name to send message to.
 * @param message_name Name of the message/method to call.
 * @param value The argument value.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_send_bool(eripc_context_t *context,
                              eripc_handler_t *reply_handler,
                              const void *user_data,
                              eripc_bus_t bus_type,
                              const char *destination,
                              const char *message_name,
                              gboolean value);

/**
 * This function sends a variable message and return reply immediately. 
 * This call is blocking.
 * 
 * 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 
 * ERIPC_TYPE_INVALID. The supported types are:
 *  - ERIPC_TYPE_BOOL
 *    - The value is a gboolean.
 *  - ERIPC_TYPE_BYTE, ERIPC_TYPE_INT, ERIPC_TYPE_UINT
 *    - The value is an byte, int or an unsigned int.
 *  - ERIPC_TYPE_DOUBLE
 *    - The value is a float.
 *  - ERIPC_TYPE_STRING
 *    - The value is a pointer to a string.
 *  - ERIPC_TYPE_DATA
 *    - Two values are expected: first an integer indicating length of 
 *      the data block (e.g. array), second a pointer to the data block.
 *
 * @param [in]  context IPC context returned by #eripc_init.
 * @param [out] reply A pointer pointer to the event info structure where 
 *              the return info goes. Set to NULL for no reply arguments. 
 *              If the expected reply does not come within the RPC timeout
 *              value  set with the #eripc_set_timeout function. Caller 
 *              must free the reply structure using #eripc_event_info_free.
 * @param [in]  bus_type The bus type (session or system bus).
 * @param [in]  destination Interface name to send message to.
 * @param [in]  message_name Name of the message/method to call.
 * @param [in]  arg_type The type of the first argument.
 * @param [in]  ... The first argument value, and then a type-value list of 
 * other arguments. This list must end in a #ERIPC_TYPE_INVALID type.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_send_varargs_and_wait(eripc_context_t *context,
                                          eripc_event_info_t **reply,
                                          eripc_bus_t bus_type,
                                          const char *destination,
                                          const char *message_name,
                                          eripc_data_t arg_type, ...);

/**
 * This function sends a string message and return reply immediately. 
 * This call is blocking.
 * 
 * Instead of the variable arguments of #eripc_send_varargs_and_wait, 
 * this function has single string as argument. 
 *
 * @param [in]  context IPC context returned by #eripc_init.
 * @param [out] reply A pointer pointer to the event info structure where 
 *              the return info goes. Set to NULL for no reply arguments. 
 *              If the expected reply does not come within the RPC timeout
 *              value  set with the #eripc_set_timeout function. Caller 
 *              must free the reply structure using #eripc_event_info_free.
 * @param [in]  bus_type The bus type (session or system bus).
 * @param [in]  destination Interface name to send message to.
 * @param [in]  message_name Name of the message/method to call.
 * @param [in]  string The argument string.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_send_string_and_wait(eripc_context_t *context,
                                         eripc_event_info_t **reply,
                                         eripc_bus_t bus_type,
                                         const char *destination,
                                         const char *message_name,
                                         const char *string);

/**
 * This function sends an integer message and return reply immediately. 
 * This call is blocking.
 * 
 * Instead of the variable arguments of #eripc_send_varargs_and_wait, 
 * this function has single integer as argument. 
 *
 * @param [in]  context IPC context returned by #eripc_init.
 * @param [out] reply A pointer pointer to the event info structure where 
 *              the return info goes. Set to NULL for no reply arguments. 
 *              If the expected reply does not come within the RPC timeout
 *              value  set with the #eripc_set_timeout function. Caller 
 *              must free the reply structure using #eripc_event_info_free.
 * @param [in]  bus_type The bus type (session or system bus).
 * @param [in]  destination Interface name to send message to.
 * @param [in]  message_name Name of the message/method to call.
 * @param [in]  value The argument value.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_send_int_and_wait(eripc_context_t *context,
                                      eripc_event_info_t **reply,
                                      eripc_bus_t bus_type,
                                      const char *destination,
                                      const char *message_name,
                                      int value);

/**
 * This function sends a boolean message and return reply immediately. 
 * This call is blocking.
 * 
 * Instead of the variable arguments of #eripc_send_varargs_and_wait, 
 * this function has single boolean as argument. 
 *
 * @param [in]  context IPC context returned by #eripc_init.
 * @param [out] reply A pointer pointer to the event info structure where 
 *              the return info goes. Set to NULL for no reply arguments. 
 *              If the expected reply does not come within the RPC timeout
 *              value  set with the #eripc_set_timeout function. Caller 
 *              must free the reply structure using #eripc_event_info_free.
 * @param [in]  bus_type The bus type (session or system bus).
 * @param [in]  destination Interface name to send message to.
 * @param [in]  message_name Name of the message/method to call.
 * @param [in]  value The argument value.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_send_bool_and_wait(eripc_context_t *context,
                                       eripc_event_info_t **reply,
                                       eripc_bus_t bus_type,
                                       const char *destination,
                                       const char *message_name,
                                       gboolean value);

/**
 * This function sends a signal with optional string argument.
 * 
 * The signal defaults to the path and interface in the 
 * context. For more flexibility, use #eripc_send_signal_varargs.
 *
 * @param context IPC context returned by #eripc_init.
 * @param bus_type The bus type (session or system bus).
 * @param signal_name Name of the signal to send.
 * @param argument The argument string or NULL for no argument.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_send_signal(eripc_context_t *context,
                                eripc_bus_t bus_type,
                                const char *signal_name,
                                const char *argument);

/**
 * This function sends a signal with variable arguments.
 * 
 * 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 
 * ERIPC_TYPE_INVALID. The supported types are:
 *  - ERIPC_TYPE_BOOL
 *    - The value is a gboolean.
 *  - ERIPC_TYPE_BYTE, ERIPC_TYPE_INT, ERIPC_TYPE_UINT
 *    - The value is an byte, int or an unsigned int.
 *  - ERIPC_TYPE_DOUBLE
 *    - The value is a float.
 *  - ERIPC_TYPE_STRING
 *    - The value is a pointer to a string.
 *  - ERIPC_TYPE_DATA
 *    - Two values are expected: first an integer indicating length of 
 *      the data block (e.g. array), second a pointer to the data block.
 *
 * @param context IPC context returned by #eripc_init.
 * @param bus_type The bus type (session or system bus).
 * @param signal_path The object path of the signal to send.
 * @param signal_interface The interface name of the signal to send.
 * @param signal_name Name of the signal to send.
 * @param arg_type The type of the first argument.
 * @param ... The first argument value, and then a type-value list of other
 * arguments. This list must end in a #ERIPC_TYPE_INVALID type.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_send_signal_varargs(eripc_context_t *context,
                                        eripc_bus_t bus_type,
                                        const char *signal_path,
                                        const char *signal_interface,
                                        const char *signal_name,
                                        eripc_data_t arg_type, ...);

/**
 * This function frees the event info structure and associated message.
 *
 * @param context IPC context returned by #eripc_init.
 * @param reply A pointer to the event info structure where the return 
 *              info is stored.
 *
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_event_info_free(eripc_context_t *context,
                                    eripc_event_info_t *reply);


/**********************/
/* reply to a message */
/**********************/

/**
 * This function returns a reply to a message with variable arguments.
 * 
 * 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 
 * ERIPC_TYPE_INVALID. The supported types are:
 *  - ERIPC_TYPE_BOOL
 *    - The value is a gboolean.
 *  - ERIPC_TYPE_BYTE, ERIPC_TYPE_INT, ERIPC_TYPE_UINT
 *    - The value is an byte, int or an unsigned int.
 *  - ERIPC_TYPE_DOUBLE
 *    - The value is a float.
 *  - ERIPC_TYPE_STRING
 *    - The value is a pointer to a string.
 *  - ERIPC_TYPE_DATA
 *    - Two values are expected: first an integer indicating length of 
 *      the data block (e.g. array), second a pointer to the data block.
 *
 * @param context IPC context returned by #eripc_init.
 * @param message_id ID string of the received message to reply to.
 * @param arg_type The type of the first argument.
 * @param ... The first argument value, and then a type-value list of other
 * arguments. This list must end in a #ERIPC_TYPE_INVALID type.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_reply_varargs(eripc_context_t *context,
                                  const char *message_id,
                                  eripc_data_t arg_type, ...);

/**
 * This function returns a reply to a message with a string argument.
 * 
 * Instead of the variable arguments of #eripc_reply_varargs, 
 * this function has single string as argument. 
 *
 * @param context IPC context returned by #eripc_init.
 * @param message_id ID string of the received message to reply to.
 * @param string The argument string.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_reply_string(eripc_context_t *context,
                                 const char *message_id,
                                 const char *string);

/**
 * This function returns a reply to a message with an integer argument.
 * 
 * Instead of the variable arguments of #eripc_reply_varargs, 
 * this function has single integer as argument. 
 *
 * @param context IPC context returned by #eripc_init.
 * @param message_id ID string of the received message to reply to.
 * @param value The argument value.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_reply_int(eripc_context_t *context,
                                 const char *message_id,
                                 int value);

/**
 * This function returns a reply to a message with a boolean argument.
 * 
 * Instead of the variable arguments of #eripc_reply_varargs, 
 * this function has single boolean as argument. 
 *
 * @param context IPC context returned by #eripc_init.
 * @param message_id ID string of the received message to reply to.
 * @param value The argument value.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_reply_bool(eripc_context_t *context,
                                 const char *message_id,
                                 gboolean value);

/**
 * This function return an error in reply to a message.
 * 
 * The error_name indicates the error which can be fully-qualitfied.
 * When the service is omitted from the error name, the service 
 * of the given context is used.
 *
 * @param context IPC context returned by #eripc_init.
 * @param message_id ID string of the received message to reply to.
 * @param error_name The name of the error to return.
 * @param error_message Text string with error description.
 * @return #ERIPC_ERROR_SUCCESS on success.
 */
eripc_error_t eripc_reply_error(eripc_context_t *context,
                                const char *message_id,
                                const char *error_name,
                                const char *error_message);

G_END_DECLS

/** @} */

#endif /* _ERIPC_ */