Create An Iterator To Traverse A Changeset

*** DRAFT ***

## Session Module C Interface

## Create An Iterator To Traverse A Changeset

>     int sqlite3changeset_start(
>       sqlite3_changeset_iter **pp,    /* OUT: New changeset iterator handle */
>       int nChangeset,                 /* Size of changeset blob in bytes */
>       void *pChangeset                /* Pointer to blob containing changeset */
>     );

Create an iterator used to iterate through the contents of a changeset. If successful, *pp is set to point to the iterator handle and SQLITE_OK is returned. Otherwise, if an error occurs, *pp is set to zero and an SQLite error code is returned.

The following functions can be used to advance and query a changeset iterator created by this function:

- sqlite3changeset_next()
- sqlite3changeset_op()
- sqlite3changeset_new()
- sqlite3changeset_old()

It is the responsibility of the caller to eventually destroy the iterator by passing it to sqlite3changeset_finalize(). The buffer containing the changeset (pChangeset) must remain valid until after the iterator is destroyed.

Assuming the changeset blob was created by one of the sqlite3session_changeset(), sqlite3changeset_concat() or sqlite3changeset_invert() functions, all changes within the changeset that apply to a single table are grouped together. This means that when an application iterates through a changeset using an iterator created by this function, all changes that relate to a single table are visited consecutively. There is no chance that the iterator will visit a change the applies to table X, then one for table Y, and then later on visit another change for table X.

See also lists of Objects, Constants, and Functions.

*** DRAFT ***