path: root/src/lib/include/gnunet_dbus_lib_push.h

#ifndef GNUNET_DBUS_LIB_PUSH_H
#define GNUNET_DBUS_LIB_PUSH_H

#include <dbus/dbus.h>
#include <gnunet/platform.h>
#include <gnunet/gnunet_common.h>
#include <gnunet/gnunet_crypto_lib.h>

/**
 * Push a byte to a DBus message, advancing the iterator.
 */
void
GNUNET_DBUS_push_byte (
    DBusMessage *message,
    DBusMessageIter *iter,
    const unsigned char *value);

/**
 * Push a boolean to a DBus message, advancing the iterator.
 */
void
GNUNET_DBUS_push_boolean (
    DBusMessage *message,
    DBusMessageIter *iter,
    const dbus_bool_t *value);

/**
 * Push an int16 to a DBus message, advancing the iterator.
 */
void
GNUNET_DBUS_push_int16 (
    DBusMessage *message,
    DBusMessageIter *iter,
    const dbus_int16_t *value);

/**
 * Push a uint16 to a DBus message, advancing the iterator.
 */
void
GNUNET_DBUS_push_uint16 (
    DBusMessage *message,
    DBusMessageIter *iter,
    const dbus_uint16_t *value);

/**
 * Push an int32 to a DBus message, advancing the iterator.
 */
void
GNUNET_DBUS_push_int32 (
    DBusMessage *message,
    DBusMessageIter *iter,
    const dbus_int32_t *value);

/**
 * Push a uint32 to a DBus message, advancing the iterator.
 */
void
GNUNET_DBUS_push_uint32 (
    DBusMessage *message,
    DBusMessageIter *iter,
    const dbus_uint32_t *value);

/**
 * Push an int64 to a DBus message, advancing the iterator.
 */
void
GNUNET_DBUS_push_int64 (
    DBusMessage *message,
    DBusMessageIter *iter,
    const dbus_int64_t *value);

/**
 * Push a uint64 to a DBus message, advancing the iterator.
 */
void
GNUNET_DBUS_push_uint64 (
    DBusMessage *message,
    DBusMessageIter *iter,
    const dbus_uint64_t *value);

/**
 * Push a double to a DBus message, advancing the iterator.
 */
void
GNUNET_DBUS_push_double (
    DBusMessage *message,
    DBusMessageIter *iter,
    const double *value);

/**
 * Push a string to a DBus message, advancing the iterator.
 */
void
GNUNET_DBUS_push_string (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *const *value);

/**
 * Push an object path to a DBus message, advancing the iterator.
 */
void
GNUNET_DBUS_push_object_path (
    DBusMessage *message,
    DBusMessageIter *iter,
    const struct GNUNET_DBUS_ObjectPath *path);

/**
 * Push a DBus type signature to a DBus message, advancing the iterator.
 */
void
GNUNET_DBUS_push_signature (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *const *value);

/**
 * Push a unix file descriptor to a DBus message, advancing the iterator.
 */
void
GNUNET_DBUS_push_unix_fd (
    DBusMessage *message,
    DBusMessageIter *iter,
    const int *value);

/**
 * Push a unix file descriptor to a DBus message, advancing the iterator.
 */
void
GNUNET_DBUS_push_open_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    DBusMessageIter *iter_sub,
    const char *signature);

/**
 * Commence pushing an array to a DBusMessage. iter_sub is initialised to point
 * to the start of a new array and can be used to populate the array.
 * GNUNET_DBUS_push_close_array must be called after the array has been
 * populated. iter is invalid until GNUNET_DBUS_push_close_array has been called.
 */
void
GNUNET_DBUS_push_open_struct (
    DBusMessage *message,
    DBusMessageIter *iter,
    DBusMessageIter *iter_sub);

