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

#ifndef GNUNET_DBUS_LIB_POP_H
#define GNUNET_DBUS_LIB_POP_H

/**
 * Pop a byte from a DBus message, advancing the iterator. `arg_name` is used
 * for reporting useful diagnostics if the value in the message is missing or
 * the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_byte (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    unsigned char *value);

/**
 * Pop a boolean from a DBus message, advancing the iterator. `arg_name` is
 * used for reporting useful diagnostics if the value in the message is missing
 * or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_boolean (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    dbus_bool_t *value);

/**
 * Pop an int16 from a DBus message, advancing the iterator. `arg_name` is used
 * for reporting useful diagnostics if the value in the message is missing or
 * the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_int16 (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    dbus_int16_t *value);

/**
 * Pop a uint16 from a DBus message, advancing the iterator. `arg_name` is used
 * for reporting useful diagnostics if the value in the message is missing or
 * the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_uint16 (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    dbus_uint16_t *value);

/**
 * Pop an int32 from a DBus message, advancing the iterator. `arg_name` is
 * used for reporting useful diagnostics if the value in the message is missing
 * or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_int32 (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    dbus_int32_t *value);

/**
 * Pop a uint32 from a DBus message, advancing the iterator. `arg_name` is
 * used for reporting useful diagnostics if the value in the message is missing
 * or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_uint32 (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    dbus_uint32_t *value);

/**
 * Pop an int64 from a DBus message, advancing the iterator. `arg_name` is
 * used for reporting useful diagnostics if the value in the message is missing
 * or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_int64 (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    dbus_int64_t *value);

/**
 * Pop a uint64 from a DBus message, advancing the iterator. `arg_name` is
 * used for reporting useful diagnostics if the value in the message is missing
 * or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_uint64 (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    dbus_uint64_t *value);

/**
 * Pop a double from a DBus message, advancing the iterator. `arg_name` is used
 * for reporting useful diagnostics if the value in the message is missing or
 * the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_double (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    double *value);

/**
 * Pop a string from a DBus message, advancing the iterator. `arg_name` is used
 * for reporting useful diagnostics if the value in the message is missing or
 * the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_string (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    const char **value);

/**
 * Pop a DBus object path from a DBus message, advancing the iterator. The
 * object path is returned in *value as a string. `arg_name` is used for
 * reporting useful diagnostics if the value in the message is missing or the
 * wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_object_path (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    const char **value);

/**
 * Pop a DBus type signature from a DBusMessage, advancing the iterator. The
 * type signature is returned in *value as a string. `arg_name` is used for
 * reporting useful diagnostics if the value in the message is missing or the
 * wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_signature (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    const char **value);

/**
 * Pop a unix file descriptor from a DBusMessage, advancing the iterator.
 * `arg_name` is used for reporting useful diagnostics if the value in the
 * message is missing or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_unix_fd (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    int *value);

/**
 * Pop an array from a DBusMessage. Moves iter past the array and initialises
 * iter_sub to point to the first element of the array. The length of the array
 * is returned in *len. `arg_name` is used for reporting useful diagnostics if
 * the value in the message is missing or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_enter_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    DBusMessageIter *iter_sub,
    const char *arg_name,
    size_t *len);

/**
 * Pop a struct from a DBusMessage. Moves iter past the struct and initialises
 * iter_sub to point to the first element of the struct. `arg_name` is used for
 * reporting useful diagnostics if the value in the message is missing or the
 * wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_enter_struct (
    DBusMessage *message,
    DBusMessageIter *iter,
    DBusMessageIter *iter_sub,
    const char *arg_name);

/**
 * Pop a variant from a DBusMessage. Moves iter past the variant and
 * initialises iter_sub to point to the value inside the variant. `arg_name`
 * is used for reporting useful diagnostics if the value in the message is
 * missing or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_enter_variant (
    DBusMessage *message,
    DBusMessageIter *iter,
    DBusMessageIter *iter_sub,
    const char *arg_name);

/**
 * Pop a dictionary entry from a DBusMessage. Moves iter past the dictionary
 * entry and initialises iter_sub to point to the key. The key and value can
 * then be popped in sequence using iter_sub. `arg_name` is used for reporting
 * useful diagnostics if the value in the message is missing or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_enter_dict_entry (
    DBusMessage *message,
    DBusMessageIter *iter,
    DBusMessageIter *iter_sub,
    const char *arg_name);

/**
 * Pop an array of bytes from a DBusMessage. A pointer to the array is stored
 * in *value. The array is not copied so *value will become invalid once the
 * message has been freed. The length of the array is stored in *n_elements.
 * `arg_name` is used for reporting useful diagnostics if the value in the
 * message is missing or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_byte_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    const unsigned char **value,
    int *n_elements);

/**
 * Pop an array of booleans from a DBusMessage. A pointer to the array is
 * stored in *value. The array is not copied so *value will become invalid once
 * the message has been freed. The length of the array is stored in
 * *n_elements. `arg_name` is used for reporting useful diagnostics if the
 * value in the message is missing or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_boolean_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    const dbus_bool_t **value,
    int *n_elements);

/**
 * Pop an array of int16s from a DBusMessage. A pointer to the array is stored
 * in *value. The array is not copied so *value will become invalid once the
 * message has been freed. The length of the array is stored in *n_elements.
 * `arg_name` is used for reporting useful diagnostics if the value in the
 * message is missing or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_int16_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    const int16_t **value,
    int *n_elements);

/**
 * Pop an array of uint16s from a DBusMessage. A pointer to the array is stored
 * in *value. The array is not copied so *value will become invalid once the
 * message has been freed. The length of the array is stored in *n_elements.
 * `arg_name` is used for reporting useful diagnostics if the value in the
 * message is missing or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_uint16_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    const uint16_t **value,
    int *n_elements);

/**
 * Pop an array of int32s from a DBusMessage. A pointer to the array is stored
 * in *value. The array is not copied so *value will become invalid once the
 * message has been freed. The length of the array is stored in *n_elements.
 * `arg_name` is used for reporting useful diagnostics if the value in the
 * message is missing or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_int32_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    const int32_t **value,
    int *n_elements);

/**
 * Pop an array of uint32s from a DBusMessage. A pointer to the array is stored
 * in *value. The array is not copied so *value will become invalid once the
 * message has been freed. The length of the array is stored in *n_elements.
 * `arg_name` is used for reporting useful diagnostics if the value in the
 * message is missing or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_uint32_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    const uint32_t **value,
    int *n_elements);

/**
 * Pop an array of int64s from a DBusMessage. A pointer to the array is stored
 * in *value. The array is not copied so *value will become invalid once the
 * message has been freed. The length of the array is stored in *n_elements.
 * `arg_name` is used for reporting useful diagnostics if the value in the
 * message is missing or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_int64_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    const int64_t **value,
    int *n_elements);

/**
 * Pop an array of uint64s from a DBusMessage. A pointer to the array is stored
 * in *value. The array is not copied so *value will become invalid once the
 * message has been freed. The length of the array is stored in *n_elements.
 * `arg_name` is used for reporting useful diagnostics if the value in the
 * message is missing or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_uint64_array (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    const uint64_t **value,
    int *n_elements);

/*
 * Pop a bitfield enum from 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. 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 want to pass
 * 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. `arg_name` is used for reporting
 * useful diagnostics if the value in the message is missing or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_bitfield (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    int *value,
    const struct GNUNET_DBUS_StringEnumPair *fields);

/**
 * Pop an enum from a DBusMessage, advancing the iterator. enums can be sent
 * across the wire as either a uint32 or as a string. 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 want
 * to pass 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. `arg_name` is used for
 * reporting useful diagnostics if the value in the message is missing or the
 * wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_enum (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    int *value,
    const struct GNUNET_DBUS_StringEnumPair *names);

/**
 * Pop a GNUNET_HashCode from a DBusMessage, advancing the iterator.
 * `arg_name` is used for reporting useful diagnostics if the value in the
 * message is missing or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_hashcode (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    struct GNUNET_HashCode *value);
  
/**
 * Pop a GNUNET_PeerIdentity from a DBusMessage, advancing the iterator.
 * `arg_name` is used for reporting useful diagnostics if the value in the
 * message is missing or the wrong type.
 */
DBusMessage *
GNUNET_DBUS_pop_peer_identity (
    DBusMessage *message,
    DBusMessageIter *iter,
    const char *arg_name,
    struct GNUNET_PeerIdentity *value);

#endif