1.Dd January 24, 2024 2.Dt SQLITE3CHANGESET_START 3 3.Os 4.Sh NAME 5.Nm sqlite3changeset_start , 6.Nm sqlite3changeset_start_v2 7.Nd create an iterator to traverse a changeset 8.Sh SYNOPSIS 9.In sqlite3.h 10.Ft int 11.Fo sqlite3changeset_start 12.Fa "sqlite3_changeset_iter **pp" 13.Fa "int nChangeset" 14.Fa "void *pChangeset" 15.Fc 16.Ft int 17.Fo sqlite3changeset_start_v2 18.Fa "sqlite3_changeset_iter **pp" 19.Fa "int nChangeset" 20.Fa "void *pChangeset" 21.Fa "int flags" 22.Fc 23.Sh DESCRIPTION 24Create an iterator used to iterate through the contents of a changeset. 25If successful, *pp is set to point to the iterator handle and SQLITE_OK 26is returned. 27Otherwise, if an error occurs, *pp is set to zero and an SQLite error 28code is returned. 29.Pp 30The following functions can be used to advance and query a changeset 31iterator created by this function: 32.Bl -bullet 33.It 34.Fn sqlite3changeset_next 35.It 36.Fn sqlite3changeset_op 37.It 38.Fn sqlite3changeset_new 39.It 40.Fn sqlite3changeset_old 41.El 42.Pp 43It is the responsibility of the caller to eventually destroy the iterator 44by passing it to 45.Fn sqlite3changeset_finalize . 46The buffer containing the changeset (pChangeset) must remain valid 47until after the iterator is destroyed. 48.Pp 49Assuming the changeset blob was created by one of the 50.Fn sqlite3session_changeset , 51.Fn sqlite3changeset_concat 52or 53.Fn sqlite3changeset_invert 54functions, all changes within the changeset that apply to a single 55table are grouped together. 56This means that when an application iterates through a changeset using 57an iterator created by this function, all changes that relate to a 58single table are visited consecutively. 59There is no chance that the iterator will visit a change the applies 60to table X, then one for table Y, and then later on visit another change 61for table X. 62.Pp 63The behavior of sqlite3changeset_start_v2() and its streaming equivalent 64may be modified by passing a combination of supported flags 65as the 4th parameter. 66.Pp 67Note that the sqlite3changeset_start_v2() API is still \fBexperimental\fP 68and therefore subject to change. 69.Sh IMPLEMENTATION NOTES 70These declarations were extracted from the 71interface documentation at line 11435. 72.Bd -literal 73SQLITE_API int sqlite3changeset_start( 74 sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */ 75 int nChangeset, /* Size of changeset blob in bytes */ 76 void *pChangeset /* Pointer to blob containing changeset */ 77); 78SQLITE_API int sqlite3changeset_start_v2( 79 sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */ 80 int nChangeset, /* Size of changeset blob in bytes */ 81 void *pChangeset, /* Pointer to blob containing changeset */ 82 int flags /* SESSION_CHANGESETSTART_* flags */ 83); 84.Ed 85.Sh SEE ALSO 86.Xr sqlite3changeset_concat 3 , 87.Xr sqlite3changeset_finalize 3 , 88.Xr sqlite3changeset_invert 3 , 89.Xr sqlite3changeset_new 3 , 90.Xr sqlite3changeset_next 3 , 91.Xr sqlite3changeset_old 3 , 92.Xr sqlite3changeset_op 3 , 93.Xr sqlite3session_changeset 3 , 94.Xr SQLITE_CHANGESETSTART_INVERT 3 95