libfwevt(3)

💅 libfwevt(3) — Library Functions Manual, but make it a group chat 💅

okay so bestie, welcome to the libfwevt(3) page — it's the manual entry for libfwevt.h, and it's a lot in the best way. Grab a snack, we're going through the whole thing. 🍓

---

✨ NAME ✨

libfwevt.h — the library that supports the Windows XML Event Log (EVTX) data types. yup, that's the whole pitch. no cap. 🪟📜

---

🌸 SYNOPSIS 🌸

first thing first, you gotta pull the header in:

#include <libfwevt.h>

then you've got a million functions grouped into little squads. every single one is listed below, fr fr, nobody's getting skipped. 💖

---

🫶 Support functions

the little guy that just tells you stuff about the library itself:

const char *
libfwevt_get_version(void);

---

📣 Notify functions

for when you want the library to talk — verbosity knob, and stream open/close vibes:

void
libfwevt_notify_set_verbose(int verbose);

int
libfwevt_notify_set_stream(FILE *stream, libfwevt_error_t **error);

int
libfwevt_notify_stream_open(const char *filename,
    libfwevt_error_t **error);

int
libfwevt_notify_stream_close(libfwevt_error_t **error);

---

😭 Error functions

the clean-up-your-mess squad. free 'em, print 'em to a stream, sprint 'em into a string — and yes, there's a backtrace version of both, because sometimes you need to know how you got here:

void
libfwevt_error_free(libfwevt_error_t **error);

int
libfwevt_error_fprint(libfwevt_error_t *error, FILE *stream);

int
libfwevt_error_sprint(libfwevt_error_t *error, char *string,
    size_t size);

int
libfwevt_error_backtrace_fprint(libfwevt_error_t *error, FILE *stream);

int
libfwevt_error_backtrace_sprint(libfwevt_error_t *error, char *string,
    size_t size);

---

📺 Channel functions

channels!! free one, grab its identifier, and get the name as either UTF-8 or UTF-16 — both a <..._size> getter and the getter itself, because we measure before we allocate, as one does:

int
libfwevt_channel_free(libfwevt_channel_t **channel,
    libfwevt_error_t **error);

int
libfwevt_channel_get_identifier(libfwevt_channel_t *channel,
    uint32_t *identifier, libfwevt_error_t **error);

int
libfwevt_channel_get_utf8_name_size(libfwevt_channel_t *channel,
    size_t *utf8_string_size, libfwevt_error_t **error);

int
libfwevt_channel_get_utf8_name(libfwevt_channel_t *channel,
    uint8_t *utf8_string, size_t utf8_string_size,
    libfwevt_error_t **error);

int
libfwevt_channel_get_utf16_name_size(libfwevt_channel_t *channel,
    size_t *utf16_string_size, libfwevt_error_t **error);

int
libfwevt_channel_get_utf16_name(libfwevt_channel_t *channel,
    uint16_t *utf16_string, size_t utf16_string_size,
    libfwevt_error_t **error);

---

🔥 Event functions

the events themselves. free it, get its identifier, its version, its message identifier, and the offset of its template:

int
libfwevt_event_free(libfwevt_event_t **event, libfwevt_error_t **error);

int
libfwevt_event_get_identifier(libfwevt_event_t *event,
    uint32_t *identifier, libfwevt_error_t **error);

int
libfwevt_event_get_version(libfwevt_event_t *event, uint8_t *version,
    libfwevt_error_t **error);

int
libfwevt_event_get_message_identifier(libfwevt_event_t *event,
    uint32_t *message_identifier, libfwevt_error_t **error);

int
libfwevt_event_get_template_offset(libfwevt_event_t *event,
    uint32_t *template_offset, libfwevt_error_t **error);

---

🔑 Keyword functions

just the one. short king. 👑

int
libfwevt_keyword_free(libfwevt_keyword_t **keyword,
    libfwevt_error_t **error);

---

🪜 Level functions

also just the one. free your level and move on:

int
libfwevt_level_free(libfwevt_level_t **level, libfwevt_error_t **error);

---

📚 Manifest functions

the manifest squad — the main character of this whole library ngl. initialize, free, read from raw data, then count and look up providers (by index or by identifier):

