### C Quick Start Example

Source: https://github.com/libyal/libpff/blob/main/_autodocs/MANIFEST.txt

A basic C program demonstrating file opening, reading, and closing with libpff. Ensure libpff is built and installed.

```c
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include "pff.h"

int main(int argc, char **argv)
{
    if (argc != 2)
    {
        fprintf(stderr, "Usage: %s <pff_file>\n", argv[0]);
        return 1;
    }

    int return_code = 1;
    struct _pff_file *pff_file = NULL;

    if (pff_open(argv[1], &pff_file) != 0)
    {
        fprintf(stderr, "Unable to open file: %s\n", argv[1]);
        goto end;
    }

    struct _pff_file_info file_info;
    if (pff_get_file_info(pff_file, &file_info) != 0)
    {
        fprintf(stderr, "Unable to get file information.\n");
        goto end;
    }

    printf("File information:\n");
    printf("  Version: %u\n", file_info.version);
    printf("  Codepage: %s\n", file_info.codepage);
    printf("  Locale: %s\n", file_info.locale);
    printf("  Sort locale: %s\n", file_info.sort_locale);
    printf("  Sort table: %s\n", file_info.sort_table);
    printf("  Sort table length: %u\n", file_info.sort_table_length);

    return_code = 0;

end:
    if (pff_file)
    {
        pff_close(pff_file);
    }

    return return_code;
}

```

--------------------------------

### Python Quick Start Example

Source: https://github.com/libyal/libpff/blob/main/_autodocs/MANIFEST.txt

A basic Python script demonstrating file opening and basic information retrieval using the pypff library. Ensure pypff is installed.

```python
import sys

import pypff

def main():
    if len(sys.argv) != 2:
        print(f"Usage: {sys.argv[0]} <pff_file>")
        return 1

    try:
        pff_file = pypff.file()
        pff_file.open(sys.argv[1])

        file_info = pff_file.get_file_info()

        print("File information:")
        print(f"  Version: {file_info['version']}")
        print(f"  Codepage: {file_info['codepage']}")
        print(f"  Locale: {file_info['locale']}")
        print(f"  Sort locale: {file_info['sort_locale']}")
        print(f"  Sort table: {file_info['sort_table']}")
        print(f"  Sort table length: {file_info['sort_table_length']}")

        pff_file.close()

    except Exception as error:
        print(f"Error: {error}")
        return 1

    return 0

if __name__ == '__main__':
    sys.exit(main())

```

--------------------------------

### Basic Build and Install

Source: https://github.com/libyal/libpff/wiki/Building

Standard commands to configure, build, and install libpff. Ensure build tools and dependencies are installed first.

```bash
./configure
make

```

```bash
sudo make install
```

--------------------------------

### Custom Installation Prefix

Source: https://github.com/libyal/libpff/wiki/Building

Configure libpff to install binaries in a specific directory, such as /usr, instead of the default /usr/local.

```bash
./configure --prefix=/usr
```

--------------------------------

### Install Python Wheel

Source: https://github.com/libyal/libpff/wiki/Building

Installs the libpff Python wheel package from a local distribution directory.

```bash
python -m pip install --find-links=dist --no-index libpff-python
```

--------------------------------

### Install LIBPFF via vcpkg

Source: https://github.com/libyal/libpff/blob/main/_autodocs/configuration.md

Installs the LIBPFF library for the x64 Windows platform using the vcpkg package manager.

```bash
vcpkg install libpff:x64-windows
```

--------------------------------

### Basic Build Process

Source: https://github.com/libyal/libpff/blob/main/_autodocs/README.md

Use this sequence for a standard build of libpff. Ensure you have the necessary build tools installed.

```bash
./autogen.sh
./configure
make
sudo make install
```

--------------------------------

### Python Example: Read PST File

Source: https://github.com/libyal/libpff/blob/main/_autodocs/INDEX.md

A Python example demonstrating how to open a PST file and iterate through its folders and messages using the libpff Python bindings.

```python
import libpff

pst_file = libpff.file()
pst_file.open('example.pst')

root_folder = pst_file.get_root_folder()

def process_folder(folder):
    print(f"Folder: {folder.name}")
    for message in folder.get_messages():
        print(f"  Message: {message.subject}")
    for sub_folder in folder.get_sub_folders():
        process_folder(sub_folder)

process_folder(root_folder)
pst_file.close()
```

--------------------------------

### Install RedHat Build Dependencies

Source: https://github.com/libyal/libpff/wiki/Building

Installs necessary packages for building libpff with RPM on RedHat-based systems.

```bash
dnf install rpm-build zlib-devel python3-devel
```

--------------------------------

### Installing Debian Packages

