11edcae2de6036165b1c4d4ea44f21da1c234995
[vlc.git] / include / vlc / libvlc_dialog.h
1 /*****************************************************************************
2  * libvlc_dialog.h:  libvlc dialog API
3  *****************************************************************************
4  * Copyright © 2016 VLC authors and VideoLAN
5  *
6  * This program is free software; you can redistribute it and/or modify it
7  * under the terms of the GNU Lesser General Public License as published by
8  * the Free Software Foundation; either version 2.1 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  * GNU Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public License
17  * along with this program; if not, write to the Free Software Foundation,
18  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
19  *****************************************************************************/
20
21 #ifndef LIBVLC_DIALOG_H
22 #define LIBVLC_DIALOG_H 1
23
24 #include <stdbool.h>
25
26 # ifdef __cplusplus
27 extern "C" {
28 # endif
29
30 typedef struct libvlc_dialog_id libvlc_dialog_id;
31
32 /**
33  * @defgroup libvlc_dialog LibVLC dialog
34  * @ingroup libvlc
35  * @{
36  * @file
37  * LibVLC dialog external API
38  */
39
40 typedef enum libvlc_dialog_question_type
41 {
42     LIBVLC_DIALOG_QUESTION_NORMAL,
43     LIBVLC_DIALOG_QUESTION_WARNING,
44     LIBVLC_DIALOG_QUESTION_CRITICAL,
45 } libvlc_dialog_question_type;
46
47 /**
48  * Dialog callbacks to be implemented
49  */
50 typedef struct libvlc_dialog_cbs
51 {
52     /**
53      * Called when an error message needs to be displayed
54      *
55      * @param p_data opaque pointer for the callback
56      * @param psz_title title of the diaog
57      * @param psz_text text of the dialog
58      */
59     void (*pf_display_error)(void *p_data, const char *psz_title,
60                              const char *psz_text);
61
62     /**
63      * Called when a login dialog needs to be displayed
64      *
65      * You can interact with this dialog by calling libvlc_dialog_post_login()
66      * to post an answer or libvlc_dialog_dismiss() to cancel this dialog.
67      *
68      * @note to receive this callack, libvlc_dialog_cbs.pf_cancel should not be
69      * NULL.
70      *
71      * @param p_data opaque pointer for the callback
72      * @param p_id id used to interact with the dialog
73      * @param psz_title title of the diaog
74      * @param psz_text text of the dialog
75      * @param psz_default_username user name that should be set on the user form
76      * @param b_ask_store if true, ask the user if he wants to save the
77      * credentials
78      */
79     void (*pf_display_login)(void *p_data, libvlc_dialog_id *p_id,
80                              const char *psz_title, const char *psz_text,
81                              const char *psz_default_username,
82                              bool b_ask_store);
83
84     /**
85      * Called when a question dialog needs to be displayed
86      *
87      * You can interact with this dialog by calling libvlc_dialog_post_action()
88      * to post an answer or libvlc_dialog_dismiss() to cancel this dialog.
89      *
90      * @note to receive this callack, libvlc_dialog_cbs.pf_cancel should not be
91      * NULL.
92      *
93      * @param p_data opaque pointer for the callback
94      * @param p_id id used to interact with the dialog
95      * @param psz_title title of the diaog
96      * @param psz_text text of the dialog
97      * @param i_type question type (or severity) of the dialog
98      * @param psz_cancel text of the cancel button
99      * @param psz_action1 text of the first button, if NULL, don't display this
100      * button
101      * @param psz_action2 text of the second button, if NULL, don't display
102      * this button
103      */
104     void (*pf_display_question)(void *p_data, libvlc_dialog_id *p_id,
105                                 const char *psz_title, const char *psz_text,
106                                 libvlc_dialog_question_type i_type,
107                                 const char *psz_cancel, const char *psz_action1,
108                                 const char *psz_action2);
109
110     /**
111      * Called when a progress dialog needs to be displayed
112      *
113      * If cancellable (psz_cancel != NULL), you can cancel this dialog by
114      * calling libvlc_dialog_dismiss()
115      *
116      * @note to receive this callack, libvlc_dialog_cbs.pf_cancel and
117      * libvlc_dialog_cbs.pf_update_progress should not be NULL.
118      *
119      * @param p_data opaque pointer for the callback
120      * @param p_id id used to interact with the dialog
121      * @param psz_title title of the diaog
122      * @param psz_text text of the dialog
123      * @param b_indeterminate true if the progress dialog is indeterminate
124      * @param f_position initial position of the progress bar (between 0.0 and
125      * 1.0)
126      * @param psz_cancel text of the cancel button, if NULL the dialog is not
127      * cancellable
128      */
129     void (*pf_display_progress)(void *p_data, libvlc_dialog_id *p_id,
130                                 const char *psz_title, const char *psz_text,
131                                 bool b_indeterminate, float f_position,
132                                 const char *psz_cancel);
133
134     /**
135      * Called when a displayed dialog needs to be cancelled
136      *
137      * The implementation must call libvlc_dialog_dismiss() to really release
138      * the dialog.
139      *
140      * @param p_data opaque pointer for the callback
141      * @param p_id id of the dialog
142      */
143     void (*pf_cancel)(void *p_data, libvlc_dialog_id *p_id);
144
145     /**
146      * Called when a progress dialog needs to be updated
147      *
148      * @param p_data opaque pointer for the callback
149      * @param p_id id of the dialog
150      * @param f_position osition of the progress bar (between 0.0 and 1.0)
151      * @param psz_text new text of the progress dialog
152      */
153     void (*pf_update_progress)(void *p_data, libvlc_dialog_id *p_id,
154                                float f_position, const char *psz_text);
155 } libvlc_dialog_cbs;
156
157 /**
158  * Register callbacks in order to handle VLC dialogs
159  *
160  * @version LibVLC 3.0.0 and later.
161  *
162  * @param p_cbs a pointer to callbacks, or NULL to unregister callbacks.
163  * @param p_data opaque pointer for the callback
164  */
165 LIBVLC_API void
166 libvlc_dialog_set_callbacks(libvlc_instance_t *p_instance,
167                             const libvlc_dialog_cbs *p_cbs, void *p_data);
168
169 /**
170  * Associate an opaque pointer with the dialog id
171  *
172  * @version LibVLC 3.0.0 and later.
173  */
174 LIBVLC_API void
175 libvlc_dialog_set_context(libvlc_dialog_id *p_id, void *p_context);
176
177 /**
178  * Return the opaque pointer associated with the dialog id
179  *
180  * @version LibVLC 3.0.0 and later.
181  */
182 LIBVLC_API void *
183 libvlc_dialog_get_context(libvlc_dialog_id *p_id);
184
185 /**
186  * Post a login answer
187  *
188  * After this call, p_id won't be valid anymore
189  *
190  * @see libvlc_dialog_cbs.pf_display_login
191  *
192  * @version LibVLC 3.0.0 and later.
193  *
194  * @param p_id id of the dialog
195  * @param psz_username valid and non empty string
196  * @param psz_password valid string (can be empty)
197  * @param b_store if true, store the credentials
198  * @return 0 on success, or -1 on error
199  */
200 LIBVLC_API int
201 libvlc_dialog_post_login(libvlc_dialog_id *p_id, const char *psz_username,
202                          const char *psz_password, bool b_store);
203
204 /**
205  * Post a question answer
206  *
207  * After this call, p_id won't be valid anymore
208  *
209  * @see libvlc_dialog_cbs.pf_display_question
210  *
211  * @version LibVLC 3.0.0 and later.
212  *
213  * @param p_id id of the dialog
214  * @param i_action 1 for action1, 2 for action2
215  * @return 0 on success, or -1 on error
216  */
217 LIBVLC_API int
218 libvlc_dialog_post_action(libvlc_dialog_id *p_id, int i_action);
219
220 /**
221  * Dismiss a dialog
222  *
223  * After this call, p_id won't be valid anymore
224  *
225  * @see libvlc_dialog_cbs.pf_cancel
226  *
227  * @version LibVLC 3.0.0 and later.
228  *
229  * @param p_id id of the dialog
230  * @return 0 on success, or -1 on error
231  */
232 LIBVLC_API int
233 libvlc_dialog_dismiss(libvlc_dialog_id *p_id);
234
235 /** @} */
236
237 # ifdef __cplusplus
238 }
239 # endif
240
241 #endif /* LIBVLC_DIALOG_H */