NetSurf
searchweb.h
Go to the documentation of this file.
1/*
2 * Copyright 2014 Vincent Sanders <vince@netsurf-browser.org>
3 *
4 * This file is part of NetSurf, http://www.netsurf-browser.org/
5 *
6 * NetSurf is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; version 2 of the License.
9 *
10 * NetSurf is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18
19/**
20 * \file desktop/searchweb.h
21 * \brief core web search facilities interface.
22 */
23
24#ifndef _NETSURF_DESKTOP_SEARCH_WEB_H_
25#define _NETSURF_DESKTOP_SEARCH_WEB_H_
26
27struct bitmap;
28struct nsurl;
29
30/**
31 * Graphical user interface browser web search function table.
32 *
33 */
35 /**
36 * called when the search provider details are updated.
37 *
38 * \param provider_name The name of the provider.
39 * \param ico_bitmap The bitmap of the search icon may be NULL
40 * if no icon is yet available.
41 */
42 nserror (*provider_update)(const char *provider_name, struct bitmap *ico_bitmap);
43};
44
45/**
46 * Flags which alter the behaviour of the omin search.
47 */
49 /** no changes to default operation */
51
52 /** The search does not attempt to interpret the url as a url
53 * before using it as a search term.
54 */
56};
57
58/**
59 * Generate a nsurl from a search term.
60 *
61 * This interface obtains a url appropriate for the given search
62 * term. The flags allow control over the operation. By default the
63 * operations are:
64 * - interpret the \a term as a url
65 * - if missing a scheme as a https: url
66 * - combined with the search providers url into a url for that provider.
67 *
68 * \param term The search term.
69 * \param flags Flags to control operation.
70 * \param url_out The ourput url on success.
71 * \return NSERROR_OK on success or appropriate error code.
72 */
73nserror search_web_omni(const char *term, enum search_web_omni_flags flags, struct nsurl **url_out);
74
75
76/**
77 * obtain the current providers bitmap
78 *
79 * obtain the icon representing the current web search provider
80 *
81 * \param bitmap_out recives the resulting bitmap which may be NULL
82 * \return NSERROR_OK on success or NSERROR_INIT_FAILED if not initialised
83 */
85
86/**
87 * Change the currently selected web search provider.
88 *
89 * \param selection Name of the search provider to select or NULL to
90 * reselect the current provider
91 * \return NSERROR_OK on success or appropriate error code.
92 */
94
95
96/**
97 * Iterate the search providers, returning their names.
98 *
99 * \param from Index to start iteration from. Use -1 to begin iteration.
100 * Use the value returned from search_web_iterate_providers to
101 * continue an iteration.
102 * \param name Pointer to fill in with the search provider name requested.
103 * \return -1 if there are no more, otherwise the iterator for the next item.
104 *
105 * \verbatim
106 * ssize_t iter = -1;
107 * const char *name;
108 * ...
109 * iter = search_web_iterate_providers(iter, &name);
110 * while(iter !=-1) {
111 * do_something_with(name);
112 * iter = search_web_iterate_providers(iter, &name);
113 * }
114 * \endverbatim
115 */
116ssize_t search_web_iterate_providers(ssize_t iter, const char **name);
117
118
119/**
120 * Initialise the web search operations.
121 *
122 * \param provider_fname Path to web search providers file.
123 * \return NSERROR_OK on successful initialisation or appropriate error code.
124 */
125nserror search_web_init(const char *provider_fname);
126
127/**
128 * Finalise the web search operations freeing all resources.
129 *
130 * \return NSERROR_OK on success or appropriate error code.
131 */
133
134#endif
nserror
Enumeration of error codes.
Definition: errors.h:29
struct nsurl nsurl
NetSurf URL object.
Definition: nsurl.h:31
nserror search_web_omni(const char *term, enum search_web_omni_flags flags, struct nsurl **url_out)
Generate a nsurl from a search term.
Definition: searchweb.c:318
nserror search_web_init(const char *provider_fname)
Initialise the web search operations.
Definition: searchweb.c:525
nserror search_web_select_provider(const char *selection)
Change the currently selected web search provider.
Definition: searchweb.c:397
search_web_omni_flags
Flags which alter the behaviour of the omin search.
Definition: searchweb.h:48
@ SEARCH_WEB_OMNI_NONE
no changes to default operation
Definition: searchweb.h:50
@ SEARCH_WEB_OMNI_SEARCHONLY
The search does not attempt to interpret the url as a url before using it as a search term.
Definition: searchweb.h:55
nserror search_web_finalise(void)
Finalise the web search operations freeing all resources.
Definition: searchweb.c:582
ssize_t search_web_iterate_providers(ssize_t iter, const char **name)
Iterate the search providers, returning their names.
Definition: searchweb.c:506
nserror search_web_get_provider_bitmap(struct bitmap **bitmap_out)
obtain the current providers bitmap
Definition: searchweb.c:370
RISC OS wimp toolkit bitmap.
Definition: bitmap.c:68
Graphical user interface browser web search function table.
Definition: searchweb.h:34
nserror(* provider_update)(const char *provider_name, struct bitmap *ico_bitmap)
called when the search provider details are updated.
Definition: searchweb.h:42