/**
 * Commence pushing a variant to a DBusMessage. iter_sub is initialised to
 * point to an empty variant and must be used to place the value in the
 * variant. After the value is placed, GNUNET_DBUS_push_close_variant must be
 * called. iter is invalid until GNUNET_DBUS_push_close_array has been called.
 */
void
GNUNET_DBUS_push_open_variant (
    DBusMessage *message,
    DBusMessageIter *iter,
    DBusMessageIter *iter_sub,
    const char *signature);

/**
 * Commence pushing a dictionary entry onto a DBusMessage. iter_sub is
 * initialised to point to the start of the new dictionary entry. It must be
 * used to push the key and value in order after which
 * GNUNET_DBUS_push_close_dict_entry must be called. iter is invalid until
 * GNUNET_DBUS_push_close_array has been called.
 */
void
GNUNET_DBUS_push_open_dict_entry (
    DBusMessage *message,
    DBusMessageIter *iter,
    DBusMessageIter *iter_sub);

/**
 * Finish pushing an array to a DBusMesage. This must be called after
 * GNUNET_DBUS_push_open_array and after the array elements have been pushed to
 * the message. After calling this function, iter_sub becomes invalid and iter
 * can again be used to push data to the message.
 */
void
GNUNET_DBUS_push_close_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    DBusMessageIter *iter_sub);

/**
 * Finish pushing a struct to a DBusMessage. This must be called after
 * GNUNET_DBUS_push_open_struct and after the struct members have been pushed
 * to the message. iter is invalid until GNUNET_DBUS_push_close_array has been
 * called. After calling this function, iter_sub becomes invalid and iter can
 * again be used to push data to the message.
 */
void
GNUNET_DBUS_push_close_struct (
    DBusMessage *message,
    DBusMessageIter *iter,
    DBusMessageIter *iter_sub);

/**
 * Finish pushing a variant to a DBusMessage. This must be called after
 * GNUNET_DBUS_push_open_variant and after the variant's value has been pushed
 * to the message. After calling this function, iter_sub becomes invalid and
 * iter can again be used to push data to the message.
 */
void
GNUNET_DBUS_push_close_variant (
    DBusMessage *message,
    DBusMessageIter *iter,
    DBusMessageIter *iter_sub);

/**
 * Finish pushing a dictionary entry to a DBusMessage. This must be called
 * after GNUNET_DBUS_push_open_dict_entry and after the key and value have been
 * pushed to the message. After calling this function, iter_sub becomes invalid
 * and iter can again be used to push data to the message.
 */
void
GNUNET_DBUS_push_close_dict_entry (
    DBusMessage *message,
    DBusMessageIter *iter,
    DBusMessageIter *iter_sub);

/**
 * Push an array of bytes to a DBusMessage, advancing the iterator. The values
 * are copied to the message. value_count is the number of elements in the array.
 */
void
GNUNET_DBUS_push_byte_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const unsigned char *value,
    size_t value_count);

/**
 * Push an array of booleans to a DBusMessage, advancing the iterator. The values
 * are copied to the message. value_count is the number of elements in the array.
 */
void
GNUNET_DBUS_push_boolean_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const dbus_bool_t *value,
    size_t value_count);

/**
 * Push an array of int16s to a DBusMessage, advancing the iterator. The values
 * are copied to the message. value_count is the number of elements in the array.
 */
void
GNUNET_DBUS_push_int16_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const dbus_int16_t *value,
    size_t value_count);

/**
 * Push an array of uint16s to a DBusMessage, advancing the iterator. The values
 * are copied to the message. value_count is the number of elements in the array.
 */
void
GNUNET_DBUS_push_uint16_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const dbus_uint16_t *value,
    size_t value_count);

/**
 * Push an array of int32s to a DBusMessage, advancing the iterator. The values
 * are copied to the message. value_count is the number of elements in the array.
 */
void
GNUNET_DBUS_push_int32_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const unsigned char *value,
    size_t value_count);

/**
 * Push an array of uint32s to a DBusMessage, advancing the iterator. The values
 * are copied to the message. value_count is the number of elements in the array.
 */
