1 | /* |
2 | * Copyright (c) 2015-2017, Intel Corporation |
3 | * |
4 | * Redistribution and use in source and binary forms, with or without |
5 | * modification, are permitted provided that the following conditions are met: |
6 | * |
7 | * * Redistributions of source code must retain the above copyright notice, |
8 | * this list of conditions and the following disclaimer. |
9 | * * Redistributions in binary form must reproduce the above copyright |
10 | * notice, this list of conditions and the following disclaimer in the |
11 | * documentation and/or other materials provided with the distribution. |
12 | * * Neither the name of Intel Corporation nor the names of its contributors |
13 | * may be used to endorse or promote products derived from this software |
14 | * without specific prior written permission. |
15 | * |
16 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
17 | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
18 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
19 | * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE |
20 | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
21 | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
22 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
23 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
24 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
25 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
26 | * POSSIBILITY OF SUCH DAMAGE. |
27 | */ |
28 | |
29 | /** \file |
30 | * \brief Hamster Wheel Literal Matcher: runtime API. |
31 | */ |
32 | |
33 | #ifndef HWLM_H |
34 | #define HWLM_H |
35 | |
36 | #include "ue2common.h" |
37 | |
38 | #ifdef __cplusplus |
39 | extern "C" |
40 | { |
41 | #endif |
42 | |
43 | /** \brief Error return type for exec functions. */ |
44 | typedef int hwlm_error_t; |
45 | |
46 | /** \brief Type representing a set of groups as a bitmap. */ |
47 | typedef u64a hwlm_group_t; |
48 | |
49 | /** \brief HWLM callback return type. */ |
50 | typedef hwlm_group_t hwlmcb_rv_t; |
51 | |
52 | /** \brief Value representing all possible literal groups. */ |
53 | #define HWLM_ALL_GROUPS ((hwlm_group_t)~0ULL) |
54 | |
55 | /** \brief Callback return value indicating that we should continue matching. */ |
56 | #define HWLM_CONTINUE_MATCHING HWLM_ALL_GROUPS |
57 | |
58 | /** \brief Callback return value indicating that we should halt matching. */ |
59 | #define HWLM_TERMINATE_MATCHING 0 |
60 | |
61 | /** \brief Matching finished without being terminated by the user. */ |
62 | #define HWLM_SUCCESS 0 |
63 | |
64 | /** \brief The user terminated matching by returning HWLM_TERMINATE_MATCHING |
65 | * from the match callback. */ |
66 | #define HWLM_TERMINATED 1 |
67 | |
68 | /** \brief An error occurred during matching. |
69 | * |
70 | * This should only be used if an unsupported engine was called (like one |
71 | * designed for a different architecture). */ |
72 | #define HWLM_ERROR_UNKNOWN 2 |
73 | |
74 | /** \brief Max length of the literal passed to HWLM. */ |
75 | #define HWLM_LITERAL_MAX_LEN 8 |
76 | |
77 | struct hs_scratch; |
78 | struct HWLM; |
79 | |
80 | /** \brief The type for an HWLM callback. |
81 | * |
82 | * This callback receives an end-of-match offset, the ID of the match and |
83 | * the context pointer that was passed into \ref hwlmExec or |
84 | * \ref hwlmExecStreaming. |
85 | * |
86 | * A callback return of \ref HWLM_TERMINATE_MATCHING will stop matching. |
87 | * |
88 | * A callback return of \ref HWLM_CONTINUE_MATCHING continues matching. |
89 | * |
90 | * An arbitrary group mask may be given as the return value. This will be taken |
91 | * as a hint by the underlying engine that only literals with groups |
92 | * overlapping the provided mask need to be reported. |
93 | * |
94 | * The underlying engine may choose not to report a match if there is no group |
95 | * belonging to the literal which was active at the when the end match location |
96 | * was first reached. |
97 | */ |
98 | typedef hwlmcb_rv_t (*HWLMCallback)(size_t end, u32 id, |
99 | struct hs_scratch *scratch); |
100 | |
101 | /** \brief Match strings in table. |
102 | * |
103 | * If a match occurs, the callback function given will be called with the index |
104 | * of the last character in the string and the \p context (passed through |
105 | * without interpretation). |
106 | * |
107 | * Returns \ref HWLM_TERMINATED if scanning is cancelled due to the callback |
108 | * returning \ref HWLM_TERMINATE_MATCHING. |
109 | * |
110 | * \p start is the first offset at which a match may start. Note: match |
111 | * starts may include masks overhanging the main literal. |
112 | * |
113 | * The underlying engine may choose not to report any match which starts before |
114 | * the first possible match of a literal which is in the initial group mask. |
115 | */ |
116 | hwlm_error_t hwlmExec(const struct HWLM *tab, const u8 *buf, size_t len, |
117 | size_t start, HWLMCallback callback, |
118 | struct hs_scratch *scratch, hwlm_group_t groups); |
119 | |
120 | /** \brief As for \ref hwlmExec, but a streaming case across two buffers. |
121 | * |
122 | * \p len is the length of the main buffer to be scanned. |
123 | * |
124 | * \p start is an advisory hint representing the first offset at which a match |
125 | * may start. Some underlying literal matches may not respect it. Note: match |
126 | * starts may include masks overhanging the main literal. |
127 | * |
128 | * \p scratch is used to access the history buffer, history length and |
129 | * the main buffer. |
130 | * |
131 | * Two buffers/lengths are provided. Matches that occur entirely within |
132 | * the history buffer will not be reported by this function. The offsets |
133 | * reported for the main buffer are relative to the start of that buffer (a |
134 | * match at byte 10 of the main buffer is reported as 10). Matches that start |
135 | * in the history buffer will have starts reported with 'negative' values. |
136 | */ |
137 | hwlm_error_t hwlmExecStreaming(const struct HWLM *tab, size_t len, size_t start, |
138 | HWLMCallback callback, |
139 | struct hs_scratch *scratch, hwlm_group_t groups); |
140 | |
141 | #ifdef __cplusplus |
142 | } /* extern "C" */ |
143 | #endif |
144 | |
145 | #endif |
146 | |