meta_oxide 0.1.1

Universal metadata extraction library supporting 13 formats (HTML Meta, Open Graph, Twitter Cards, JSON-LD, Microdata, Microformats, RDFa, Dublin Core, Web App Manifest, oEmbed, rel-links, Images, SEO) with 7 language bindings
Documentation 
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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314

/**
 * MetaOxide C API
 *
 * A fast, comprehensive metadata extraction library for HTML content.
 * Extracts 13 different metadata formats including:
 * - Standard HTML meta tags
 * - Open Graph (Facebook, LinkedIn)
 * - Twitter Cards
 * - JSON-LD (Schema.org)
 * - Microdata
 * - Microformats (h-card, h-entry, h-event, etc.)
 * - RDFa
 * - Dublin Core
 * - Web App Manifest
 * - oEmbed
 * - rel-* link relationships
 *
 * ## Memory Management
 *
 * All functions that return pointers allocate memory that must be freed by the caller.
 * Use the appropriate `*_free()` functions to deallocate memory:
 * - `meta_oxide_result_free()` for MetaOxideResult structs
 * - `meta_oxide_string_free()` for individual strings
 * - `meta_oxide_manifest_discovery_free()` for ManifestDiscovery structs
 *
 * ## Error Handling
 *
 * Functions return NULL on error and set the thread-local error state.
 * Check errors using:
 * - `meta_oxide_last_error()` - returns error code
 * - `meta_oxide_error_message()` - returns error description
 *
 * ## Thread Safety
 *
 * All functions are thread-safe. Error state is thread-local.
 *
 * ## Example Usage
 *
 * ```c
 * #include "meta_oxide.h"
 * #include <stdio.h>
 * #include <stdlib.h>
 *
 * int main() {
 *     const char* html = "<html><head><title>Test</title></head></html>";
 *
 *     MetaOxideResult* result = meta_oxide_extract_all(html, NULL);
 *     if (result == NULL) {
 *         fprintf(stderr, "Error: %s\n", meta_oxide_error_message());
 *         return 1;
 *     }
 *
 *     if (result->meta != NULL) {
 *         printf("Meta tags: %s\n", result->meta);
 *     }
 *
 *     meta_oxide_result_free(result);
 *     return 0;
 * }
 * ```
 *
 * @version 0.1.0
 * @license MIT OR Apache-2.0
 */

#ifndef META_OXIDE_H
#define META_OXIDE_H

#pragma once

#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>

/**
 * Result structure containing all extracted metadata
 *
 * Each field is a JSON string or NULL if no data was found.
 * The caller must free this struct using `meta_oxide_result_free()`.
 */
typedef struct MetaOxideResult {
  /**
   * Standard HTML meta tags (JSON object)
   */
  char *meta;
  /**
   * Open Graph metadata (JSON object)
   */
  char *open_graph;
  /**
   * Twitter Card metadata (JSON object)
   */
  char *twitter;
  /**
   * JSON-LD structured data (JSON array)
   */
  char *json_ld;
  /**
   * Microdata items (JSON array)
   */
  char *microdata;
  /**
   * Microformats data (JSON object with h-card, h-entry, etc.)
   */
  char *microformats;
  /**
   * RDFa structured data (JSON array)
   */
  char *rdfa;
  /**
   * Dublin Core metadata (JSON object)
   */
  char *dublin_core;
  /**
   * Web App Manifest discovery (JSON object)
   */
  char *manifest;
  /**
   * oEmbed endpoint discovery (JSON object)
   */
  char *oembed;
  /**
   * rel-* link relationships (JSON object)
   */
  char *rel_links;
} MetaOxideResult;

/**
 * Manifest discovery result with URL and parsed content
 */
typedef struct ManifestDiscovery {
  /**
   * Manifest URL (may be NULL)
   */
  char *href;
  /**
   * Full manifest JSON (may be NULL)
   */
  char *manifest;
} ManifestDiscovery;

