Add Python bindings

[joachimmetz]

Complete work on Python bindings

• complete multi value
• add name to id map entry object
• add message store object
• add task object support
• add recipients object support
  • Placeholder object added in c8faa63
• add tests

[kevthehermit]

I appreciate this is still WIP.
Im writing a native PST Parser for a DFIR Platform. I have most of the library working the way i need it to.
See Gist here - https://gist.github.com/kevthehermit/40ff03e3adc524ece04f735e68be43c2

With the exception of Extracting attachments.
I see this partially exists -

libpff/pypff/pypff_message.c

Line 159 in 3aefe76

/* TODO create attachment item

Any timeline on this feature and anything i can do to help?

Just trying to avoid OS calls.

Appreciate all the work you have done.

[kujenga]

I'm also curious about support for attachments. I'd be happy to take a look at implementing support for it and opening a PR if you could give me some pointers as to what needs to be done @joachimmetz

[joachimmetz]

Sorry for the slower response, quite busy at the moment. What needs to be done is adding attachment support to the Python bindings. Which is largely a wrapper around the API. Unless you're very familiar with writing Python bindings, it is likely faster for me to implement it than explain it. But if you want you have a look at the current code.

[kujenga]

No worries, and fair enough! I don't have any prior experience with writing Python bindings unfortunately. Do you have a sense of when you may have the time to tackle this?

I see this commented out code:

libpff/pypff/pypff_message.h

Lines 105 to 118 in 3222929

	/* TODO create attachment item
	PyObject *pypff_message_get_attachment_by_index(
	pypff_item_t *pypff_item,
	int attachment_index );
	PyObject *pypff_message_get_attachment(
	pypff_item_t *pypff_item,
	PyObject *arguments,
	PyObject *keywords );
	PyObject *pypff_message_get_attachments(
	pypff_item_t *pypff_item,
	PyObject *arguments );
	*/

And at first glance what look like the necessary implementations here:

libpff/pypff/pypff_message.c

Lines 2089 to 2274 in 3222929

	/* Retrieves a specific attachment by index
	* Returns a Python object if successful or NULL on error
	*/
	PyObject *pypff_message_get_attachment_by_index(
	pypff_item_t *pypff_item,
	int attachment_index )
	{
	libcerror_error_t *error = NULL;
	libpff_item_t *sub_item = NULL;
	PyObject *sub_item_object = NULL;
	static char *function = "pypff_message_get_attachment_by_index";
	uint8_t sub_item_type = 0;
	int result = 0;
	if( pypff_item == NULL )
	{
	PyErr_Format(
	PyExc_TypeError,
	"%s: invalid item.",
	function );
	return( NULL );
	}
	Py_BEGIN_ALLOW_THREADS
	result = libpff_message_get_attachment(
	pypff_item->item,
	attachment_index,
	&sub_item,
	&error );
	Py_END_ALLOW_THREADS
	if( result != 1 )
	{
	pypff_error_raise(
	error,
	PyExc_IOError,
	"%s: unable to retrieve attachment: %d.",
	function,
	attachment_index );
	libcerror_error_free(
	&error );
	goto on_error;
	}
	Py_BEGIN_ALLOW_THREADS
	result = libpff_item_get_type(
	sub_item,
	&sub_item_type,
	&error );
	Py_END_ALLOW_THREADS
	if( result != 1 )
	{
	pypff_error_raise(
	error,
	PyExc_IOError,
	"%s: unable to retrieve attachment: %d type.",
	function,
	attachment_index );
	libcerror_error_free(
	&error );
	goto on_error;
	}
	sub_item_object = pypff_item_new(
	&pypff_message_type_object,
	sub_item,
	pypff_item->file_object );
	if( sub_item_object == NULL )
	{
	PyErr_Format(
	PyExc_MemoryError,
	"%s: unable to create attachment object.",
	function );
	goto on_error;
	}
	return( sub_item_object );
	on_error:
	if( sub_item != NULL )
	{
	libpff_item_free(
	&sub_item,
	NULL );
	}
	return( NULL );
	}
	/* Retrieves a specific attachment
	* Returns a Python object if successful or NULL on error
	*/
	PyObject *pypff_message_get_attachment(
	pypff_item_t *pypff_item,
	PyObject *arguments,
	PyObject *keywords )
	{
	PyObject *sub_item_object = NULL;
	static char *keyword_list[] = { "attachment_index", NULL };
	int attachment_index = 0;
	if( PyArg_ParseTupleAndKeywords(
	arguments,
	keywords,
	"i",
	keyword_list,
	&attachment_index ) == 0 )
	{
	return( NULL );
	}
	sub_item_object = pypff_message_get_attachment_by_index(
	pypff_item,
	attachment_index );
	return( sub_item_object );
	}
	/* Retrieves an items sequence and iterator object for the attachments
	* Returns a Python object if successful or NULL on error
	*/
	PyObject *pypff_message_get_attachments(
	pypff_item_t *pypff_item,
	PyObject *arguments PYPFF_ATTRIBUTE_UNUSED )
	{
	libcerror_error_t *error = NULL;
	PyObject *sub_items_object = NULL;
	static char *function = "pypff_message_get_attachments";
	int number_of_attachments = 0;
	int result = 0;
	PYPFF_UNREFERENCED_PARAMETER( arguments )
	if( pypff_item == NULL )
	{
	PyErr_Format(
	PyExc_TypeError,
	"%s: invalid item.",
	function );
	return( NULL );
	}
	Py_BEGIN_ALLOW_THREADS
	result = libpff_message_get_number_of_attachments(
	pypff_item->item,
	&number_of_attachments,
	&error );
	Py_END_ALLOW_THREADS
	if( result != 1 )
	{
	pypff_error_raise(
	error,
	PyExc_IOError,
	"%s: unable to retrieve number of attachments.",
	function );
	libcerror_error_free(
	&error );
	return( NULL );
	}
	sub_items_object = pypff_items_new(
	pypff_item,
	&pypff_message_get_attachment_by_index,
	number_of_attachments );
	if( sub_items_object == NULL )
	{
	PyErr_Format(
	PyExc_MemoryError,
	"%s: unable to create sub items object.",
	function );
	return( NULL );
	}
	return( sub_items_object );
	}

Is there much left to do beyond uncommenting the headers and other definitions?

[0x6e69636f]

I'm also interested in this binding, but have no experience writing this kind of things
Should I write a program in C instead or is the C lib dedicated to be used with Python ?