vlc_dialog.h

/*****************************************************************************
 * vlc_dialog.h: user interaction dialogs
 *****************************************************************************
 * Copyright (C) 2009 Rémi Denis-Courmont
 * Copyright (C) 2016 VLC authors and VideoLAN
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
 *****************************************************************************/

#ifndef VLC_DIALOG_H_
#define VLC_DIALOG_H_
# include <stdarg.h>

typedef struct vlc_dialog_provider vlc_dialog_provider;
typedef struct vlc_dialog_id vlc_dialog_id;
typedef struct extension_dialog_t extension_dialog_t;

/* Called from src/libvlc.c */
int
libvlc_InternalDialogInit(libvlc_int_t *p_libvlc);

/* Called from src/libvlc.c */
void
libvlc_InternalDialogClean(libvlc_int_t *p_libvlc);

/**
 * @defgroup vlc_dialog VLC dialog
 * @ingroup interface
 * @{
 * @file
 * This file declares VLC dialog functions
 * @defgroup vlc_dialog_api VLC dialog functions
 * In order to interact with the user
 * @{
 */

/**
 * Dialog question type, see vlc_dialog_wait_question()
 */
typedef enum vlc_dialog_question_type
{
    VLC_DIALOG_QUESTION_NORMAL,
    VLC_DIALOG_QUESTION_WARNING,
    VLC_DIALOG_QUESTION_CRITICAL,
} vlc_dialog_question_type;

/**
 * Sends an error message
 *
 * This function returns immediately
 *
 * @param p_obj the VLC object emitting the error
 * @param psz_title title of the error dialog
 * @param psz_fmt format string for the error message
 * @return VLC_SUCCESS on success, or a VLC error code on error
 */
VLC_API int
vlc_dialog_display_error(vlc_object_t *p_obj, const char *psz_title,
                         const char *psz_fmt, ...) VLC_FORMAT(3,4);
