[libgda/LIBGDA_4.0] GdaBlop corrections

[Vivien Malerba <vivien src gnome org>]

commit 45bf997e3bff2f0f789cd29dcbf88f32a35a75bc
Author: Vivien Malerba <malerba gnome-db org>
Date:   Fri Oct 9 21:09:45 2009 +0200

    GdaBlop corrections
    
    and documentation improvements regarding blobs

 doc/C/tmpl/gda-blob-op.sgml |   53 ++++++++++++++++++++++++++++++++++++++----
 libgda/dir-blob-op.c        |    5 +--
 libgda/gda-blob-op.c        |   13 ++++++++--
 libgda/gda-value.h          |   12 ++++++++-
 4 files changed, 70 insertions(+), 13 deletions(-)
---
diff --git a/doc/C/tmpl/gda-blob-op.sgml b/doc/C/tmpl/gda-blob-op.sgml
index 7afd35b..855a384 100644
--- a/doc/C/tmpl/gda-blob-op.sgml
+++ b/doc/C/tmpl/gda-blob-op.sgml
@@ -24,14 +24,57 @@ and <link linkend="GdaBlob">GdaBlob</link>:
 </para>
 
 <para>
-  Note that a <link linkend="GdaBlob">GdaBlob</link> value will often not contain any data (or only some part of the actual BLOB)
-  and that it's up to the user to use the associated <link linkend="GdaBlobOp">GdaBlobOp</link> object to "load" the data into
-  the container (into the actual process heap).
+  Note that a <link linkend="GdaBlob">GdaBlob</link> value (the "data" attribute) will often not contain any data
+  (or only some part of the actual BLOB)
+  and that it's up to the user to use the associated <link linkend="GdaBlobOp">GdaBlobOp</link> object to
+  "load" the data into the container (into the actual process heap).
 </para>
 
 <para>
-  See the <link linkend="libgda-provider-blobop">Virtual methods for Blob operations</link> section for more information
-  about how to implement the virtual methods when creating a database provider.
+  For example to load the 1st 40 bytes of a blob:
+  <programlisting>
+GValue *blob_value = ...
+GdaBlob *blob;
+
+blob = (GdaBlob*) gda_value_get_blob (blob_value);
+gda_blob_op_read (blob->op, blob, 0, 40);
+  </programlisting>
+</para>
+
+<para>
+  Another example is to write the contents of a blob to a file on disk, using a special
+  <link linkend="GdaBlobOp">GdaBlobOp</link> object (internal to &LIBGDA; which interfaces
+  with a file in a filesystem):
+  <programlisting>
+GValue *blob_value; /* value to copy from */
+GValue *tmp_value;
+GdaBlob *file_blob;
+
+GValue *blob_value = ...
+tmp_value = gda_value_new_blob_from_file ("MyFile.bin");
+file_blob = (GdaBlob*) gda_value_get_blob (tmp_value);
+
+if (! gda_blob_op_write_all (file_blob->op, gda_value_get_blob (blob_value))) {
+       /* error */
+}
+else {
+       gsize size;
+       size = gda_blob_op_get_length (file_blob->op);
+       g_print ("Wrote %s, size = %d\n", filename, size);
+}
+gda_value_free (tmp_value);
+  </programlisting>
+</para>
+
+<para>
+  For further information, see:
+  <itemizedlist>
+    <listitem><para>the section about <link linkend="gen:blobs">Binary large objects (BLOBs)</link>'s
+	abstraction</para></listitem>
+    <listitem><para><link linkend="libgda-provider-blobop">Virtual methods for Blob operations</link>
+	section for more information
+	about how to implement the virtual methods when creating a database provider</para></listitem>
+  </itemizedlist>
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
diff --git a/libgda/dir-blob-op.c b/libgda/dir-blob-op.c
index b4ea849..f7815d3 100644
--- a/libgda/dir-blob-op.c
+++ b/libgda/dir-blob-op.c
@@ -242,11 +242,10 @@ gda_dir_blob_op_write (GdaBlobOp *op, GdaBlob *blob, glong offset)
 
 	if (blob->op && (blob->op != op)) {
 		/* use data through blob->op */
-		//#define buf_size 262144
-                #define buf_size 16000
+                #define buf_size 16384
 		gint nread = 0;
 		GdaBlob *tmpblob = g_new0 (GdaBlob, 1);
-		tmpblob->op = blob->op;
+		gda_blob_set_op (tmpblob, blob->op);
 
 		nbwritten = 0;
 
diff --git a/libgda/gda-blob-op.c b/libgda/gda-blob-op.c
index 1e133c1..7aeac97 100644
--- a/libgda/gda-blob-op.c
+++ b/libgda/gda-blob-op.c
@@ -159,7 +159,11 @@ gda_blob_op_read_all (GdaBlobOp *op, GdaBlob *blob)
  * @blob: a #GdaBlob which contains the data to write
  * @offset: offset to write from the start of the blob (starts at 0)
  *
- * Writes a chunk of bytes from a @blob to the BLOB accessible through @op.
+ * Writes a chunk of bytes from a @blob to the BLOB accessible through @op, @blob is unchanged after
+ * this call.
+ *
+ * If @blob has an associated #GdaBlobOp (ie. if @blob->op is not %NULL) then the data to be written
+ * using @op is the data fetched using @blob->op.
  *
  * Returns: the number of bytes written. In case of error, -1 is returned and the
  * provider should have added an error to the connection.
@@ -192,6 +196,9 @@ gda_blob_op_write_all (GdaBlobOp *op, GdaBlob *blob)
 
 	if (CLASS (op)->write_all != NULL)
 		return CLASS (op)->write_all (op, blob);
-	else
-		return gda_blob_op_write (op, blob, 0);
+	else {
+		glong res;
+		res = gda_blob_op_write (op, blob, 0);
+		return res >= 0 ? TRUE : FALSE;
+	}
 }
diff --git a/libgda/gda-value.h b/libgda/gda-value.h
index 7a3854b..64b7f1d 100644
--- a/libgda/gda-value.h
+++ b/libgda/gda-value.h
@@ -96,10 +96,18 @@ typedef struct {
 	glong   binary_length;
 } GdaBinary;
 
+/**
+ * GdaBlob
+ * @data: data buffer, as a #GdaBinary
+ * @op: a pointer to a #GdaBlopOp, or %NULL
+ *
+ * Represents some binary data, accessed through a #GdaBlobOp object.
+ * @op is generally set up by database providers when giving access to an existing BLOB in
+ * a database, but can be modified if needed using gda_blob_set_op().
+ */
 typedef struct {
 	GdaBinary  data;
-	GdaBlobOp *op; /* set up by providers if the GdaBlob is linked to something actually existing in the database, 
-			  useable by anyone */
+	GdaBlobOp *op;
 } GdaBlob;
 
 typedef GList GdaValueList;