1.Dd January 24, 2024 2.Dt SQLITE3CHANGESET_APPLY_STRM 3 3.Os 4.Sh NAME 5.Nm sqlite3changeset_apply_strm , 6.Nm sqlite3changeset_apply_v2_strm , 7.Nm sqlite3changeset_concat_strm , 8.Nm sqlite3changeset_invert_strm , 9.Nm sqlite3changeset_start_strm , 10.Nm sqlite3changeset_start_v2_strm , 11.Nm sqlite3session_changeset_strm , 12.Nm sqlite3session_patchset_strm , 13.Nm sqlite3changegroup_add_strm , 14.Nm sqlite3changegroup_output_strm , 15.Nm sqlite3rebaser_rebase_strm 16.Nd streaming versions of API functions 17.Sh SYNOPSIS 18.In sqlite3.h 19.Ft int 20.Fo sqlite3changeset_apply_strm 21.Fa "sqlite3 *db" 22.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" 23.Fa "void *pIn" 24.Fa "int(*xFilter)( void *pCtx,const char *zTab)" 25.Fa "int(*xConflict)( void *pCtx,int eConflict,sqlite3_changeset_iter *p)" 26.Fa "void *pCtx" 27.Fc 28.Ft int 29.Fo sqlite3changeset_apply_v2_strm 30.Fa "sqlite3 *db" 31.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" 32.Fa "void *pIn" 33.Fa "int(*xFilter)( void *pCtx,const char *zTab)" 34.Fa "int(*xConflict)( void *pCtx,int eConflict,sqlite3_changeset_iter *p)" 35.Fa "void *pCtx" 36.Fa "void **ppRebase" 37.Fa "int *pnRebase" 38.Fa "int flags" 39.Fc 40.Ft int 41.Fo sqlite3changeset_concat_strm 42.Fa "int (*xInputA)(void *pIn, void *pData, int *pnData)" 43.Fa "void *pInA" 44.Fa "int (*xInputB)(void *pIn, void *pData, int *pnData)" 45.Fa "void *pInB" 46.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" 47.Fa "void *pOut" 48.Fc 49.Ft int 50.Fo sqlite3changeset_invert_strm 51.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" 52.Fa "void *pIn" 53.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" 54.Fa "void *pOut" 55.Fc 56.Ft int 57.Fo sqlite3changeset_start_strm 58.Fa "sqlite3_changeset_iter **pp" 59.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" 60.Fa "void *pIn" 61.Fc 62.Ft int 63.Fo sqlite3changeset_start_v2_strm 64.Fa "sqlite3_changeset_iter **pp" 65.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" 66.Fa "void *pIn" 67.Fa "int flags" 68.Fc 69.Ft int 70.Fo sqlite3session_changeset_strm 71.Fa "sqlite3_session *pSession" 72.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" 73.Fa "void *pOut" 74.Fc 75.Ft int 76.Fo sqlite3session_patchset_strm 77.Fa "sqlite3_session *pSession" 78.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" 79.Fa "void *pOut" 80.Fc 81.Ft int 82.Fo sqlite3changegroup_add_strm 83.Fa "sqlite3_changegroup*" 84.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" 85.Fa "void *pIn" 86.Fc 87.Ft int 88.Fo sqlite3changegroup_output_strm 89.Fa "sqlite3_changegroup*" 90.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" 91.Fa "void *pOut" 92.Fc 93.Ft int 94.Fo sqlite3rebaser_rebase_strm 95.Fa "sqlite3_rebaser *pRebaser" 96.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" 97.Fa "void *pIn" 98.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" 99.Fa "void *pOut" 100.Fc 101.Sh DESCRIPTION 102The six streaming API xxx_strm() functions serve similar purposes to 103the corresponding non-streaming API functions: 104.Pp 105 Streaming function Non-streaming equivalent 106 sqlite3changeset_apply_strm sqlite3changeset_apply 107 sqlite3changeset_apply_strm_v2 sqlite3changeset_apply_v2 108 sqlite3changeset_concat_strm sqlite3changeset_concat 109 sqlite3changeset_invert_strm sqlite3changeset_invert 110 sqlite3changeset_start_strm sqlite3changeset_start 111 sqlite3session_changeset_strm sqlite3session_changeset 112 sqlite3session_patchset_strm sqlite3session_patchset 113.Pp 114Non-streaming functions that accept changesets (or patchsets) as input 115require that the entire changeset be stored in a single buffer in memory. 116Similarly, those that return a changeset or patchset do so by returning 117a pointer to a single large buffer allocated using sqlite3_malloc(). 118Normally this is convenient. 119However, if an application running in a low-memory environment is required 120to handle very large changesets, the large contiguous memory allocations 121required can become onerous. 122.Pp 123In order to avoid this problem, instead of a single large buffer, input 124is passed to a streaming API functions by way of a callback function 125that the sessions module invokes to incrementally request input data 126as it is required. 127In all cases, a pair of API function parameters such as 128.Bd -literal 129 int nChangeset, void *pChangeset, 130.Ed 131.Pp 132Is replaced by: 133.Bd -literal 134 int (*xInput)(void *pIn, void *pData, int *pnData), void 135*pIn, 136.Ed 137.Pp 138Each time the xInput callback is invoked by the sessions module, the 139first argument passed is a copy of the supplied pIn context pointer. 140The second argument, pData, points to a buffer (*pnData) bytes in size. 141Assuming no error occurs the xInput method should copy up to (*pnData) 142bytes of data into the buffer and set (*pnData) to the actual number 143of bytes copied before returning SQLITE_OK. 144If the input is completely exhausted, (*pnData) should be set to zero 145to indicate this. 146Or, if an error occurs, an SQLite error code should be returned. 147In all cases, if an xInput callback returns an error, all processing 148is abandoned and the streaming API function returns a copy of the error 149code to the caller. 150.Pp 151In the case of sqlite3changeset_start_strm(), the xInput callback may 152be invoked by the sessions module at any point during the lifetime 153of the iterator. 154If such an xInput callback returns an error, the iterator enters an 155error state, whereby all subsequent calls to iterator functions immediately 156fail with the same error code as returned by xInput. 157.Pp 158Similarly, streaming API functions that return changesets (or patchsets) 159return them in chunks by way of a callback function instead of via 160a pointer to a single large buffer. 161In this case, a pair of parameters such as: 162.Bd -literal 163 int *pnChangeset, void **ppChangeset, 164.Ed 165.Pp 166Is replaced by: 167.Bd -literal 168 int (*xOutput)(void *pOut, const void *pData, int nData), 169void *pOut 170.Ed 171.Pp 172The xOutput callback is invoked zero or more times to return data to 173the application. 174The first parameter passed to each call is a copy of the pOut pointer 175supplied by the application. 176The second parameter, pData, points to a buffer nData bytes in size 177containing the chunk of output data being returned. 178If the xOutput callback successfully processes the supplied data, it 179should return SQLITE_OK to indicate success. 180Otherwise, it should return some other SQLite error code. 181In this case processing is immediately abandoned and the streaming 182API function returns a copy of the xOutput error code to the application. 183.Pp 184The sessions module never invokes an xOutput callback with the third 185parameter set to a value less than or equal to zero. 186Other than this, no guarantees are made as to the size of the chunks 187of data returned. 188.Sh IMPLEMENTATION NOTES 189These declarations were extracted from the 190interface documentation at line 12507. 191.Bd -literal 192SQLITE_API int sqlite3changeset_apply_strm( 193 sqlite3 *db, /* Apply change to "main" db of this handle */ 194 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */ 195 void *pIn, /* First arg for xInput */ 196 int(*xFilter)( 197 void *pCtx, /* Copy of sixth arg to _apply() */ 198 const char *zTab /* Table name */ 199 ), 200 int(*xConflict)( 201 void *pCtx, /* Copy of sixth arg to _apply() */ 202 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */ 203 sqlite3_changeset_iter *p /* Handle describing change and conflict */ 204 ), 205 void *pCtx /* First argument passed to xConflict */ 206); 207SQLITE_API int sqlite3changeset_apply_v2_strm( 208 sqlite3 *db, /* Apply change to "main" db of this handle */ 209 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */ 210 void *pIn, /* First arg for xInput */ 211 int(*xFilter)( 212 void *pCtx, /* Copy of sixth arg to _apply() */ 213 const char *zTab /* Table name */ 214 ), 215 int(*xConflict)( 216 void *pCtx, /* Copy of sixth arg to _apply() */ 217 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */ 218 sqlite3_changeset_iter *p /* Handle describing change and conflict */ 219 ), 220 void *pCtx, /* First argument passed to xConflict */ 221 void **ppRebase, int *pnRebase, 222 int flags 223); 224SQLITE_API int sqlite3changeset_concat_strm( 225 int (*xInputA)(void *pIn, void *pData, int *pnData), 226 void *pInA, 227 int (*xInputB)(void *pIn, void *pData, int *pnData), 228 void *pInB, 229 int (*xOutput)(void *pOut, const void *pData, int nData), 230 void *pOut 231); 232SQLITE_API int sqlite3changeset_invert_strm( 233 int (*xInput)(void *pIn, void *pData, int *pnData), 234 void *pIn, 235 int (*xOutput)(void *pOut, const void *pData, int nData), 236 void *pOut 237); 238SQLITE_API int sqlite3changeset_start_strm( 239 sqlite3_changeset_iter **pp, 240 int (*xInput)(void *pIn, void *pData, int *pnData), 241 void *pIn 242); 243SQLITE_API int sqlite3changeset_start_v2_strm( 244 sqlite3_changeset_iter **pp, 245 int (*xInput)(void *pIn, void *pData, int *pnData), 246 void *pIn, 247 int flags 248); 249SQLITE_API int sqlite3session_changeset_strm( 250 sqlite3_session *pSession, 251 int (*xOutput)(void *pOut, const void *pData, int nData), 252 void *pOut 253); 254SQLITE_API int sqlite3session_patchset_strm( 255 sqlite3_session *pSession, 256 int (*xOutput)(void *pOut, const void *pData, int nData), 257 void *pOut 258); 259SQLITE_API int sqlite3changegroup_add_strm(sqlite3_changegroup*, 260 int (*xInput)(void *pIn, void *pData, int *pnData), 261 void *pIn 262); 263SQLITE_API int sqlite3changegroup_output_strm(sqlite3_changegroup*, 264 int (*xOutput)(void *pOut, const void *pData, int nData), 265 void *pOut 266); 267SQLITE_API int sqlite3rebaser_rebase_strm( 268 sqlite3_rebaser *pRebaser, 269 int (*xInput)(void *pIn, void *pData, int *pnData), 270 void *pIn, 271 int (*xOutput)(void *pOut, const void *pData, int nData), 272 void *pOut 273); 274.Ed 275.Sh SEE ALSO 276.Xr sqlite3changeset_apply 3 , 277.Xr sqlite3changeset_concat 3 , 278.Xr sqlite3changeset_invert 3 , 279.Xr sqlite3changeset_start 3 , 280.Xr sqlite3session_changeset 3 , 281.Xr sqlite3session_patchset 3 282