Sidebar
endurox:v8.0.x:api:ubf:bnext.3
Name
Bnext — Iterate over the UBF buffer
Synopsis
#include <ubf.h>
int Bnext (UBFH *p_ub, BFLDID *bfldid, BFLDOCC *occ, char *buf, BFLDLEN *len);
int Bnext2(Bnext_state_t *bnext_state, UBFH *p_ub, BFLDID *bfldid, BFLDOCC *occ, char *buf, BFLDLEN *len, char **d_ptr);
Link with -lubf -lnstd -lm -lpthread
DESCRIPTION
Iterate over the UBF buffer pointed by p_ub. To start (or restart) loop over the buffer, bfldid value must be set to BFIRSTFLDID. If function succeeds it returns field id in bfldid, occurrence in occ and data value in buf/len pair. buf and len both are optional fields. len on input indicate the buffer length, on output it indicates the the length of data loaded. If len is set to NULL, then it is assumed that on input buffer is large enough to store data. The state of iteration is stored in thread local storage (TLS).
When Bnext() and Bnext2() steps onto BFLD_VIEW type field, Bnext initializes the buf as BVIEWFLD with trailing data. Thus the BVIEWFLD.data is set to memory address of buf + sizeof(BVIEWFLD). If len was specified, before returning the data len is reduced by sizeof(BVIEWFLD).
Bnext() is not reentrant, meaning that iteration state is kept in the thread local storage and while iterating one buffer, if attempt to iterate another buffer is done, the first buffer iteration state is lost.
To operate with two or more buffers at the same time, use Bnext2() version of the function, where the iteration state is stored at bnext_state parameter. bnext_state parameter is automatically initialized when iteration is stated by BFIRSTFLDID. This version of the function additionally returns pointer to the raw field data in d_ptr parameter. The use of d_ptr may give some performance boost as extra data copy is avoided during the data access. In case if current field is BFLD_VIEW, returned d_ptr will return pointer to the initialized BVIEWFLD field. The BVIEWFLD initialization data is stored in thread local storage, meaning that if iterating two or more buffers with BFLD_VIEW fields, then d_ptr would be valid only for last result. If data shell be kept while accessing other UBF buffer with view fields, copy of d_ptr to local variable of BVIEWFLD type may be done. Returned d_ptr pointer is valid only while the UBF buffer is not modified (including no modifications to parent of the embedded buffer).
Functions are thread safe.
RETURN VALUE
On success, Bnext() and Bnext2() return 1, if End Of Buffer reached, then 0 is returned; on error, -1 is returned, with Berror set to indicate the error.