libpff(3)

πŸ“¦
this version Β· 2 versions
, in nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu resolute, ubuntu stonking

πŸ’– NAME

okay so this is libpff(3), the manual page for libpff.h, and it is literally the Library to access the Personal Folder File (OST, PAB and PST) format. That's the whole name vibe, bestie. πŸŽ€

  • libpff.h β€” Library to access the Personal Folder File (OST, PAB and PST) format

✨ SYNOPSIS

first things first, here's the include you need:

#include <libpff.h>

this synopsis is giving huge friend-group energy: support functions, notify functions, error functions, file functions, item functions, name to ID map entry functions, record set functions, and record entry functions. every single one is below, no skips, no cuts. πŸ’…

πŸ› οΈ Support functions

the little support girlies that keep the vibe check passing:

const char *
libpff_get_version(void);

int
libpff_get_access_flags_read(void);

int
libpff_get_codepage(int *codepage, libpff_error_t **error);

int
libpff_set_codepage(int codepage, libpff_error_t **error);

int
libpff_check_file_signature(const char *filename,
    libpff_error_t **error);
πŸ¦‹ Available when compiled with wide character string support:
int
libpff_check_file_signature_wide(const wchar_t *filename,
    libpff_error_t **error);
πŸ¦‹ Available when compiled with libbfio support:
int
libpff_check_file_signature_file_io_handle(libbfio_handle_t *file_io_handle,
    libpff_error_t **error);

πŸ”” Notify functions

these are the notify functions, aka the ones that handle the "hey bestie, listen" energy:

void
libpff_notify_set_verbose(int verbose);

int
libpff_notify_set_stream(FILE *stream, libpff_error_t **error);

int
libpff_notify_stream_open(const char *filename, libpff_error_t **error);

int
libpff_notify_stream_close(libpff_error_t **error);

🚨 Error functions

error functions, because sometimes the code is not slaying and we need receipts:

void
libpff_error_free(libpff_error_t **error);

int
libpff_error_fprint(libpff_error_t *error, FILE *stream);

int
libpff_error_sprint(libpff_error_t *error, char *string, size_t size);

int
libpff_error_backtrace_fprint(libpff_error_t *error, FILE *stream);

int
libpff_error_backtrace_sprint(libpff_error_t *error, char *string,
    size_t size);

πŸ“ File functions

the file functions. this is the main character section, honestly:

int
libpff_file_initialize(libpff_file_t **file, libpff_error_t **error);

int
libpff_file_free(libpff_file_t **file, libpff_error_t **error);

int
libpff_file_signal_abort(libpff_file_t *file, libpff_error_t **error);

int
libpff_file_open(libpff_file_t *file, const char *filename,
    int access_flags, libpff_error_t **error);

int
libpff_file_close(libpff_file_t *file, libpff_error_t **error);

int
libpff_file_is_corrupted(libpff_file_t *file, libpff_error_t **error);

int
libpff_file_recover_items(libpff_file_t *file, uint8_t recovery_flags,
    libpff_error_t **error);

int
libpff_file_get_size(libpff_file_t *file, size64_t *size,
    libpff_error_t **error);

int
libpff_file_get_content_type(libpff_file_t *file, uint8_t *content_type,
    libpff_error_t **error);

int
libpff_file_get_type(libpff_file_t *file, uint8_t *type,
    libpff_error_t **error);

int
libpff_file_get_encryption_type(libpff_file_t *file,
    uint8_t *encryption_type, libpff_error_t **error);

int
libpff_file_get_ascii_codepage(libpff_file_t *file, int *ascii_codepage,
    libpff_error_t **error);

int
libpff_file_set_ascii_codepage(libpff_file_t *file, int ascii_codepage,
    libpff_error_t **error);

int
libpff_file_get_number_of_unallocated_blocks(libpff_file_t *file,
    int unallocated_block_type, int *number_of_unallocated_blocks,
    libpff_error_t **error);

int
libpff_file_get_unallocated_block(libpff_file_t *file,
    int unallocated_block_type, int unallocated_block_index,
    off64_t *offset, size64_t *size, libpff_error_t **error);