Source: https://github.com/libyal/libpff/wiki/Building

Install a specific Debian package, such as the libpff library, using dpkg.

```bash
sudo dpkg -i libpff_<version>-1_<arch>.deb
```

--------------------------------

### Install libpff RPM Package

Source: https://github.com/libyal/libpff/wiki/Building

Installs the built libpff RPM package on a RedHat-based system.

```bash
sudo rpm -ivh libpff-<version>-1.<arch>.rpm
```

--------------------------------

### Install pypff Python Bindings

Source: https://github.com/libyal/libpff/blob/main/_autodocs/configuration.md

Instructions for installing the pypff Python bindings. This can be done by building from source or using pip if the package is available.

```bash
# Build from source with Python support
./configure --enable-python-bindings
make
sudo make install

# Or use pip (if packaged)
pip install pypff
```

--------------------------------

### Cygwin Build Output

Source: https://github.com/libyal/libpff/wiki/Building

Example output files expected after building libpff with Cygwin.

```bash
libpff/.libs/cygpff-0.dll
```

```bash
pfftools/.libs/pffexport.exe
```

```bash
pfftools/.libs/pffinfo.exe
```

--------------------------------

### Install Build Dependencies on Fedora

Source: https://github.com/libyal/libpff/wiki/Building

Installs the necessary development tools for building libpff from source on Fedora-based systems.

```bash
sudo dnf install git autoconf automake gettext-devel libtool pkg-config
```

--------------------------------

### Visual Studio Runtime Error Example

Source: https://github.com/libyal/libpff/wiki/Troubleshooting

This runtime error typically occurs when an executable built with Visual Studio 2010 or later is run on an unsupported Windows version. Ensure correct Visual Studio run-time DLLs are installed and check WINVER settings.

```text
The procedure entry point DecodePointer could not be located in the dynamic link library KERNEL32.DLL
```

--------------------------------

### Install Build Dependencies on Debian/Ubuntu

Source: https://github.com/libyal/libpff/wiki/Building

Installs the necessary development tools for building libpff from source on Debian-based systems.

```bash
sudo apt install git autoconf automake autopoint libtool pkg-config
```

--------------------------------

### Python Bindings Setup

Source: https://github.com/libyal/libpff/blob/main/_autodocs/INDEX.md

Details the steps for setting up the Python bindings for libpff. This allows using libpff functionality from Python scripts.

```shell
# Ensure libpff is built with --enable-python-bindings
# Then install the Python bindings:
python setup.py install
```

--------------------------------

### Install Build Dependencies on macOS

Source: https://github.com/libyal/libpff/wiki/Building

Installs the necessary development tools for building libpff from source on macOS using MacPorts.

```bash
sudo port install git autoconf automake gettext libtool pkgconfig
```

--------------------------------

### Open and Read a PST File

Source: https://github.com/libyal/libpff/blob/main/_autodocs/INDEX.md

Demonstrates how to open a PST file and access its root folder. This is a common starting point for most operations.

```c
#include <stdio.h>
#include <stdlib.h>
#include <libpff.h>

int
main(int argc, char **argv)
{
    struct pff_file *pff_file;
    int error;

    if (argc < 2)
    {
        fprintf(stderr, "Usage: %s <pst_file>\n", argv[0]);

        return 1;
    }

    error = libpff_file_open(argv[1], &pff_file);
    if (error != 0)
    {
        fprintf(stderr, "Unable to open file %s: %d\n", argv[1], error);

        return 1;
    }

    fprintf(stderr, "File opened: %s\n", argv[1]);

    libpff_file_close(pff_file);

    return 0;
}
```

--------------------------------

### Build the Library

Source: https://github.com/libyal/libpff/blob/main/_autodocs/INDEX.md

Provides instructions on how to build libpff using the Autotools build system. This covers configuration, compilation, and installation.

```shell
./configure \
    --enable-python-bindings \
    --with-codepage=UTF-8 \
    --disable-debug
make
make install
```

--------------------------------

### Install libpff Build Files with DESTDIR

Source: https://github.com/libyal/libpff/wiki/Building

Installs libpff build files into a temporary directory using DESTDIR to ensure correct library paths for distribution.

```bash
make install DESTDIR=$PWD/tmp
```

--------------------------------

### Create macOS Package

Source: https://github.com/libyal/libpff/wiki/Building

Creates a macOS package (.pkg) from the installed libpff files.

```bash
pkgbuild --root $PWD/tmp --identifier com.github.libyal.libpff --version <version> --ownership recommended ../libpff-<version>.pkg
```

--------------------------------

### Prerequisites for Debian Package Building

Source: https://github.com/libyal/libpff/wiki/Building

Install necessary packages for building Debian packages of libpff.

