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