int
libpff_file_get_root_item(libpff_file_t *file,
    libpff_item_t **root_item, libpff_error_t **error);

int
libpff_file_get_message_store(libpff_file_t *file,
    libpff_item_t **message_store, libpff_error_t **error);

int
libpff_file_get_name_to_id_map(libpff_file_t *file,
    libpff_item_t **name_to_id_map, libpff_error_t **error);

int
libpff_file_get_root_folder(libpff_file_t *file,
    libpff_item_t **root_folder, libpff_error_t **error);

int
libpff_file_get_item_by_identifier(libpff_file_t *file,
    uint32_t item_identifier, libpff_item_t **item,
    libpff_error_t **error);

int
libpff_file_get_number_of_orphan_items(libpff_file_t *file,
    int *number_of_orphan_items, libpff_error_t **error);

int
libpff_file_get_orphan_item_by_index(libpff_file_t *file,
    int orphan_item_index, libpff_item_t **orphan_item,
    libpff_error_t **error);

int
libpff_file_get_number_of_recovered_items(libpff_file_t *file,
    int *number_of_recovered_items, libpff_error_t **error);

int
libpff_file_get_recovered_item_by_index(libpff_file_t *file,
    int recovered_item_index, libpff_item_t **recovered_item,
    libpff_error_t **error);
πŸ¦‹ Available when compiled with wide character string support:
int
libpff_file_open_wide(libpff_file_t *file, const wchar_t *filename,
    int access_flags, libpff_error_t **error);
πŸ¦‹ Available when compiled with libbfio support:
int
libpff_file_open_file_io_handle(libpff_file_t *file,
    libbfio_handle_t *file_io_handle, int access_flags,
    libpff_error_t **error);

πŸŽ€ Item functions

item functions, serving looks and structs:

int
libpff_item_free(libpff_item_t **item, libpff_error_t **error);

int
libpff_item_get_identifier(libpff_item_t *item, uint32_t *identifier,
    libpff_error_t **error);

int
libpff_item_get_number_of_record_sets(libpff_item_t *item,
    int *number_of_record_sets, libpff_error_t **error);

int
libpff_item_get_record_set_by_index(libpff_item_t *item,
    int record_set_index, libpff_record_set_t **record_set,
    libpff_error_t **error);

int
libpff_item_get_number_of_entries(libpff_item_t *item,
    uint32_t *number_of_entries, libpff_error_t **error);

int
libpff_item_get_type(libpff_item_t *item, uint8_t *item_type,
    libpff_error_t **error);

int
libpff_item_get_number_of_sub_items(libpff_item_t *item,
    int *number_of_sub_items, libpff_error_t **error);

int
libpff_item_get_sub_item(libpff_item_t *item, int sub_item_index,
    libpff_item_t **sub_item, libpff_error_t **error);

int
libpff_item_get_sub_item_by_identifier(libpff_item_t *item,
    uint32_t sub_item_identifier, libpff_item_t **sub_item,
    libpff_error_t **error);

πŸͺͺ Name to ID map entry functions

name to ID map entry functions. yes, the name is long. yes, it ate:

int
libpff_name_to_id_map_entry_get_type(libpff_name_to_id_map_entry_t *name_to_id_map_entry,
    uint8_t *entry_type, libpff_error_t **error);

int
libpff_name_to_id_map_entry_get_number(libpff_name_to_id_map_entry_t *name_to_id_map_entry,
    uint32_t *number, libpff_error_t **error);

int
libpff_name_to_id_map_entry_get_utf8_string_size(libpff_name_to_id_map_entry_t *name_to_id_map_entry,
    size_t *utf8_string_size, libpff_error_t **error);

int
libpff_name_to_id_map_entry_get_utf8_string(libpff_name_to_id_map_entry_t *name_to_id_map_entry,
    uint8_t *utf8_string, size_t utf8_string_size,
    libpff_error_t **error);

int
libpff_name_to_id_map_entry_get_utf16_string_size(libpff_name_to_id_map_entry_t *name_to_id_map_entry,
    size_t *utf16_string_size, libpff_error_t **error);

int
libpff_name_to_id_map_entry_get_utf16_string(libpff_name_to_id_map_entry_t *name_to_id_map_entry,
    uint16_t *utf16_string, size_t utf16_string_size,
    libpff_error_t **error);