```bash
sudo apt install autotools-dev build-essential debhelper dh-autoreconf dh-python fakeroot pkg-config python3-dev python3-setuptools zlib1g-dev
```

--------------------------------

### Build Static Executables

Source: https://github.com/libyal/libpff/wiki/Building

Configure libpff to build static executables. Ensure static versions of glibc and zlib are installed.

```bash
./configure --enable-static-executables=yes
```

--------------------------------

### Configure and Build libpff on macOS

Source: https://github.com/libyal/libpff/wiki/Building

Configures and builds libpff with Python support on macOS, setting the installation prefix to /usr/local.

```bash
./configure --prefix=/usr/local --enable-python --with-pyprefix
make
```

--------------------------------

### Enable Python Bindings

Source: https://github.com/libyal/libpff/wiki/Building

Configure libpff to build Python bindings. Ensure Python development files (e.g., python3-dev, python3-setuptools) are installed.

```bash
./configure --enable-python
```

--------------------------------

### Basic pypff Usage Example

Source: https://github.com/libyal/libpff/blob/main/_autodocs/configuration.md

Demonstrates opening a PFF file using the pypff Python bindings, checking its signature, and iterating through its root folder and subfolders/messages.

```python
import pypff

# Check file signature
if pypff.check_file_signature("message.pst"):
    print("Valid PFF file")

# Open and read file
pff_file = pypff.open("message.pst")

# Get root folder
root = pff_file.root_folder
if root:
    print(f"Root folder: {root.name}")
    
    # Iterate subfolders
    for subfolder in root.sub_folders:
        print(f"  - {subfolder.name}")
        for message in subfolder.sub_messages:
            print(f"    - {message.name}")

pff_file.close()
```

--------------------------------

### Update Library Cache

Source: https://github.com/libyal/libpff/wiki/Building

On Linux, run this command after installation to update the shared library cache, ensuring the system can find the newly installed libpff.so.

```bash
sudo ldconfig
```

--------------------------------

### Build libpff with Python Bindings

Source: https://github.com/libyal/libpff/blob/main/_autodocs/configuration.md

Example of configuring libpff to build Python extensions (pypff). This enables Python scripting capabilities.

```bash
./configure --enable-python-bindings --prefix=/usr/local
make
make install
```

--------------------------------

### Build Process with Python Bindings

Source: https://github.com/libyal/libpff/blob/main/_autodocs/README.md

Enable Python bindings during the configure step for Python integration. This requires Python development headers to be installed.

```bash
./configure --enable-python-bindings
make
sudo make install
```

--------------------------------

### Get Help Information for pypff Modules

Source: https://github.com/libyal/libpff/wiki/Python-development

Uses the built-in help() function to display documentation for various pypff modules and classes.

```python
import pypff

help(pypff)
help(pypff.file)
help(pypff.item)
help(pypff.folder)
help(pypff.message)
```

--------------------------------

### Iterate Over Items in Root Folder

Source: https://github.com/libyal/libpff/wiki/Python-development

Iterates through all items in the root folder. This example shows how to check if an item is a URL and print its location.

```python
pff_root_folder = pff_file.get_root_folder()
for pff_item in pff_root_folder.items:
    if isinstance(pff_item, pypff.url):
        print(pff_item.location)
```

--------------------------------

### GCC Compilation Error Example

Source: https://github.com/libyal/libpff/wiki/Troubleshooting

This error indicates a compilation failure. Examine the config.log file for lines containing ': error: ' to pinpoint the specific cause.

```text
error: command 'gcc' failed with exit status 1
```

```text
libclocale_locale.c:358:7: error: 'LOCALE_NAME_USER_DEFAULT' undeclared (first use in this function)
```

--------------------------------

### Get libpff file name-to-ID map

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-file.md

Retrieves the name-to-ID map item from the PFF file. This map is used to associate custom property names and GUIDs with MAPI property IDs.

```c
int libpff_file_get_name_to_id_map(
    libpff_file_t *file,
    libpff_item_t **name_to_id_map,
    libcerror_error_t **error );
```

--------------------------------

### Initialize, Open, and Iterate Folders in C

Source: https://github.com/libyal/libpff/blob/main/_autodocs/README.md

Demonstrates the basic workflow for initializing, opening, and iterating through subfolders of a PST file using libpff. Ensure libpff is correctly included and linked.

