include/vlc_services_discovery.h

   1 /*****************************************************************************
   2  * vlc_services_discovery.h : Services Discover functions
   3  *****************************************************************************
   4  * Copyright (C) 1999-2004 VLC authors and VideoLAN
   5  * $Id$
   6  *
   7  * Authors: Pierre d'Herbemont <pdherbemont # videolan.org>
   8  *
   9  * This program is free software; you can redistribute it and/or modify it
  10  * under the terms of the GNU Lesser General Public License as published by
  11  * the Free Software Foundation; either version 2.1 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17  * GNU Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public License
  20  * along with this program; if not, write to the Free Software Foundation,
  21  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  22  *****************************************************************************/
  23
  24 #ifndef VLC_SERVICES_DISCOVERY_H_
  25 #define VLC_SERVICES_DISCOVERY_H_
  26
  27 #include <vlc_input.h>
  28 #include <vlc_probe.h>
  29
  30 /**
  31  * \file
  32  * This file lists functions and structures for service discovery (SD) in vlc
  33  */
  34
  35 # ifdef __cplusplus
  36 extern "C" {
  37 # endif
  38
  39 /**
  40  * @{
  41  */
  42
  43 struct services_discovery_owner_t
  44 {
  45     void *sys; /**< Private data for the owner callbacks */
  46     void (*item_added)(struct services_discovery_t *sd, input_item_t *parent,
  47                        input_item_t *item, const char *category);
  48     void (*item_removed)(struct services_discovery_t *sd, input_item_t *item);
  49 };
  50
  51 /**
  52  * Main service discovery structure to build a SD module
  53  */
  54 struct services_discovery_t
  55 {
  56     VLC_COMMON_MEMBERS
  57     module_t *          p_module;             /**< Loaded module */
  58
  59     char *psz_name;                           /**< Main name of the SD */
  60     config_chain_t *p_cfg;                    /**< Configuration for the SD */
  61
  62     const char *description; /**< Human-readable name */
  63
  64     /** Control function
  65      * \see services_discovery_command_e
  66      */
  67     int ( *pf_control ) ( services_discovery_t *, int, va_list );
  68
  69     services_discovery_sys_t *p_sys;          /**< Custom private data */
  70
  71     struct services_discovery_owner_t owner; /**< Owner callbacks */
  72 };
  73
  74 /**
  75  * Service discovery categories
  76  * \see vlc_sd_probe_Add
  77  */
  78 enum services_discovery_category_e
  79 {
  80     SD_CAT_DEVICES = 1,           /**< Devices, like portable music players */
  81     SD_CAT_LAN,                   /**< LAN/WAN services, like Upnp or SAP */
  82     SD_CAT_INTERNET,              /**< Internet or Website channels services */
  83     SD_CAT_MYCOMPUTER             /**< Computer services, like Discs or Apps */
  84 };
  85
  86 /**
  87  * Service discovery control commands
  88  */
  89 enum services_discovery_command_e
  90 {
  91     SD_CMD_SEARCH = 1,          /**< arg1 = query */
  92     SD_CMD_DESCRIPTOR           /**< arg1 = services_discovery_descriptor_t* */
  93 };
  94
  95 /**
  96  * Service discovery capabilities
  97  */
  98 enum services_discovery_capability_e
  99 {
 100     SD_CAP_SEARCH = 1           /**< One can search in the SD */
 101 };
 102
 103 /**
 104  * Service discovery descriptor
 105  * \see services_discovery_command_e
 106  */
 107 typedef struct
 108 {
 109     char *psz_short_desc;       /**< The short description, human-readable */
 110     char *psz_icon_url;         /**< URL to the icon that represents it */
 111     char *psz_url;              /**< URL for the service */
 112     int   i_capabilities;       /**< \see services_discovery_capability_e */
 113 } services_discovery_descriptor_t;
 114
 115
 116 /***********************************************************************
 117  * Service Discovery
 118  ***********************************************************************/
 119
 120 /**
 121  * Ask for a research in the SD
 122  * @param p_sd: the Service Discovery
 123  * @param i_control: the command to issue
 124  * @param args: the argument list
 125  * @return VLC_SUCCESS in case of success, the error code overwise
 126  */
 127 static inline int vlc_sd_control( services_discovery_t *p_sd, int i_control, va_list args )
 128 {
 129     if( p_sd->pf_control )
 130         return p_sd->pf_control( p_sd, i_control, args );
 131     else
 132         return VLC_EGENERIC;
 133 }
 134
 135 /* Get the services discovery modules names to use in Create(), in a null
 136  * terminated string array. Array and string must be freed after use. */
 137 VLC_API char ** vlc_sd_GetNames( vlc_object_t *, char ***, int ** ) VLC_USED;
 138 #define vlc_sd_GetNames(obj, pln, pcat ) \
 139         vlc_sd_GetNames(VLC_OBJECT(obj), pln, pcat)
 140
 141 /**
 142  * Creates a services discoverer.
 143  */
 144 VLC_API services_discovery_t *vlc_sd_Create(vlc_object_t *parent,
 145     const char *chain, const struct services_discovery_owner_t *owner)
 146 VLC_USED;
 147
 148 VLC_API void vlc_sd_Destroy( services_discovery_t * );
 149
 150 /**
 151  * Added top-level service callback.
 152  *
 153  * This is a convenience wrapper for services_discovery_AddSubItem().
 154  * It covers the most comomn case wherby the added item is a top-level service,
 155  * i.e. it has no parent node.
 156  */
 157 static inline void services_discovery_AddItem(services_discovery_t *sd,
 158                                               input_item_t *item)
 159 {
 160     return sd->owner.item_added(sd, NULL, item, NULL);
 161 }
 162
 163 /**
 164  * Added service callback.
 165  *
 166  * A services discovery module invokes this function when it "discovers" a new
 167  * service, i.e. a new input item.
 168  *
 169  * @note This callback does not take ownership of the input item; it might
 170  * however (and most probably will) add one of more references to the item.
 171  *
 172  * The caller is responsible for releasing its own reference(s) eventually.
 173  * Keeping a reference is necessary to call services_discovery_RemoveItem() or
 174  * to alter the item later. However, if the caller will never remove nor alter
 175  * the item, it can drop its reference(s) immediately.
 176  *
 177  * @param sd services discoverer / services discovery module instance
 178  * @param item input item to add
 179  */
 180 static inline void services_discovery_AddSubItem(services_discovery_t *sd,
 181                                                  input_item_t *parent,
 182                                                  input_item_t *item)
 183 {
 184     return sd->owner.item_added(sd, parent, item, NULL);
 185 }
 186
 187 /**
 188  * Added service backward compatibility callback.
 189  *
 190  * @param category Optional name of a group that the item belongs in
 191  *                 (for backward compatibility with legacy modules)
 192  */
 193 VLC_DEPRECATED
 194 static inline void services_discovery_AddItemCat(services_discovery_t *sd,
 195                                                  input_item_t *item,
 196                                                  const char *category)
 197 {
 198     return sd->owner.item_added(sd, item, NULL, category);
 199 }
 200
 201 /**
 202  * Removed service callback.
 203  *
 204  * A services discovery module invokes this function when it senses that a
 205  * service is no longer available.
 206  */
 207 static inline void services_discovery_RemoveItem(services_discovery_t *sd,
 208                                                  input_item_t *item)
 209 {
 210     return sd->owner.item_removed(sd, item);
 211 }
 212
 213 /* SD probing */
 214
 215 VLC_API int vlc_sd_probe_Add(vlc_probe_t *, const char *, const char *, int category);
 216
 217 #define VLC_SD_PROBE_SUBMODULE \
 218     add_submodule() \
 219         set_capability( "services probe", 100 ) \
 220         set_callbacks( vlc_sd_probe_Open, NULL )
 221
 222 #define VLC_SD_PROBE_HELPER(name, longname, cat) \
 223 static int vlc_sd_probe_Open (vlc_object_t *obj) \
 224 { \
 225     return vlc_sd_probe_Add ((struct vlc_probe_t *)obj, name, \
 226                              longname, cat); \
 227 }
 228
 229 /** @} */
 230 # ifdef __cplusplus
 231 }
 232 # endif
 233
 234 #endif