add preliminary support for passing data by fd

Passing data out-of-band using data paths has a couple of issues (different
user, chroot, ownership / deletion, in-place modification by callers, etc.)
that passing data via file descriptors can avoid. Recent versions of D-Bus and
python-dbus have support for fd passing, so we can add alternative versions of
the functions that take a data path and have the alternatives take a file
descriptor instead.

Support for this is still suboptimal as we make a copy and pass a path
internally. We can easily improve on that later as it's just a matter of
performance, not functionality.

We may even consider dropping the non-fd counterparts. However, since D-Bus
still does not support a "maybe" type, we'll need alternative versions of these
calls that don't take a file descriptor, for use with metadata-only entries. We
could also pass a reference to /dev/null, but that's more a hack than a
solution.

1 files changed, 22 insertions, 0 deletions

diff --git a/tests/native_api_v1.txt b/tests/native_api_v1.txt
index 5df64d8..4eee755 100644
--- a/tests/native_api_v1.txt
+++ b/tests/native_api_v1.txt
@@ -119,11 +119,24 @@ Create an entry with content:
 >>> dog_oid = ds.create(dog_props, dog_file_name)
 
 
+You can also pass the data as a file descriptor, useful for streaming:
+>>> dog2_file = tempfile.TemporaryFile()
+>>> dog2_file.write(dog_content)
+>>> dog2_file.flush()
+>>> dog2_file.seek(0)
+>>> dog2_oid = ds.create_fd({'title': 'DS test object 4', 'mime_type': 'text/plain', 'activity': 'org.sugarlabs.DataStoreTest1'}, dog2_file.fileno())
+>>> dog2_file.close()
+
+
 Retrieve and verify the entry with content:
 >>> dog_retrieved = ds.get_data_path(*dog_oid)
 >>> assert(file(dog_retrieved).read() == dog_content)
 >>> os.remove(dog_retrieved)
 
+The same using file descriptor passing:
+>>> dog2_retrieved_file = os.fdopen(ds.get_data_fd(*dog2_oid).take(), 'r')
+>>> assert(dog2_retrieved_file.read() == dog_content)
+
 
 Update the entry content (creates a new version):
 >>> dog_content_2 = 'The quick brown fox jumped over the lazy dog.'
@@ -131,6 +144,15 @@ Update the entry content (creates a new version):
 >>> dog_updated_version_id = ds.add_version(dog_oid[0], dog_oid[1], dog_props, dog_file_name)
 
 
+Update the entry content by passing a file descriptor:
+>>> dog_content_2 = 'The quick brown fox jumped over the lazy dog.'
+>>> dog2_file = tempfile.TemporaryFile()
+>>> dog2_file.write(dog_content)
+>>> dog2_file.flush()
+>>> dog2_file.seek(0)
+>>> dog2_updated_version_id = ds.add_version_fd(dog_oid[0], dog_oid[1], dog_props, dog2_file.fileno())
+
+
 Verify updated content:
 >>> dog_retrieved = ds.get_data_path(dog_oid[0], dog_updated_version_id)
 >>> assert(file(dog_retrieved).read() == dog_content_2)