int
libpff_name_to_id_map_entry_get_guid(libpff_name_to_id_map_entry_t *name_to_id_map_entry,
    uint8_t *guid, size_t size, libpff_error_t **error);

🧺 Record set functions

record set functions, keeping the entries organized like a perfectly curated playlist:

int
libpff_record_set_free(libpff_record_set_t **record_set,
    libpff_error_t **error);

int
libpff_record_set_get_number_of_entries(libpff_record_set_t *record_set,
    int *number_of_entries, libpff_error_t **error);

int
libpff_record_set_get_entry_by_index(libpff_record_set_t *record_set,
    int record_entry_index, libpff_record_entry_t **record_entry,
    libpff_error_t **error);

int
libpff_record_set_get_entry_by_type(libpff_record_set_t *record_set,
    uint32_t entry_type, uint32_t value_type,
    libpff_record_entry_t **record_entry, uint8_t flags,
    libpff_error_t **error);

int
libpff_record_set_get_entry_by_utf8_name(libpff_record_set_t *record_set,
    const uint8_t *utf8_string, size_t utf8_string_length,
    uint32_t value_type, libpff_record_entry_t **record_entry,
    uint8_t flags, libpff_error_t **error);

int
libpff_record_set_get_entry_by_utf16_name(libpff_record_set_t *record_set,
    const uint16_t *utf16_string, size_t utf16_string_length,
    uint32_t value_type, libpff_record_entry_t **record_entry,
    uint8_t flags, libpff_error_t **error);

🌸 Record entry functions

record entry functions. this is the data-getter section and it is so comprehensive:

int
libpff_record_entry_free(libpff_record_entry_t **record_entry,
    libpff_error_t **error);

int
libpff_record_entry_get_entry_type(libpff_record_entry_t *record_entry,
    uint32_t *entry_type, libpff_error_t **error);

int
libpff_record_entry_get_value_type(libpff_record_entry_t *record_entry,
    uint32_t *value_type, libpff_error_t **error);

int
libpff_record_entry_get_name_to_id_map_entry(libpff_record_entry_t *record_entry,
    libpff_name_to_id_map_entry_t **name_to_id_map_entry,
    libpff_error_t **error);

int
libpff_record_entry_get_data_size(libpff_record_entry_t *record_entry,
    size_t *data_size, libpff_error_t **error);

int
libpff_record_entry_get_data(libpff_record_entry_t *record_entry,
    uint8_t *data, size_t data_size, libpff_error_t **error);

int
libpff_record_entry_get_data_as_boolean(libpff_record_entry_t *record_entry,
    uint8_t *value_boolean, libpff_error_t **error);

int
libpff_record_entry_get_data_as_16bit_integer(libpff_record_entry_t *record_entry,
    uint16_t *value_16bit, libpff_error_t **error);

int
libpff_record_entry_get_data_as_32bit_integer(libpff_record_entry_t *record_entry,
    uint32_t *value_32bit, libpff_error_t **error);

int
libpff_record_entry_get_data_as_64bit_integer(libpff_record_entry_t *record_entry,
    uint64_t *value_64bit, libpff_error_t **error);

int
libpff_record_entry_get_data_as_filetime(libpff_record_entry_t *record_entry,
    uint64_t *filetime, libpff_error_t **error);

int
libpff_record_entry_get_data_as_floatingtime(libpff_record_entry_t *record_entry,
    uint64_t *floatingtime, libpff_error_t **error);

int
libpff_record_entry_get_data_as_size(libpff_record_entry_t *record_entry,
    size64_t *value_size, libpff_error_t **error);

int
libpff_record_entry_get_data_as_floating_point(libpff_record_entry_t *record_entry,
    double *value_floating_point, libpff_error_t **error);

int
libpff_record_entry_get_data_as_utf8_string_size(libpff_record_entry_t *record_entry,
    size_t *utf8_string_size, libpff_error_t **error);

int
libpff_record_entry_get_data_as_utf8_string(libpff_record_entry_t *record_entry,
    uint8_t *utf8_string, size_t utf8_string_size,
    libpff_error_t **error);

