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
27extern "C" {
28# endif
29
30typedef 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
40typedef 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 */
50typedef 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 dialog
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 callback, 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 dialog
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 callback, 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 dialog
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 callback, 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 dialog
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 */
165LIBVLC_API void
166libvlc_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 */
174LIBVLC_API void
175libvlc_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 */
182LIBVLC_API void *
183libvlc_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 */
200LIBVLC_API int
201libvlc_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 */
217LIBVLC_API int
218libvlc_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 */
232LIBVLC_API int
233libvlc_dialog_dismiss(libvlc_dialog_id *p_id);
234
235/** @} */
236
237# ifdef __cplusplus
238}
239# endif
240
241#endif /* LIBVLC_DIALOG_H */
242

source code of include/vlc/libvlc_dialog.h