Rename playlist_NodesCreateForSD to playlist_NodesPairCreate and document it

include/vlc_playlist.h

@@ -394,7 +394,7 @@ VLC_EXPORT( int, playlist_NodeRemoveItem, (playlist_t *,playlist_item_t*,playlis
 VLC_EXPORT( playlist_item_t *, playlist_ChildSearchName, (playlist_item_t*, const char* ) );
 VLC_EXPORT( int, playlist_NodeDelete, ( playlist_t *, playlist_item_t *, vlc_bool_t , vlc_bool_t ) );
 VLC_EXPORT( int, playlist_NodeEmpty, ( playlist_t *, playlist_item_t *, vlc_bool_t ) );
-VLC_EXPORT( void, playlist_NodesCreateForSD, (playlist_t *, char *, playlist_item_t **, playlist_item_t ** ) );
+VLC_EXPORT( void, playlist_NodesPairCreate, (playlist_t *, char *, playlist_item_t **, playlist_item_t **, vlc_bool_t ) );
 VLC_EXPORT( playlist_item_t *, playlist_GetPreferredNode, ( playlist_t *p_playlist, playlist_item_t *p_node ) );
 
 /***********************************************************************

modules/services_discovery/hal.c

@@ -127,8 +127,9 @@ static int Open( vlc_object_t *p_this )
         return VLC_EGENERIC;
     }
 
-    playlist_NodesCreateForSD( p_playlist, _("Devices"),
-                               &p_sys->p_node_cat, &p_sys->p_node_one );
+    playlist_NodesPairCreate( p_playlist, _("Devices"),
+                              &p_sys->p_node_cat, &p_sys->p_node_one,
+                              VLC_TRUE );
     vlc_object_release( p_playlist );
 
     return VLC_SUCCESS;

modules/services_discovery/sap.c

@@ -313,8 +313,9 @@ static int Open( vlc_object_t *p_this )
         return VLC_EGENERIC;
     }
 
-    playlist_NodesCreateForSD( p_sys->p_playlist, _("SAP sessions"),
-                               &p_sys->p_node_cat, &p_sys->p_node_one );
+    playlist_NodesPairCreate( p_sys->p_playlist, _("SAP sessions"),
+                              &p_sys->p_node_cat, &p_sys->p_node_one,
+                              VLC_TRUE );
 
     p_sys->i_announces = 0;
     p_sys->pp_announces = NULL;

src/playlist/tree.c

@@ -287,24 +287,42 @@ playlist_item_t *playlist_ChildSearchName( playlist_item_t *p_node,
     return NULL;
 }
 
-
-void playlist_NodesCreateForSD( playlist_t *p_playlist, char *psz_name,
+/**
+ * Create a pair of nodes in the category and onelevel trees.
+ * They share the same input ID.
+ * \todo really share the input item
+ * \param p_playlist the playlist
+ * \param psz_name the name of the nodes
+ * \param pp_node_cat pointer to return the node in category tree
+ * \param pp_node_one pointer to return the node in onelevel tree
+ * \param b_for_sd For Services Discovery ? (make node read-only and unskipping)
+ */
+void playlist_NodesPairCreate( playlist_t *p_playlist, char *psz_name,
                                playlist_item_t **pp_node_cat,
-                                playlist_item_t **pp_node_one )
+                               playlist_item_t **pp_node_one,
+                               vlc_bool_t b_for_sd )
 {
     *pp_node_cat = playlist_NodeCreate( p_playlist, psz_name,
                                         p_playlist->p_root_category );
-    (*pp_node_cat)->i_flags |= PLAYLIST_RO_FLAG;
-    (*pp_node_cat)->i_flags |= PLAYLIST_SKIP_FLAG;
-
     *pp_node_one = playlist_NodeCreate( p_playlist, psz_name,
                                         p_playlist->p_root_onelevel );
+    (*pp_node_one)->p_input->i_id = (*pp_node_cat)->p_input->i_id;
+    if( b_for_sd )
+    {
+        (*pp_node_cat)->i_flags |= PLAYLIST_RO_FLAG;
+        (*pp_node_cat)->i_flags |= PLAYLIST_SKIP_FLAG;
         (*pp_node_one)->i_flags |= PLAYLIST_RO_FLAG;
         (*pp_node_one)->i_flags |= PLAYLIST_SKIP_FLAG;
-
-    (*pp_node_one)->p_input->i_id = (*pp_node_cat)->p_input->i_id;
+    }
 }
 
+/**
+ * Get the node in the preferred tree from a node in one of category
+ * or onelevel tree. 
+ * For example, for the SAP node, it will return the node in the category
+ * tree if --playlist-tree is not set to never, because the SAP node prefers
+ * category
+ */
 playlist_item_t * playlist_GetPreferredNode( playlist_t *p_playlist,
                                              playlist_item_t *p_node )
 {