Debian Codegraph @

include/libpsl.h.in

raw
1 /*
2 * Copyright(c) 2014-2024 Tim Ruehsen
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a
5 * copy of this software and associated documentation files (the "Software"),
6 * to deal in the Software without restriction, including without limitation
7 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
8 * and/or sell copies of the Software, and to permit persons to whom the
9 * Software is furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included in
12 * all copies or substantial portions of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
20 * DEALINGS IN THE SOFTWARE.
21 *
22 * This file is part of libpsl.
23 *
24 * Header file for libpsl library routines
25 *
26 * Changelog
27 * 20.03.2014 Tim Ruehsen created
28 *
29 */
30
31 #ifndef LIBPSL_LIBPSL_H
32 #define LIBPSL_LIBPSL_H
33
34 #include <stdio.h>
35 #include <time.h>
36
37 #define PSL_VERSION "@LIBPSL_VERSION@"
38 #define PSL_VERSION_MAJOR @LIBPSL_VERSION_MAJOR@
39 #define PSL_VERSION_MINOR @LIBPSL_VERSION_MINOR@
40 #define PSL_VERSION_PATCH @LIBPSL_VERSION_PATCH@
41 #define PSL_VERSION_NUMBER @LIBPSL_VERSION_NUMBER@
42
43 /* support clang's __has_declspec_attribute attribute */
44 #ifndef __has_declspec_attribute
45 # define __has_declspec_attribute(x) 0
46 #endif
47
48 #ifndef PSL_API
49 #if defined BUILDING_PSL && HAVE_VISIBILITY
50 # define PSL_API __attribute__ ((__visibility__("default")))
51 #elif defined BUILDING_PSL && (defined _MSC_VER || __has_declspec_attribute(dllexport)) && !defined PSL_STATIC
52 # define PSL_API __declspec(dllexport)
53 #elif (defined _MSC_VER || __has_declspec_attribute(dllimport)) && !defined PSL_STATIC
54 # define PSL_API __declspec(dllimport)
55 #else
56 # define PSL_API
57 #endif
58 #endif
59
60 #ifdef __cplusplus
61 extern "C" {
62 #endif
63
64 /* types for psl_is_public_suffix2() */
65 #define PSL_TYPE_ICANN (1<<0)
66 #define PSL_TYPE_PRIVATE (1<<1)
67 #define PSL_TYPE_NO_STAR_RULE (1<<2)
68 #define PSL_TYPE_ANY (PSL_TYPE_ICANN | PSL_TYPE_PRIVATE)
69
70 /**
71 * psl_error_t:
72 * @PSL_SUCCESS: Successful return.
73 * @PSL_ERR_INVALID_ARG: Invalid argument.
74 * @PSL_ERR_CONVERTER: Failed to open libicu utf-16 converter.
75 * @PSL_ERR_TO_UTF16: Failed to convert to utf-16.
76 * @PSL_ERR_TO_LOWER: Failed to convert utf-16 to lowercase.
77 * @PSL_ERR_TO_UTF8: Failed to convert utf-16 to utf-8.
78 * @PSL_ERR_NO_MEM: Failed to allocate memory.
79 *
80 * Return codes for PSL functions.
81 * Negative return codes mean failure.
82 * Positive values are reserved for non-error return codes.
83 */
84 typedef enum {
85 PSL_SUCCESS = 0,
86 PSL_ERR_INVALID_ARG = -1,
87 PSL_ERR_CONVERTER = -2, /* failed to open libicu utf-16 converter */
88 PSL_ERR_TO_UTF16 = -3, /* failed to convert to utf-16 */
89 PSL_ERR_TO_LOWER = -4, /* failed to convert utf-16 to lowercase */
90 PSL_ERR_TO_UTF8 = -5, /* failed to convert utf-16 to utf-8 */
91 PSL_ERR_NO_MEM = -6 /* failed to allocate memory */
92 } psl_error_t;
93
94 typedef struct psl_ctx_st psl_ctx_t;
95
96 /* frees PSL context */
97 PSL_API
98 void
99 psl_free(psl_ctx_t *psl);
100
101 /* frees memory allocated by libpsl routines */
102 PSL_API
103 void
104 psl_free_string(char *str);
105
106 /* loads PSL data from file */
107 PSL_API
108 psl_ctx_t *
109 psl_load_file(const char *fname);
110
111 /* loads PSL data from FILE pointer */
112 PSL_API
113 psl_ctx_t *
114 psl_load_fp(FILE *fp);
115
116 /* retrieves builtin PSL data */
117 PSL_API
118 const psl_ctx_t *
119 psl_builtin(void);
120
121 /* retrieves most recent PSL data */
122 PSL_API
123 psl_ctx_t *
124 psl_latest(const char *fname);
125
126 /* checks whether domain is a public suffix or not */
127 PSL_API
128 int
129 psl_is_public_suffix(const psl_ctx_t *psl, const char *domain);
130
131 /* checks whether domain is a public suffix regarding the type or not */
132 PSL_API
133 int
134 psl_is_public_suffix2(const psl_ctx_t *psl, const char *domain, int type);
135
136 /* checks whether cookie_domain is acceptable for domain or not */
137 PSL_API
138 int
139 psl_is_cookie_domain_acceptable(const psl_ctx_t *psl, const char *hostname, const char *cookie_domain);
140
141 /* returns the longest not registrable domain within 'domain' or NULL if none found */
142 PSL_API
143 const char *
144 psl_unregistrable_domain(const psl_ctx_t *psl, const char *domain);
145
146 /* returns the shortest possible registrable domain part or NULL if domain is not registrable at all */
147 PSL_API
148 const char *
149 psl_registrable_domain(const psl_ctx_t *psl, const char *domain);
150
151 /* convert a string into lowercase UTF-8 */
152 PSL_API
153 psl_error_t
154 psl_str_to_utf8lower(const char *str, const char *encoding, const char *locale, char **lower);
155
156 /* does not include exceptions */
157 PSL_API
158 int
159 psl_suffix_count(const psl_ctx_t *psl);
160
161 /* just counts exceptions */
162 PSL_API
163 int
164 psl_suffix_exception_count(const psl_ctx_t *psl);
165
166 /* just counts wildcards */
167 PSL_API
168 int
169 psl_suffix_wildcard_count(const psl_ctx_t *psl);
170
171 /* returns mtime of PSL source file */
172 PSL_API
173 time_t
174 psl_builtin_file_time(void);
175
176 /* returns SHA1 checksum (hex-encoded, lowercase) of PSL source file */
177 PSL_API
178 const char *
179 psl_builtin_sha1sum(void);
180
181 /* returns file name of PSL source file */
182 PSL_API
183 const char *
184 psl_builtin_filename(void);
185
186 /* returns name of distribution PSL data file */
187 PSL_API
188 const char *
189 psl_dist_filename(void);
190
191 /* returns library version string */
192 PSL_API
193 const char *
194 psl_get_version(void);
195
196 /* checks library version number */
197 PSL_API
198 int
199 psl_check_version_number(int version);
200
201 /* returns whether the built-in data is outdated or not */
202 PSL_API
203 int
204 psl_builtin_outdated(void);
205
206 #ifdef __cplusplus
207 }
208 #endif
209
210 #endif /* LIBPSL_LIBPSL_H */