programming.txt

Getting started with programming libewf:

Define a handle object and make sure to set it to NULL, like:
libewf_handle_t *handle = NULL;

Initialize the handle:
libewf_error_t *error = NULL;

if( libewf_handle_initialize(
     &handle,
     &error ) != 1 )
{
	<error>
}

The &error argument can also be NULL. Libewf created an error object on error (return value -1).
The information in the error object can be accessed with the corresponding 'libewf_error_' functions.
After use 'free' the error object using 'libewf_error_free'.

After initializing the handle object it can be used to open a set of EWF files.
E.g. to open a set of EWF files for reading.

if( libewf_handle_open(
     handle,
     filename,
     number_of_filenames,
     LIBEWF_OPEN_READ,
     error ) != 1 )
{
	<error>
}

You'll need to pass all the filenames part of the set.
If you only have the first filename of the set use the 'libewf_glob' function to determine the
others.

After the handle object has been opened the storage media data can be read from the EWF files
using 'libewf_handle_read_buffer' or 'libewf_handle_read_random'.

If done reading or writing close the handle object.

if( libewf_handle_close(
     handle,
     &error ) != 0 )
{
	<error>
}

Note that the return value corresponds to that of the 'close' function.

After use 'free' the handle object using:

if( libewf_handle_free(
     &handle,
     &error ) != 1 )
{
	<error>
}


Multi-threading and low-level IO:

Libewf is not tread-safe but offers several functions to perform 'low-level IO'.
These are:
* libewf_handle_prepare_read_chunk
* libewf_handle_read_chunk
* libewf_handle_prepare_write_chunk
* libewf_handle_write_chunk

The 'libewf_handle_read_chunk' function read a chunk of data as stored in the EWF files,
The 'libewf_handle_prepare_read_chunk' prepares the chunk of data for processing, i.e. if
the chunk is compressed the function will decompress the data.

The prepare functions can be used by multiple threads.