Result interface

Result-handling functions. More...

Functions
err_t	evsql_result_check (struct evsql_result *res)
	Check the result for errors.
err_t	evsql_result_begin (struct evsql_result_info *info, struct evsql_result *res)
	The iterator-based interface results interface.
int	evsql_result_next (struct evsql_result *res,...)
	Reads the next result row from the result prepared using evsql_result_begin.
void	evsql_result_end (struct evsql_result *res)
	Ends the result iteration, releasing any associated resources and the result itself.
const char *	evsql_result_error (const struct evsql_result *res)
	Get the error message associated with the result, intended for use after evsql_result_check/begin return an error code.
size_t	evsql_result_rows (const struct evsql_result *res)
	Get the number of data rows returned by the query.
size_t	evsql_result_cols (const struct evsql_result *res)
	Get the number of columns in the data results from the query.
size_t	evsql_result_affected (const struct evsql_result *res)
	Get the number of rows affected by an UPDATE/INSERT/etc query.
int	evsql_result_binary (const struct evsql_result *res, size_t row, size_t col, const char **ptr, size_t *size, bool nullok)
	Fetch the raw binary value for the given field, returning it via ptr/size.
int	evsql_result_string (const struct evsql_result *res, size_t row, size_t col, const char **ptr, int nullok)
	Fetch the textual value of the given field, returning it via ptr.
int	evsql_result_uint16 (const struct evsql_result *res, size_t row, size_t col, uint16_t *uval, int nullok)
	Use evsql_result_binary to read a binary field value, and then convert it using ntoh[slq], storing the value in *val.
int	evsql_result_uint32 (const struct evsql_result *res, size_t row, size_t col, uint32_t *uval, int nullok)
int	evsql_result_uint64 (const struct evsql_result *res, size_t row, size_t col, uint64_t *uval, int nullok)
void	evsql_result_free (struct evsql_result *res)
	Every result handle passed to evsql_query_cb() MUST be released by the user, using this function.

---

Detailed Description

Result-handling functions.

See also:

evsql.h

evsql_result

---

Function Documentation

size_t evsql_result_affected

(

const struct evsql_result *

res

)

Get the number of rows affected by an UPDATE/INSERT/etc query.

Parameters:

res

the result handle passed to evsql_query_cb()

Returns:

the number of rows affected, >= 0

err_t evsql_result_begin	(	struct evsql_result_info *	info,
		struct evsql_result *	res
	)

The iterator-based interface results interface.

Define an evsql_result_info struct that describes the columns returned by the query, and call evsql_result_begin on the evsql_result. This verifies the query result, and then prepares it for iteration using evsql_result_next.

Call evsql_result_end once you've stopped iteration.

Returns zero if the evsql_result is ready for iteration, err otherwise. EIO indicates an SQL error, the error message can be retreived using evsql_result_error. The result must be released in both cases.

Note: currently the iterator state is simply stored in evsql_result, so only one iterator at a time per evsql_result.

Parameters:

	info	the metadata to use to handle the result row columns
	res	the result handle passed to evsql_query_cb()

Returns:

zero on success, +err on error

int evsql_result_binary	(	const struct evsql_result *	res,
		size_t	row,
		size_t	col,
		const char **	ptr,
		size_t *	size,
		bool	nullok
	)

Fetch the raw binary value for the given field, returning it via ptr/size.

The given row/col must be within bounds as returned by evsql_result_rows/cols.

*ptr will point to *size bytes of read-only memory allocated internally.

Parameters:

	res	the result handle passed to evsql_query_cb()
	row	the row index to access
	col	the column index to access
	ptr	where to store a pointer to the read-only field data, free'd upon evsql_result_free
	size	updated to the size of the field value pointed to by ptr
	nullok	when true and the field value is NULL, *ptr and *size are not modified, otherwise NULL means an error

Returns:

zero on success, <0 on error

err_t evsql_result_check

(

struct evsql_result *

res

)