void
GNUNET_DBUS_push_uint32_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const unsigned char *value,
    size_t value_count);

/**
 * Push an array of int64s to a DBusMessage, advancing the iterator. The values
 * are copied to the message. value_count is the number of elements in the array.
 */
void
GNUNET_DBUS_push_int64_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const unsigned char *value,
    size_t value_count);

/**
 * Push an array of uint64s to a DBusMessage, advancing the iterator. The values
 * are copied to the message. value_count is the number of elements in the array.
 */
void
GNUNET_DBUS_push_uint64_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const unsigned char *value,
    size_t value_count);

/**
 * Push an array of doubles to a DBusMessage, advancing the iterator. The values
 * are copied to the message. value_count is the number of elements in the array.
 */
void
GNUNET_DBUS_push_double_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const unsigned char *value,
    size_t value_count);

/**
 * Push binary data to a DBusMessage, advancing the iterator. The data is
 * copied to the message. value_count is the number of bytes of data. The data
 * may be represented on-the-wire as either an array of bytes or a base32
 * encoded string depending on the pretty_encoding flag of the message.
 */
void
GNUNET_DBUS_push_data (
    DBusMessage *message,
    DBusMessageIter *iter,
    const void *value,
    size_t value_size);

/*
 * Push a bitfield enum to a DBusMessage, advancing the iterator. A bitfield
 * enum is an enum where the individual bits represent different flags. See for
 * example the definition of GNUNET_GNSRECORD_Flags:
 *
 *  enum GNUNET_GNSRECORD_Flags { GNUNET_GNSRECORD_RF_PRIVATE = 2, //
 *  GNUNET_GNSRECORD_RF_UNUSED = 4, GNUNET_GNSRECORD_RF_RELATIVE_EXPIRATION =
 *  8, GNUNET_GNSRECORD_RF_SHADOW_RECORD = 16 }
 *
 * Bitfield enums can be sent across the wire in either their integer form (as
 * a uint32) or as an array of strings depending on the pretty_encoding flag of
 * the message. Sending an int is more efficient and is what libraries built
 * around the DBus API would use. People using the DBus API directly via the
 * command line or a DBus debugger may prefer to receive human-readable strings
 * for convenience. names is a pointer to a {NULL, 0}-terminated array of
 * GNUNET_DBUS_StringEnumPair which assigns human-readable names to the
 * bitfields.
 */
void
GNUNET_DBUS_push_bitfield (
    DBusMessage *message,
    DBusMessageIter *iter,
    const int *value,
    const struct GNUNET_DBUS_StringEnumPair *fields);

/**
 * Push an enum to a DBusMessage, advancing the iterator. enums can be sent
 * across the wire as either a uint32 or as a string depending on the
 * pretty_encoding flag of the message. Sending a uint32 is more efficient and
 * is what libraries built around the DBus API would use. People using the DBus
 * API directly via the command line or a DBus debugger may prefer to receive
 * human-readable strings for convenience. names is a pointer to a
 * {NULL, 0}-terminated array of GNUNET_DBUS_StringEnumPair which assigns
 * human-readable names to the different enum variants.
 */
void
GNUNET_DBUS_push_enum (
    DBusMessage *message,
    DBusMessageIter *iter,
    const int *value,
    const struct GNUNET_DBUS_StringEnumPair *names);

/**
 * Push a GNUNET_HashCode to a DBusMessage, advancing the iterator.
 */
void
GNUNET_DBUS_push_hashcode (
    DBusMessage *message,
    DBusMessageIter *iter,
    const struct GNUNET_HashCode *value);

/**
 * Push a GNUNET_PeerIdentity to a DBusMessage, advancing the iterator.
 */
void
GNUNET_DBUS_push_peer_identity (
    DBusMessage *message,
    DBusMessageIter *iter,
    const struct GNUNET_PeerIdentity *value);

#endif