gda-blob

## gda-blob gda-blob — Management of BLOBs (Binary Large OBjects) |

## Synopsis

    enum        GdaBlobMode;
                GdaBlob;
    gint        gda_blob_open                   (GdaBlob *blob,
                                                 GdaBlobMode mode);
    gint        gda_blob_read                   (GdaBlob *blob,
                                                 gpointer buf,
                                                 gint size,
                                                 gint *bytes_read);
    gint        gda_blob_write                  (GdaBlob *blob,
                                                 gpointer buf,
                                                 gint size,
                                                 gint *bytes_written);
    gint        gda_blob_lseek                  (GdaBlob *blob,
                                                 gint offset,
                                                 gint whence);
    gint        gda_blob_close                  (GdaBlob *blob);
    gint        gda_blob_remove                 (GdaBlob *blob);
    void        gda_blob_free_data              (GdaBlob *blob);

## Description

## Details

### enum GdaBlobMode

    typedef enum {
    	GDA_BLOB_MODE_READ = 1,
    	GDA_BLOB_MODE_WRITE = 1 << 1,
    	GDA_BLOB_MODE_RDWR = 0x03
    } GdaBlobMode;

### GdaBlob

    typedef struct {
    	/* Private */
    	gint (* open) (GdaBlob *blob, GdaBlobMode mode);

    	gint (* read) (GdaBlob *blob, gpointer buf, gint size,
    			gint *bytes_read);

    	gint (* write) (GdaBlob *blob, gpointer buf, gint size,
    			gint *bytes_written);

    	gint (* lseek) (GdaBlob *blob, gint offset, gint whence);

    	gint (* close) (GdaBlob *blob);

    	gint (* remove) (GdaBlob *blob);

    	gchar * (* stringify) (GdaBlob *blob);

    	void (* free_data) (GdaBlob *blob);

    	gpointer priv_data;
    	/* */

    	/* Public */
    	gpointer user_data;
    } GdaBlob;

### gda_blob_open ()

    gint        gda_blob_open                   (GdaBlob *blob,
                                                 GdaBlobMode mode);

Opens an existing BLOB. The BLOB must be initialized by gda_connection_create_blob or obtained from a GdaValue.

`blob` : | a GdaBlob structure obtained from a GdaValue or allocated by the user when he/she wants to create a new GdaBlob.
`mode` : | see GdaBlobMode.
Returns : | 0 if everything's ok. In case of error, -1 is returned and the provider should have added an error to the connection.

### gda_blob_read ()

    gint        gda_blob_read                   (GdaBlob *blob,
                                                 gpointer buf,
                                                 gint size,
                                                 gint *bytes_read);

Reads a chunk of bytes from the BLOB into a user-provided location.

`blob` : | a GdaBlob which is opened with the flag GDA_BLOB_MODE_READ set.
`buf` : | buffer to read the data into.
`size` : | maximum number of bytes to read.
`bytes_read` : | on return it will point to the number of bytes actually read.
Returns : | 0 if everything's ok. In case of error, -1 is returned and the provider should have added an error to the connection.

### gda_blob_write ()

    gint        gda_blob_write                  (GdaBlob *blob,
                                                 gpointer buf,
                                                 gint size,
                                                 gint *bytes_written);

Writes a chunk of bytes from a user-provided location to the BLOB.

`blob` : | a GdaBlob which is opened with the flag GDA_BLOB_MODE_WRITE set.
`buf` : | buffer to write the data from.
`size` : | maximum number of bytes to read.
`bytes_written` : | on return it will point to the number of bytes actually written.
Returns : | 0 if everything's ok. In case of error, -1 is returned and the provider should have added an error to the connection.

### gda_blob_lseek ()

    gint        gda_blob_lseek                  (GdaBlob *blob,
                                                 gint offset,
                                                 gint whence);

Sets the blob read/write position.

`blob` : | a opened GdaBlob.
`offset` : | offset added to the position specified by `whence`.
`whence` : | SEEK_SET, SEEK_CUR or SEEK_END with the same meaning as in fseek(3).
Returns : | the current position in the blob or < 0 in case of error. In case of error the provider should have added an error to the connection.

### gda_blob_close ()

    gint        gda_blob_close                  (GdaBlob *blob);

Closes the BLOB. After calling this function, `blob` should no longer be used.

`blob` : | a opened GdaBlob.
Returns : | 0 if everything's ok. In case of error, -1 is returned and the provider should have added an error to the connection.

### gda_blob_remove ()

    gint        gda_blob_remove                 (GdaBlob *blob);

Removes the BLOB from the database. After calling this function, `blob` should no longer be used.

`blob` : | a valid GdaBlob.
Returns : | 0 if everything's ok. In case of error, -1 is returned and the provider should have added an error to the connection.

### gda_blob_free_data ()

    void        gda_blob_free_data              (GdaBlob *blob);

Let the provider free any internal data stored in `blob`. The user is still responsible for deallocating `blob` itself.

`blob` : | a valid GdaBlob.