Hydranode Core/GUI Communication Library

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):

Configuration Subsystem allows setting various options to tweak the behaviour of the Engine
Logging Subsystem provides access to the extensive logging capabilities of Hydranode Engine
Modules Subsystem provides access to loading, unloading and listing of loaded modules in the Engine
WorkThread Subsystem provides view of IO work thread job queues, current job process and related features
Network Subsystem provides overview and access to global networking-related features
MetaData Subsystem provides access to Hydranode MetaDb, which keeps record of all known files, their hashes, names, etc.
Search Subsystem provides means of searching for files. The searches are handled by Engine plugins, so it's undefined where the exact results come from - network, server, local cache ...
Object Hierarchy provides access to Hydranode Virtual Filesystem, a file-tree-like view of the entire Engine objects, including objects found in Modules that are not accessible via other means.
Download List includes all files that are currently being downloaded
Shared Files List includes all files that are being shared with other clients on the networks

    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.