1 files changed, 408 insertions, 0 deletions

diff --git a/src/lib/include/gnunet_dbus_lib_pop.h b/src/lib/include/gnunet_dbus_lib_pop.h
new file mode 100644
index 0000000..6ffde70
--- /dev/null
+++ b/src/lib/include/gnunet_dbus_lib_pop.h
@@ -0,0 +1,408 @@
+#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
+