int
libfwevt_manifest_initialize(libfwevt_manifest_t **manifest,
    libfwevt_error_t **error);

int
libfwevt_manifest_free(libfwevt_manifest_t **manifest,
    libfwevt_error_t **error);

int
libfwevt_manifest_read(libfwevt_manifest_t *manifest,
    const uint8_t *data, size_t data_size, libfwevt_error_t **error);

int
libfwevt_manifest_get_number_of_providers(libfwevt_manifest_t *manifest,
    int *number_of_providers, libfwevt_error_t **error);

int
libfwevt_manifest_get_provider_by_index(libfwevt_manifest_t *manifest,
    int provider_index, libfwevt_provider_t **provider,
    libfwevt_error_t **error);

int
libfwevt_manifest_get_provider_by_identifier(libfwevt_manifest_t *manifest,
    const uint8_t *provider_identifier, size_t provider_identifier_size,
    libfwevt_provider_t **provider, libfwevt_error_t **error);

---

🗺️ Map functions

one function, one vibe:

int
libfwevt_map_free(libfwevt_map_t **map, libfwevt_error_t **error);

---

⚙️ Opcode functions

same energy, different noun:

int
libfwevt_opcode_free(libfwevt_opcode_t **opcode,
    libfwevt_error_t **error);

---

👑 Provider functions

okay this is the big one — providers are basically the whole personality of a manifest, and they come with channels, events, keywords, levels, maps, opcodes, tasks and templates. every collection gets a "how many?" and a "gimme the one at index N", plus a couple of by-identifier / by-offset lookups for events and templates:

int
libfwevt_provider_free(libfwevt_provider_t **provider,
    libfwevt_error_t **error);

int
libfwevt_provider_get_identifier(libfwevt_provider_t *provider,
    uint8_t *guid_data, size_t guid_data_size,
    libfwevt_error_t **error);

int
libfwevt_provider_get_number_of_channels(libfwevt_provider_t *provider,
    int *number_of_channels, libfwevt_error_t **error);

int
libfwevt_provider_get_channel_by_index(libfwevt_provider_t *provider,
    int channel_index, libfwevt_channel_t **channel,
    libfwevt_error_t **error);

int
libfwevt_provider_get_number_of_events(libfwevt_provider_t *provider,
    int *number_of_events, libfwevt_error_t **error);

int
libfwevt_provider_get_event_by_index(libfwevt_provider_t *provider,
    int event_index, libfwevt_event_t **event,
    libfwevt_error_t **error);

int
libfwevt_provider_get_event_by_identifier(libfwevt_provider_t *provider,
    uint32_t event_identifier, libfwevt_event_t **event,
    libfwevt_error_t **error);

int
libfwevt_provider_get_number_of_keywords(libfwevt_provider_t *provider,
    int *number_of_keywords, libfwevt_error_t **error);

int
libfwevt_provider_get_keyword_by_index(libfwevt_provider_t *provider,
    int keyword_index, libfwevt_keyword_t **keyword,
    libfwevt_error_t **error);

int
libfwevt_provider_get_number_of_levels(libfwevt_provider_t *provider,
    int *number_of_levels, libfwevt_error_t **error);

int
libfwevt_provider_get_level_by_index(libfwevt_provider_t *provider,
    int level_index, libfwevt_level_t **level,
    libfwevt_error_t **error);

int
libfwevt_provider_get_number_of_maps(libfwevt_provider_t *provider,
    int *number_of_maps, libfwevt_error_t **error);

int
libfwevt_provider_get_map_by_index(libfwevt_provider_t *provider,
    int map_index, libfwevt_map_t **map, libfwevt_error_t **error);

int
libfwevt_provider_get_number_of_opcodes(libfwevt_provider_t *provider,
    int *number_of_opcodes, libfwevt_error_t **error);

int
libfwevt_provider_get_opcode_by_index(libfwevt_provider_t *provider,
    int opcode_index, libfwevt_opcode_t **opcode,
    libfwevt_error_t **error);

int
libfwevt_provider_get_number_of_tasks(libfwevt_provider_t *provider,
    int *number_of_tasks, libfwevt_error_t **error);

