VLC 4.0.0-dev
Loading...
Searching...
No Matches
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
35extern "C" {
36# endif
37
38/**
39 * @{
40 */
41
44 void (*item_added)(struct services_discovery_t *sd, input_item_t *parent,
46 void (*item_removed)(struct services_discovery_t *sd, input_item_t *item);
47};
48
52 void *sys; /**< Private data for the owner callbacks */
53};
54
55/**
56 * Main service discovery structure to build a SD module
57 */
60 struct vlc_object_t obj;
61 module_t * p_module; /**< Loaded module */
63 char *psz_name; /**< Main name of the SD */
64 config_chain_t *p_cfg; /**< Configuration for the SD */
66 const char *description; /**< Human-readable name */
68 /** Control function
69 * \see services_discovery_command_e
70 */
71 int ( *pf_control ) ( services_discovery_t *, int, va_list );
73 void *p_sys; /**< Custom private data */
75 struct services_discovery_owner_t owner; /**< Owner callbacks */
76};
77
78/**
79 * Service discovery categories
80 * \see vlc_sd_probe_Add
81 */
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};
90/**
91 * Service discovery control commands
92 */
95 SD_CMD_SEARCH = 1, /**< arg1 = query */
96 SD_CMD_DESCRIPTOR /**< arg1 = services_discovery_descriptor_t* */
97};
99/**
100 * Service discovery capabilities
101 */
104 SD_CAP_SEARCH = 1 /**< One can search in the SD */
105};
107/**
108 * Service discovery descriptor
109 * \see services_discovery_command_e
110 */
111typedef struct
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 otherwise
130 */
131static inline int vlc_sd_control( services_discovery_t *p_sd, int i_control, va_list args )
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. */
141VLC_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)
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 */
165{
166 sd->owner.cbs->item_added(sd, NULL, item);
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 the service discovery instance exposing the item
184 * @param parent the parent to attach the item to
185 * @param item input item to add
186 */
189 input_item_t *item)
190{
191 sd->owner.cbs->item_added(sd, parent, item);
192}
193
194/**
195 * Removed service callback.
196 *
197 * A services discovery module invokes this function when it senses that a
198 * service is no longer available.
199 */
202{
203 sd->owner.cbs->item_removed(sd, item);
204}
205
206/* SD probing */
207
208VLC_API int vlc_sd_probe_Add(vlc_probe_t *, const char *, const char *, int category);
209
210#define VLC_SD_PROBE_SUBMODULE \
211 add_submodule() \
212 set_capability( "services probe", 100 ) \
213 set_callback( vlc_sd_probe_Open )
214
215#define VLC_SD_PROBE_HELPER(name, longname, cat) \
216static int vlc_sd_probe_Open (vlc_object_t *obj) \
217{ \
218 return vlc_sd_probe_Add ((struct vlc_probe_t *)obj, name, \
219 longname, cat); \
220}
221
222/** @} */
223# ifdef __cplusplus
224}
225# endif
226
227#endif
#define VLC_USED
Definition fourcc_gen.c:32
#define VLC_API
Definition fourcc_gen.c:31
#define VLC_EGENERIC
Unspecified error.
Definition vlc_common.h:480
Definition vlc_configuration.h:320
Describes an input and is used to spawn input_thread_t objects.
Definition vlc_input_item.h:98
Internal module descriptor.
Definition modules.h:76
Definition vlc_services_discovery.h:44
void(* item_removed)(struct services_discovery_t *sd, input_item_t *item)
Definition vlc_services_discovery.h:47
void(* item_added)(struct services_discovery_t *sd, input_item_t *parent, input_item_t *item)
Definition vlc_services_discovery.h:45
Service discovery descriptor.
Definition vlc_services_discovery.h:113
char * psz_short_desc
The short description, human-readable.
Definition vlc_services_discovery.h:114
int i_capabilities
Definition vlc_services_discovery.h:117
char * psz_url
URL for the service.
Definition vlc_services_discovery.h:116
char * psz_icon_url
URL to the icon that represents it.
Definition vlc_services_discovery.h:115
Definition vlc_services_discovery.h:51
void * sys
Private data for the owner callbacks.
Definition vlc_services_discovery.h:53
const struct services_discovery_callbacks * cbs
Definition vlc_services_discovery.h:52
Main service discovery structure to build a SD module.
Definition vlc_services_discovery.h:60
config_chain_t * p_cfg
Configuration for the SD.
Definition vlc_services_discovery.h:65
struct services_discovery_owner_t owner
Owner callbacks.
Definition vlc_services_discovery.h:76
char * psz_name
Main name of the SD.
Definition vlc_services_discovery.h:64
struct vlc_object_t obj
Definition vlc_services_discovery.h:61
module_t * p_module
Loaded module.
Definition vlc_services_discovery.h:62
int(* pf_control)(services_discovery_t *, int, va_list)
Control function.
Definition vlc_services_discovery.h:72
const char * description
Human-readable name.
Definition vlc_services_discovery.h:67
void * p_sys
Custom private data.
Definition vlc_services_discovery.h:74
VLC object common members.
Definition vlc_objects.h:53
Definition vlc_probe.h:41
This file is a collection of common definitions and types.
Input thread interface.
This file defines functions and structures to run-time probe VLC extensions.
void vlc_sd_Destroy(services_discovery_t *)
Definition services_discovery.c:131
services_discovery_category_e
Service discovery categories.
Definition vlc_services_discovery.h:84
@ SD_CAT_INTERNET
Internet or Website channels services.
Definition vlc_services_discovery.h:87
@ SD_CAT_LAN
LAN/WAN services, like Upnp or SAP.
Definition vlc_services_discovery.h:86
@ SD_CAT_MYCOMPUTER
Computer services, like Discs or Apps.
Definition vlc_services_discovery.h:88
@ SD_CAT_DEVICES
Devices, like portable music players.
Definition vlc_services_discovery.h:85
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
static void services_discovery_RemoveItem(services_discovery_t *sd, input_item_t *item)
Removed service callback.
Definition vlc_services_discovery.h:201
#define vlc_sd_Create(obj, a, b)
Definition vlc_services_discovery.h:152
services_discovery_capability_e
Service discovery capabilities.
Definition vlc_services_discovery.h:104
@ SD_CAP_SEARCH
One can search in the SD.
Definition vlc_services_discovery.h:105
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
Service discovery control commands.
Definition vlc_services_discovery.h:95
@ SD_CMD_SEARCH
arg1 = query
Definition vlc_services_discovery.h:96
@ SD_CMD_DESCRIPTOR
arg1 = services_discovery_descriptor_t*
Definition vlc_services_discovery.h:97
int vlc_sd_probe_Add(vlc_probe_t *, const char *, const char *, int category)
Definition services_discovery.c:41
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:188
#define vlc_sd_GetNames(obj, pln, pcat)
Definition vlc_services_discovery.h:143