```c
#include <libpff.h>

int main() {
    libpff_file_t *file = NULL;
    libpff_error_t *error = NULL;
    
    // Initialize file
    libpff_file_initialize(&file, &error);
    
    // Open file
    libpff_file_open(file, "message.pst", LIBPFF_OPEN_READ, &error);
    
    // Get root folder
    libpff_item_t *root_folder = NULL;
    libpff_file_get_root_folder(file, &root_folder, &error);
    
    if (root_folder != NULL) {
        // Iterate subfolders
        int num_subfolders = 0;
        libpff_folder_get_number_of_sub_folders(root_folder, &num_subfolders, &error);
        
        for (int i = 0; i < num_subfolders; i++) {
            libpff_item_t *subfolder = NULL;
            libpff_folder_get_sub_folder(root_folder, i, &subfolder, &error);
            
            if (subfolder != NULL) {
                // Process subfolder
                libpff_item_free(&subfolder, &error);
            }
        }
        
        libpff_item_free(&root_folder, &error);
    }
    
    // Cleanup
    libpff_file_close(file, &error);
    libpff_file_free(&file, &error);
    
    return 0;
}

```

--------------------------------

### Configure and Make with MinGW

Source: https://github.com/libyal/libpff/wiki/Building

Standard build commands for MinGW when mingw32-configure and mingw32-make are available.

```bash
mingw32-configure --prefix=/opt/local/i386-mingw32 --enable-winapi=yes
mingw32-make
```

--------------------------------

### Get the format type of a libpff file

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-file.md

Returns the file format type: 32 (32-bit), 64 (64-bit), or 65 (64-bit 4k pages with compression).

```c
int libpff_file_get_type(
    libpff_file_t *file,
    uint8_t *type,
    libcerror_error_t **error );
```

--------------------------------

### Complete File Reading Example

Source: https://github.com/libyal/libpff/blob/main/_autodocs/common-patterns.md

This snippet shows how to initialize, open, read, and close a PFF file. It also demonstrates checking the file's content type and retrieving the root folder.

```c
#include <libpff.h>
#include <stdlib.h>
#include <stdio.h>

int main(int argc, char *argv[]) {
    if (argc < 2) {
        fprintf(stderr, "Usage: %s <filename>\n", argv[0]);
        return 1;
    }
    
    libpff_file_t *file = NULL;
    libpff_error_t *error = NULL;
    
    // Initialize
    if (libpff_file_initialize(&file, &error) != 1) {
        fprintf(stderr, "Failed to initialize file object\n");
        return 1;
    }
    
    // Open
    if (libpff_file_open(file, argv[1], LIBPFF_OPEN_READ, &error) != 1) {
        fprintf(stderr, "Failed to open: %s\n", argv[1]);
        libpff_file_free(&file, &error);
        return 1;
    }
    
    // Check file type
    uint8_t content_type = 0;
    libpff_file_get_content_type(file, &content_type, &error);
    
    const char *type_name = "";
    switch (content_type) {
        case LIBPFF_FILE_CONTENT_TYPE_PST: type_name = "PST"; break;
        case LIBPFF_FILE_CONTENT_TYPE_OST: type_name = "OST"; break;
        case LIBPFF_FILE_CONTENT_TYPE_PAB: type_name = "PAB"; break;
        default: type_name = "Unknown"; break;
    }
    
    printf("File Type: %s\n", type_name);
    
    // Get root folder
    libpff_item_t *root_folder = NULL;
    if (libpff_file_get_root_folder(file, &root_folder, &error) == 1) {
        printf("Found root folder\n");
        libpff_item_free(&root_folder, &error);
    }
    
    // Cleanup
    libpff_file_close(file, &error);
    libpff_file_free(&file, &error);
    
    return 0;
}

```

--------------------------------

### Building libpff with MSBuild

Source: https://github.com/libyal/libpff/wiki/Building

Use MSBuild via the command line to build the libpff solution. Ensure Visual Studio environment variables are set first.

```bash
C:\Program Files\Microsoft Visual Studio 9.0\VC\bin\vcvars32.bat
msbuild msvscpp\libpff.sln /p:Configuration=Release;Platform=Win32
```

--------------------------------

### Converting Visual Studio Solution Files

Source: https://github.com/libyal/libpff/wiki/Building

Convert Visual Studio 2008 solution files to 2010 format and add x64 settings using the msvscpp_convert script.

```bash
msvscpp_convert.py --extend-with-x64 --output-format 2010 msvscpp\libpff.sln
```

--------------------------------

### Get Attachment Filename by Index

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-attachment.md

Retrieves the filename of an attachment by its index. It uses the PR_ATTACH_FILENAME MAPI property (0x3704) to get the Unicode string filename.