…and the parade of libpff_record_entry_* functions keeps going, no brakes:

int
libpff_record_entry_get_data_as_utf16_string_size(libpff_record_entry_t *record_entry,
    size_t *utf16_string_size, libpff_error_t **error);

int
libpff_record_entry_get_data_as_utf16_string(libpff_record_entry_t *record_entry,
    uint16_t *utf16_string, size_t utf16_string_size,
    libpff_error_t **error);

int
libpff_record_entry_get_data_as_guid(libpff_record_entry_t *record_entry,
    uint8_t *guid_data, size_t guid_data_size, libpff_error_t **error);

int
libpff_record_entry_get_multi_value(libpff_record_entry_t *record_entry,
    libpff_multi_value_t **multi_value, libpff_error_t **error);

ssize_t
libpff_record_entry_read_buffer(libpff_record_entry_t *record_entry,
    uint8_t *buffer, size_t buffer_size, libpff_error_t **error);

off64_t
libpff_record_entry_seek_offset(libpff_record_entry_t *record_entry,
    off64_t offset, int whence, libpff_error_t **error);

🌈 Multi value functions

okay these ones are literally the multi-value girlies, they come in packs πŸ’…

int
libpff_multi_value_free(libpff_multi_value_t **multi_value,
    libpff_error_t **error);

int
libpff_multi_value_get_number_of_values(libpff_multi_value_t *multi_value,
    int *number_of_values, libpff_error_t **error);

int
libpff_multi_value_get_value(libpff_multi_value_t *multi_value,
    int value_index, uint32_t *value_type, uint8_t **value_data,
    size_t *value_data_size, libpff_error_t **error);

int
libpff_multi_value_get_value_32bit(libpff_multi_value_t *multi_value,
    int value_index, uint32_t *value_32bit, libpff_error_t **error);

int
libpff_multi_value_get_value_64bit(libpff_multi_value_t *multi_value,
    int value_index, uint64_t *value_64bit, libpff_error_t **error);

int
libpff_multi_value_get_value_filetime(libpff_multi_value_t *multi_value,
    int value_index, uint64_t *value_64bit, libpff_error_t **error);

int
libpff_multi_value_get_value_utf8_string_size(libpff_multi_value_t *multi_value,
    int value_index, size_t *utf8_string_size, libpff_error_t **error);

int
libpff_multi_value_get_value_utf8_string(libpff_multi_value_t *multi_value,
    int value_index, uint8_t *utf8_string, size_t utf8_string_size,
    libpff_error_t **error);

int
libpff_multi_value_get_value_utf16_string_size(libpff_multi_value_t *multi_value,
    int value_index, size_t *utf16_string_size, libpff_error_t **error);

int
libpff_multi_value_get_value_utf16_string(libpff_multi_value_t *multi_value,
    int value_index, uint16_t *utf16_string, size_t utf16_string_size,
    libpff_error_t **error);

int
libpff_multi_value_get_value_binary_data_size(libpff_multi_value_t *multi_value,
    int value_index, size_t *size, libpff_error_t **error);

int
libpff_multi_value_get_value_binary_data(libpff_multi_value_t *multi_value,
    int value_index, uint8_t *binary_data, size_t size,
    libpff_error_t **error);

int
libpff_multi_value_get_value_guid(libpff_multi_value_t *multi_value,
    int value_index, uint8_t *guid, size_t size,
    libpff_error_t **error);

πŸŽ€ Folder item functions

folders!! the whole nesting situation, we love a hierarchy ✨

int
libpff_folder_get_type(libpff_item_t *folder, uint8_t *type,
    libpff_error_t **error);

int
libpff_folder_get_utf8_name_size(libpff_item_t *folder,
    size_t *utf8_string_size, libpff_error_t **error);

int
libpff_folder_get_utf8_name(libpff_item_t *folder, uint8_t *utf8_string,
    size_t utf8_string_size, libpff_error_t **error);

int
libpff_folder_get_utf16_name_size(libpff_item_t *folder,
    size_t *utf16_string_size, libpff_error_t **error);

