Sq3BlobC_TOR_C_API

Sq3BlobC - various functions to create, initialize and destroy … More...

Collaboration diagram for Sq3BlobC_TOR_C_API:

Functions
static enum MkErrorE	Sq3BlobOpen (SQ3_LITE sq3lite, MK_STRN zDb, MK_STRN zTable, MK_STRN zColumn, MK_I64 iRow, MK_I32 flags, SQ3_BLOB *ppBlob)
	Open A BLOB For Incremental I/O …
static enum MkErrorE	Sq3BlobClose (SQ3_BLOB sq3blob)
	Close A BLOB Handle …

Sq3BlobC - Sq3BlobC_TOR_C_API - function
enum MkErrorE	Sq3BlobOpenP (SQ3_LITE sq3lite, MK_STRN zDb, MK_STRN zTable, MK_STRN zColumn, MK_I64 iRow, MK_I32 flags, SQ3_BLOB *ppBlob)
	Non-inline replacement for Sq3BlobOpen …
enum MkErrorE	Sq3BlobCloseP (SQ3_BLOB sq3blob)
	Non-inline replacement for Sq3BlobClose …

Sq3BlobC - Sq3BlobC_TOR_C_API - overload
#define	Sq3BlobOpen_E(...)
#define	Sq3BlobOpen_C(...)
#define	Sq3BlobOpen_e(...)
#define	Sq3BlobClose_E(...)
#define	Sq3BlobClose_C(...)

Detailed Description

Sq3BlobC - various functions to create, initialize and destroy …

Macro Definition Documentation

Sq3BlobClose_C

#define Sq3BlobClose_C

(

...

)

Value:

if (MkErrorCheckI(Sq3BlobClose(__VA_ARGS__)))

Definition at line 80 of file sqlite3_overload_sq3.h.

Sq3BlobClose_E

#define Sq3BlobClose_E

(

...

)

Value:

MkErrorCheck(Sq3BlobClose(__VA_ARGS__))

Definition at line 79 of file sqlite3_overload_sq3.h.

Sq3BlobOpen_C

#define Sq3BlobOpen_C

(

...

)

Value:

if (MkErrorCheckI(Sq3BlobOpen(__VA_ARGS__)))

Definition at line 75 of file sqlite3_overload_sq3.h.

Sq3BlobOpen_E

#define Sq3BlobOpen_E

(

...

)

Value:

MkErrorCheck(Sq3BlobOpen(__VA_ARGS__))

Definition at line 74 of file sqlite3_overload_sq3.h.

Sq3BlobOpen_e

#define Sq3BlobOpen_e

(

...

)

Value:

MK_EMBEDDED(SQ3_BLOB,Sq3BlobOpen,__VA_ARGS__)

Definition at line 76 of file sqlite3_overload_sq3.h.

Function Documentation

Sq3BlobClose()

static enum MkErrorE Sq3BlobClose ( SQ3_BLOB sq3blob )

inlinestatic

Close A BLOB Handle …

This function closes an open BLOB handle. The BLOB handle is closed unconditionally. Even if this routine returns an error code, the handle is still closed.

If the blob handle being closed was opened for read-write access, and if the database is in auto-commit mode and there are no other open read-write blob handles or active write statements, the current transaction is committed. If an error occurs while committing the transaction, an error code is returned and the transaction rolled back.

Calling this function with an argument that is not a NULL pointer or an open blob handle results in undefined behavior. Calling this routine with a null pointer (such as would be returned by a failed call to Sq3BlobOpen ()) is a harmless no-op. Otherwise, if this function is passed a valid open blob handle, the values returned by the Sq3LiteErrCode() and Sq3LiteErrMsg() functions are set before returning.

Reference code from sqlite3:

SQLITE_API int sqlite3_blob_close(sqlite3_blob *);

Definition at line 93 of file Sq3BlobC_sq3.h.

                                                          {
    enum Sq3ErrorE errVal = (enum Sq3ErrorE)sqlite3_blob_close(sq3blob->nat);
    Sq3ErrorE_Check(sq3blob, errVal);
    return MK_OK;
  error:
    return MK_ERROR;
  }

Sq3BlobCloseP()

enum MkErrorE Sq3BlobCloseP

(

SQ3_BLOB

sq3blob

)

Non-inline replacement for Sq3BlobClose …

Sq3BlobOpen()

static enum MkErrorE Sq3BlobOpen ( SQ3_LITE sq3lite, MK_STRN zDb, MK_STRN zTable, MK_STRN zColumn, MK_I64 iRow, MK_I32 flags, SQ3_BLOB * ppBlob )