```c
// Attachment items have a display name property
libpff_record_set_t *record_set = NULL;
int result = libpff_item_get_record_set_by_index(
    attachment, 0, &record_set, NULL);

if (result == 1) {
    libpff_record_entry_t *entry = NULL;
    result = libpff_record_set_get_entry_by_type(
        record_set,
        0x3704,  // PR_ATTACH_FILENAME
        LIBPFF_VALUE_TYPE_STRING_UNICODE,
        &entry,
        0,
        NULL);
    
    if (result == 1) {
        size_t filename_size = 0;
        libpff_record_entry_get_data_as_utf8_string_size(
            entry, &filename_size, NULL);
        
        uint8_t *filename = malloc(filename_size);
        libpff_record_entry_get_data_as_utf8_string(
            entry, filename, filename_size, NULL);
        
        printf("Attachment: %s\n", (char *)filename);
        
        free(filename);
        libpff_record_entry_free(&entry, NULL);
    }
    
    libpff_record_set_free(&record_set, NULL);
}
```

--------------------------------

### Allocate File Structure

Source: https://github.com/libyal/libpff/wiki/C-development

Demonstrates how to allocate and initialize a file structure using `libpff_file_initialize`. The function returns 1 on success and -1 on error. An optional error structure can be provided.

```APIDOC
## libpff_file_initialize

### Description
Allocates and initializes a file structure.

### Method
`libpff_error_t *libpff_file_initialize(libpff_file_t **file, libpff_error_t **error)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
libpff_error_t *error = NULL;
libpff_file_t *file = NULL;

if( libpff_file_initialize(&file, &error) != 1 )
{
    fprintf(stderr, "Unable to initialize file.\n");

    libpff_error_free(&error);

    exit(EXIT_FAILURE);
}
```

### Response
#### Success Response (1)
Returns 1 on success.

#### Response Example
1

#### Error Response (-1)
Returns -1 on error. An error structure is created unless `error` is NULL.

#### Error Handling
- The `error` argument is optional and can be NULL.
- The error structure must be freed by calling `libpff_error_free`.
```

--------------------------------

### Get Library Version

Source: https://github.com/libyal/libpff/blob/main/_autodocs/configuration.md

Retrieves the version of the LIBPFF library as a string in YYYYMMDD format.

```c
const char *libpff_get_version(void);
```

--------------------------------

### Configure and Make without MinGW tools

Source: https://github.com/libyal/libpff/wiki/Building

Alternative build commands for MinGW if mingw32-configure and mingw32-make are not directly accessible.

```bash
./configure --host=i386-mingw32 --prefix=/opt/local/i386-mingw32 --enable-winapi=yes
make
```

--------------------------------

### Get the content type of a libpff file

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-file.md

Returns the content type: LIBPFF_FILE_CONTENT_TYPE_PST ('p'), LIBPFF_FILE_CONTENT_TYPE_PAB ('a'), or LIBPFF_FILE_CONTENT_TYPE_OST ('o').

```c
int libpff_file_get_content_type(
    libpff_file_t *file,
    uint8_t *content_type,
    libcerror_error_t **error );
```

--------------------------------

### Extract Messages

Source: https://github.com/libyal/libpff/blob/main/_autodocs/INDEX.md

Provides an example of iterating through messages within a folder. This is fundamental for processing email content.

```c
struct pff_message *pff_message;
int number_of_messages;
int message_index;
int error;

error = libpff_folder_get_number_of_messages(pff_folder, &number_of_messages);
if (error != 0)
{
    fprintf(stderr, "Unable to get number of messages: %d\n", error);

    return 1;
}

for (message_index = 0; message_index < number_of_messages; ++message_index)
{
    error = libpff_folder_get_message(pff_folder, message_index, &pff_message);
    if (error != 0)
    {
        fprintf(stderr, "Unable to get message %d: %d\n", message_index, error);

        continue;
    }

    // Process message here

    libpff_message_free(pff_message);
}
```

--------------------------------

### Download and Prepare Git Repository Source

Source: https://github.com/libyal/libpff/wiki/Building

Downloads the libpff source code from the Git repository and prepares it for building using autotools.

```bash
git clone https://github.com/libyal/libpff.git
cd libpff/
./synclibs.sh
./autogen.sh
```

--------------------------------

### Build libpff from Source

Source: https://github.com/libyal/libpff/blob/main/_autodocs/configuration.md

Standard build instructions for libpff using the Autotools build system. Ensure dependencies are met before running.

```bash
./autogen.sh
./configure [options]
make
make install
```

--------------------------------

### Get the size of a libpff file

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-file.md

Returns the total file size in bytes. This is read from the file I/O handle.

```c
int libpff_file_get_size(
    libpff_file_t *file,
    size64_t *size,
    libcerror_error_t **error );
```

--------------------------------

### Copy License Files

Source: https://github.com/libyal/libpff/wiki/Building

Copies license and documentation files to the appropriate directory for packaging.