int
libpff_folder_get_utf16_name(libpff_item_t *folder,
    uint16_t *utf16_string, size_t utf16_string_size,
    libpff_error_t **error);

int
libpff_folder_get_number_of_sub_folders(libpff_item_t *folder,
    int *number_of_sub_folders, libpff_error_t **error);

int
libpff_folder_get_sub_folder(libpff_item_t *folder,
    int sub_folder_index, libpff_item_t **sub_folder,
    libpff_error_t **error);

int
libpff_folder_get_sub_folder_by_utf8_name(libpff_item_t *folder,
    uint8_t *utf8_sub_folder_name, size_t utf8_sub_folder_name_size,
    libpff_item_t **sub_folder, libpff_error_t **error);

int
libpff_folder_get_sub_folder_by_utf16_name(libpff_item_t *folder,
    uint16_t *utf16_sub_folder_name, size_t utf16_sub_folder_name_size,
    libpff_item_t **sub_folder, libpff_error_t **error);

int
libpff_folder_get_sub_folders(libpff_item_t *folder,
    libpff_item_t **sub_folders, libpff_error_t **error);

int
libpff_folder_get_number_of_sub_messages(libpff_item_t *folder,
    int *number_of_sub_messages, libpff_error_t **error);

int
libpff_folder_get_sub_message(libpff_item_t *folder,
    int sub_message_index, libpff_item_t **sub_message,
    libpff_error_t **error);

int
libpff_folder_get_sub_message_by_utf8_name(libpff_item_t *folder,
    uint8_t *utf8_sub_message_name, size_t utf8_sub_message_name_size,
    libpff_item_t **sub_message, libpff_error_t **error);

int
libpff_folder_get_sub_message_by_utf16_name(libpff_item_t *folder,
    uint16_t *utf16_sub_message_name,
    size_t utf16_sub_message_name_size, libpff_item_t **sub_message,
    libpff_error_t **error);

int
libpff_folder_get_sub_messages(libpff_item_t *folder,
    libpff_item_t **sub_messages, libpff_error_t **error);

int
libpff_folder_get_number_of_sub_associated_contents(libpff_item_t *folder,
    int *number_of_sub_associated_contents, libpff_error_t **error);

int
libpff_folder_get_sub_associated_content(libpff_item_t *folder,
    int sub_associated_content_index,
    libpff_item_t **sub_associated_content, libpff_error_t **error);

int
libpff_folder_get_sub_associated_contents(libpff_item_t *folder,
    libpff_item_t **sub_associated_contents, libpff_error_t **error);

int
libpff_folder_get_unknowns(libpff_item_t *folder,
    libpff_item_t **unknowns, libpff_error_t **error);

πŸ¦‹ Message item functions

messages, aka the main characters of this entire library, periodt πŸ‘‘

int
libpff_message_get_entry_value_utf8_string_size(libpff_item_t *message,
    uint32_t entry_type, size_t *utf8_string_size,
    libpff_error_t **error);

int
libpff_message_get_entry_value_utf8_string(libpff_item_t *message,
    uint32_t entry_type, uint8_t *utf8_string, size_t utf8_string_size,
    libpff_error_t **error);

int
libpff_message_get_entry_value_utf16_string_size(libpff_item_t *message,
    uint32_t entry_type, size_t *utf16_string_size,
    libpff_error_t **error);

int
libpff_message_get_entry_value_utf16_string(libpff_item_t *message,
    uint32_t entry_type, uint16_t *utf16_string,
    size_t utf16_string_size, libpff_error_t **error);

int
libpff_message_get_client_submit_time(libpff_item_t *message,
    uint64_t *filetime, libpff_error_t **error);

int
libpff_message_get_delivery_time(libpff_item_t *message,
    uint64_t *filetime, libpff_error_t **error);

int
libpff_message_get_creation_time(libpff_item_t *message,
    uint64_t *filetime, libpff_error_t **error);

int
libpff_message_get_modification_time(libpff_item_t *message,
    uint64_t *filetime, libpff_error_t **error);

int
libpff_message_get_number_of_attachments(libpff_item_t *message,
    int *number_of_attachments, libpff_error_t **error);

