## Blobs

Blobs — Binary data and BLOBs handling

## Stability Level

Stable, unless otherwise indicated

## Functions

glong | gda_blob_op_get_length ()
glong | gda_blob_op_read ()
gboolean | gda_blob_op_read_all ()
glong | gda_blob_op_write ()
gboolean | gda_blob_op_write_all ()

## Types and Values

| GdaBlobOp

## Object Hierarchy

        GObject
        ╰── GdaBlobOp

## Includes

    #include <libgda/gda-blob-op.h>

## Description

This object is a base class for individual database providers which support BLOB types. It supports operations to read and write data in a BLOB value (of type GDA_BLOB_TYPE).

Libgda offers two methods to manipulate binary values as two containers: GdaBinary and GdaBlob:

- When reading from a data model returned by Libgda binary data will often be in a GdaBlob object, and the associated GdaBlobOp object can be used to manipulate the binary object (in a database for example)

- When the binary value is created by the user, then there is no point in using a GdaBlob as there can not be any GdaBlobOp object, so the GdaBinary container is enough.

Note that a GdaBlob 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 GdaBlobOp object to "load" the data into the container (into the actual process heap).

For example to load the 1st 40 bytes of a blob:

    GValue *blob_value = ...
    GdaBlob *blob;

    blob = (GdaBlob*) gda_value_get_blob (blob_value);
    gda_blob_op_read (blob->op, blob, 0, 40);

Another example is to write the contents of a blob to a file on disk, using a special

GdaBlobOp object (internal to Libgda which interfaces

with a file in a filesystem):

    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);

For further information, see:

- the section about Binary large objects (BLOBs)'s abstraction

- Virtual methods for Blob operations section for more information about how to implement the virtual methods when creating a database provider

## Functions

### gda_blob_op_get_length ()

    glong
    gda_blob_op_get_length (GdaBlobOp *op);

#### Parameters

op | an existing GdaBlobOp |

#### Returns

the length of the blob in bytes. In case of error, -1 is returned and the provider should have added an error (a GdaConnectionEvent) to the connection.

### gda_blob_op_read ()

    glong
    gda_blob_op_read (GdaBlobOp *op,
                      GdaBlob *blob,
                      glong offset,
                      glong size);

Reads a chunk of bytes from the BLOB accessible through `op` into `blob` .

#### Parameters

op | a GdaBlobOp |
blob | a GdaBlob to read data to |
offset | offset to read from the start of the blob (starts at 0) |
size | maximum number of bytes to read. |

#### Returns

the number of bytes actually read. In case of error, -1 is returned and the provider should have added an error to the connection.

### gda_blob_op_read_all ()

    gboolean
    gda_blob_op_read_all (GdaBlobOp *op,
                          GdaBlob *blob);

Reads the whole contents of the blob manipulated by `op` into `blob`

#### Parameters

op | a GdaBlobOp |
blob | a GdaBlob to read data to |

#### Returns

TRUE if `blob->data` contains the whole BLOB manipulated by `op`

### gda_blob_op_write ()

    glong
    gda_blob_op_write (GdaBlobOp *op,
                       GdaBlob *blob,
                       glong offset);

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` .

#### Parameters

op | a GdaBlobOp |
blob | a GdaBlob which contains the data to write |
offset | offset to write from the start of the blob (starts at 0) |

#### Returns

the number of bytes written. In case of error, -1 is returned and the provider should have added an error to the connection.

### gda_blob_op_write_all ()

    gboolean
    gda_blob_op_write_all (GdaBlobOp *op,
                           GdaBlob *blob);

Writes the whole contents of `blob` into the blob manipulated by `op` . If necessary the resulting blob is truncated from its previous length.

#### Parameters

op | a GdaBlobOp |
blob | a GdaBlob which contains the data to write |

#### Returns

TRUE on success

## Types and Values

### GdaBlobOp

    typedef struct _GdaBlobOp GdaBlobOp;