lws-fts.h (7089B)
1/* 2 * libwebsockets - small server side websockets and web server implementation 3 * 4 * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com> 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a copy 7 * of this software and associated documentation files (the "Software"), to 8 * deal in the Software without restriction, including without limitation the 9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 10 * sell copies of the Software, and to permit persons to whom the Software is 11 * furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be included in 14 * all copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 22 * IN THE SOFTWARE. 23 */ 24 25/** \defgroup search Search 26 * 27 * ##Full-text search 28 * 29 * Lws provides superfast indexing and fulltext searching from index files on 30 * storage. 31 */ 32///@{ 33 34struct lws_fts; 35struct lws_fts_file; 36 37/* 38 * Queries produce their results in an lwsac, using these public API types. 39 * The first thing in the lwsac is always a struct lws_fts_result (see below) 40 * containing heads for linked-lists of the other result types. 41 */ 42 43/* one filepath's results */ 44 45struct lws_fts_result_filepath { 46 struct lws_fts_result_filepath *next; 47 int matches; /* logical number of matches */ 48 int matches_length; /* bytes in length table (may be zero) */ 49 int lines_in_file; 50 int filepath_length; 51 52 /* - uint32_t line table follows (first for alignment) */ 53 /* - filepath (of filepath_length) follows */ 54}; 55 56/* autocomplete result */ 57 58struct lws_fts_result_autocomplete { 59 struct lws_fts_result_autocomplete *next; 60 int instances; 61 int agg_instances; 62 int ac_length; 63 char elided; /* children skipped in interest of antecedent children */ 64 char has_children; 65 66 /* - autocomplete suggestion (of length ac_length) follows */ 67}; 68 69/* 70 * The results lwsac always starts with this. If no results and / or no 71 * autocomplete the members may be NULL. This implies the symbol nor any 72 * suffix on it exists in the trie file. 73 */ 74struct lws_fts_result { 75 struct lws_fts_result_filepath *filepath_head; 76 struct lws_fts_result_autocomplete *autocomplete_head; 77 int duration_ms; 78 int effective_flags; /* the search flags that were used */ 79}; 80 81/* 82 * index creation functions 83 */ 84 85/** 86 * lws_fts_create() - Create a new index file 87 * 88 * \param fd: The fd opened for write 89 * 90 * Inits a new index file, returning a struct lws_fts to represent it 91 */ 92LWS_VISIBLE LWS_EXTERN struct lws_fts * 93lws_fts_create(int fd); 94 95/** 96 * lws_fts_destroy() - Finalize a new index file / destroy the trie lwsac 97 * 98 * \param trie: The previously opened index being finalized 99 * 100 * Finalizes an index file that was being created, and frees the memory involved 101 * *trie is set to NULL afterwards. 102 */ 103LWS_VISIBLE LWS_EXTERN void 104lws_fts_destroy(struct lws_fts **trie); 105 106/** 107 * lws_fts_file_index() - Create a new entry in the trie file for an input path 108 * 109 * \param t: The previously opened index being written 110 * \param filepath: The filepath (which may be virtual) associated with this file 111 * \param filepath_len: The number of chars in the filepath 112 * \param priority: not used yet 113 * 114 * Returns an ordinal that represents this new filepath in the index file. 115 */ 116LWS_VISIBLE LWS_EXTERN int 117lws_fts_file_index(struct lws_fts *t, const char *filepath, int filepath_len, 118 int priority); 119 120/** 121 * lws_fts_fill() - Process all or a bufferload of input file 122 * 123 * \param t: The previously opened index being written 124 * \param file_index: The ordinal representing this input filepath 125 * \param buf: A bufferload of data from the input file 126 * \param len: The number of bytes in buf 127 * 128 * Indexes a buffer of data from the input file. 129 */ 130LWS_VISIBLE LWS_EXTERN int 131lws_fts_fill(struct lws_fts *t, uint32_t file_index, const char *buf, 132 size_t len); 133 134/** 135 * lws_fts_serialize() - Store the in-memory trie into the index file 136 * 137 * \param t: The previously opened index being written 138 * 139 * The trie is held in memory where it can be added to... after all the input 140 * filepaths and data have been processed, this is called to serialize / 141 * write the trie data into the index file. 142 */ 143LWS_VISIBLE LWS_EXTERN int 144lws_fts_serialize(struct lws_fts *t); 145 146/* 147 * index search functions 148 */ 149 150/** 151 * lws_fts_open() - Open an existing index file to search it 152 * 153 * \param filepath: The filepath to the index file to open 154 * 155 * Opening the index file returns an opaque struct lws_fts_file * that is 156 * used to perform other operations on it, or NULL if it can't be opened. 157 */ 158LWS_VISIBLE LWS_EXTERN struct lws_fts_file * 159lws_fts_open(const char *filepath); 160 161#define LWSFTS_F_QUERY_AUTOCOMPLETE (1 << 0) 162#define LWSFTS_F_QUERY_FILES (1 << 1) 163#define LWSFTS_F_QUERY_FILE_LINES (1 << 2) 164#define LWSFTS_F_QUERY_QUOTE_LINE (1 << 3) 165 166struct lws_fts_search_params { 167 /* the actual search term */ 168 const char *needle; 169 /* if non-NULL, FILE results for this filepath only */ 170 const char *only_filepath; 171 /* will be set to the results lwsac */ 172 struct lwsac *results_head; 173 /* combination of LWSFTS_F_QUERY_* flags */ 174 int flags; 175 /* maximum number of autocomplete suggestions to return */ 176 int max_autocomplete; 177 /* maximum number of filepaths to return */ 178 int max_files; 179 /* maximum number of line number results to return per filepath */ 180 int max_lines; 181}; 182 183/** 184 * lws_fts_search() - Perform a search operation on an index 185 * 186 * \param jtf: The index file struct returned by lws_fts_open 187 * \param ftsp: The struct lws_fts_search_params filled in by the caller 188 * 189 * The caller should memset the ftsp struct to 0 to ensure members that may be 190 * introduced in later versions contain known values, then set the related 191 * members to describe the kind of search action required. 192 * 193 * ftsp->results_head is the results lwsac, or NULL. It should be freed with 194 * lwsac_free() when the results are finished with. 195 * 196 * Returns a pointer into the results lwsac that is a struct lws_fts_result 197 * containing the head pointers into linked-lists of results for autocomplete 198 * and filepath data, along with some sundry information. This does not need 199 * to be freed since freeing the lwsac will also remove this and everything it 200 * points to. 201 */ 202LWS_VISIBLE LWS_EXTERN struct lws_fts_result * 203lws_fts_search(struct lws_fts_file *jtf, struct lws_fts_search_params *ftsp); 204 205/** 206 * lws_fts_close() - Close a previously-opened index file 207 * 208 * \param jtf: The pointer returned from the open 209 * 210 * Closes the file handle on the index and frees any allocations 211 */ 212LWS_VISIBLE LWS_EXTERN void 213lws_fts_close(struct lws_fts_file *jtf); 214 215///@}