/**
 * Extract ALL metadata from HTML
 *
 * Returns a MetaOxideResult containing all extracted data as JSON strings.
 * Returns NULL on error.
 *
 * # Arguments
 * * `html` - HTML content (must not be NULL)
 * * `base_url` - Base URL for resolving relative URLs (may be NULL)
 *
 * # Memory
 * The caller must free the returned struct using `meta_oxide_result_free()`.
 *
 * # Safety
 * - `html` must be a valid null-terminated C string
 * - `base_url` may be NULL or a valid null-terminated C string
 */
struct MetaOxideResult *meta_oxide_extract_all(const char *html, const char *base_url);

/**
 * Extract standard HTML meta tags
 *
 * # Returns
 * JSON string or NULL on error
 */
char *meta_oxide_extract_meta(const char *html, const char *base_url);

/**
 * Extract Open Graph metadata
 *
 * # Returns
 * JSON string or NULL on error
 */
char *meta_oxide_extract_open_graph(const char *html, const char *base_url);

/**
 * Extract Twitter Card metadata
 *
 * # Returns
 * JSON string or NULL on error
 */
char *meta_oxide_extract_twitter(const char *html, const char *base_url);

/**
 * Extract JSON-LD structured data
 *
 * # Returns
 * JSON array string or NULL on error
 */
char *meta_oxide_extract_json_ld(const char *html, const char *base_url);

/**
 * Extract Microdata
 *
 * # Returns
 * JSON array string or NULL on error
 */
char *meta_oxide_extract_microdata(const char *html, const char *base_url);

/**
 * Extract Microformats (all 9 types: h-card, h-entry, h-event, etc.)
 *
 * # Returns
 * JSON object string with format types as keys, or NULL on error
 */
char *meta_oxide_extract_microformats(const char *html, const char *base_url);

/**
 * Extract RDFa structured data
 *
 * # Returns
 * JSON array string or NULL on error
 */
char *meta_oxide_extract_rdfa(const char *html, const char *base_url);

/**
 * Extract Dublin Core metadata
 *
 * # Returns
 * JSON object string or NULL on error
 */
char *meta_oxide_extract_dublin_core(const char *html);

/**
 * Extract Web App Manifest link
 *
 * # Returns
 * JSON object string or NULL on error
 */
char *meta_oxide_extract_manifest(const char *html, const char *base_url);

/**
 * Parse Web App Manifest JSON content
 *
 * # Returns
 * JSON object string or NULL on error
 */
char *meta_oxide_parse_manifest(const char *json, const char *base_url);

/**
 * Extract oEmbed endpoint discovery
 *
 * # Returns
 * JSON object string or NULL on error
 */
char *meta_oxide_extract_oembed(const char *html, const char *base_url);

/**
 * Extract rel-* link relationships
 *
 * # Returns
 * JSON object string or NULL on error
 */
char *meta_oxide_extract_rel_links(const char *html, const char *base_url);

/**
 * Get the last error code
 *
 * Returns MetaOxideError::Ok (0) if no error occurred
 */
int meta_oxide_last_error(void);

/**
 * Get the last error message
 *
 * Returns a static string describing the error, or NULL if no error occurred.
 * The returned string is valid until the next FFI call on this thread.
 *
 * # Note
 * This function returns a pointer to thread-local storage. The string does
 * not need to be freed by the caller.
 */
const char *meta_oxide_error_message(void);

/**
 * Free a MetaOxideResult structure
 *
 * # Safety
 * - `result` must be a pointer returned by `meta_oxide_extract_all()`
 * - `result` must not be NULL
 * - `result` must not have been freed previously
 */
void meta_oxide_result_free(struct MetaOxideResult *result);

/**
 * Free a string returned by any MetaOxide function
 *
 * # Safety
 * - `s` must be a pointer returned by a MetaOxide function
 * - `s` must not be NULL
 * - `s` must not have been freed previously
 */
void meta_oxide_string_free(char *s);

/**
 * Free a ManifestDiscovery structure
 *
 * # Safety
 * - `discovery` must be a pointer returned by `meta_oxide_extract_manifest_discovery()`
 * - `discovery` must not be NULL
 * - `discovery` must not have been freed previously
 */
void meta_oxide_manifest_discovery_free(struct ManifestDiscovery *discovery);

/**
 * Get the library version string
 *
 * Returns a static string that does not need to be freed
 */
const char *meta_oxide_version(void);

#endif  /* META_OXIDE_H */