```bash
mkdir -p $PWD/tmp/usr/share/doc/libpff
cp AUTHORS COPYING COPYING.LESSER NEWS README $PWD/tmp/usr/share/doc/libpff
```

--------------------------------

### Get Item Identifier

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-item.md

Retrieves the unique identifier of an item. This identifier can be used to retrieve the item again using libpff_file_get_item_by_identifier().

```c
int libpff_item_get_identifier(
    libpff_item_t *item,
    uint32_t *identifier,
    libcerror_error_t **error );
```

--------------------------------

### Get pypff Version

Source: https://github.com/libyal/libpff/wiki/Python-development

Use the get_version() function to retrieve the version of the pypff library. This returns a Unicode string.

```python
pypff.get_version()
```

--------------------------------

### Get Number of Recovered Items

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-file.md

Retrieves the count of recovered items. This count reflects items found after a recovery process.

```c
int libpff_file_get_number_of_recovered_items(
    libpff_file_t *file,
    int *number_of_recovered_items,
    libcerror_error_t **error );
```

--------------------------------

### libpff_record_entry_get_name_to_id_map_entry

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-record-entry.md

Retrieves the name-to-ID map entry for custom properties (entry type > 0x8000), which contains the property name or GUID.

```APIDOC
## libpff_record_entry_get_name_to_id_map_entry

### Description
Retrieves the name-to-ID map entry for custom properties.

### Method
(Not specified, likely a C function call)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Parameters
- **record_entry** (libpff_record_entry_t *) - Yes - Record entry object
- **name_to_id_map_entry** (libpff_name_to_id_map_entry_t **) - Yes - Address to receive name-to-ID map entry
- **error** (libcerror_error_t **) - Yes - Error information pointer

### Returns
`int` — 1 on success, 0 if not a custom property, -1 on error.

### Description
For custom properties (entry type > 0x8000), returns the name-to-ID map entry that contains the property name or GUID.
```

--------------------------------

### Building Debian Packages

Source: https://github.com/libyal/libpff/wiki/Building

Build Debian packages for libpff after copying the dpkg directory and running dpkg-buildpackage.

```bash
cp -rf dpkg debian
dpkg-buildpackage -rfakeroot
```

--------------------------------

### Get Folder Type

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-folder.md

Retrieves the type or class of a folder item. This function is used to determine the nature of the folder's content.

```c
int libpff_folder_get_type(
    libpff_item_t *folder,
    uint8_t *type,
    libcerror_error_t **error );
```

--------------------------------

### Get Attachment Type

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-attachment.md

Retrieves the type of an attachment. Use this to determine if an attachment contains binary data, an embedded item, or a reference.

```c
int libpff_attachment_get_type(
    libpff_item_t *attachment,
    int *attachment_type,
    libcerror_error_t **error );
```

--------------------------------

### Get Number of Items

Source: https://github.com/libyal/libpff/wiki/Python-development

Retrieves the number of items within a folder. This can be done using either the get_number_of_items() function or the number_of_items property.

```python
number_of_items = pff_root_folder.get_number_of_items()
```

```python
number_of_items = pff_root_folder.number_of_items
```

--------------------------------

### Custom Build Script for MinGW

Source: https://github.com/libyal/libpff/wiki/Building

A shell script to manually set up compiler and linker paths and then configure and build libpff with MinGW.

```bash
#!/bin/sh
CC=/opt/local/bin/i386-mingw32-gcc
CXX=/opt/local/bin/i386-mingw32-g++
AR=/opt/local/bin/i386-mingw32-ar
OBJDUMP=/opt/local/bin/i386-mingw32-objdump
RANLIB=/opt/local/bin/i386-mingw32-ranlib
STRIP=/opt/local/bin/i386-mingw32-strip
MINGWFLAGS="-mwin32 -mconsole -march=i586 "
CFLAGS="$MINGWFLAGS"
CXXFLAGS="$MINGWFLAGS"

CC=$CC CXX=$CXX AR=$AR OBJDUMP=$OBJDUMP RANLIB=$RANLIB STRIP=$STRIP ./configure --host=i586-mingw32msvc --prefix=/opt/local/i386-mingw32 --enable-winapi=yes
CC=$CC CXX=$CXX AR=$AR OBJDUMP=$OBJDUMP RANLIB=$RANLIB STRIP=$STRIP CFLAGS="$CFLAGS" CXXFLAGS="$CXXFLAGS" make
```

--------------------------------

### libpff_file_initialize

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-file.md

Initializes a new file object. Allocates and initializes a new file object. The returned pointer must be freed with `libpff_file_free()`.

```APIDOC
## libpff_file_initialize

### Description
Initializes a new file object.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Returns
`int` — 1 on success, -1 on error.

### Description
Allocates and initializes a new file object. The returned pointer must be freed with `libpff_file_free()`.

### Source
`libpff/libpff_file.h:123-126`
```

