VLC 4.0.0-dev
Loading...
Searching...
No Matches
libvlc_dialog.h
Go to the documentation of this file.
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
31
32/**
33 * @defgroup libvlc_dialog LibVLC dialog
34 * @ingroup libvlc
35 * @{
36 * @file
37 * LibVLC dialog external API
38 */
39
46
47/**
48 * Dialog callbacks to be implemented
49 *
50 * @attention starting with vlc 4.0.0 the error callback (pf_display_error) is
51 * no longer part of this struct and need to be registered separately
52 * using @a libvlc_dialog_set_error_callback
53 *
54 * @see libvlc_dialog_set_error_callback
55 */
56typedef struct libvlc_dialog_cbs
57{
58 /**
59 * Called when a login dialog needs to be displayed
60 *
61 * You can interact with this dialog by calling libvlc_dialog_post_login()
62 * to post an answer or libvlc_dialog_dismiss() to cancel this dialog.
63 *
64 * @note to receive this callback, libvlc_dialog_cbs.pf_cancel should not be
65 * NULL.
66 *
67 * @param p_data opaque pointer for the callback
68 * @param p_id id used to interact with the dialog
69 * @param psz_title title of the dialog
70 * @param psz_text text of the dialog
71 * @param psz_default_username user name that should be set on the user form
72 * @param b_ask_store if true, ask the user if he wants to save the
73 * credentials
74 */
75 void (*pf_display_login)(void *p_data, libvlc_dialog_id *p_id,
76 const char *psz_title, const char *psz_text,
77 const char *psz_default_username,
78 bool b_ask_store);
79
80 /**
81 * Called when a question dialog needs to be displayed
82 *
83 * You can interact with this dialog by calling libvlc_dialog_post_action()
84 * to post an answer or libvlc_dialog_dismiss() to cancel this dialog.
85 *
86 * @note to receive this callback, libvlc_dialog_cbs.pf_cancel should not be
87 * NULL.
88 *
89 * @param p_data opaque pointer for the callback
90 * @param p_id id used to interact with the dialog
91 * @param psz_title title of the dialog
92 * @param psz_text text of the dialog
93 * @param i_type question type (or severity) of the dialog
94 * @param psz_cancel text of the cancel button
95 * @param psz_action1 text of the first button, if NULL, don't display this
96 * button
97 * @param psz_action2 text of the second button, if NULL, don't display
98 * this button
99 */
100 void (*pf_display_question)(void *p_data, libvlc_dialog_id *p_id,
101 const char *psz_title, const char *psz_text,
103 const char *psz_cancel, const char *psz_action1,
104 const char *psz_action2);
105
106 /**
107 * Called when a progress dialog needs to be displayed
108 *
109 * If cancellable (psz_cancel != NULL), you can cancel this dialog by
110 * calling libvlc_dialog_dismiss()
111 *
112 * @note to receive this callback, libvlc_dialog_cbs.pf_cancel and
113 * libvlc_dialog_cbs.pf_update_progress should not be NULL.
114 *
115 * @param p_data opaque pointer for the callback
116 * @param p_id id used to interact with the dialog
117 * @param psz_title title of the dialog
118 * @param psz_text text of the dialog
119 * @param b_indeterminate true if the progress dialog is indeterminate
120 * @param f_position initial position of the progress bar (between 0.0 and
121 * 1.0)
122 * @param psz_cancel text of the cancel button, if NULL the dialog is not
123 * cancellable
124 */
125 void (*pf_display_progress)(void *p_data, libvlc_dialog_id *p_id,
126 const char *psz_title, const char *psz_text,
127 bool b_indeterminate, float f_position,
128 const char *psz_cancel);
129
130 /**
131 * Called when a displayed dialog needs to be cancelled
132 *
133 * The implementation must call libvlc_dialog_dismiss() to really release
134 * the dialog.
135 *
136 * @param p_data opaque pointer for the callback
137 * @param p_id id of the dialog
138 */
139 void (*pf_cancel)(void *p_data, libvlc_dialog_id *p_id);
140
141 /**
142 * Called when a progress dialog needs to be updated
143 *
144 * @param p_data opaque pointer for the callback
145 * @param p_id id of the dialog
146 * @param f_position osition of the progress bar (between 0.0 and 1.0)
147 * @param psz_text new text of the progress dialog
148 */
149 void (*pf_update_progress)(void *p_data, libvlc_dialog_id *p_id,
150 float f_position, const char *psz_text);
152
153
154/**
155 * Called when an error message needs to be displayed
156 *
157 * @param p_data opaque pointer for the callback
158 * @param psz_title title of the dialog
159 * @param psz_text text of the dialog
160 */
161typedef void (*libvlc_dialog_error_cbs)(void *p_data, const char *psz_title, const char *psz_text);
162
163/**
164 * Register callbacks in order to handle VLC dialogs
165 *
166 * @version LibVLC 3.0.0 and later.
167 *
168 * @param p_instance the libvlc instance to attach the dialog callbacks to
169 * @param p_cbs a pointer to callbacks, or NULL to unregister callbacks.
170 * @param p_data opaque pointer for the callback
171 */
172LIBVLC_API void
174 const libvlc_dialog_cbs *p_cbs, void *p_data);
175
176/*
177* Register callback in order to handle VLC error messages
178*
179* @version LibVLC 4.0.0 and later.
180*
181* @param p_cbs a pointer to callback, or NULL to unregister callback.
182* @param p_data opaque pointer for the callback
183*/
184LIBVLC_API void
186 libvlc_dialog_error_cbs p_cbs, void *p_data);
187
188/**
189 * Associate an opaque pointer with the dialog id
190 *
191 * @version LibVLC 3.0.0 and later.
192 */
193LIBVLC_API void
195
196/**
197 * Return the opaque pointer associated with the dialog id
198 * \see libvlc_dialog_set_context
199 * @version LibVLC 3.0.0 and later.
200 */
201LIBVLC_API void *
203
204/**
205 * Post a login answer
206 *
207 * After this call, p_id won't be valid anymore
208 *
209 * @see libvlc_dialog_cbs.pf_display_login
210 *
211 * @version LibVLC 3.0.0 and later.
212 *
213 * @param p_id id of the dialog
214 * @param psz_username valid and non empty string
215 * @param psz_password valid string (can be empty)
216 * @param b_store if true, store the credentials
217 * @return 0 on success, or -1 on error
218 */
219LIBVLC_API int
220libvlc_dialog_post_login(libvlc_dialog_id *p_id, const char *psz_username,
221 const char *psz_password, bool b_store);
222
223/**
224 * Post a question answer
225 *
226 * After this call, p_id won't be valid anymore
227 *
228 * @see libvlc_dialog_cbs.pf_display_question
229 *
230 * @version LibVLC 3.0.0 and later.
231 *
232 * @param p_id id of the dialog
233 * @param i_action 1 for action1, 2 for action2
234 * @return 0 on success, or -1 on error
235 */
236LIBVLC_API int
238
239/**
240 * Dismiss a dialog
241 *
242 * After this call, p_id won't be valid anymore
243 *
244 * @see libvlc_dialog_cbs.pf_cancel
245 *
246 * @version LibVLC 3.0.0 and later.
247 *
248 * @param p_id id of the dialog
249 * @return 0 on success, or -1 on error
250 */
251LIBVLC_API int
253
254/** @} */
255
256# ifdef __cplusplus
257}
258# endif
259
260#endif /* LIBVLC_DIALOG_H */
struct libvlc_instance_t libvlc_instance_t
This structure is opaque.
Definition libvlc.h:76
LIBVLC_API void libvlc_dialog_set_error_callback(libvlc_instance_t *p_instance, libvlc_dialog_error_cbs p_cbs, void *p_data)
libvlc_dialog_question_type
Definition libvlc_dialog.h:41
LIBVLC_API int libvlc_dialog_dismiss(libvlc_dialog_id *p_id)
Dismiss a dialog.
LIBVLC_API int libvlc_dialog_post_action(libvlc_dialog_id *p_id, int i_action)
Post a question answer.
LIBVLC_API void libvlc_dialog_set_callbacks(libvlc_instance_t *p_instance, const libvlc_dialog_cbs *p_cbs, void *p_data)
Register callbacks in order to handle VLC dialogs.
LIBVLC_API void libvlc_dialog_set_context(libvlc_dialog_id *p_id, void *p_context)
Associate an opaque pointer with the dialog id.
void(* libvlc_dialog_error_cbs)(void *p_data, const char *psz_title, const char *psz_text)
Called when an error message needs to be displayed.
Definition libvlc_dialog.h:161
LIBVLC_API int libvlc_dialog_post_login(libvlc_dialog_id *p_id, const char *psz_username, const char *psz_password, bool b_store)
Post a login answer.
LIBVLC_API void * libvlc_dialog_get_context(libvlc_dialog_id *p_id)
Return the opaque pointer associated with the dialog id.
@ LIBVLC_DIALOG_QUESTION_WARNING
Definition libvlc_dialog.h:43
@ LIBVLC_DIALOG_QUESTION_CRITICAL
Definition libvlc_dialog.h:44
@ LIBVLC_DIALOG_QUESTION_NORMAL
Definition libvlc_dialog.h:42
#define LIBVLC_API
Definition libvlc.h:42
int i_type
Definition httpd.c:1299
struct libvlc_dialog_id libvlc_dialog_id
Definition libvlc_dialog.h:30
Dialog callbacks to be implemented.
Definition libvlc_dialog.h:57
void(* pf_display_login)(void *p_data, libvlc_dialog_id *p_id, const char *psz_title, const char *psz_text, const char *psz_default_username, bool b_ask_store)
Called when a login dialog needs to be displayed.
Definition libvlc_dialog.h:75
void(* pf_update_progress)(void *p_data, libvlc_dialog_id *p_id, float f_position, const char *psz_text)
Called when a progress dialog needs to be updated.
Definition libvlc_dialog.h:149
void(* pf_cancel)(void *p_data, libvlc_dialog_id *p_id)
Called when a displayed dialog needs to be cancelled.
Definition libvlc_dialog.h:139
void(* pf_display_question)(void *p_data, libvlc_dialog_id *p_id, const char *psz_title, const char *psz_text, libvlc_dialog_question_type i_type, const char *psz_cancel, const char *psz_action1, const char *psz_action2)
Called when a question dialog needs to be displayed.
Definition libvlc_dialog.h:100
void(* pf_display_progress)(void *p_data, libvlc_dialog_id *p_id, const char *psz_title, const char *psz_text, bool b_indeterminate, float f_position, const char *psz_cancel)
Called when a progress dialog needs to be displayed.
Definition libvlc_dialog.h:125