~drizzle-trunk/drizzle/development : contents of libdrizzle/query.h at revision 1912

~drizzle-trunk/drizzle/development : (revision 1912)

/*
 * Drizzle Client & Protocol Library
 *
 * Copyright (C) 2008 Eric Day (eday@oddments.org)
 * All rights reserved.
 *
 * Use and distribution licensed under the BSD license.  See
 * the COPYING.BSD file in the root source directory for full text.
 */

/**
 * @file
 * @brief Query Declarations
 */

#ifndef __DRIZZLE_QUERY_H
#define __DRIZZLE_QUERY_H

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @addtogroup drizzle_query Query Declarations
 *
 * @ingroup drizzle_client_interface
 * These functions are used to issue queries on a connection. Single queries are
 * made using the drizzle_query function, or you can queue multiple queries and
 * run them concurrently using the other query functions.
 * @{
 */

/**
 * Send query to server. A \ref drizzle_result_st will be created for the
 * results.
 *
 * @param[in] con connection to use to send the query.
 * @param[in,out] result pointer to an unused structure that will be used for
 *                       the results, or NULL to allocate a new structure.
 * @param[in] query query string to send.
 * @param[in] size length of the query string in bytes.
 * @param[out] ret_ptr pointer to the result code.
 * @return result, a pointer to the newly allocated result structure, or NULL
 *         if the allocation failed.
 */
DRIZZLE_API
drizzle_result_st *drizzle_query(drizzle_con_st *con, drizzle_result_st *result,
                                 const char *query, size_t size,
                                 drizzle_return_t *ret_ptr);

/**
 * Send query to server, using strlen to get the size of query buffer..
 */
DRIZZLE_API
drizzle_result_st *drizzle_query_str(drizzle_con_st *con,
                                     drizzle_result_st *result,
                                     const char *query,
                                     drizzle_return_t *ret_ptr);

/**
 * Send query incrementally.
 */
DRIZZLE_API
drizzle_result_st *drizzle_query_inc(drizzle_con_st *con,
                                     drizzle_result_st *result,
                                     const char *query, size_t size,
                                     size_t total, drizzle_return_t *ret_ptr);

/**
 * Add a query to be run concurrently.
 */
DRIZZLE_API
drizzle_query_st *drizzle_query_add(drizzle_st *drizzle,
                                    drizzle_query_st *query,
                                    drizzle_con_st *con,
                                    drizzle_result_st *result,
                                    const char *query_string, size_t size,
                                    drizzle_query_options_t options,
                                    void *context);

/**
 * Initialize a query structure.
 */
DRIZZLE_API
drizzle_query_st *drizzle_query_create(drizzle_st *drizzle,
                                       drizzle_query_st *query);

/**
 * Free a query structure.
 */
DRIZZLE_API
void drizzle_query_free(drizzle_query_st *query);

/**
 * Free a query structure.
 */
DRIZZLE_API
void drizzle_query_free_all(drizzle_st *drizzle);

/**
 * Get connection struct for a query.
 */
DRIZZLE_API
drizzle_con_st *drizzle_query_con(drizzle_query_st *query);

/**
 * Set connection struct for a query.
 */
DRIZZLE_API
void drizzle_query_set_con(drizzle_query_st *query, drizzle_con_st *con);

/**
 * Get result struct for a query.
 */
DRIZZLE_API
drizzle_result_st *drizzle_query_result(drizzle_query_st *query);

/**
 * Set result struct for a query.
 */
DRIZZLE_API
void drizzle_query_set_result(drizzle_query_st *query,
                              drizzle_result_st *result);

/**
 * Get query string for a query.
 */
DRIZZLE_API
char *drizzle_query_string(drizzle_query_st *query, size_t *size);

/**
 * Set query string for a query.
 */
DRIZZLE_API
void drizzle_query_set_string(drizzle_query_st *query, const char *string,
                              size_t size);

/**
 * Get options for a query. 
 */
DRIZZLE_API
drizzle_query_options_t drizzle_query_options(drizzle_query_st *query);

/**
 * Set options for a query.
 */
DRIZZLE_API
void drizzle_query_set_options(drizzle_query_st *query,
                               drizzle_query_options_t options);

/**
 * Add options for a query.
 */
DRIZZLE_API
void drizzle_query_add_options(drizzle_query_st *query,
                               drizzle_query_options_t options);

/**
 * Remove options for a query.
 */
DRIZZLE_API
void drizzle_query_remove_options(drizzle_query_st *query,
                                  drizzle_query_options_t options);

/**
 * Get application context for a query.
 */
DRIZZLE_API
void *drizzle_query_context(drizzle_query_st *query);

/**
 * Set application context for a query.
 */
DRIZZLE_API
void drizzle_query_set_context(drizzle_query_st *query, void *context);

/**
 * Set callback function when the context pointer should be freed.
 */
DRIZZLE_API
void drizzle_query_set_context_free_fn(drizzle_query_st *query,
                                       drizzle_query_context_free_fn *function);

/**
 * Run queries concurrently, returning when one is complete.
 */
DRIZZLE_API
drizzle_query_st *drizzle_query_run(drizzle_st *drizzle,
                                    drizzle_return_t *ret_ptr);

/**
 * Run queries until they are all complete. Returns \ref DRIZZLE_RETURN_OK if
 * all queries complete, even if some return errors. This returns immediately
 * if some other error occurs, leaving some queries unprocessed. You must call
 * drizzle_result_error_code() to check if each query succeeded.
 */
DRIZZLE_API
drizzle_return_t drizzle_query_run_all(drizzle_st *drizzle);

/*
 * Escape a string or encode a string in hexadecimal. The return value is the
 * size of the output string in to.
 */
DRIZZLE_API
size_t drizzle_escape_string(char *to, const char *from, size_t from_size);
DRIZZLE_API
size_t drizzle_hex_string(char *to, const char *from, size_t from_size);
DRIZZLE_API
void drizzle_mysql_password_hash(char *to, const char *from, size_t from_size);

/** @} */

#ifdef __cplusplus
}
#endif