int
libfwevt_provider_get_task_by_index(libfwevt_provider_t *provider,
    int task_index, libfwevt_task_t **task, libfwevt_error_t **error);

int
libfwevt_provider_get_number_of_templates(libfwevt_provider_t *provider,
    int *number_of_templates, libfwevt_error_t **error);

int
libfwevt_provider_get_template_by_index(libfwevt_provider_t *provider,
    int template_index, libfwevt_template_t **wevt_template,
    libfwevt_error_t **error);

int
libfwevt_provider_get_template_by_offset(libfwevt_provider_t *provider,
    uint32_t offset, libfwevt_template_t **wevt_template,
    libfwevt_error_t **error);

---

📋 Task functions

tiny section, big responsibility:

int
libfwevt_task_free(libfwevt_task_t **task, libfwevt_error_t **error);

---

🧩 Template functions

templates get the full glow-up: initialize, free, read raw data, read an XML document into them, set the ASCII codepage, set data, get/set the offset, get the size, get the identifier, then count and index into the items:

int
libfwevt_template_initialize(libfwevt_template_t **wevt_template,
    libfwevt_error_t **error);

int
libfwevt_template_free(libfwevt_template_t **wevt_template,
    libfwevt_error_t **error);

int
libfwevt_template_read(libfwevt_template_t *wevt_template,
    const uint8_t *data, size_t data_size, size_t data_offset,
    libfwevt_error_t **error);

int
libfwevt_template_read_xml_document(libfwevt_template_t *wevt_template,
    libfwevt_xml_document_t *xml_document, libfwevt_error_t **error);

int
libfwevt_template_set_ascii_codepage(libfwevt_template_t *wevt_template,
    int ascii_codepage, libfwevt_error_t **error);

int
libfwevt_template_set_data(libfwevt_template_t *wevt_template,
    const uint8_t *data, size_t data_size, libfwevt_error_t **error);

int
libfwevt_template_get_offset(libfwevt_template_t *wevt_template,
    uint32_t *offset, libfwevt_error_t **error);

int
libfwevt_template_set_offset(libfwevt_template_t *wevt_template,
    uint32_t offset, libfwevt_error_t **error);

int
libfwevt_template_get_size(libfwevt_template_t *wevt_template,
    uint32_t *size, libfwevt_error_t **error);

int
libfwevt_template_get_identifier(libfwevt_template_t *wevt_template,
    uint8_t *guid_data, size_t guid_data_size,
    libfwevt_error_t **error);

int
libfwevt_template_get_number_of_items(libfwevt_template_t *wevt_template,
    int *number_of_items, libfwevt_error_t **error);

int
libfwevt_template_get_item_by_index(libfwevt_template_t *wevt_template,
    int item_index, libfwevt_template_item_t **item,
    libfwevt_error_t **error);

---

🎀 Template item functions

the items inside the templates. free one, then interrogate it about its input data type, output data type, number of values, value data size, and its name in both UTF-8 and UTF-16 (size getter first, always):

int
libfwevt_template_item_free(libfwevt_template_item_t **template_item,
    libfwevt_error_t **error);

int
libfwevt_template_item_get_input_data_type(libfwevt_template_item_t *template_item,
    uint8_t *input_data_type, libfwevt_error_t **error);

int
libfwevt_template_item_get_output_data_type(libfwevt_template_item_t *template_item,
    uint8_t *output_data_type, libfwevt_error_t **error);

int
libfwevt_template_item_get_number_of_values(libfwevt_template_item_t *template_item,
    uint16_t *number_of_values, libfwevt_error_t **error);

int
libfwevt_template_item_get_value_data_size(libfwevt_template_item_t *template_item,
    uint16_t *value_data_size, libfwevt_error_t **error);

int
libfwevt_template_item_get_utf8_name_size(libfwevt_template_item_t *template_item,
    size_t *utf8_string_size, libfwevt_error_t **error);

int
libfwevt_template_item_get_utf8_name(libfwevt_template_item_t *template_item,
    uint8_t *utf8_string, size_t utf8_string_size,
    libfwevt_error_t **error);

int
libfwevt_template_item_get_utf16_name_size(libfwevt_template_item_t *template_item,
    size_t *utf16_string_size, libfwevt_error_t **error);

