Virtual methods for Blob operations

Blobs are a special feature of databases because they allow one to access the contents of a "cell" from the API without using SQL (usually no SQL can be used to manipulate a blob's contents: an SQL statement is used to create, delete or retrieve a blob, but the contents is accessed through the API).

Libgda encapsulates all blob operations in objects which must be implemented by each provider if they want to support blobs; otherwise binary data may still be used if supported by the database, but the whole binary data is transferred in the SQL statement which is not suitable for large data.

Libgda defines GdaBlob structure which is an extension of the GdaBinary structure (which contains a pointer to some data and the size of the pointed data). The extension simply adds a pointer to a GdaBlobOp object which has to be implemented by each provider which supports blobs. The following documents the GdaBlobOp's virtual methods which actually implement the reading from and writing to a blob contained in the database.

When reading from a blob in the database or writing to a blob in the database, data read or written is the stored in the GdaBinary part of the GdaBlobOp.

get_length()

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

read()

This method requests that some data be read from the blob. The data read must be stored in the GdaBinary part of the blob parameter. The data to read is the data starting at the offset offset from the beginning of the blob, and of the size length.

Note that in this method, the op attribute of the blob parameter is not used.

The returned value is the number of bytes read, or -1 if an error occured (then the provider should have added an error to the connection).

write()

This method requests the some data be written to the blob. The data has to be written in the blob starting at the offset offset from the beginning of the blob.

If the op attribute of the blob parameter is not NULL and is different than the op, then the data to be written is the complete contents of the data stored in the blob represented by the op attribute of the blob parameter. Otherwise The data to be written is stored in the GdaBinary part of the blob.

The returned value is the number of bytes written, or -1 if an error occured (then the provider should have added an error to the connection).

write_all()

This method requests that all the contents of the blob be replaced by some data (if necessary the blob is truncated from its previous length). The data to be written is the same as for the write() method, and the returned value is also the same.

If this virtual method is not implemented, then the write() virtual method is used with an offset parameter of 0.