#ifndef GNUNET_DBUS_LIB_OBJECT_H
#define GNUNET_DBUS_LIB_OBJECT_H

/**
 * Represents a DBus object advertised on a DBus service. Objects are named and
 * exist in a tree. For example, the object at the path
 * /org/freedesktop/PolicyKit1/Authority is named Authority and sits in a
 * heirarchy below four other objects including the service's root object. Each
 * object has a set of interfaces and can be associated with an arbitrary piece
 * of data.
 */
struct GNUNET_DBUS_Object;

#include "gnunet_dbus_lib_interface.h"

/**
 * An iterable, doubly-linked-list of GNUNET_DBUS_Object.
 */
struct GNUNET_DBUS_ObjectIterator
{
  /* linked list */
  struct GNUNET_DBUS_ObjectIterator *next;
  struct GNUNET_DBUS_ObjectIterator *prev;

  struct GNUNET_DBUS_Object *object;
};

/**
 * Create a new GNUNET_DBUS_Object with the given name and associated data. For
 * example, the object that exists at the path
 * /org/freedesktop/PolicyKit1/Authority has the name Authority and sits below
 * four other objects including the service's root object.
 */
struct GNUNET_DBUS_Object *
GNUNET_DBUS_object_create (
    const char *name,
    void *data);

/**
 * Increase the reference count of this GNUNET_DBUS_Object by one.
 */
void
GNUNET_DBUS_object_ref (
    struct GNUNET_DBUS_Object *object);

/**
 * Decrease the reference count of this GNUNET_DBUS_Object by one. Will free
 * the GNUNET_DBUS_Object if the reference count reaches zero.
 */
void
GNUNET_DBUS_object_unref (
    struct GNUNET_DBUS_Object *object);

/**
 * Get the name of this GNUNET_DBUS_Object.
 */
const char *
GNUNET_DBUS_object_get_name (
    const struct GNUNET_DBUS_Object *object);

/**
 * Add an interface to this GNUNET_DBUS_Object.
 */
void
GNUNET_DBUS_object_add_interface (
    struct GNUNET_DBUS_Object *object,
    struct GNUNET_DBUS_Interface *interface);

/**
 * Iterate over the interfaces of this GNUNET_DBUS_Object.
 */
const struct GNUNET_DBUS_InterfaceIterator *
GNUNET_DBUS_object_iterate_interfaces (
    struct GNUNET_DBUS_Object *object);

/**
 * Get the data associated with this GNUNET_DBUS_Object.
 */
void *
GNUNET_DBUS_object_get_data (
    struct GNUNET_DBUS_Object *object);

/**
 * Create an object with a randomly generated name, associate data with it, and
 * add it as a child to the given object. Returns the newly created object.
 */
struct GNUNET_DBUS_Object *
GNUNET_DBUS_object_create_uniquely_named_subobject (
    struct GNUNET_DBUS_Object *object,
    void *data);

/**
 * Add subobject as a child of object.
 */
void
GNUNET_DBUS_object_add_subobject (
    struct GNUNET_DBUS_Object *object,
    struct GNUNET_DBUS_Object *subobject);

/**
 * Remove the object pointed to by subobject_it as a child from object.
 */
void
GNUNET_DBUS_object_remove_subobject (
    struct GNUNET_DBUS_Object *object,
    struct GNUNET_DBUS_ObjectIterator *subobject_it);

/**
 * Iterate over an object's child objects.
 */
struct GNUNET_DBUS_ObjectIterator *
GNUNET_DBUS_object_iterate_subobjects (
    const struct GNUNET_DBUS_Object *object);

/**
 * Search the given linked list of GNUNET_DBUS_Object for an object with the
 * given name and return an iterator to it.
 */
const struct GNUNET_DBUS_ObjectIterator *
GNUNET_DBUS_object_find (
    const struct GNUNET_DBUS_ObjectIterator *object_it,
    const char *name);

#endif