#endif /* __DRIZZLE_QUERY_H */

1712.1.1 by Monty Taylor Merged libdrizzle directly into tree.	1	/*
	2	* Drizzle Client & Protocol Library
	3	*
	4	* Copyright (C) 2008 Eric Day (eday@oddments.org)
	5	* All rights reserved.
	6	*
	7	* Use and distribution licensed under the BSD license. See
1799.2.3 by Monty Taylor Reference root BSD copying file.	8	* the COPYING.BSD file in the root source directory for full text.
1712.1.1 by Monty Taylor Merged libdrizzle directly into tree.	9	*/
	10
	11	/**
	12	* @file
	13	* @brief Query Declarations
	14	*/
	15
	16	#ifndef __DRIZZLE_QUERY_H
	17	#define __DRIZZLE_QUERY_H
	18
	19	#ifdef __cplusplus
	20	extern "C" {
	21	#endif
	22
	23	/**
	24	* @addtogroup drizzle_query Query Declarations
	25	*
	26	* @ingroup drizzle_client_interface
	27	* These functions are used to issue queries on a connection. Single queries are
	28	* made using the drizzle_query function, or you can queue multiple queries and
	29	* run them concurrently using the other query functions.
	30	* @{
	31	*/
	32
	33	/**
	34	* Send query to server. A \ref drizzle_result_st will be created for the
	35	* results.
	36	*
	37	* @param[in] con connection to use to send the query.
	38	* @param[in,out] result pointer to an unused structure that will be used for
	39	* the results, or NULL to allocate a new structure.
	40	* @param[in] query query string to send.
	41	* @param[in] size length of the query string in bytes.
	42	* @param[out] ret_ptr pointer to the result code.
	43	* @return result, a pointer to the newly allocated result structure, or NULL
	44	* if the allocation failed.
	45	*/
	46	DRIZZLE_API
	47	drizzle_result_st drizzle_query(drizzle_con_st con, drizzle_result_st *result,
	48	const char *query, size_t size,
	49	drizzle_return_t *ret_ptr);
	50
	51	/**
	52	* Send query to server, using strlen to get the size of query buffer..
	53	*/
	54	DRIZZLE_API
	55	drizzle_result_st drizzle_query_str(drizzle_con_st con,
	56	drizzle_result_st *result,
	57	const char *query,
	58	drizzle_return_t *ret_ptr);
	59
	60	/**
	61	* Send query incrementally.
	62	*/
	63	DRIZZLE_API
	64	drizzle_result_st drizzle_query_inc(drizzle_con_st con,
	65	drizzle_result_st *result,
	66	const char *query, size_t size,
	67	size_t total, drizzle_return_t *ret_ptr);
	68
	69	/**
	70	* Add a query to be run concurrently.
	71	*/
	72	DRIZZLE_API
73	drizzle_query_st drizzle_query_add(drizzle_st drizzle,
74	drizzle_query_st *query,
75	drizzle_con_st *con,
76	drizzle_result_st *result,
77	const char *query_string, size_t size,
78	drizzle_query_options_t options,
79	void *context);
80
81	/**
82	* Initialize a query structure.
83	*/
84	DRIZZLE_API
85	drizzle_query_st drizzle_query_create(drizzle_st drizzle,
86	drizzle_query_st *query);
87
88	/**
89	* Free a query structure.
90	*/
91	DRIZZLE_API
92	void drizzle_query_free(drizzle_query_st *query);
93
94	/**
95	* Free a query structure.
96	*/
97	DRIZZLE_API
98	void drizzle_query_free_all(drizzle_st *drizzle);
99
100	/**
101	* Get connection struct for a query.
102	*/
103	DRIZZLE_API
104	drizzle_con_st drizzle_query_con(drizzle_query_st query);
105
106	/**
107	* Set connection struct for a query.
108	*/
109	DRIZZLE_API
110	void drizzle_query_set_con(drizzle_query_st query, drizzle_con_st con);
111
112	/**
113	* Get result struct for a query.
114	*/
115	DRIZZLE_API
116	drizzle_result_st drizzle_query_result(drizzle_query_st query);
117
118	/**
119	* Set result struct for a query.
120	*/
121	DRIZZLE_API
122	void drizzle_query_set_result(drizzle_query_st *query,
123	drizzle_result_st *result);
124
125	/**
126	* Get query string for a query.
127	*/
128	DRIZZLE_API
129	char drizzle_query_string(drizzle_query_st query, size_t *size);
130
131	/**
132	* Set query string for a query.
133	*/
134	DRIZZLE_API
135	void drizzle_query_set_string(drizzle_query_st query, const char string,
136	size_t size);
137
138	/**
139	* Get options for a query.
140	*/
141	DRIZZLE_API
142	drizzle_query_options_t drizzle_query_options(drizzle_query_st *query);
143
144	/**
145	* Set options for a query.
146	*/
147	DRIZZLE_API
148	void drizzle_query_set_options(drizzle_query_st *query,
149	drizzle_query_options_t options);
150
151	/**
152	* Add options for a query.
153	*/
154	DRIZZLE_API
155	void drizzle_query_add_options(drizzle_query_st *query,
156	drizzle_query_options_t options);
157
158	/**
159	* Remove options for a query.
160	*/
161	DRIZZLE_API
162	void drizzle_query_remove_options(drizzle_query_st *query,
163	drizzle_query_options_t options);
164
165	/**
166	* Get application context for a query.
167	*/
168	DRIZZLE_API
169	void drizzle_query_context(drizzle_query_st query);
170
171	/**
172	* Set application context for a query.
173	*/
174	DRIZZLE_API
175	void drizzle_query_set_context(drizzle_query_st query, void context);
176
177	/**
178	* Set callback function when the context pointer should be freed.
179	*/
180	DRIZZLE_API
181	void drizzle_query_set_context_free_fn(drizzle_query_st *query,
182	drizzle_query_context_free_fn *function);
183
184	/**
185	* Run queries concurrently, returning when one is complete.
186	*/
187	DRIZZLE_API
188	drizzle_query_st drizzle_query_run(drizzle_st drizzle,
189	drizzle_return_t *ret_ptr);
190
191	/**
192	* Run queries until they are all complete. Returns \ref DRIZZLE_RETURN_OK if
193	* all queries complete, even if some return errors. This returns immediately
194	* if some other error occurs, leaving some queries unprocessed. You must call
195	* drizzle_result_error_code() to check if each query succeeded.
196	*/
197	DRIZZLE_API
198	drizzle_return_t drizzle_query_run_all(drizzle_st *drizzle);
199
200	/*
201	* Escape a string or encode a string in hexadecimal. The return value is the
202	* size of the output string in to.
203	*/
204	DRIZZLE_API
205	size_t drizzle_escape_string(char to, const char from, size_t from_size);
206	DRIZZLE_API
207	size_t drizzle_hex_string(char to, const char from, size_t from_size);
208	DRIZZLE_API
209	void drizzle_mysql_password_hash(char to, const char from, size_t from_size);
210
211	/** @} */
212
213	#ifdef __cplusplus
214	}
215	#endif
216
217	#endif /* __DRIZZLE_QUERY_H */