sd: use owner structure instead of legacy event manager
[vlc.git] / 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 *item,
47                        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     /** Control function
63      * \see services_discovery_command_e
64      */
65     int ( *pf_control ) ( services_discovery_t *, int, va_list );
66
67     services_discovery_sys_t *p_sys;          /**< Custom private data */
68
69     struct services_discovery_owner_t owner; /**< Owner callbacks */
70 };
71
72 /**
73  * Service discovery categories
74  * \see vlc_sd_probe_Add
75  */
76 enum services_discovery_category_e
77 {
78     SD_CAT_DEVICES = 1,           /**< Devices, like portable music players */
79     SD_CAT_LAN,                   /**< LAN/WAN services, like Upnp or SAP */
80     SD_CAT_INTERNET,              /**< Internet or Website channels services */
81     SD_CAT_MYCOMPUTER             /**< Computer services, like Discs or Apps */
82 };
83
84 /**
85  * Service discovery control commands
86  */
87 enum services_discovery_command_e
88 {
89     SD_CMD_SEARCH = 1,          /**< arg1 = query */
90     SD_CMD_DESCRIPTOR           /**< arg1 = services_discovery_descriptor_t* */
91 };
92
93 /**
94  * Service discovery capabilities
95  */
96 enum services_discovery_capability_e
97 {
98     SD_CAP_SEARCH = 1           /**< One can search in the SD */
99 };
100
101 /**
102  * Service discovery descriptor
103  * \see services_discovery_command_e
104  */
105 typedef struct
106 {
107     char *psz_short_desc;       /**< The short description, human-readable */
108     char *psz_icon_url;         /**< URL to the icon that represents it */
109     char *psz_url;              /**< URL for the service */
110     int   i_capabilities;       /**< \see services_discovery_capability_e */
111 } services_discovery_descriptor_t;
112
113
114 /***********************************************************************
115  * Service Discovery
116  ***********************************************************************/
117
118 /**
119  * Ask for a research in the SD
120  * @param p_sd: the Service Discovery
121  * @param i_control: the command to issue
122  * @param args: the argument list
123  * @return VLC_SUCCESS in case of success, the error code overwise
124  */
125 static inline int vlc_sd_control( services_discovery_t *p_sd, int i_control, va_list args )
126 {
127     if( p_sd->pf_control )
128         return p_sd->pf_control( p_sd, i_control, args );
129     else
130         return VLC_EGENERIC;
131 }
132
133 /* Get the services discovery modules names to use in Create(), in a null
134  * terminated string array. Array and string must be freed after use. */
135 VLC_API char ** vlc_sd_GetNames( vlc_object_t *, char ***, int ** ) VLC_USED;
136 #define vlc_sd_GetNames(obj, pln, pcat ) \
137         vlc_sd_GetNames(VLC_OBJECT(obj), pln, pcat)
138
139 /**
140  * Creates a services discoverer.
141  */
142 VLC_API services_discovery_t *vlc_sd_Create(vlc_object_t *parent,
143     const char *chain, const struct services_discovery_owner_t *owner)
144 VLC_USED;
145
146 VLC_API bool vlc_sd_Start( services_discovery_t * );
147 VLC_API void vlc_sd_Stop( services_discovery_t * );
148 VLC_API void vlc_sd_Destroy( services_discovery_t * );
149
150 /**
151  * Helper to stop and destroy the Service Discovery
152  */
153 static inline void vlc_sd_StopAndDestroy( services_discovery_t * p_this )
154 {
155     vlc_sd_Stop( p_this );
156     vlc_sd_Destroy( p_this );
157 }
158
159 /* Read info from discovery object */
160 VLC_API char * services_discovery_GetLocalizedName( services_discovery_t * p_this ) VLC_USED;
161
162 /* Receive event notification (preferred way to get new items) */
163 VLC_API vlc_event_manager_t * services_discovery_EventManager( services_discovery_t * p_this ) VLC_USED;
164
165 /**
166  * Added service callback.
167  *
168  * A services discovery module invokes this function when it "discovers" a new
169  * service, i.e. a new input item.
170  *
171  * @note The function does not take ownership of the input item; it might
172  * however add one of more references. The caller is responsible for releasing
173  * its reference to the input item.
174  *
175  * @param sd services discoverer / services discovery module instance
176  * @param item input item to add
177  * @param category Optional name of a group that the item belongs in
178  *                 (for backward compatibility with legacy modules)
179  */
180 static inline void services_discovery_AddItem(services_discovery_t *sd,
181                                               input_item_t *item,
182                                               const char *category)
183 {
184     return sd->owner.item_added(sd, item, category);
185 }
186
187 /**
188  * Removed service callback.
189  *
190  * A services discovery module invokes this function when it senses that a
191  * service is no longer available.
192  */
193 static inline void services_discovery_RemoveItem(services_discovery_t *sd,
194                                                  input_item_t *item)
195 {
196     return sd->owner.item_removed(sd, item);
197 }
198
199 /* SD probing */
200
201 VLC_API int vlc_sd_probe_Add(vlc_probe_t *, const char *, const char *, int category);
202
203 #define VLC_SD_PROBE_SUBMODULE \
204     add_submodule() \
205         set_capability( "services probe", 100 ) \
206         set_callbacks( vlc_sd_probe_Open, NULL )
207
208 #define VLC_SD_PROBE_HELPER(name, longname, cat) \
209 static int vlc_sd_probe_Open (vlc_object_t *obj) \
210 { \
211     return vlc_sd_probe_Add ((struct vlc_probe_t *)obj, \
212                              name "{longname=\"" longname "\"}", \
213                              longname, cat); \
214 }
215
216 /** @} */
217 # ifdef __cplusplus
218 }
219 # endif
220
221 #endif