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 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  */
 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 */