#define vlc_dialog_display_error(a, b, c, ...) \
    vlc_dialog_display_error(VLC_OBJECT(a), b, c, ##__VA_ARGS__)

/**
 * Sends an error message
 *
 * Equivalent to vlc_dialog_display_error() expect that it's called with a
 * va_list.
 */
VLC_API int
vlc_dialog_display_error_va(vlc_object_t *p_obj, const char *psz_title,
                            const char *psz_fmt, va_list ap);

/**
 * Requests an user name and a password
 *
 * This function waits until the user dismisses the dialog or responds. It's
 * interruptible via vlc_interrupt. In that case, vlc_dialog_cbs.pf_cancel()
 * will be invoked. If p_store is not NULL, the user will be asked to store the
 * password or not.
 *
 * @param p_obj the VLC object emitting the dialog
 * @param ppsz_username a pointer to the user name provided by the user, it
 * must be freed with free() on success
 * @param ppsz_password a pointer to the password provided by the user, it must
 * be freed with free() on success
 * @param p_store a pointer to the store answer provided by the user (optional)
 * @param psz_default_username default user name proposed
 * @param psz_title title of the login dialog
 * @param psz_fmt format string for the login message
 * @return < 0 on error, 0 if the user cancelled it, and 1 if ppsz_username and
 * ppsz_password are valid.
 */
VLC_API int
vlc_dialog_wait_login(vlc_object_t *p_obj, char **ppsz_username,
                      char **ppsz_password, bool *p_store,
                      const char *psz_default_username,
                      const char *psz_title, const char *psz_fmt, ...)
                      VLC_FORMAT(7,8);
#define vlc_dialog_wait_login(a, b, c, d, e, f, g, ...) \
    vlc_dialog_wait_login(VLC_OBJECT(a), b, c, d, e, f, g, ##__VA_ARGS__)

/**
 * Requests an user name and a password
 *
 * Equivalent to vlc_dialog_wait_login() expect that it's called with a
 * va_list.
 */
VLC_API int
vlc_dialog_wait_login_va(vlc_object_t *p_obj, char **ppsz_username,
                         char **ppsz_password, bool *p_store,
                         const char *psz_default_username,
                         const char *psz_title, const char *psz_fmt, va_list ap);

/**
 * Asks a total (Yes/No/Cancel) question
 *
 * This function waits until the user dismisses the dialog or responds. It's
 * interruptible via vlc_interrupt. In that case, vlc_dialog_cbs.pf_cancel()
 * will be invoked. The psz_cancel is mandatory since this dialog is always
 * cancellable by the user.
 *
 * @param p_obj the VLC object emitting the dialog
 * @param i_type question type (severity of the question)
 * @param psz_cancel text of the cancel button
 * @param psz_action1 first choice/button text (optional)
 * @param psz_action2 second choice/button text (optional)
 * @param psz_title title of the question dialog
 * @param psz_fmt format string for the question message
 * @return < 0 on error, 0 if the user cancelled it, 1 on action1, 2 on action2
 */
VLC_API int
vlc_dialog_wait_question(vlc_object_t *p_obj,
                         vlc_dialog_question_type i_type,
                         const char *psz_cancel, const char *psz_action1,
                         const char *psz_action2, const char *psz_title,
                         const char *psz_fmt, ...) VLC_FORMAT(7,8);
#define vlc_dialog_wait_question(a, b, c, d, e, f, g, ...) \
    vlc_dialog_wait_question(VLC_OBJECT(a), b, c, d, e, f, g, ##__VA_ARGS__)

/**
 * Asks a total (Yes/No/Cancel) question
 *
 * Equivalent to vlc_dialog_wait_question() expect that it's called with a
 * va_list.
 */
VLC_API int
vlc_dialog_wait_question_va(vlc_object_t *p_obj,
                            vlc_dialog_question_type i_type,
                            const char *psz_cancel, const char *psz_action1,
                            const char *psz_action2, const char *psz_title,
                            const char *psz_fmt, va_list ap);

/**
 * Display a progress dialog
 *
 * This function returns immediately
 *
 * @param p_obj the VLC object emitting the dialog
 * @param b_indeterminate true if the progress dialog is indeterminate
 * @param f_position initial position of the progress bar (between 0.0 and 1.0)
 * @param psz_cancel text of the cancel button, if NULL the dialog is not
 * cancellable (optional)
 * @param psz_title title of the progress dialog
 * @param psz_fmt format string for the progress message
 * @return a valid vlc_dialog_id on success, must be released with
 * vlc_dialog_id_release()
 */
VLC_API vlc_dialog_id *
vlc_dialog_display_progress(vlc_object_t *p_obj, bool b_indeterminate,
                            float f_position, const char *psz_cancel,
                            const char *psz_title, const char *psz_fmt, ...)
                            VLC_FORMAT(6,7);
#define vlc_dialog_display_progress(a, b, c, d, e, f, ...) \
    vlc_dialog_display_progress(VLC_OBJECT(a), b, c, d, e, f, ##__VA_ARGS__)

/**
 * Display a progress dialog
 *
 * Equivalent to vlc_dialog_display_progress() expect that it's called with a
 * va_list.
 */
VLC_API vlc_dialog_id *
vlc_dialog_display_progress_va(vlc_object_t *p_obj, bool b_indeterminate,
                               float f_position, const char *psz_cancel,
                               const char *psz_title, const char *psz_fmt,
                               va_list ap);

/**
 * Update the position of the progress dialog
 *
 * @param p_obj the VLC object emitting the dialog
 * @param p_id id of the dialog to update
 * @param f_position position of the progress bar (between 0.0 and 1.0)
 * @return VLC_SUCCESS on success, or a VLC error code on error
 */
VLC_API int
vlc_dialog_update_progress(vlc_object_t *p_obj, vlc_dialog_id *p_id,
                           float f_position);
#define vlc_dialog_update_progress(a, b, c) \
    vlc_dialog_update_progress(VLC_OBJECT(a), b, c)

/**
 * Update the position and the message of the progress dialog
 *
 * @param p_obj the VLC object emitting the dialog
 * @param p_id id of the dialog to update
 * @param f_position position of the progress bar (between 0.0 and 1.0)
 * @param psz_fmt format string for the progress message
 * @return VLC_SUCCESS on success, or a VLC error code on error
 */
VLC_API int
vlc_dialog_update_progress_text(vlc_object_t *p_obj, vlc_dialog_id *p_id,
                                float f_position, const char *psz_fmt, ...)
                                VLC_FORMAT(4, 5);
#define vlc_dialog_update_progress_text(a, b, c, d, ...) \
    vlc_dialog_update_progress_text(VLC_OBJECT(a), b, c, d, ##__VA_ARGS__)

/**
 * Update the position and the message of the progress dialog
 *
 * Equivalent to vlc_dialog_update_progress_text() expect that it's called
 * with a va_list.
 */
VLC_API int
vlc_dialog_update_progress_text_va(vlc_object_t *p_obj, vlc_dialog_id *p_id,
                                   float f_position, const char *psz_fmt,
                                   va_list ap);

/**
 * Release the dialog id returned by vlc_dialog_display_progress()
 *
 * It causes the vlc_dialog_cbs.pf_cancel() callback to be invoked.
 *
 * @param p_obj the VLC object emitting the dialog
 * @param p_id id of the dialog to release
 */
VLC_API void
vlc_dialog_release(vlc_object_t *p_obj, vlc_dialog_id *p_id);
#define vlc_dialog_release(a, b) \
    vlc_dialog_release(VLC_OBJECT(a), b)

/**
 * Return true if the dialog id is cancelled
 *
 * @param p_obj the VLC object emitting the dialog
 * @param p_id id of the dialog
 */
VLC_API bool
vlc_dialog_is_cancelled(vlc_object_t *p_obj, vlc_dialog_id *p_id);
#define vlc_dialog_is_cancelled(a, b) \
    vlc_dialog_is_cancelled(VLC_OBJECT(a), b)

/**
 * @}
 * @defgroup vlc_dialog_impl VLC dialog callbacks
 * Need to be implemented by GUI modules or libvlc
 * @{
 */

/**
 * Dialog callbacks to be implemented
 */
typedef struct vlc_dialog_cbs
{
    /**
     * Called when an error message needs to be displayed
     *
     * @param p_data opaque pointer for the callback
     * @param psz_title title of the dialog
     * @param psz_text text of the dialog
     */
    void (*pf_display_error)(void *p_data, const char *psz_title,
                             const char *psz_text);

    /**
     * Called when a login dialog needs to be displayed
     *
     * You can interact with this dialog by calling vlc_dialog_id_post_login()
     * to post an answer or vlc_dialog_id_dismiss() to cancel this dialog.
     *
     * @note to receive this callback, vlc_dialog_cbs.pf_cancel should not be
     * NULL.
     *
     * @param p_data opaque pointer for the callback
     * @param p_id id used to interact with the dialog
     * @param psz_title title of the dialog
     * @param psz_text text of the dialog
     * @param psz_default_username user name that should be set on the user form
     * @param b_ask_store if true, ask the user if he wants to save the
     * credentials
     */
    void (*pf_display_login)(void *p_data, vlc_dialog_id *p_id,
                             const char *psz_title, const char *psz_text,
                             const char *psz_default_username,
                             bool b_ask_store);

    /**
     * Called when a question dialog needs to be displayed
     *
     * You can interact with this dialog by calling vlc_dialog_id_post_action()
     * to post an answer or vlc_dialog_id_dismiss() to cancel this dialog.
     *
     * @note to receive this callback, vlc_dialog_cbs.pf_cancel should not be
     * NULL.
     *
     * @param p_data opaque pointer for the callback
     * @param p_id id used to interact with the dialog
     * @param psz_title title of the dialog
     * @param psz_text text of the dialog
     * @param i_type question type (or severity) of the dialog
     * @param psz_cancel text of the cancel button
     * @param psz_action1 text of the first button, if NULL, don't display this
     * button
     * @param psz_action2 text of the second button, if NULL, don't display
     * this button
     */
    void (*pf_display_question)(void *p_data, vlc_dialog_id *p_id,
                                const char *psz_title, const char *psz_text,
                                vlc_dialog_question_type i_type,
                                const char *psz_cancel, const char *psz_action1,
                                const char *psz_action2);

    /**
     * Called when a progress dialog needs to be displayed
     *
     * If cancellable (psz_cancel != NULL), you can cancel this dialog by
     * calling vlc_dialog_id_dismiss()
     *
     * @note to receive this callback, vlc_dialog_cbs.pf_cancel and
     * vlc_dialog_cbs.pf_update_progress should not be NULL.
     *
     * @param p_data opaque pointer for the callback
     * @param p_id id used to interact with the dialog
     * @param psz_title title of the dialog
     * @param psz_text text of the dialog
     * @param b_indeterminate true if the progress dialog is indeterminate
     * @param f_position initial position of the progress bar (between 0.0 and
     * 1.0)
     * @param psz_cancel text of the cancel button, if NULL the dialog is not
     * cancellable
     */
    void (*pf_display_progress)(void *p_data, vlc_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 displayed dialog needs to be cancelled
     *
     * The implementation must call vlc_dialog_id_dismiss() to really release
     * the dialog.
     *
     * @param p_data opaque pointer for the callback
     * @param p_id id of the dialog
     */
    void (*pf_cancel)(void *p_data, vlc_dialog_id *p_id);

    /**
     * Called when a progress dialog needs to be updated
     *
     * @param p_data opaque pointer for the callback
     * @param p_id id of the dialog
     * @param f_position osition of the progress bar (between 0.0 and 1.0)
     * @param psz_text new text of the progress dialog
     */
    void (*pf_update_progress)(void *p_data, vlc_dialog_id *p_id,
                               float f_position, const char *psz_text);
} vlc_dialog_cbs;

/**
 * Register callbacks to handle VLC dialogs
 *
 * @param p_cbs a pointer to callbacks, or NULL to unregister callbacks.
 * @param p_data opaque pointer for the callback
 */
VLC_API void
vlc_dialog_provider_set_callbacks(vlc_object_t *p_obj,
                                  const vlc_dialog_cbs *p_cbs, void *p_data);
#define vlc_dialog_provider_set_callbacks(a, b, c) \
    vlc_dialog_provider_set_callbacks(VLC_OBJECT(a), b, c)

/**
 * Associate an opaque pointer with the dialog id
 */
VLC_API void
vlc_dialog_id_set_context(vlc_dialog_id *p_id, void *p_context);

/**
 * Return the opaque pointer associated with the dialog id
 */
VLC_API void *
vlc_dialog_id_get_context(vlc_dialog_id *p_id);

/**
 * Post a login answer
 *
 * After this call, p_id won't be valid anymore
 *
 * @see vlc_dialog_cbs.pf_display_login
 *
 * @param p_id id of the dialog
 * @param psz_username valid and non empty string
 * @param psz_password valid string (can be empty)
 * @param b_store if true, store the credentials
 * @return VLC_SUCCESS on success, or a VLC error code on error
 */
VLC_API int
vlc_dialog_id_post_login(vlc_dialog_id *p_id, const char *psz_username,
                         const char *psz_password, bool b_store);

/**
 * Post a question answer
 *
 * After this call, p_id won't be valid anymore
 *
 * @see vlc_dialog_cbs.pf_display_question
 *
 * @param p_id id of the dialog
 * @param i_action 1 for action1, 2 for action2
 * @return VLC_SUCCESS on success, or a VLC error code on error
 */
VLC_API int
vlc_dialog_id_post_action(vlc_dialog_id *p_id, int i_action);

/**
 * Dismiss a dialog
 *
 * After this call, p_id won't be valid anymore
 *
 * @see vlc_dialog_cbs.pf_cancel
 *
 * @param p_id id of the dialog
 * @return VLC_SUCCESS on success, or a VLC error code on error
 */
VLC_API int
vlc_dialog_id_dismiss(vlc_dialog_id *p_id);

/**
 * @}
 * @defgroup vlc_dialog_ext VLC extension dialog functions
 * @{
 */

VLC_API int
vlc_ext_dialog_update(vlc_object_t *p_obj, extension_dialog_t *dialog);
#define vlc_ext_dialog_update(a, b) \
    vlc_ext_dialog_update(VLC_OBJECT(a), b)

/**
 * Dialog extension callback to be implemented
 */
typedef void (*vlc_dialog_ext_update_cb)(extension_dialog_t *p_ext_dialog,
                                         void *p_data);

/**
 * Register a callback for VLC extension dialog
 *
 * @param pf_update a pointer to the update callback, or NULL to unregister
 * callback
 * @param p_data opaque pointer for the callback
 */
VLC_API void
vlc_dialog_provider_set_ext_callback(vlc_object_t *p_obj,
                                     vlc_dialog_ext_update_cb pf_update,
                                     void *p_data);
#define vlc_dialog_provider_set_ext_callback(a, b, c) \
    vlc_dialog_provider_set_ext_callback(VLC_OBJECT(a), b, c)

/** @} @} */

#endif