Check the result for errors.

Intended for use with non-data queries, i.e. CREATE, etc.

Returns zero if the query was OK, err otherwise. EIO indicates an SQL error, the error message can be retrived using evsql_result_error.

Parameters:

res

the result handle passed to evsql_query_cb()

Returns:

zero on success, EIO on SQL error, positive error code otherwise

size_t evsql_result_cols

(

const struct evsql_result *

res

)

Get the number of columns in the data results from the query.

Parameters:

res

the result handle passed to evsql_query_cb()

Returns:

the number of columns, presumeably zero if there were no results

void evsql_result_end

(

struct evsql_result *

res

)

Ends the result iteration, releasing any associated resources and the result itself.

The result should not be iterated or accessed anymore.

Note: this does the same thing as evsql_result_free, and works regardless of evsql_result_begin returning succesfully or not.

Parameters:

res

the result handle passed to evsql_query_cb()

See also:

evsql_result_free

const char* evsql_result_error

(

const struct evsql_result *

res

)

Get the error message associated with the result, intended for use after evsql_result_check/begin return an error code.

Parameters:

res

the result handle passed to evsql_query_cb()

Returns:

a char* containing the NUL-terminated error string. Valid until evsql_result_free is called.

void evsql_result_free

(

struct evsql_result *

res

)

Every result handle passed to evsql_query_cb() MUST be released by the user, using this function.

Parameters:

res

the result handle passed to evsql_query_cb()

int evsql_result_next	(	struct evsql_result *	res,
			...
	)

Reads the next result row from the result prepared using evsql_result_begin.

Stores the field values into to given pointer arguments based on the evsql_result_info given to evsql_result_begin.

If a field is NULL, and the result_info's evsql_item_type has flags.null_ok set, the given pointer is left untouched, otherwise, an error is returned.

Parameters:

	res	the result handle previous prepared using evsql_result_begin
	...	a set of pointers corresponding to the evsql_result_info specified using evsql_result_begin

Returns:

>0 when a row was read, zero when there are no more rows left, and -err on error

size_t evsql_result_rows

(

const struct evsql_result *

res

)

Get the number of data rows returned by the query.

Parameters:

res

the result handle passed to evsql_query_cb()

Returns:

the number of rows, >= 0

int evsql_result_string	(	const struct evsql_result *	res,
		size_t	row,
		size_t	col,
		const char **	ptr,
		int	nullok
	)

Fetch the textual value of the given field, returning it via ptr.

The given row/col must be within bounds as returned by evsql_result_rows/cols.

*ptr will point to a NUL-terminated string allocated internally.

Parameters:

	res	the result handle passed to evsql_query_cb()
	row	the row index to access
	col	the column index to access
	ptr	where to store a pointer to the read-only field data, free'd upon evsql_result_free
	nullok	when true and the field value is NULL, *ptr and *size are not modified, otherwise NULL means an error

Returns:

zero on success, <0 on error

int evsql_result_uint16	(	const struct evsql_result *	res,
		size_t	row,
		size_t	col,
		uint16_t *	uval,
		int	nullok
	)

Use evsql_result_binary to read a binary field value, and then convert it using ntoh[slq], storing the value in *val.

The given row/col must be within bounds as returned by evsql_result_rows/cols.

Parameters:

	res	the result handle passed to evsql_query_cb()
	row	the row index to access
	col	the column index to access
	uval	where to store the decoded value
	nullok	when true and the field value is NULL, *ptr and *size are not modified, otherwise NULL means an error

Returns:

zero on success, <0 on error

int evsql_result_uint32	(	const struct evsql_result *	res,
		size_t	row,
		size_t	col,
		uint32_t *	uval,
		int	nullok
	)

See also:

evsql_result_uint16

int evsql_result_uint64	(	const struct evsql_result *	res,
		size_t	row,
		size_t	col,
		uint64_t *	uval,
		int	nullok
	)

See also:

evsql_result_uint16