From 3d9aef9d0ed0f142eb74cea360f73bc7370b48bc Mon Sep 17 00:00:00 2001
From: Jakob Leben <jleben@videolan.org>
Date: Tue, 8 Jun 2010 02:16:18 +0200
Subject: [PATCH] SD API

---
 include/vlc_services_discovery.h |   98 ++++++++++++++++++++++++++++++++++++++
 1 files changed, 98 insertions(+), 0 deletions(-)

diff --git a/include/vlc_services_discovery.h b/include/vlc_services_discovery.h
index 956b77b..d7829d1 100644
--- a/include/vlc_services_discovery.h
+++ b/include/vlc_services_discovery.h
@@ -41,16 +41,100 @@ extern "C" {
  * @{
  */
 
+/******************************************************************************
+  VLC Services Discovery Protocol:
+
+  A SD client creates and starts a SD service.
+
+  The service will provide a tree structure of nodes of type sd_node_t that may
+  or may not be associated with actual playable items at their p_input_item
+  field. The b_is_container field of a node indicates if any children can be
+  provided for that node. Typically, container nodes will not themselves be
+  associated with any playable items (p_input_item == NULL).
+
+  The method by which the service provides nodes is as follows:
+
+  The service fills a particular parent node with children only AFTER the client
+  requests so with services_discovery_Fetch(). If b_is_container field of the
+  (parent) node is false then trying to fetch children should do nothing, and
+  the opposite: the service should set the field to true if children can be
+  provided for that particular (parent) node.
+  For every child node provided, the system will emit an "item-added" event.
+
+  The b_has_live_update field of a node indicates that the service is able to
+  spontaneously and continuously update the set of node's children AFTER the
+  children have first been fetched AND the client has requested updating with
+  services_discovery_SwitchLiveUpdate(... , true). For every child node
+  added/removed an "item-added"/"item-removed" event will be emitted.
+
+  Already when started up, the service provides the abstract root node at its
+  p_root field, of which children will be the actual meaningful nodes.
+
+  Except for i_children, pp_children and p_parent, no fields of sd_node_t should
+  be modified after it has been "published" by the service.
+
+*******************************************************************************/
+
+typedef struct sd_node_t sd_node_t;
+typedef struct sd_node_sys_t sd_node_sys_t;
+
+struct sd_node_t
+{
+    VLC_GC_MEMBERS
+
+    int i_children;
+
+    sd_node_t **pp_children;
+
+    sd_node_t *p_parent;
+
+    /* Pointer to SD responsible for this node. Purpose:
+      A) so the client API can forward requests to the module
+      B) it also allows for SD hierarchy: a SD module can offer
+         an item of which children will be provided by another SD module.
+         (a SD could for example provide the root node of another SD) */
+    services_discovery_t *p_sd;
+
+    char *psz_name;
+
+    input_item_t *p_input_item;
+
+    bool b_is_container;
+
+    bool b_has_live_update;
+
+    /* ...other meta-information about the node...? */
+
+    /* for the module to store the data needed to fetch children. */
+    sd_node_sys_t *p_sys;
+};
+
 struct services_discovery_t
 {
     VLC_COMMON_MEMBERS
     module_t *          p_module;
 
+    /* EM for the module to issue node addition/removal events whenever
+       it changes the array of children of a node */
     vlc_event_manager_t event_manager;      /* Accessed through Setters for non class function */
 
+    /* Lock for both client and SD for access to i_children, pp_children
+       and p_parent fields of all sd_node_t for which this SD module is
+       responsible */
+    vlc_mutex_t lock;
+
     char *psz_name;
     config_chain_t *p_cfg;
 
+    sd_node_t *p_root;
+
+    /* Pointer to module's function to fill/refresh p_parent node's children */
+    int ( *pf_fetch ) ( sd_node_t *p_parent );
+
+    /* Pointer to module's function to enable live updating of p_parent node's
+       children */
+    int ( *pf_switch_live_update ) ( sd_node_t *p_parent, bool b_on );
+
     services_discovery_sys_t *p_sys;
 };
 
@@ -90,6 +174,20 @@ VLC_EXPORT( char *,                 services_discovery_GetLocalizedName, ( servi
 /* Receive event notification (preferred way to get new items) */
 VLC_EXPORT( vlc_event_manager_t *,  services_discovery_EventManager, ( services_discovery_t * p_this ) );
 
+/* Client's request for service to fill / update the set of children
+   for given node */
+VLC_EXPORT( int,                    services_discovery_Fetch, ( services_discovery_t *, sd_node_t *p_parent ) );
+
+/* Client's request for service to enable or disable spontaneous and continuous
+   updating of children of given node */
+VLC_EXPORT( int,                    services_discovery_SwitchLiveUpdate, ( services_discovery_t *, sd_node_t *p_parent, bool b_on ) );
+
+/* For service to add a new child to a parent node */
+VLC_EXPORT( void,                   services_discovery_AddNode, ( services_discovery_t *, sd_node_t *p_child, sd_node_t * p_parent ) );
+
+/* For service to remove a node and all its children */
+VLC_EXPORT( void,                   services_discovery_RemoveNode, ( services_discovery_t *, sd_node_t *p_node ) );
+
 /* Used by services_discovery to post update about their items */
     /* About the psz_category, it is a legacy way to add info to the item,
      * for more options, directly set the (meta) data on the input item */
-- 
1.7.0.4