int
libfwevt_template_item_get_utf16_name(libfwevt_template_item_t *template_item,
    uint16_t *utf16_string, size_t utf16_string_size,
    libfwevt_error_t **error);

---

🦋 XML document functions

and the last group in this stretch: initialize an XML document, free it, grab its root XML tag, read one in from binary data (with an ASCII codepage and a flags byte), and — the very last line of what we've got here — get the size of its UTF-8 XML string:

int
libfwevt_xml_document_initialize(libfwevt_xml_document_t **xml_document,
    libfwevt_error_t **error);

int
libfwevt_xml_document_free(libfwevt_xml_document_t **xml_document,
    libfwevt_error_t **error);

int
libfwevt_xml_document_get_root_xml_tag(libfwevt_xml_document_t *xml_document,
    libfwevt_xml_tag_t **root_xml_tag, libfwevt_error_t **error);

int
libfwevt_xml_document_read(libfwevt_xml_document_t *xml_document,
    const uint8_t *binary_data, size_t binary_data_size,
    size_t binary_data_offset, int ascii_codepage, uint8_t flags,
    libfwevt_error_t **error);

int
libfwevt_xml_document_get_utf8_xml_string_size(libfwevt_xml_document_t *xml_document,
    size_t *utf8_string_size, libfwevt_error_t **error);

and that's where this part stops, bestie — more is coming 💜

okay bestie, we're still in the synopsis era — here's the rest of the function lineup, no cap ✨

int
libfwevt_xml_document_get_utf8_xml_string(libfwevt_xml_document_t *xml_document,
    uint8_t *utf8_string, size_t utf8_string_size,
    libfwevt_error_t **error);

int
libfwevt_xml_document_get_utf16_xml_string_size(libfwevt_xml_document_t *xml_document,
    size_t *utf16_string_size, libfwevt_error_t **error);

int
libfwevt_xml_document_get_utf16_xml_string(libfwevt_xml_document_t *xml_document,
    uint16_t *utf16_string, size_t utf16_string_size,
    libfwevt_error_t **error);

XML tag functions 💅

int
libfwevt_xml_tag_free(libfwevt_xml_tag_t **xml_tag,
    libfwevt_error_t **error);

int
libfwevt_xml_tag_get_utf8_name_size(libfwevt_xml_tag_t *xml_tag,
    size_t *utf8_string_size, libfwevt_error_t **error);

int
libfwevt_xml_tag_get_utf8_name(libfwevt_xml_tag_t *xml_tag,
    uint8_t *utf8_string, size_t utf8_string_size,
    libfwevt_error_t **error);

int
libfwevt_xml_tag_get_utf16_name_size(libfwevt_xml_tag_t *xml_tag,
    size_t *utf16_string_size, libfwevt_error_t **error);

int
libfwevt_xml_tag_get_utf16_name(libfwevt_xml_tag_t *xml_tag,
    uint16_t *utf16_string, size_t utf16_string_size,
    libfwevt_error_t **error);

int
libfwevt_xml_tag_get_value(libfwevt_xml_tag_t *xml_tag,
    libfwevt_xml_value_t **xml_value, libfwevt_error_t **error);

int
libfwevt_xml_tag_get_number_of_attributes(libfwevt_xml_tag_t *xml_tag,
    int *number_of_attributes, libfwevt_error_t **error);

int
libfwevt_xml_tag_get_attribute_by_index(libfwevt_xml_tag_t *xml_tag,
    int attribute_index, libfwevt_xml_tag_t **attribute_xml_tag,
    libfwevt_error_t **error);

int
libfwevt_xml_tag_get_attribute_by_utf8_name(libfwevt_xml_tag_t *xml_tag,
    const uint8_t *utf8_string, size_t utf8_string_length,
    libfwevt_xml_tag_t **attribute_xml_tag, libfwevt_error_t **error);

int
libfwevt_xml_tag_get_attribute_by_utf16_name(libfwevt_xml_tag_t *xml_tag,
    const uint16_t *utf16_string, size_t utf16_string_length,
    libfwevt_xml_tag_t **attribute_xml_tag, libfwevt_error_t **error);