--------------------------------

### libpff_file_get_root_item

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-file.md

Retrieves the root item of the PFF file hierarchy. This item serves as the starting point for navigating the file's structure.

```APIDOC
## libpff_file_get_root_item

### Description
Retrieves the root item.

### Method
C Function

### Parameters
#### Path Parameters
- **file** (libpff_file_t *) - Yes - File object
- **root_item** (libpff_item_t **) - Yes - Address to receive root item
- **error** (libcerror_error_t **) - Yes - Error information pointer

### Returns:
`int` — 1 on success, 0 if not available, -1 on error.

### Description:
Returns the root item from which all other items in the file hierarchy descend. The returned item must be freed with `libpff_item_free()`.
```

--------------------------------

### Navigate Folders

Source: https://github.com/libyal/libpff/blob/main/_autodocs/INDEX.md

Shows how to navigate through the folder hierarchy of a PST file. This is useful for accessing specific message collections.

```c
struct pff_folder *pff_folder;
struct pff_folder *pff_sub_folder;
int number_of_sub_folders;
int sub_folder_index;
int error;

error = libpff_file_get_root_folder(pff_file, &pff_folder);
if (error != 0)
{
    fprintf(stderr, "Unable to get root folder: %d\n", error);

    return 1;
}

error = libpff_folder_get_number_of_sub_folders(pff_folder, &number_of_sub_folders);
if (error != 0)
{
    fprintf(stderr, "Unable to get number of sub folders: %d\n", error);

    return 1;
}

for (sub_folder_index = 0; sub_folder_index < number_of_sub_folders; ++sub_folder_index)
{
    error = libpff_folder_get_sub_folder(pff_folder, sub_folder_index, &pff_sub_folder);
    if (error != 0)
    {
        fprintf(stderr, "Unable to get sub folder %d: %d\n", sub_folder_index, error);

        continue;
    }

    // Process sub_folder here

    libpff_folder_free(pff_sub_folder);
}
```

--------------------------------

### Build Python Wheel

Source: https://github.com/libyal/libpff/wiki/Building

Creates a Python wheel package for libpff in the 'dist' subdirectory.

```bash
python -m build --outdir=dist --wheel
```

--------------------------------

### Basic pypff File Operations (Python)

Source: https://github.com/libyal/libpff/blob/main/_autodocs/common-patterns.md

This Python snippet shows how to open a PST file using pypff, retrieve basic metadata like version, size, and content type, and access the root folder. Ensure the 'pypff' library is installed.

```python
import pypff

# Open file
pff = pypff.open("message.pst")

# Check version
print(f"Library version: {pypff.get_version()}")

# Get metadata
print(f"Size: {pff.size} bytes")
print(f"Content type: {pff.content_type}")
print(f"Encryption: {pff.encryption_type}")

# Get root folder
root = pff.root_folder
if root:
    print(f"Root folder has {len(root.sub_folders)} subfolders")

pff.close()
```

--------------------------------

### Example: Handling libpff File Open Errors

Source: https://github.com/libyal/libpff/blob/main/_autodocs/errors.md

Demonstrates how to check the result of a file open operation and potentially inspect the error type using libcerror API. This is useful for diagnosing specific input issues like signature mismatches.

```c
libpff_error_t *error = NULL;
int result = libpff_file_open(file, "file.pst", LIBPFF_OPEN_READ, &error);
if (result == -1) {
    // Check if it's a signature mismatch
    // via libcerror API
}
```

--------------------------------

### Get Unallocated Block Information

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-file.md

Retrieve the file offset and size of an unallocated block by its index and type. Returns 0 if the index is out of range.

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

--------------------------------

### Build libpff with Microsoft Visual Studio on Windows

Source: https://github.com/libyal/libpff/wiki/Building

Clones the libpff repository and runs PowerShell scripts to synchronize dependencies and generate build files for use with Microsoft Visual Studio.

```powershell
git clone https://github.com/libyal/libpff.git
cd libpff\
.\synclibs.ps1
.\synczlib.ps1
.\autogen.ps1
```

--------------------------------

### Get Recovered Item by Index

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-file.md

Retrieves a recovered item from the PFF file by its zero-based index. The index must be between 0 and `number_of_recovered_items - 1`.

```c
int libpff_file_get_recovered_item_by_index(
    libpff_file_t *file,
    int recovered_item_index,
    libpff_item_t **recovered_item,
    libcerror_error_t **error );
```

--------------------------------

### Recovering from File Corruption

Source: https://github.com/libyal/libpff/blob/main/_autodocs/errors.md