int
libpff_message_get_attachment(libpff_item_t *message,
    int attachment_index, libpff_item_t **attachment,
    libpff_error_t **error);

int
libpff_message_get_attachments(libpff_item_t *message,
    libpff_item_t **attachments, libpff_error_t **error);

int
libpff_message_get_recipients(libpff_item_t *message,
    libpff_item_t **recipients, libpff_error_t **error);

int
libpff_message_get_plain_text_body_size(libpff_item_t *message,
    size_t *size, libpff_error_t **error);

int
libpff_message_get_plain_text_body(libpff_item_t *message,
    uint8_t *message_body, size_t size, libpff_error_t **error);

int
libpff_message_get_rtf_body_size(libpff_item_t *message, size_t *size,
    libpff_error_t **error);

int
libpff_message_get_rtf_body(libpff_item_t *message,
    uint8_t *message_body, size_t size, libpff_error_t **error);

int
libpff_message_get_html_body_size(libpff_item_t *message, size_t *size,
    libpff_error_t **error);

int
libpff_message_get_html_body(libpff_item_t *message,
    uint8_t *message_body, size_t size, libpff_error_t **error);

πŸ“ Attachment item functions

the little files riding along with your mail, obsessed with them honestly πŸ’–

int
libpff_attachment_get_type(libpff_item_t *attachment,
    int *attachment_type, libpff_error_t **error);

int
libpff_attachment_get_data_size(libpff_item_t *attachment,
    size64_t *size, libpff_error_t **error);

ssize_t
libpff_attachment_data_read_buffer(libpff_item_t *attachment,
    uint8_t *buffer, size_t buffer_size, libpff_error_t **error);

off64_t
libpff_attachment_data_seek_offset(libpff_item_t *attachment,
    off64_t offset, int whence, libpff_error_t **error);

int
libpff_attachment_get_item(libpff_item_t *attachment,
    libpff_item_t **attached_item, libpff_error_t **error);
πŸ‘‘ Available when compiled with libbfio support:
int
libpff_attachment_get_data_file_io_handle(libpff_item_t *attachment,
    libbfio_handle_t **file_io_handle, libpff_error_t **error);

✨ DESCRIPTION ✨

So the one function that actually gets a full sentence here is libpff_get_version() β€” bestie, all it does is tell you the version of the library you're running. That's it. That's the whole description. Iconic in its minimalism, honestly.


πŸ’€ RETURN VALUES πŸ’€

Most of these functions hand back NULL or -1 when things go wrong, and which one you get depends on the return type of the specific function you called. Want the actual, exact return values for each one? Go look in libpff.h. No cap, that's the source of truth.


🌈 ENVIRONMENT 🌈

None. Nothing here. Zero environment variables, your shell env is safe.


πŸŽ€ FILES πŸŽ€

None. Also nothing. No files to worry about.


πŸ”₯ NOTES πŸ”₯

libpff can be compiled with wide character support (wchar_t). Yes, that's a thing, and yes it matters for what the API expects.

To compile libpff with wide character support, use:

./configure --enable-wide-character-type=yes

or define:

_UNICODE

or:

UNICODE

during compilation.

And if you're sitting there wondering "wait, was this build compiled with wide character support or not??" β€” you can check LIBPFF_WIDE_CHARACTER_TYPE in libpff/features.h to find out. Life saver fr fr 🫢


πŸ› BUGS πŸ›

Found a bug of literally any kind? Please report it on the project issue tracker:

https://github.com/libyal/libpff/issues

They want to hear about it, don't be shy πŸ’œ


πŸ’… AUTHOR πŸ’…

These man pages are generated from libpff.h. Yep, auto-generated, that's why they're so thorough.


Copyright (C) 2008-2023, 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.

πŸ’€ read that again: no warranty, not even the implied "this will work for its intended purpose" one. Use it, love it, but don't come for anybody if it misbehaves.

⭐ SEE ALSO ⭐

  • the libpff.h include file β€” that's where everything literally lives, go read it, iykyk

and that's the whole page, bestie 🧚 this was libpff β€” the manual page for version libpff, dated November 14, 2021, filed under libpff(3). mwah, go read libpff.h πŸ’œβœ¨

πŸ“¦ where this page comes from