summaryrefslogtreecommitdiff
path: root/include/netsurf/misc.h
blob: ac58cf302199229fffe461231d9fac1df2d01804 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
/*
 * 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 ssl_cert_info;
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);

	/**
	 * Warn the user of an event.
	 *
	 * \param[in] message A warning looked up in the message
	 *                      translation table
	 * \param[in] detail Additional text to be displayed or NULL.
	 * \return NSERROR_OK on success or error code if there was a
	 *           faliure displaying the message to the user.
	 */
	nserror (*warning)(const char *message, const char *detail);


	/* 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 ssl_cert_info *certs,
			unsigned long num,
			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