Shows how to attempt recovery of file items using `libpff_file_recover_items` if an initial file open operation fails. This is useful for corrupted files.

```c
int result = libpff_file_open(file, "file.pst", LIBPFF_OPEN_READ, &error);
if (result == -1) {
    // Try recovery
    libpff_file_recover_items(file, 
        LIBPFF_RECOVERY_FLAG_IGNORE_ALLOCATION_DATA | 
        LIBPFF_RECOVERY_FLAG_SCAN_FOR_FRAGMENTS, 
        NULL);
}
```

--------------------------------

### Get Item by Identifier

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-file.md

Retrieves a specific item from the PFF file using its unique identifier. This function looks up items in the descriptors table.

```c
int libpff_file_get_item_by_identifier(
    libpff_file_t *file,
    uint32_t item_identifier,
    libpff_item_t **item,
    libcerror_error_t **error );
```

--------------------------------

### Get All Sub-Messages Container

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-folder.md

Obtains a special container item of type `LIBPFF_ITEM_TYPE_SUB_MESSAGES` that holds all messages within a folder. This can be useful for iterating through all messages.

```c
int libpff_folder_get_sub_messages(
    libpff_item_t *item,
    libpff_item_t **sub_messages,
    libcerror_error_t **error );
```

--------------------------------

### Checking Return Values for libpff Functions

Source: https://github.com/libyal/libpff/blob/main/_autodocs/errors.md

Demonstrates how to check the return value of libpff functions, distinguishing between success, item not found (0), and error (-1). Always handle these cases explicitly.

```c
int result = libpff_folder_get_sub_folder(folder, 0, &subfolder, &error);
if (result == -1) {
    // Error occurred
} else if (result == 0) {
    // Item not found (not an error)
} else {
    // Success (result == 1)
}
```

--------------------------------

### Create macOS Disk Image

Source: https://github.com/libyal/libpff/wiki/Building

Creates a distributable disk image (.dmg) containing the libpff macOS package.

```bash
hdiutil create ../libpff-<version>.dmg -srcfolder ../libpff-<version>.pkg -fs HFS+
```

--------------------------------

### Get Embedded Item from Attachment

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-attachment.md

Retrieves an embedded item from an attachment of type LIBPFF_ATTACHMENT_TYPE_ITEM. The retrieved item must be freed using libpff_item_free().

```c
int libpff_attachment_get_item(
    libpff_item_t *attachment,
    libpff_item_t **attached_item,
    libcerror_error_t **error );
```

--------------------------------

### Open a PFF/OFF File Using a File I/O Handle

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-file.md

Opens a file using a libbfio file I/O handle. Allows use of custom I/O implementations (memory buffers, network streams, etc.).

```c
int libpff_file_open_file_io_handle(
    libpff_file_t *file,
    libbfio_handle_t *file_io_handle,
    int access_flags,
    libcerror_error_t **error );
```

--------------------------------

### Get Attachment Data Size

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-attachment.md

Retrieves the total size of attachment data in bytes. This is useful for pre-allocating buffers or understanding the scope of data.

```c
int libpff_attachment_get_data_size(
    libpff_item_t *attachment,
    size64_t *size,
    libcerror_error_t **error );
```

--------------------------------

### Get Item Type

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-item.md

Retrieves the type of an item. The type is an enumeration value from LIBPFF_ITEM_TYPES, indicating if it's a folder, email, contact, etc.

```c
int libpff_item_get_type(
    libpff_item_t *item,
    uint8_t *item_type,
    libcerror_error_t **error );
```

--------------------------------

### Get Root Folder Item

Source: https://github.com/libyal/libpff/wiki/Python-development

Retrieves the root folder of the PFF file. This can be done using either the get_root_folder() function or the root_folder property.

```python
pff_root_folder = pff_file.get_root_folder()
```

```python
pff_root_folder = pff_file.root_folder
```

--------------------------------

### libpff_file_get_name_to_id_map

Source: https://github.com/libyal/libpff/blob/main/_autodocs/api-file.md

Retrieves the name-to-ID map item from the PFF file, used for mapping custom property names and GUIDs to MAPI property IDs.

```APIDOC
## libpff_file_get_name_to_id_map

### Description
Retrieves the name-to-ID map item.

### Method
C Function

### Parameters
#### Path Parameters
- **file** (libpff_file_t *) - Yes - File object
- **name_to_id_map** (libpff_item_t **) - Yes - Address to receive name-to-ID map item
- **error** (libcerror_error_t **) - Yes - Error information pointer

### Returns:
`int` — 1 on success, 0 if not available, -1 on error.

### Description:
Returns the name-to-ID map item, which maps custom property names/GUIDs to MAPI property IDs.
```