Development

C/C++ development

The following examples require the following headers to be included:

#include <stdlib.h>
#include <stdio.h>

#include <libesedb.h>

Most of the functions return 1 if successful or -1 on error. The close function is an exception since it returns 0 if successful or -1 on error. More details about the return values can be found in libesedb.h

Allocate file structure

libesedb_error_t *error = NULL;
libesedb_file_t *file   = NULL;

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

    libesedb_error_free(&error);

    exit(EXIT_FAILURE);
}

When calling the libesedb_file_initialize function the file argument must refer to NULL to allocate and initialize a file structure. The error argument is optional and can be NULL.

The function will return 1 if successful or -1 on error. On error an the library creates an error structure except if error is NULL e.g.

libesedb_file_initialize(&file, NULL)

The error structure must be freed by calling the libesedb_error_free function.

Free file structure

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

    libesedb_error_free(&error);

    exit(EXIT_FAILURE);
}

The function will return 1 if successful or -1 on error. File is set to NULL. The function will also close the file if it was opened.

Open file

filename = "Windows.edb";

if( libesedb_file_open(file, filename, LIBESEDB_OPEN_READ, &error) != 1 )
{
    fprintf(stderr, "Unable to open file.\n" );

    libesedb_file_free(&file, NULL);
    libesedb_error_free(&error);

    exit(EXIT_FAILURE);
}

Libesedb provides both narrow and wide character string functions for filenames. The wide character equivalent of the open function is libesedb_file_open_wide. By default libesedb will only enable wide character string support on Windows since other operating systems have build-in support for UTF-8 narrow character strings.

To compile with wide character support add --enable-wide-character-type=yes to configure, e.g.:

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

Or on Windows define WINAPI and either _UNICODE or UNICODE

When wide character string support is enabled LIBESEDB_HAVE_WIDE_CHARACTER_TYPE is defined in <libesedb/features.h>

Open file-like object

TODO describe

libesedb allows to be compiled with file-like object support using libbfio. The libesedb configure script will automatically detect if a compatible version of libbfio is available.

When libbfio is support is enabled LIBESEDB_HAVE_BFIO is defined in <libesedb/features.h>

Close file

if( libesedb_file_close(file, &error) != 0 )
{
    fprintf(stderr, "Unable to close file.\n" );

    libesedb_file_free(&file, NULL);
    libesedb_error_free(&error);

    exit(EXIT_FAILURE);
}

Retrieving the number of tables

After opening the file the number of tables can be retrieved using the function:

int number_of_tables = 0;

if( libesedb_file_get_number_of_tables(file, &number_of_files, &error) != 1 )
{
    fprintf(stderr, "Unable to retrieve number of tables.\n" );

    libesedb_error_free(&error);
}

Retrieving a table

To retrieve a specific table, e.g. the first table (index 0):

libesedb_table_t *table = NULL;

if( libesedb_file_get_table(file, 0, &table, &error) != 1 )
{
    fprintf(stderr, "Unable to retrieve table: 0.\n" );

    libesedb_error_free(&error);
}

The table structure must be freed by calling the libesedb_table_free function.

A table can also be retrieved by name using either libesedb_file_get_table_by_utf8_name or libesedb_file_get_table_by_utf16_name. Note that the library will return the first table that matches the name.

Retrieving a column

TODO describe

libesedb_column_t *column = NULL;

if( libesedb_table_get_column(table, 0, &column, &error) != 1 )
{
    fprintf(stderr, "Unable to retrieve column: 0.\n" );

    libesedb_error_free(&error);
}

The column structure must be freed by calling the libesedb_column_free function.

Retrieving a record

TODO describe

libesedb_record_t *record = NULL;

if( libesedb_table_get_record(table, 0, &record, &error) != 1 )
{
    fprintf(stderr, "Unable to retrieve record: 0.\n" );

    libesedb_error_free(&error);
}

The record structure must be freed by calling the libesedb_record_free function.

Retrieving a record value

TODO describe

uint32_t column_type = 0;

if( libesedb_record_get_column_type(record, 0, &column_type, &error) != 1 )
{
    fprintf(stderr, "Unable to retrieve record: 0 column type.\n" );

    libesedb_error_free(&error);
}

Based on the column type one of the record get value functions can be called e.g. for column type LIBESEDB_COLUMN_TYPE_TEXT either the libesedb_record_get_value_utf8_string or libesedb_record_get_value_utf16_string function can be used.

uint8_t *string = NULL;
size_t string_size = 0;

if( libesedb_record_get_value_utf8_string_size(record, 0, &string_size, &error) != 1 )
{
    fprintf(stderr, "Unable to retrieve record: 0 string size.\n" );

    libesedb_error_free(&error);
}

/* Allocate the string */

if( libesedb_record_get_value_utf8_string(record, 0, string, string_size, &error) != 1 )
{
    fprintf(stderr, "Unable to retrieve record: 0 string.\n" );

    libesedb_error_free(&error);
}

Retrieving an index

TODO describe

libesedb_index_t *index = NULL;

if( libesedb_table_get_index(table, 0, &index, &error) != 1 )
{
    fprintf(stderr, "Unable to retrieve index: 0.\n" );

    libesedb_error_free(&error);
}

The index structure must be freed by calling the libesedb_index_free function.

Also see

• libesedb.h
• man 3 libesedb

Python development

Get version

import pyesedb

pyesedb.get_version()

Open file

import pyesedb

esedb_file = pyesedb.file()

esedb_file.open("Windows.edb")

esedb_file.close()

Note that the explicit call to close is not required.

Open file using a file-like object

import pyesedb

file_object = open("Windows.edb", "rb")

esedb_file = pyesedb.file()

esedb_file.open_file_object(file_object)

esedb_file.close()

Note that the explicit call to close is not required.

Also see

import pyesedb

help(pyesedb)
help(pyesedb.file)