int
libfwevt_xml_tag_get_number_of_elements(libfwevt_xml_tag_t *xml_tag,
    int *number_of_elements, libfwevt_error_t **error);

int
libfwevt_xml_tag_get_element_by_index(libfwevt_xml_tag_t *xml_tag,
    int element_index, libfwevt_xml_tag_t **element_xml_tag,
    libfwevt_error_t **error);

int
libfwevt_xml_tag_get_element_by_utf8_name(libfwevt_xml_tag_t *xml_tag,
    const uint8_t *utf8_string, size_t utf8_string_length,
    libfwevt_xml_tag_t **element_xml_tag, libfwevt_error_t **error);

int
libfwevt_xml_tag_get_element_by_utf16_name(libfwevt_xml_tag_t *xml_tag,
    const uint16_t *utf16_string, size_t utf16_string_length,
    libfwevt_xml_tag_t **element_xml_tag, libfwevt_error_t **error);

int
libfwevt_xml_tag_get_flags(libfwevt_xml_tag_t *xml_tag, uint8_t *flags,
    libfwevt_error_t **error);

XML value functions 🧚

int
libfwevt_xml_value_free(libfwevt_xml_value_t **xml_value,
    libfwevt_error_t **error);

int
libfwevt_xml_value_get_data_size(libfwevt_xml_value_t *xml_value,
    size_t *data_size, libfwevt_error_t **error);

int
libfwevt_xml_value_copy_data(libfwevt_xml_value_t *xml_value,
    uint8_t *data, size_t data_size, libfwevt_error_t **error);

int
libfwevt_value_get_data_as_8bit_integer(libfwevt_xml_value_t *xml_value,
    uint8_t *value_8bit, libfwevt_error_t **error);

int
libfwevt_value_get_data_as_32bit_integer(libfwevt_xml_value_t *xml_value,
    uint32_t *value_32bit, libfwevt_error_t **error);

int
libfwevt_value_get_data_as_64bit_integer(libfwevt_xml_value_t *xml_value,
    uint64_t *value_64bit, libfwevt_error_t **error);

int
libfwevt_value_get_data_as_filetime(libfwevt_xml_value_t *xml_value,
    uint64_t *filetime, libfwevt_error_t **error);

int
libfwevt_xml_value_get_data_as_utf8_string_size(libfwevt_xml_value_t *xml_value,
    size_t *utf8_string_size, libfwevt_error_t **error);

int
libfwevt_xml_value_get_data_as_utf8_string(libfwevt_xml_value_t *xml_value,
    uint8_t *utf8_string, size_t utf8_string_size,
    libfwevt_error_t **error);

int
libfwevt_xml_value_get_data_as_utf16_string_size(libfwevt_xml_value_t *xml_value,
    size_t *utf16_string_size, libfwevt_error_t **error);

int
libfwevt_xml_value_get_data_as_utf16_string(libfwevt_xml_value_t *xml_value,
    uint16_t *utf16_string, size_t utf16_string_size,
    libfwevt_error_t **error);

🌸 DESCRIPTION 🌸

okay so libfwevt_get_version() is the function you use to retrieve the library version. literally that's its whole job, and it ate. 💖

💖 RETURN VALUES 💖

Most of the functions return NULL or -1 on error, dependent on the return type. For the actual return values, see "libfwevt.h" — it's giving the receipts, bestie. 👑

🍓 ENVIRONMENT 🍓

None — no cap, nothing to configure here. ✨

🎀 FILES 🎀

None — literally no files, and that's the vibe. 🌸

💀 BUGS 💀

Please report bugs of any kind on the project issue tracker: https://github.com/libyal/libfwevt/issues. don't be shy, bestie, they wanna hear it. 😭

👑 AUTHOR 👑

These man pages are generated from "libfwevt.h" — yes, the header is the author of this whole situation. 💅

🌈 COPYRIGHT 🌈

Copyright (C) 2011-2024, Joachim Metz <joachim.metz@gmail.com>.

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

periodt — that's the legal tea. 🫶

⭐ SEE ALSO ⭐

the libfwevt.h include file — go peek, iykyk. 🦋

---

okay that's the whole page, bestie — footer vibes: this one's from libfwevt, dated May 1, 2024, and it's the libfwevt(3) page. mwah 💖🎀