cgi/mysqlw.h File Reference

mysql helper functions. More...

#include <stdio.h>
#include <stdlib.h>
#include <mysql.h>
#include <mysqld_error.h>

Data Structures
struct	s_mysql_result
	MySQL result type. More...
Typedefs
typedef struct s_mysql	t_mysql
	MySQL connection type.
typedef struct s_mysql_result	t_mysql_result
	MySQL result type.
typedef struct s_mysql_row	t_mysql_row
	MySQL row type.
Functions
int	mysqlw_escape_string (char **string, char *str)
	Escape null-terminated string.
int	mysqlw_escape_binstring (char **string, char *str, int length)
	Escape binary data.
t_mysql *	mysqlw_connect (char *host, char *username, char *password, char *db)
	Connect to MySQL database.
void	mysqlw_close (t_mysql *conn)
	Close MySQL connection.
t_mysql_result *	mysqlw_query (t_mysql *conn, char *fmt,...)
	Perform a query to MySQL database.
void	mysqlw_free_result (t_mysql_result *result)
	Free MySQL result and release its memory.
t_mysql_row *	mysqlw_fetch_row (t_mysql_result *result)
	Return next data row in dataset.
char *	mysqlw_field_by_name (t_mysql_row *row, char *name)
	Return row data by field name.
long	mysqlw_length_by_name (t_mysql_row *row, char *name)
	Return row data length by field name.
long	mysqlw_data_seek (t_mysql_result *result, long where)
	Seek to the certain position in the dataset.

---

Detailed Description

mysql helper functions.

Author:

Vladimir Pavluk, 2006-2007

MySQL is a light RDBMS, convenient for small to mid-sized databases. This file contains helper functions to make communications with mysql easy and comfortable. To make differ from native MySQL functions, all functions declared here have mysqlw_ prefix, where last w stands for 'wrapper'.

---

Typedef Documentation

typedef struct s_mysql t_mysql

MySQL connection type.

Holds MySQL connection information.

typedef struct s_mysql_result t_mysql_result

MySQL result type.

Contains information about query resut MySQL.

typedef struct s_mysql_row t_mysql_row

MySQL row type.

Holds one row of a dataset returned by MySQL query.

---

Function Documentation

void mysqlw_close

(

t_mysql *

conn

)

Close MySQL connection.

Closes MySQL connection.

Parameters:

conn

connection to close.

See also:

mysqlw_connect(char *, char *, char *, char *)

t_mysql* mysqlw_connect	(	char *	host,
		char *	username,
		char *	password,
		char *	db
	)

Connect to MySQL database.

Opens connection to MySQL database with given parameters.

Parameters:

	host	MySQL host.
	username	MySQL user.
	password	MySQL password.
	db	database name to use.

Returns:

MySQL connection on success, NULL otherwise.

See also:

mysqlw_close(t_mysql *)

long mysqlw_data_seek	(	t_mysql_result *	result,
		long	where
	)

Seek to the certain position in the dataset.

Seeks to the certain position in the dataset.

Parameters:

	result	MySQL result.
	where	row number to seek to.

Returns:

new cursor position.

See also:

mysqlw_query(t_mysql *, char *, ...)

mysqlw_fetch_row(t_mysql_result *)

int mysqlw_escape_binstring	(	char **	string,
		char *	str,
		int	length
	)

Escape binary data.

Escapes an array of binary data.

Parameters:

	string	pointer to char* variable. Will hold pointer to null-terminated escaped data.
	str	string to escape.
	length	unescaped string length.

Returns:

escaped string length.

int mysqlw_escape_string	(	char **	string,
		char *	str
	)

Escape null-terminated string.

Escapes null-terminated char* string.

Parameters:

	string	pointer to char* variable. Will hold pointer to escaped string.
	str	string to escape.

Returns:

escaped string length.

t_mysql_row* mysqlw_fetch_row

(

t_mysql_result *

result

)

Return next data row in dataset.

Returns next data row in dataset. If there are no more rows, returns NULL.

Parameters:

result

MySQL query result.

Returns:

field data.

See also:

mysqlw_free_result(t_mysql_result *)

mysqlw_query(t_mysql *, char *, ...)

char* mysqlw_field_by_name	(	t_mysql_row *	row,
		char *	name
	)

Return row data by field name.

Returns row data by field name. Note, that data is read only - you are not responsible for freeing the data.

Parameters:

	row	data row.
	name	field name.

Returns:

field data.

See also:

mysqlw_length_by_name(t_mysql_row *, char *)

mysqlw_fetch_row(t_mysql_result *)

mysqlw_query(t_mysql *, char *, ...)

void mysqlw_free_result

(

t_mysql_result *

result

)

Free MySQL result and release its memory.

Frees MySQL result and releases its memory.

Parameters:

result

MySQL result.

See also:

mysqlw_query(t_mysql *, char *, ...)

long mysqlw_length_by_name	(	t_mysql_row *	row,
		char *	name
	)

Return row data length by field name.

Returns row data length by field name. Length is needed only for binary fields - character and number strings are null-terminated.

Parameters:

	row	data row.
	name	field name.

Returns:

field data.

See also:

mysqlw_field_by_name(t_mysql_row *, char *)

mysqlw_fetch_row(t_mysql_result *)

mysqlw_query(t_mysql *, char *, ...)

t_mysql_result* mysqlw_query	(	t_mysql *	conn,
		char *	fmt,
			...
	)

Perform a query to MySQL database.

Compiles a query using specified parameters, and performs a query. This function is very similar to *printf family functions. It uses the same format strings; however, it has two additional arguments to string format.

• q - quoted string. This format flag instructs mysqlw_query to escape corresponding string argument.
• b - quoted string. This format flag instructs mysqlw_query to escape corresponding string argument as binary string. In this case one additional argument should be specified - length of the binary string (long integer).

Example:

 mysqlw_query(conn, "SELECT t.name FROM t WHERE name = '%qs'", "Sam");

 mysqlw_query(conn, "UPDATE t SET t.photo = '%bs'", photo, photo_len);

 mysqlw_query(conn, "SELECT t.name FROM t WHERE t.id = '%i'", 12);

Parameters:

	conn	MySQL connection.
	fmt	format string.

Returns:

MySQL result on success, NULL otherwise.

See also:

mysqlw_free_result(t_mysql_result *)

mysqlw_fetch_row(t_mysql_result *)

mysqlw_connect(char *, char *, char *, char *)