inlinestatic

Open A BLOB For Incremental I/O …

This interfaces opens a handle to the BLOB located in row iRow, column zColumn, table zTable in database zDb; in other words, the same BLOB that would be selected by:

SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;

Parameter zDb is not the filename that contains the database, but rather the symbolic name of the database. For attached databases, this is the name that appears after the AS keyword in the ATTACH statement. For the main database file, the database name is "main". For TEMP tables, the database name is "temp".

If the flags parameter is non-zero, then the BLOB is opened for read and write access. If the flags parameter is zero, the BLOB is opened for read-only access.

On success, SQ3_RESULT_OK is returned and the new BLOB handle is stored in *ppBlob. Otherwise an error code is returned and, unless the error code is SQ3_RESULT_MISUSE, *ppBlob is set to NULL. This means that, provided the API is not misused, it is always safe to call Sq3BlobClose () on *ppBlob after this function it returns.

This function fails with SQ3_RESULT_ERROR if any of the following are true:

• Database zDb does not exist,
• Table zTable does not exist within database zDb,
• Table zTable is a WITHOUT ROWID table,
• Column zColumn does not exist,
• Row iRow is not present in the table,
• The specified column of row iRow contains a value that is not a TEXT or BLOB value,
• Column zColumn is part of an index, PRIMARY KEY or UNIQUE constraint and the blob is being opened for read/write access,
• Foreign key constraints are enabled, column zColumn is part of a child key definition and the blob is being opened for read/write access.

Unless it returns SQ3_RESULT_MISUSE, this function sets the database connection error code and message accessible via Sq3LiteErrCode () and Sq3LiteErrMsg () and related functions.

A BLOB referenced by Sq3BlobOpen() may be read using the Sq3BlobRead () interface and modified by using Sq3BlobWrite (). The BLOB handle can be moved to a different row of the same table using the Sq3BlobReopen () interface. However, the column, table, or database of a BLOB handle cannot be changed after the BLOB handle is opened.

If the row that a BLOB handle points to is modified by an UPDATE, DELETE, or by ON CONFLICT side-effects then the BLOB handle is marked as "expired". This is true if any column of the row is changed, even a column other than the one the BLOB handle is open on. Calls to Sq3BlobRead () and Sq3BlobWrite () for an expired BLOB handle fail with a return code of SQ3_RESULT_ABORT. Changes written into a BLOB prior to the BLOB expiring are not rolled back by the expiration of the BLOB. Such changes will eventually commit if the transaction continues to completion.

Use the Sq3BlobBytes () interface to determine the size of the opened blob. The size of a blob may not be changed by this interface. Use the UPDATE SQL command to change the size of a blob.

The Sq3StmtBindZeroblob () and sqlite3_result_zeroblob () interfaces and the built-in zeroblob SQL function may be used to create a zero-filled blob to read or write using the incremental-blob interface.

To avoid a resource leak, every open BLOB handle should eventually be released by a call to Sq3BlobClose ().

See also: Sq3BlobClose (), Sq3BlobReopen (), Sq3BlobRead (), Sq3BlobBytes (), Sq3BlobWrite ().

Reference code from sqlite3:

SQLITE_API int sqlite3_blob_open(
  sqlite3*,
  const char *zDb,
  const char *zTable,
  const char *zColumn,
  sqlite3_int64 iRow,
  int flags,
  sqlite3_blob **ppBlob
);

Definition at line 78 of file Sq3BlobC_sq3.h.

                                                                                                                                                    {
    *ppBlob = NULL;
    struct sqlite3 * sq3lite_hdl = sq3lite->nat;
    sqlite3_blob* ppBlob_val = NULL;
    enum Sq3ErrorE errVal = (enum Sq3ErrorE)sqlite3_blob_open(sq3lite_hdl, zDb, zTable, zColumn, iRow, flags, &ppBlob_val);
    *ppBlob = Sq3BlobC_ObjCreate(ppBlob_val);
    Sq3ErrorE_Check_Static(Sq3BlobC_TT,errVal);
    return MK_OK;
  error:
    return MK_ERROR;
  }

Here is the caller graph for this function:

Sq3BlobOpenP()

enum MkErrorE Sq3BlobOpenP	(	SQ3_LITE	sq3lite,
		MK_STRN	zDb,
		MK_STRN	zTable,
		MK_STRN	zColumn,
		MK_I64	iRow,
		MK_I32	flags,
		SQ3_BLOB *	ppBlob )

Non-inline replacement for Sq3BlobOpen …