Hydranode Core/GUI Communication API

Preamble

        Implementing a user interface for a complex application, such as Hydranode Engine is not a trivial task. Furthermore, implementing support for an existing User Interface for a new P2P Client Engine is not a trivial task either. The complexity itself stems from the Core/GUI Communication Layer, which differs between clients, thus in order to implement support for a new core, one must first learn and implement the Core/GUI Communication Protocol, which is time-consuming. In order to simplify implementing User Interfaces for Hydranode Engine, or adding support for Hydranode Engine into existing User Interfaces, this document describes Hydranode Core/GUI Communication API, which hides the actual protocol implementation behind a generic interface, thus allowing GUI programmers to interact with an API rather than a protocol.
        This document describes the API in C++, but implementations may choose any viable programming language, to allow User Interfaces to be written in other languages.
       It should also be noted that it is perfectly possible to communicate with Hydranode Engine directly using the underlying Core/GUI Communication Protocol, and this library is provided merely for convenience.

Overview

    Hydranode Engine is divided into a number of subsystems. Each subsystem performs a specific set of tasks assigned to it. As such, this API will follow that design principle, and is also divided into sections by subsystems. The subsystems are (in no particular order):
    A careful reader might notice that the last two are, in a way, virtual subsystems. Download List and Shared Files List are both handled by Files Management Subsystem internally in the Engine, however for this API, they have been separated to simplify User Interface programming, since it is common to separate these two in User Interfaces.
    Object Hierarchy system provides callback-based updates engine for real-time GUI updates whenever something changes anywhere in the tree (events are propagated up the tree). This is used internally by other parts of this API for notifications, and this is also the only way to access Engine plugins data structures (such as eDonkey2000 Server List for example).
    Other interesting topics left out in the above listing are Upload List and Clients Listing. Again, internally Hydranode Engine does not have such concepts (they are handled per-plugin, inside plugin code), and as such, they are accessible via Object Hierarchy. More on this later.