← Back to branch summary

~drizzle-trunk/drizzle/development

« back to all changes in this revision

Viewing changes to libdrizzle/drizzle.h

  • Committer: Brian Aker
  • Date: 2009-08-17 01:44:23 UTC
  • mto: This revision was merged to the branch mainline in revision 1118.
  • Revision ID: brian@gaz-20090817014423-jxi2qonsumm8mndf
Remove SQL level reference for DELAY (just now done correctly by default in
engine).

Show diffs side-by-side

added added

removed removed

Lines of Context:
libdrizzle/drizzle.h
1
 
/*
2
 
 * Drizzle Client & Protocol Library
3
 
 *
4
 
 * Copyright (C) 2008 Eric Day (eday@oddments.org)
5
 
 * All rights reserved.
6
 
 *
7
 
 * Redistribution and use in source and binary forms, with or without
8
 
 * modification, are permitted provided that the following conditions are
9
 
 * met:
10
 
 *
11
 
 *     * Redistributions of source code must retain the above copyright
12
 
 * notice, this list of conditions and the following disclaimer.
13
 
 *
14
 
 *     * Redistributions in binary form must reproduce the above
15
 
 * copyright notice, this list of conditions and the following disclaimer
16
 
 * in the documentation and/or other materials provided with the
17
 
 * distribution.
18
 
 *
19
 
 *     * The names of its contributors may not be used to endorse or
20
 
 * promote products derived from this software without specific prior
21
 
 * written permission.
22
 
 *
23
 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24
 
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25
 
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
26
 
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
27
 
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
28
 
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
29
 
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
30
 
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
31
 
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
32
 
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
33
 
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34
 
 *
35
 
 */
36
 
 
37
 
/**
38
 
 * @file
39
 
 * @brief Drizzle Declarations
40
 
 */
41
 
 
42
 
#ifndef __DRIZZLE_H
43
 
#define __DRIZZLE_H
44
 
 
45
 
 
46
 
#include <inttypes.h>
47
 
#include <sys/types.h>
48
 
 
49
 
#ifdef _WIN32
50
 
# define WIN32_LEAN_AND_MEAN
51
 
 
52
 
# include <Windows.h>
53
 
# include <winsock2.h>
54
 
# include <ws2tcpip.h>
55
 
# include <io.h>
56
 
 
57
 
# undef close
58
 
# define close _close
59
 
typedef unsigned int in_port_t;
60
 
typedef long ssize_t;
61
 
 
62
 
# define snprintf _snprintf
63
 
# define inline __inline
64
 
 
65
 
struct sockaddr_un
66
 
{
67
 
  short int sun_family;
68
 
  char sun_path[108];
69
 
};
70
 
 
71
 
# define poll WSAPoll
72
 
//# define pollfd WSAPOLLFD
73
 
 
74
 
#if defined(__GNUC__)
75
 
# include <stdbool.h>
76
 
#else
77
 
typedef enum { false = 0, true = 1 } _Bool;
78
 
typedef _Bool bool;
79
 
#endif
80
 
 
81
 
#else
82
 
# if !defined(__cplusplus)
83
 
#  include <stdbool.h>
84
 
# endif
85
 
# include <sys/socket.h>
86
 
# include <netinet/in.h>
87
 
# include <arpa/inet.h>
88
 
# include <sys/un.h>
89
 
# include <netdb.h>
90
 
# include <poll.h>
91
 
#endif
92
 
 
93
 
#include <assert.h>
94
 
#include <errno.h>
95
 
 
96
 
#include <libdrizzle/visibility.h>
97
 
#include <libdrizzle/constants.h>
98
 
#include <libdrizzle/structs.h>
99
 
#include <libdrizzle/conn.h>
100
 
#include <libdrizzle/result.h>
101
 
#include <libdrizzle/column.h>
102
 
 
103
 
#ifdef  __cplusplus
104
 
