1.Dd March 11, 2017 2.Dt SQLITE3CHANGESET_APPLY_STRM 3 3.Os 4.Sh NAME 5.Nm sqlite3changeset_apply_strm , 6.Nm sqlite3changeset_concat_strm , 7.Nm sqlite3changeset_invert_strm , 8.Nm sqlite3changeset_start_strm , 9.Nm sqlite3session_changeset_strm , 10.Nm sqlite3session_patchset_strm , 11.Nm sqlite3changegroup_add_strm , 12.Nm sqlite3changegroup_output_strm 13.Nd Streaming Versions of API functions. 14.Sh SYNOPSIS 15.Ft int 16.Fo sqlite3changeset_apply_strm 17.Fa "sqlite3 *db" 18.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" 19.Fa "void *pIn" 20.Fa "int(*xFilter)( void *pCtx, const char *zTab )" 21.Fa "int(*xConflict)( void *pCtx, int eConflict, sqlite3_changeset_iter *p )" 22.Fa "void *pCtx " 23.Fc 24.Ft int 25.Fo sqlite3changeset_concat_strm 26.Fa "int (*xInputA)(void *pIn, void *pData, int *pnData)" 27.Fa "void *pInA" 28.Fa "int (*xInputB)(void *pIn, void *pData, int *pnData)" 29.Fa "void *pInB" 30.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" 31.Fa "void *pOut " 32.Fc 33.Ft int 34.Fo sqlite3changeset_invert_strm 35.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" 36.Fa "void *pIn" 37.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" 38.Fa "void *pOut " 39.Fc 40.Ft int 41.Fo sqlite3changeset_start_strm 42.Fa "sqlite3_changeset_iter **pp" 43.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" 44.Fa "void *pIn " 45.Fc 46.Ft int 47.Fo sqlite3session_changeset_strm 48.Fa "sqlite3_session *pSession" 49.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" 50.Fa "void *pOut " 51.Fc 52.Ft int 53.Fo sqlite3session_patchset_strm 54.Fa "sqlite3_session *pSession" 55.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" 56.Fa "void *pOut " 57.Fc 58.Ft int 59.Fo sqlite3changegroup_add_strm 60.Fa "sqlite3_changegroup*" 61.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" 62.Fa "void *pIn " 63.Fc 64.Ft int 65.Fo sqlite3changegroup_output_strm 66.Fa "sqlite3_changegroup*" 67.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" 68.Fa "void *pOut " 69.Fc 70.Sh DESCRIPTION 71The six streaming API xxx_strm() functions serve similar purposes to 72the corresponding non-streaming API functions: 73.Pp 74<table border=1 style="margin-left:8ex;margin-right:8ex"> <tr><th>Streaming 75function<th>Non-streaming equivalent</th> <tr><td>sqlite3changeset_apply_str<td>sqlite3changeset_apply 76<tr><td>sqlite3changeset_concat_str<td>sqlite3changeset_concat 77<tr><td>sqlite3changeset_invert_str<td>sqlite3changeset_invert 78<tr><td>sqlite3changeset_start_str<td>sqlite3changeset_start 79<tr><td>sqlite3session_changeset_str<td>sqlite3session_changeset 80<tr><td>sqlite3session_patchset_str<td>sqlite3session_patchset 81</table> 82.Pp 83Non-streaming functions that accept changesets (or patchsets) as input 84require that the entire changeset be stored in a single buffer in memory. 85Similarly, those that return a changeset or patchset do so by returning 86a pointer to a single large buffer allocated using sqlite3_malloc(). 87Normally this is convenient. 88However, if an application running in a low-memory environment is required 89to handle very large changesets, the large contiguous memory allocations 90required can become onerous. 91.Pp 92In order to avoid this problem, instead of a single large buffer, input 93is passed to a streaming API functions by way of a callback function 94that the sessions module invokes to incrementally request input data 95as it is required. 96In all cases, a pair of API function parameters such as 97.Bd -literal 98 int nChangeset, void *pChangeset, 99.Ed 100.Pp 101Is replaced by: 102.Bd -literal 103 int (*xInput)(void *pIn, void *pData, int *pnData), void 104*pIn, 105.Ed 106.Pp 107Each time the xInput callback is invoked by the sessions module, the 108first argument passed is a copy of the supplied pIn context pointer. 109The second argument, pData, points to a buffer (*pnData) bytes in size. 110Assuming no error occurs the xInput method should copy up to (*pnData) 111bytes of data into the buffer and set (*pnData) to the actual number 112of bytes copied before returning SQLITE_OK. 113If the input is completely exhausted, (*pnData) should be set to zero 114to indicate this. 115Or, if an error occurs, an SQLite error code should be returned. 116In all cases, if an xInput callback returns an error, all processing 117is abandoned and the streaming API function returns a copy of the error 118code to the caller. 119.Pp 120In the case of sqlite3changeset_start_strm(), the xInput callback may 121be invoked by the sessions module at any point during the lifetime 122of the iterator. 123If such an xInput callback returns an error, the iterator enters an 124error state, whereby all subsequent calls to iterator functions immediately 125fail with the same error code as returned by xInput. 126.Pp 127Similarly, streaming API functions that return changesets (or patchsets) 128return them in chunks by way of a callback function instead of via 129a pointer to a single large buffer. 130In this case, a pair of parameters such as: 131.Bd -literal 132 int *pnChangeset, void **ppChangeset, 133.Ed 134.Pp 135Is replaced by: 136.Bd -literal 137 int (*xOutput)(void *pOut, const void *pData, int nData), 138void *pOut 139.Ed 140.Pp 141The xOutput callback is invoked zero or more times to return data to 142the application. 143The first parameter passed to each call is a copy of the pOut pointer 144supplied by the application. 145The second parameter, pData, points to a buffer nData bytes in size 146containing the chunk of output data being returned. 147If the xOutput callback successfully processes the supplied data, it 148should return SQLITE_OK to indicate success. 149Otherwise, it should return some other SQLite error code. 150In this case processing is immediately abandoned and the streaming 151API function returns a copy of the xOutput error code to the application. 152.Pp 153The sessions module never invokes an xOutput callback with the third 154parameter set to a value less than or equal to zero. 155Other than this, no guarantees are made as to the size of the chunks 156of data returned. 157.Sh SEE ALSO 158.Xr sqlite3changeset_apply 3 , 159.Xr sqlite3changeset_concat 3 , 160.Xr sqlite3changeset_invert 3 , 161.Xr sqlite3changeset_start 3 , 162.Xr sqlite3session_changeset 3 , 163.Xr sqlite3session_patchset 3 164