/*
 * Copyright 2014 Vincent Sanders <vince@netsurf-browser.org>
 *
 * This file is part of NetSurf, http://www.netsurf-browser.org/
 *
 * NetSurf is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; version 2 of the License.
 *
 * NetSurf 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 General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

/**
 * \file
 *
 * Interface to platform-specific miscellaneous browser operation table.
 */

#ifndef NETSURF_MISC_H_
#define NETSURF_MISC_H_

struct form_control;
struct gui_window;
struct cert_chain;
struct nsurl;

/**
 * Graphical user interface browser misc function table.
 *
 * function table implementing GUI interface to miscelaneous browser
 * functionality
 */
struct gui_misc_table {
	/* Mandantory entries */

	/**
	 * Schedule a callback.
	 *
	 * \param t interval before the callback should be made in ms or
	 *          negative value to remove any existing callback.
	 * \param callback callback function
	 * \param p user parameter passed to callback function
	 * \return NSERROR_OK on sucess or appropriate error on faliure
	 *
	 * The callback function will be called as soon as possible
	 * after the timeout has elapsed.
	 *
	 * Additional calls with the same callback and user parameter will
	 * reset the callback time to the newly specified value.
	 *
	 */
	nserror (*schedule)(int t, void (*callback)(void *p), void *p);


	/* Optional entries */

	/**
	 * called to allow the gui to cleanup.
	 */
	void (*quit)(void);

	/**
	 * core has no fetcher for url
	 */
	nserror (*launch_url)(struct nsurl *url);

	/**
	 * Prompt the user to verify a certificate with issuse.
	 *
	 * \param url The URL being verified.
	 * \param certs The certificate to be verified
	 * \param num The number of certificates to be verified.
	 * \param cb Callback upon user decision.
	 * \param cbpw Context pointer passed to cb
	 * \return NSERROR_OK on sucess else error and cb never called
	 */
	nserror (*cert_verify)(struct nsurl *url,
			const struct cert_chain *chain,
			nserror (*cb)(bool proceed, void *pw),
			void *cbpw);

	/**
	 * Retrieve username/password for a given url+realm if there is one
	 * stored in a frontend-specific way (e.g. gnome-keyring)
	 *
	 * To respond, call the callback with the url, realm, username,
	 * and password.  Pass "" if the empty string
	 * is required.
	 *
	 * To keep hold of the url, remember to nsurl_ref() it, and to keep
	 * the realm, you will need to strdup() it.
	 *
	 * If the front end returns NSERROR_OK for this function, they may,
	 * at some future time, call the `cb` with `cbpw` callback exactly once.
	 *
	 * If the front end returns other than NSERROR_OK, they should not
	 * call the `cb` callback.
	 *
	 * The callback should not be called immediately upon receipt of this
	 * call as the browser window may not be reentered.
	 *
	 * **NOTE** The lifetime of the cbpw is not well defined.  In general
	 * do not use the cb if *any* browser window has navigated or been
	 * destroyed.
	 *
	 * \param url       The URL being verified.
	 * \param realm     The authorization realm.
	 * \param username  Any current username (or empty string).
	 * \param password  Any current password (or empty string).
	 * \param cb        Callback upon user decision.
	 * \param cbpw      Context pointer passed to cb
	 * \return NSERROR_OK on sucess else error and cb never called
	 */
	nserror (*login)(struct nsurl *url, const char *realm,
			 const char *username, const char *password,
			 nserror (*cb)(struct nsurl *url,
				       const char *realm,
				       const char *username,
				       const char *password,
				       void *pw),
			 void *cbpw);

	/**
	 * Prompt the user for a password for a PDF.
	 */
	void (*pdf_password)(char **owner_pass, char **user_pass, char *path);

};

#endif