extern "C" {
105
 
#endif
106
 
 
107
 
/**
108
 
 * @addtogroup drizzle Drizzle Declarations
109
 
 * @ingroup drizzle_client_interface
110
 
 * @ingroup drizzle_server_interface
111
 
 *
112
 
 * This is the core library structure that other structures (such as
113
 
 * connections) are created from.
114
 
 *
115
 
 * There is no locking within a single drizzle_st structure, so for threaded
116
 
 * applications you must either ensure isolation in the application or use
117
 
 * multiple drizzle_st structures (for example, one for each thread).
118
 
 * @{
119
 
 */
120
 
 
121
 
/**
122
 
 * Get library version string.
123
 
 *
124
 
 * @return Pointer to static buffer in library that holds the version string.
125
 
 */
126
 
DRIZZLE_API
127
 
const char *drizzle_version(void);
128
 
 
129
 
/**
130
 
 * Get bug report URL.
131
 
 *
132
 
 * @return Bug report URL string.
133
 
 */
134
 
DRIZZLE_API
135
 
const char *drizzle_bugreport(void);
136
 
 
137
 
/**
138
 
 * Get string with the name of the given verbose level.
139
 
 *
140
 
 * @param[in] verbose Verbose logging level.
141
 
 * @return String form of verbose level.
142
 
 */
143
 
DRIZZLE_API
144
 
const char *drizzle_verbose_name(drizzle_verbose_t verbose);
145
 
 
146
 
/**
147
 
 * Initialize a drizzle structure. Always check the return value even if passing
148
 
 * in a pre-allocated structure. Some other initialization may have failed.
149
 
 *
150
 
 * @param[in] drizzle Caller allocated structure, or NULL to allocate one.
151
 
 * @return On success, a pointer to the (possibly allocated) structure. On
152
 
 * failure this will be NULL.
153
 
 */
154
 
DRIZZLE_API
155
 
drizzle_st *drizzle_create(drizzle_st *drizzle);
156
 
 
157
 
/**
158
 
 * Clone a drizzle structure.
159
 
 *
160
 
 * @param[in] drizzle Caller allocated structure, or NULL to allocate one.
161
 
 * @param[in] from Drizzle structure to use as a source to clone from.
162
 
 * @return Same return as drizzle_create().
163
 
 */
164
 
DRIZZLE_API
165
 
drizzle_st *drizzle_clone(drizzle_st *drizzle, const drizzle_st *from);
166
 
 
167
 
/**
168
 
 * Free a drizzle structure.
169
 
 *
170
 
 * @param[in] drizzle Drizzle structure previously initialized with
171
 
 *  drizzle_create() or drizzle_clone().
172
 
 */
173
 
DRIZZLE_API
174
 
void drizzle_free(drizzle_st *drizzle);
175
 
 
176
 
/**
177
 
 * Return an error string for last error encountered.
178
 
 *
179
 
 * @param[in] drizzle Drizzle structure previously initialized with
180
 
 *  drizzle_create() or drizzle_clone().
181
 
 * @return Pointer to static buffer in library that holds an error string.
182
 
 */
183
 
DRIZZLE_API
184
 
const char *drizzle_error(const drizzle_st *drizzle);
185
 
 
186
 
/**
187
 
 * Value of errno in the case of a DRIZZLE_RETURN_ERRNO return value.
188
 
 *
189
 
 * @param[in] drizzle Drizzle structure previously initialized with
190
 
 *  drizzle_create() or drizzle_clone().
191
 
 * @return An errno value as defined in your system errno.h file.
192
 
 */
193
 
DRIZZLE_API
194
 
int drizzle_errno(const drizzle_st *drizzle);
195
 
 
196
 
/**
197
 
 * Get server defined error code for the last result read.
198
 
 *
199
 
 * @param[in] drizzle Drizzle structure previously initialized with
200
 
 *  drizzle_create() or drizzle_clone().
201
 
 * @return An error code given back in the server response.
202
 
 */
203
 
DRIZZLE_API
204
 
uint16_t drizzle_error_code(const drizzle_st *drizzle);
205
 
 
206
 
/**
207
 
 * Get SQL state code for the last result read.
208
 
 *
209
 
 * @param[in] drizzle Drizzle structure previously initialized with
210
 
 *  drizzle_create() or drizzle_clone().
211
 
 * @return A SQLSTATE code given back in the server response.
212
 
 */
213
 
DRIZZLE_API
214
 
const char *drizzle_sqlstate(const drizzle_st *drizzle);
215
 
 
216
 
/**
217
 
 * Get options for a drizzle structure.
218
 
 *
219
 
 * @param[in] drizzle Drizzle structure previously initialized with
220
 
 *  drizzle_create() or drizzle_clone().
221
 
 * @return Options set for the drizzle structure.
222
 
 */
223
 
DRIZZLE_API
224
 
drizzle_options_t drizzle_options(const drizzle_st *drizzle);
225
 
 
226
 
/**
227
 
 * Set options for a drizzle structure.
228
 
 *
229
 
 * @param[in] drizzle Drizzle structure previously initialized with
230
 
 *  drizzle_create() or drizzle_clone().
231
 
 * @param[in] options Available options for drizzle structure to set.
232
 
 */
233
 
DRIZZLE_API
234
 
void drizzle_set_options(drizzle_st *drizzle, drizzle_options_t options);
235
 
 
236
 
/**
237
 
 * Add options for a drizzle structure.
238
 
 *
239
 
 * @param[in] drizzle Drizzle structure previously initialized with
240
 
 *  drizzle_create() or drizzle_clone().
241
 
 * @param[in] options Available options for drizzle structure to add.
242
 
 */
243
 
DRIZZLE_API
244
 
void drizzle_add_options(drizzle_st *drizzle, drizzle_options_t options);
245
 
 
246
 
/**
247
 
 * Remove options for a drizzle structure.
248
 
 *
249
 
 * @param[in] drizzle Drizzle structure previously initialized with
250
 
 *  drizzle_create() or drizzle_clone().
251
 
 * @param[in] options Available options for drizzle structure to remove.
252
 
 */
253
 
DRIZZLE_API
254
 
void drizzle_remove_options(drizzle_st *drizzle, drizzle_options_t options);
255
 
 
256
 
/**
257
 
 * Get application context pointer.
258
 
 *
259
 
 * @param[in] drizzle Drizzle structure previously initialized with
260
 
 *  drizzle_create() or drizzle_clone().
261
 
 * @return Application context that was previously set, or NULL.
262
 
 */
263
 
DRIZZLE_API
264
 
void *drizzle_context(const drizzle_st *drizzle);
265
 
 
266
 
/**
267
 
 * Set application context pointer.
268
 
 *
269
 
 * @param[in] drizzle Drizzle structure previously initialized with
270
 
 *  drizzle_create() or drizzle_clone().
271
 
 * @param[in] context Application context to set.
272
 
 */
273
 
DRIZZLE_API
274
 
void drizzle_set_context(drizzle_st *drizzle, void *context);
275
 
 
276
 
/**
277
 
 * Set function to call when the drizzle structure is being cleaned up so
278
 
 * the application can clean up the context pointer.
279
 
 *
280
 
 * @param[in] drizzle Drizzle structure previously initialized with
281
 
 *  drizzle_create() or drizzle_clone().
282
 
 * @param[in] function Function to call to clean up drizzle context.
283
 
 */
284
 
DRIZZLE_API
285
 
void drizzle_set_context_free_fn(drizzle_st *drizzle,
286
 
                                 drizzle_context_free_fn *function);
287
 
 
288
 
/**
289
 
 * Get current socket I/O activity timeout value.
290
 
 *
291
 
 * @param[in] drizzle Drizzle structure previously initialized with
292
 
 *  drizzle_create() or drizzle_clone().
293
 
 * @return Timeout in milliseconds to wait for I/O activity. A negative value
294
 
 *  means an infinite timeout.
295
 
 */
296
 
DRIZZLE_API
297
 
int drizzle_timeout(const drizzle_st *drizzle);
298
 
 
299
 
/**
300
 
 * Set socket I/O activity timeout for connections in a Drizzle structure.
301
 
 *
302
 
 * @param[in] drizzle Drizzle structure previously initialized with
303
 
 *  drizzle_create() or drizzle_clone().
304
 
 * @param[in] timeout Milliseconds to wait for I/O activity. A negative value
305
 
 *  means an infinite timeout.
306
 
 */
307
 
DRIZZLE_API
308
 
void drizzle_set_timeout(drizzle_st *drizzle, int timeout);
309
 
 
310
 
/**
311
 
 * Get current verbosity threshold for logging messages.
312
 
 *
313
 
 * @param[in] drizzle Drizzle structure previously initialized with
314
 
 *  drizzle_create() or drizzle_clone().
315
 
 * @return Current verbosity threshold.
316
 
 */
317
 
DRIZZLE_API
318
 
drizzle_verbose_t drizzle_verbose(const drizzle_st *drizzle);
319
 
 
320
 
/**
321
 
 * Set verbosity threshold for logging messages. If this is set above
322
 
 * DRIZZLE_VERBOSE_NEVER and the drizzle_set_log_fn() callback is set to NULL,
323
 
 * messages are printed to STDOUT.
324
 
 *
325
 
 * @param[in] drizzle Drizzle structure previously initialized with
326
 
 *  drizzle_create() or drizzle_clone().
327
 
 * @param[in] verbose Verbosity threshold of what to log.
328
 
 */
329
 
DRIZZLE_API
330
 
void drizzle_set_verbose(drizzle_st *drizzle, drizzle_verbose_t verbose);
331
 
 
332
 
/**
333
 
 * Set logging function for a drizzle structure. This function is only called
334
 
 * for log messages that are above the verbosity threshold set with
335
 
 * drizzle_set_verbose().
336
 
 *
337
 
 * @param[in] drizzle Drizzle structure previously initialized with
338
 
 *  drizzle_create() or drizzle_clone().
339
 
 * @param[in] function Function to call when there is a logging message.
340
 
 * @param[in] context Argument to pass into the callback function.
341
 
 */
342
 
DRIZZLE_API
343
 
void drizzle_set_log_fn(drizzle_st *drizzle, drizzle_log_fn *function,
344
 
                        void *context);
345
 
 
346
 
/**
347
 
 * Set a custom I/O event watcher function for a drizzle structure. Used to
348
 
 * integrate libdrizzle with a custom event loop. The callback will be invoked
349
 
 * to register or deregister interest in events for a connection. When the
350
 
 * events are triggered, drizzle_con_set_revents() should be called to
351
 
 * indicate which events are ready. The event loop should stop waiting for
352
 
 * these events, as libdrizzle will call the callback again if it is still
353
 
 * interested. To resume processing, the libdrizzle function that returned
354
 
 * DRIZZLE_RETURN_IO_WAIT should be called again. See drizzle_event_watch_fn().
355
 
 *
356
 
 * @param[in] drizzle Drizzle structure previously initialized with
357
 
 *  drizzle_create() or drizzle_clone().
358
 
 * @param[in] function Function to call when there is an I/O event.
359
 
 * @param[in] context Argument to pass into the callback function.
360
 
 */
361
 
DRIZZLE_API
362
 
void drizzle_set_event_watch_fn(drizzle_st *drizzle,
363
 
                                drizzle_event_watch_fn *function,
364
 
                                void *context);
365
 
 
366
 
/**
367
 
 * Initialize a connection structure. Always check the return value even if
368
 
 * passing in a pre-allocated structure. Some other initialization may have
369
 
 * failed.
370
 
 *
371
 
 * @param[in] drizzle Drizzle structure previously initialized with
372
 
 *  drizzle_create() or drizzle_clone().
373
 
 * @param[in] con Caller allocated structure, or NULL to allocate one.
374
 
 * @return On success, a pointer to the (possibly allocated) structure. On
375
 
 *  failure this will be NULL.
376
 
 */
377
 
DRIZZLE_API
378
 
drizzle_con_st *drizzle_con_create(drizzle_st *drizzle, drizzle_con_st *con);
379
 
 
380
 
/**
381
 
 * Clone a connection structure.
382
 
 *
383
 
 * @param[in] drizzle Drizzle structure previously initialized with
384
 
 *  drizzle_create() or drizzle_clone().
385
 
 * @param[in] con Caller allocated structure, or NULL to allocate one.
386
 
 * @param[in] from Connection structure to use as a source to clone from.
387
 
 * @return Same return as drizzle_con_create().
388
 
 */
389
 
DRIZZLE_API
390
 
drizzle_con_st *drizzle_con_clone(drizzle_st *drizzle, drizzle_con_st *con,
391
 
                                  const drizzle_con_st *from);
392
 
 
393
 
/**
394
 
 * Free a connection structure.
395
 
 *
396
 
 * @param[in] con Connection structure previously initialized with
397
 
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
398
 
 */
399
 
DRIZZLE_API
400
 
void drizzle_con_free(drizzle_con_st *con);
401
 
 
402
 
/**
403
 
 * Free all connections in a drizzle structure.
404
 
 *
405
 
 * @param[in] drizzle Drizzle structure previously initialized with
406
 
 *  drizzle_create() or drizzle_clone().
407
 
 */
408
 
DRIZZLE_API
409
 
void drizzle_con_free_all(drizzle_st *drizzle);
410
 
 
411
 
/**
412
 
 * Wait for I/O on connections.
413
 
 *
414
 
 * @param[in] drizzle Drizzle structure previously initialized with
415
 
 *  drizzle_create() or drizzle_clone().
416
 
 * @return Standard drizzle return value.
417
 
 */
418
 
DRIZZLE_API
419
 
drizzle_return_t drizzle_con_wait(drizzle_st *drizzle);
420
 
 
421
 
/**
422
 
 * Get next connection that is ready for I/O.
423
 
 *
424
 
 * @param[in] drizzle Drizzle structure previously initialized with
425
 
 *  drizzle_create() or drizzle_clone().
426
 
 * @return Connection that is ready for I/O, or NULL if there are none.
427
 
 */
428
 
DRIZZLE_API
429
 
drizzle_con_st *drizzle_con_ready(drizzle_st *drizzle);
430
 
 
431
 
/** @} */
432
 
 
433
 
#ifdef  __cplusplus
434
 
}
435
 
#endif
436
 
 
437
 
#endif /* __DRIZZLE_H */