include/vlc_dialog.h

   1 /*****************************************************************************
   2  * vlc_dialog.h: user interaction dialogs
   3  *****************************************************************************
   4  * Copyright (C) 2009 Rémi Denis-Courmont
   5  * Copyright (C) 2016 VLC authors and VideoLAN
   6  *
   7  * This program is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU Lesser General Public License as published by
   9  * the Free Software Foundation; either version 2.1 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  15  * GNU Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public License
  18  * along with this program; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  20  *****************************************************************************/
  21
  22 #ifndef VLC_DIALOG_H_
  23 #define VLC_DIALOG_H_
  24 # include <stdarg.h>
  25
  26 typedef struct vlc_dialog_provider vlc_dialog_provider;
  27 typedef struct vlc_dialog_id vlc_dialog_id;
  28 typedef struct extension_dialog_t extension_dialog_t;
  29
  30 /* Called from src/libvlc.c */
  31 int
  32 libvlc_InternalDialogInit(libvlc_int_t *p_libvlc);
  33
  34 /* Called from src/libvlc.c */
  35 void
  36 libvlc_InternalDialogClean(libvlc_int_t *p_libvlc);
  37
  38 /**
  39  * @defgroup vlc_dialog VLC dialog
  40  * @ingroup interface
  41  * @{
  42  * @file
  43  * This file declares VLC dialog functions
  44  * @defgroup vlc_dialog_api VLC dialog functions
  45  * In order to interact with the user
  46  * @{
  47  */
  48
  49 /**
  50  * Dialog question type, see vlc_dialog_wait_question()
  51  */
  52 typedef enum vlc_dialog_question_type
  53 {
  54     VLC_DIALOG_QUESTION_NORMAL,
  55     VLC_DIALOG_QUESTION_WARNING,
  56     VLC_DIALOG_QUESTION_CRITICAL,
  57 } vlc_dialog_question_type;
  58
  59 /**
  60  * Sends an error message
  61  *
  62  * This function returns immediately
  63  *
  64  * @param p_obj the VLC object emitting the error
  65  * @param psz_title title of the error dialog
  66  * @param psz_fmt format string for the error message
  67  * @return VLC_SUCCESS on success, or a VLC error code on error
  68  */
  69 VLC_API int
  70 vlc_dialog_display_error(vlc_object_t *p_obj, const char *psz_title,
  71                          const char *psz_fmt, ...) VLC_FORMAT(3,4);
  72 #define vlc_dialog_display_error(a, b, c, ...) \
  73     vlc_dialog_display_error(VLC_OBJECT(a), b, c, ##__VA_ARGS__)
  74
  75 /**
  76  * Sends an error message
  77  *
  78  * Equivalent to vlc_dialog_display_error() expect that it's called with a
  79  * va_list.
  80  */
  81 VLC_API int
  82 vlc_dialog_display_error_va(vlc_object_t *p_obj, const char *psz_title,
  83                             const char *psz_fmt, va_list ap);
  84
  85 /**
  86  * Requests an user name and a password
  87  *
  88  * This function waits until the user dismisses the dialog or responds. It's
  89  * interruptible via vlc_interrupt. In that case, vlc_dialog_cbs.pf_cancel()
  90  * will be invoked. If p_store is not NULL, the user will be asked to store the
  91  * password or not.
  92  *
  93  * @param p_obj the VLC object emitting the dialog
  94  * @param ppsz_username a pointer to the user name provided by the user, it
  95  * must be freed with free() on success
  96  * @param ppsz_password a pointer to the password provided by the user, it must
  97  * be freed with free() on success
  98  * @param p_store a pointer to the store answer provided by the user (optional)
  99  * @param psz_default_username default user name proposed
 100  * @param psz_title title of the login dialog
 101  * @param psz_fmt format string for the login message
 102  * @return < 0 on error, 0 if the user cancelled it, and 1 if ppsz_username and
 103  * ppsz_password are valid.
 104  */
 105 VLC_API int
 106 vlc_dialog_wait_login(vlc_object_t *p_obj, char **ppsz_username,
 107                       char **ppsz_password, bool *p_store,
 108                       const char *psz_default_username,
 109                       const char *psz_title, const char *psz_fmt, ...)
 110                       VLC_FORMAT(7,8);
 111 #define vlc_dialog_wait_login(a, b, c, d, e, f, g, ...) \
 112     vlc_dialog_wait_login(VLC_OBJECT(a), b, c, d, e, f, g, ##__VA_ARGS__)
 113
 114 /**
 115  * Requests an user name and a password
 116  *
 117  * Equivalent to vlc_dialog_wait_login() expect that it's called with a
 118  * va_list.
 119  */
 120 VLC_API int
 121 vlc_dialog_wait_login_va(vlc_object_t *p_obj, char **ppsz_username,
 122                          char **ppsz_password, bool *p_store,
 123                          const char *psz_default_username,
 124                          const char *psz_title, const char *psz_fmt, va_list ap);
 125
 126 /**
 127  * Asks a total (Yes/No/Cancel) question
 128  *
 129  * This function waits until the user dismisses the dialog or responds. It's
 130  * interruptible via vlc_interrupt. In that case, vlc_dialog_cbs.pf_cancel()
 131  * will be invoked. The psz_cancel is mandatory since this dialog is always
 132  * cancellable by the user.
 133  *
 134  * @param p_obj the VLC object emitting the dialog
 135  * @param i_type question type (severity of the question)
 136  * @param psz_cancel text of the cancel button
 137  * @param psz_action1 first choice/button text (optional)
 138  * @param psz_action2 second choice/button text (optional)
 139  * @param psz_title title of the question dialog
 140  * @param psz_fmt format string for the question message
 141  * @return < 0 on error, 0 if the user cancelled it, 1 on action1, 2 on action2
 142  */
 143 VLC_API int
 144 vlc_dialog_wait_question(vlc_object_t *p_obj,
 145                          vlc_dialog_question_type i_type,
 146                          const char *psz_cancel, const char *psz_action1,
 147                          const char *psz_action2, const char *psz_title,
 148                          const char *psz_fmt, ...) VLC_FORMAT(7,8);
 149 #define vlc_dialog_wait_question(a, b, c, d, e, f, g, ...) \
 150     vlc_dialog_wait_question(VLC_OBJECT(a), b, c, d, e, f, g, ##__VA_ARGS__)
 151
 152 /**
 153  * Asks a total (Yes/No/Cancel) question
 154  *
 155  * Equivalent to vlc_dialog_wait_question() expect that it's called with a
 156  * va_list.
 157  */
 158 VLC_API int
 159 vlc_dialog_wait_question_va(vlc_object_t *p_obj,
 160                             vlc_dialog_question_type i_type,
 161                             const char *psz_cancel, const char *psz_action1,
 162                             const char *psz_action2, const char *psz_title,
 163                             const char *psz_fmt, va_list ap);
 164
 165 /**
 166  * Display a progress dialog
 167  *
 168  * This function returns immediately
 169  *
 170  * @param p_obj the VLC object emitting the dialog
 171  * @param b_indeterminate true if the progress dialog is indeterminate
 172  * @param f_position initial position of the progress bar (between 0.0 and 1.0)
 173  * @param psz_cancel text of the cancel button, if NULL the dialog is not
 174  * cancellable (optional)
 175  * @param psz_title title of the progress dialog
 176  * @param psz_fmt format string for the progress message
 177  * @return a valid vlc_dialog_id on success, must be released with
 178  * vlc_dialog_id_release()
 179  */
 180 VLC_API vlc_dialog_id *
 181 vlc_dialog_display_progress(vlc_object_t *p_obj, bool b_indeterminate,
 182                             float f_position, const char *psz_cancel,
 183                             const char *psz_title, const char *psz_fmt, ...)
 184                             VLC_FORMAT(6,7);
 185 #define vlc_dialog_display_progress(a, b, c, d, e, f, ...) \
 186     vlc_dialog_display_progress(VLC_OBJECT(a), b, c, d, e, f, ##__VA_ARGS__)
 187
 188 /**
 189  * Display a progress dialog
 190  *
 191  * Equivalent to vlc_dialog_display_progress() expect that it's called with a
 192  * va_list.
 193  */
 194 VLC_API vlc_dialog_id *
 195 vlc_dialog_display_progress_va(vlc_object_t *p_obj, bool b_indeterminate,
 196                                float f_position, const char *psz_cancel,
 197                                const char *psz_title, const char *psz_fmt,
 198                                va_list ap);
 199
 200 /**
 201  * Update the position of the progress dialog
 202  *
 203  * @param p_obj the VLC object emitting the dialog
 204  * @param p_id id of the dialog to update
 205  * @param f_position position of the progress bar (between 0.0 and 1.0)
 206  * @return VLC_SUCCESS on success, or a VLC error code on error
 207  */
 208 VLC_API int
 209 vlc_dialog_update_progress(vlc_object_t *p_obj, vlc_dialog_id *p_id,
 210                            float f_position);
 211 #define vlc_dialog_update_progress(a, b, c) \
 212     vlc_dialog_update_progress(VLC_OBJECT(a), b, c)
 213
 214 /**
 215  * Update the position and the message of the progress dialog
 216  *
 217  * @param p_obj the VLC object emitting the dialog
 218  * @param p_id id of the dialog to update
 219  * @param f_position position of the progress bar (between 0.0 and 1.0)
 220  * @param psz_fmt format string for the progress message
 221  * @return VLC_SUCCESS on success, or a VLC error code on error
 222  */
 223 VLC_API int
 224 vlc_dialog_update_progress_text(vlc_object_t *p_obj, vlc_dialog_id *p_id,
 225                                 float f_position, const char *psz_fmt, ...)
 226                                 VLC_FORMAT(4, 5);
 227 #define vlc_dialog_update_progress_text(a, b, c, d, ...) \
 228     vlc_dialog_update_progress_text(VLC_OBJECT(a), b, c, d, ##__VA_ARGS__)
 229
 230 /**
 231  * Update the position and the message of the progress dialog
 232  *
 233  * Equivalent to vlc_dialog_update_progress_text() expect that it's called
 234  * with a va_list.
 235  */
 236 VLC_API int
 237 vlc_dialog_update_progress_text_va(vlc_object_t *p_obj, vlc_dialog_id *p_id,
 238                                    float f_position, const char *psz_fmt,
 239                                    va_list ap);
 240
 241 /**
 242  * Release the dialog id returned by vlc_dialog_display_progress()
 243  *
 244  * It causes the vlc_dialog_cbs.pf_cancel() callback to be invoked.
 245  *
 246  * @param p_obj the VLC object emitting the dialog
 247  * @param p_id id of the dialog to release
 248  */
 249 VLC_API void
 250 vlc_dialog_release(vlc_object_t *p_obj, vlc_dialog_id *p_id);
 251 #define vlc_dialog_release(a, b) \
 252     vlc_dialog_release(VLC_OBJECT(a), b)
 253
 254 /**
 255  * Return true if the dialog id is cancelled
 256  *
 257  * @param p_obj the VLC object emitting the dialog
 258  * @param p_id id of the dialog
 259  */
 260 VLC_API bool
 261 vlc_dialog_is_cancelled(vlc_object_t *p_obj, vlc_dialog_id *p_id);
 262 #define vlc_dialog_is_cancelled(a, b) \
 263     vlc_dialog_is_cancelled(VLC_OBJECT(a), b)
 264
 265 /**
 266  * @}
 267  * @defgroup vlc_dialog_impl VLC dialog callbacks
 268  * Need to be implemented by GUI modules or libvlc
 269  * @{
 270  */
 271
 272 /**
 273  * Dialog callbacks to be implemented
 274  */
 275 typedef struct vlc_dialog_cbs
 276 {
 277     /**
 278      * Called when an error message needs to be displayed
 279      *
 280      * @param p_data opaque pointer for the callback
 281      * @param psz_title title of the dialog
 282      * @param psz_text text of the dialog
 283      */
 284     void (*pf_display_error)(void *p_data, const char *psz_title,
 285                              const char *psz_text);
 286
 287     /**
 288      * Called when a login dialog needs to be displayed
 289      *
 290      * You can interact with this dialog by calling vlc_dialog_id_post_login()
 291      * to post an answer or vlc_dialog_id_dismiss() to cancel this dialog.
 292      *
 293      * @note to receive this callback, vlc_dialog_cbs.pf_cancel should not be
 294      * NULL.
 295      *
 296      * @param p_data opaque pointer for the callback
 297      * @param p_id id used to interact with the dialog
 298      * @param psz_title title of the dialog
 299      * @param psz_text text of the dialog
 300      * @param psz_default_username user name that should be set on the user form
 301      * @param b_ask_store if true, ask the user if he wants to save the
 302      * credentials
 303      */
 304     void (*pf_display_login)(void *p_data, vlc_dialog_id *p_id,
 305                              const char *psz_title, const char *psz_text,
 306                              const char *psz_default_username,
 307                              bool b_ask_store);
 308
 309     /**
 310      * Called when a question dialog needs to be displayed
 311      *
 312      * You can interact with this dialog by calling vlc_dialog_id_post_action()
 313      * to post an answer or vlc_dialog_id_dismiss() to cancel this dialog.
 314      *
 315      * @note to receive this callback, vlc_dialog_cbs.pf_cancel should not be
 316      * NULL.
 317      *
 318      * @param p_data opaque pointer for the callback
 319      * @param p_id id used to interact with the dialog
 320      * @param psz_title title of the dialog
 321      * @param psz_text text of the dialog
 322      * @param i_type question type (or severity) of the dialog
 323      * @param psz_cancel text of the cancel button
 324      * @param psz_action1 text of the first button, if NULL, don't display this
 325      * button
 326      * @param psz_action2 text of the second button, if NULL, don't display
 327      * this button
 328      */
 329     void (*pf_display_question)(void *p_data, vlc_dialog_id *p_id,
 330                                 const char *psz_title, const char *psz_text,
 331                                 vlc_dialog_question_type i_type,
 332                                 const char *psz_cancel, const char *psz_action1,
 333                                 const char *psz_action2);
 334
 335     /**
 336      * Called when a progress dialog needs to be displayed
 337      *
 338      * If cancellable (psz_cancel != NULL), you can cancel this dialog by
 339      * calling vlc_dialog_id_dismiss()
 340      *
 341      * @note to receive this callback, vlc_dialog_cbs.pf_cancel and
 342      * vlc_dialog_cbs.pf_update_progress should not be NULL.
 343      *
 344      * @param p_data opaque pointer for the callback
 345      * @param p_id id used to interact with the dialog
 346      * @param psz_title title of the dialog
 347      * @param psz_text text of the dialog
 348      * @param b_indeterminate true if the progress dialog is indeterminate
 349      * @param f_position initial position of the progress bar (between 0.0 and
 350      * 1.0)
 351      * @param psz_cancel text of the cancel button, if NULL the dialog is not
 352      * cancellable
 353      */
 354     void (*pf_display_progress)(void *p_data, vlc_dialog_id *p_id,
 355                                 const char *psz_title, const char *psz_text,
 356                                 bool b_indeterminate, float f_position,
 357                                 const char *psz_cancel);
 358
 359     /**
 360      * Called when a displayed dialog needs to be cancelled
 361      *
 362      * The implementation must call vlc_dialog_id_dismiss() to really release
 363      * the dialog.
 364      *
 365      * @param p_data opaque pointer for the callback
 366      * @param p_id id of the dialog
 367      */
 368     void (*pf_cancel)(void *p_data, vlc_dialog_id *p_id);
 369
 370     /**
 371      * Called when a progress dialog needs to be updated
 372      *
 373      * @param p_data opaque pointer for the callback
 374      * @param p_id id of the dialog
 375      * @param f_position osition of the progress bar (between 0.0 and 1.0)
 376      * @param psz_text new text of the progress dialog
 377      */
 378     void (*pf_update_progress)(void *p_data, vlc_dialog_id *p_id,
 379                                float f_position, const char *psz_text);
 380 } vlc_dialog_cbs;
 381
 382 /**
 383  * Register callbacks to handle VLC dialogs
 384  *
 385  * @param p_cbs a pointer to callbacks, or NULL to unregister callbacks.
 386  * @param p_data opaque pointer for the callback
 387  */
 388 VLC_API void
 389 vlc_dialog_provider_set_callbacks(vlc_object_t *p_obj,
 390                                   const vlc_dialog_cbs *p_cbs, void *p_data);
 391 #define vlc_dialog_provider_set_callbacks(a, b, c) \
 392     vlc_dialog_provider_set_callbacks(VLC_OBJECT(a), b, c)
 393
 394 /**
 395  * Associate an opaque pointer with the dialog id
 396  */
 397 VLC_API void
 398 vlc_dialog_id_set_context(vlc_dialog_id *p_id, void *p_context);
 399
 400 /**
 401  * Return the opaque pointer associated with the dialog id
 402  */
 403 VLC_API void *
 404 vlc_dialog_id_get_context(vlc_dialog_id *p_id);
 405
 406 /**
 407  * Post a login answer
 408  *
 409  * After this call, p_id won't be valid anymore
 410  *
 411  * @see vlc_dialog_cbs.pf_display_login
 412  *
 413  * @param p_id id of the dialog
 414  * @param psz_username valid and non empty string
 415  * @param psz_password valid string (can be empty)
 416  * @param b_store if true, store the credentials
 417  * @return VLC_SUCCESS on success, or a VLC error code on error
 418  */
 419 VLC_API int
 420 vlc_dialog_id_post_login(vlc_dialog_id *p_id, const char *psz_username,
 421                          const char *psz_password, bool b_store);
 422
 423 /**
 424  * Post a question answer
 425  *
 426  * After this call, p_id won't be valid anymore
 427  *
 428  * @see vlc_dialog_cbs.pf_display_question
 429  *
 430  * @param p_id id of the dialog
 431  * @param i_action 1 for action1, 2 for action2
 432  * @return VLC_SUCCESS on success, or a VLC error code on error
 433  */
 434 VLC_API int
 435 vlc_dialog_id_post_action(vlc_dialog_id *p_id, int i_action);
 436
 437 /**
 438  * Dismiss a dialog
 439  *
 440  * After this call, p_id won't be valid anymore
 441  *
 442  * @see vlc_dialog_cbs.pf_cancel
 443  *
 444  * @param p_id id of the dialog
 445  * @return VLC_SUCCESS on success, or a VLC error code on error
 446  */
 447 VLC_API int
 448 vlc_dialog_id_dismiss(vlc_dialog_id *p_id);
 449
 450 /**
 451  * @}
 452  * @defgroup vlc_dialog_ext VLC extension dialog functions
 453  * @{
 454  */
 455
 456 VLC_API int
 457 vlc_ext_dialog_update(vlc_object_t *p_obj, extension_dialog_t *dialog);
 458 #define vlc_ext_dialog_update(a, b) \
 459     vlc_ext_dialog_update(VLC_OBJECT(a), b)
 460
 461 /**
 462  * Dialog extension callback to be implemented
 463  */
 464 typedef void (*vlc_dialog_ext_update_cb)(extension_dialog_t *p_ext_dialog,
 465                                          void *p_data);
 466
 467 /**
 468  * Register a callback for VLC extension dialog
 469  *
 470  * @param pf_update a pointer to the update callback, or NULL to unregister
 471  * callback
 472  * @param p_data opaque pointer for the callback
 473  */
 474 VLC_API void
 475 vlc_dialog_provider_set_ext_callback(vlc_object_t *p_obj,
 476                                      vlc_dialog_ext_update_cb pf_update,
 477                                      void *p_data);
 478 #define vlc_dialog_provider_set_ext_callback(a, b, c) \
 479     vlc_dialog_provider_set_ext_callback(VLC_OBJECT(a), b, c)
 480
 481 /** @} @} */
 482
 483 #endif