~drizzle-trunk/drizzle/development

« back to all changes in this revision

Viewing changes to libdrizzle-2.0/libdrizzle/drizzle.h

  • Committer: Monty Taylor
  • Date: 2011-03-22 18:39:54 UTC
  • mto: (2246.1.1 build)
  • mto: This revision was merged to the branch mainline in revision 2247.
  • Revision ID: mordred@inaugust.com-20110322183954-fz8ciuywjz2llbyo
Split libdrizzle into 1.0 and 2.0. Applied the C++ changes to 2.0 branch.

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
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
# if !defined(__cplusplus)
 
78
typedef enum { false = 0, true = 1 } _Bool;
 
79
typedef _Bool bool;
 
80
#endif 
 
81
#endif
 
82
 
 
83
#else
 
84
# if !defined(__cplusplus)
 
85
#  include <stdbool.h>
 
86
# endif
 
87
# include <sys/socket.h>
 
88
# include <netinet/in.h>
 
89
# include <arpa/inet.h>
 
90
# include <sys/un.h>
 
91
# include <netdb.h>
 
92
# include <poll.h>
 
93
#endif
 
94
 
 
95
#include <assert.h>
 
96
#include <errno.h>
 
97
 
 
98
#include <libdrizzle/visibility.h>
 
99
#include <libdrizzle/constants.h>
 
100
#include <libdrizzle/structs.h>
 
101
#include <libdrizzle/conn.h>
 
102
#include <libdrizzle/result.h>
 
103
#include <libdrizzle/column.h>
 
104
 
 
105
#ifdef  __cplusplus
 
106
extern "C" {
 
107
#endif
 
108
 
 
109
/**
 
110
 * @addtogroup drizzle Drizzle Declarations
 
111
 * @ingroup drizzle_client_interface
 
112
 * @ingroup drizzle_server_interface
 
113
 *
 
114
 * This is the core library structure that other structures (such as
 
115
 * connections) are created from.
 
116
 *
 
117
 * There is no locking within a single drizzle_st structure, so for threaded
 
118
 * applications you must either ensure isolation in the application or use
 
119
 * multiple drizzle_st structures (for example, one for each thread).
 
120
 * @{
 
121
 */
 
122
 
 
123
/**
 
124
 * Get library version string.
 
125
 *
 
126
 * @return Pointer to static buffer in library that holds the version string.
 
127
 */
 
128
DRIZZLE_API
 
129
const char *drizzle_version(void);
 
130
 
 
131
/**
 
132
 * Get bug report URL.
 
133
 *
 
134
 * @return Bug report URL string.
 
135
 */
 
136
DRIZZLE_API
 
137
const char *drizzle_bugreport(void);
 
138
 
 
139
/**
 
140
 * Get string with the name of the given verbose level.
 
141
 *
 
142
 * @param[in] verbose Verbose logging level.
 
143
 * @return String form of verbose level.
 
144
 */
 
145
DRIZZLE_API
 
146
const char *drizzle_verbose_name(drizzle_verbose_t verbose);
 
147
 
 
148
/**
 
149
 * Initialize a drizzle structure. Always check the return value even if passing
 
150
 * in a pre-allocated structure. Some other initialization may have failed.
 
151
 *
 
152
 * @param[in] drizzle Caller allocated structure, or NULL to allocate one.
 
153
 * @return On success, a pointer to the (possibly allocated) structure. On
 
154
 * failure this will be NULL.
 
155
 */
 
156
DRIZZLE_API
 
157
drizzle_st *drizzle_create(drizzle_st *drizzle);
 
158
 
 
159
/**
 
160
 * Clone a drizzle structure.
 
161
 *
 
162
 * @param[in] drizzle Caller allocated structure, or NULL to allocate one.
 
163
 * @param[in] from Drizzle structure to use as a source to clone from.
 
164
 * @return Same return as drizzle_create().
 
165
 */
 
166
DRIZZLE_API
 
167
drizzle_st *drizzle_clone(drizzle_st *drizzle, const drizzle_st *from);
 
168
 
 
169
/**
 
170
 * Free a drizzle structure.
 
171
 *
 
172
 * @param[in] drizzle Drizzle structure previously initialized with
 
173
 *  drizzle_create() or drizzle_clone().
 
174
 */
 
175
DRIZZLE_API
 
176
void drizzle_free(drizzle_st *drizzle);
 
177
 
 
178
/**
 
179
 * Return an error string for last error encountered.
 
180
 *
 
181
 * @param[in] drizzle Drizzle structure previously initialized with
 
182
 *  drizzle_create() or drizzle_clone().
 
183
 * @return Pointer to static buffer in library that holds an error string.
 
184
 */
 
185
DRIZZLE_API
 
186
const char *drizzle_error(const drizzle_st *drizzle);
 
187
 
 
188
/**
 
189
 * Value of errno in the case of a DRIZZLE_RETURN_ERRNO return value.
 
190
 *
 
191
 * @param[in] drizzle Drizzle structure previously initialized with
 
192
 *  drizzle_create() or drizzle_clone().
 
193
 * @return An errno value as defined in your system errno.h file.
 
194
 */
 
195
DRIZZLE_API
 
196
int drizzle_errno(const drizzle_st *drizzle);
 
197
 
 
198
/**
 
199
 * Get server defined error code for the last result read.
 
200
 *
 
201
 * @param[in] drizzle Drizzle structure previously initialized with
 
202
 *  drizzle_create() or drizzle_clone().
 
203
 * @return An error code given back in the server response.
 
204
 */
 
205
DRIZZLE_API
 
206
uint16_t drizzle_error_code(const drizzle_st *drizzle);
 
207
 
 
208
/**
 
209
 * Get SQL state code for the last result read.
 
210
 *
 
211
 * @param[in] drizzle Drizzle structure previously initialized with
 
212
 *  drizzle_create() or drizzle_clone().
 
213
 * @return A SQLSTATE code given back in the server response.
 
214
 */
 
215
DRIZZLE_API
 
216
const char *drizzle_sqlstate(const drizzle_st *drizzle);
 
217
 
 
218
/**
 
219
 * Get options for a drizzle structure.
 
220
 *
 
221
 * @param[in] drizzle Drizzle structure previously initialized with
 
222
 *  drizzle_create() or drizzle_clone().
 
223
 * @return Options set for the drizzle structure.
 
224
 */
 
225
DRIZZLE_API
 
226
int drizzle_options(const drizzle_st *drizzle);
 
227
 
 
228
/**
 
229
 * Set options for a drizzle structure.
 
230
 *
 
231
 * @param[in] drizzle Drizzle structure previously initialized with
 
232
 *  drizzle_create() or drizzle_clone().
 
233
 * @param[in] options Available options for drizzle structure to set.
 
234
 */
 
235
DRIZZLE_API
 
236
void drizzle_set_options(drizzle_st *drizzle, int options);
 
237
 
 
238
/**
 
239
 * Add options for a drizzle structure.
 
240
 *
 
241
 * @param[in] drizzle Drizzle structure previously initialized with
 
242
 *  drizzle_create() or drizzle_clone().
 
243
 * @param[in] options Available options for drizzle structure to add.
 
244
 */
 
245
DRIZZLE_API
 
246
void drizzle_add_options(drizzle_st *drizzle, int options);
 
247
 
 
248
/**
 
249
 * Remove options for a drizzle structure.
 
250
 *
 
251
 * @param[in] drizzle Drizzle structure previously initialized with
 
252
 *  drizzle_create() or drizzle_clone().
 
253
 * @param[in] options Available options for drizzle structure to remove.
 
254
 */
 
255
DRIZZLE_API
 
256
void drizzle_remove_options(drizzle_st *drizzle, drizzle_options_t options);
 
257
 
 
258
/**
 
259
 * Get application context pointer.
 
260
 *
 
261
 * @param[in] drizzle Drizzle structure previously initialized with
 
262
 *  drizzle_create() or drizzle_clone().
 
263
 * @return Application context that was previously set, or NULL.
 
264
 */
 
265
DRIZZLE_API
 
266
void *drizzle_context(const drizzle_st *drizzle);
 
267
 
 
268
/**
 
269
 * Set application context pointer.
 
270
 *
 
271
 * @param[in] drizzle Drizzle structure previously initialized with
 
272
 *  drizzle_create() or drizzle_clone().
 
273
 * @param[in] context Application context to set.
 
274
 */
 
275
DRIZZLE_API
 
276
void drizzle_set_context(drizzle_st *drizzle, void *context);
 
277
 
 
278
/**
 
279
 * Set function to call when the drizzle structure is being cleaned up so
 
280
 * the application can clean up the context pointer.
 
281
 *
 
282
 * @param[in] drizzle Drizzle structure previously initialized with
 
283
 *  drizzle_create() or drizzle_clone().
 
284
 * @param[in] function Function to call to clean up drizzle context.
 
285
 */
 
286
DRIZZLE_API
 
287
void drizzle_set_context_free_fn(drizzle_st *drizzle,
 
288
                                 drizzle_context_free_fn *function);
 
289
 
 
290
/**
 
291
 * Get current socket I/O activity timeout value.
 
292
 *
 
293
 * @param[in] drizzle Drizzle structure previously initialized with
 
294
 *  drizzle_create() or drizzle_clone().
 
295
 * @return Timeout in milliseconds to wait for I/O activity. A negative value
 
296
 *  means an infinite timeout.
 
297
 */
 
298
DRIZZLE_API
 
299
int drizzle_timeout(const drizzle_st *drizzle);
 
300
 
 
301
/**
 
302
 * Set socket I/O activity timeout for connections in a Drizzle structure.
 
303
 *
 
304
 * @param[in] drizzle Drizzle structure previously initialized with
 
305
 *  drizzle_create() or drizzle_clone().
 
306
 * @param[in] timeout Milliseconds to wait for I/O activity. A negative value
 
307
 *  means an infinite timeout.
 
308
 */
 
309
DRIZZLE_API
 
310
void drizzle_set_timeout(drizzle_st *drizzle, int timeout);
 
311
 
 
312
/**
 
313
 * Get current verbosity threshold for logging messages.
 
314
 *
 
315
 * @param[in] drizzle Drizzle structure previously initialized with
 
316
 *  drizzle_create() or drizzle_clone().
 
317
 * @return Current verbosity threshold.
 
318
 */
 
319
DRIZZLE_API
 
320
drizzle_verbose_t drizzle_verbose(const drizzle_st *drizzle);
 
321
 
 
322
/**
 
323
 * Set verbosity threshold for logging messages. If this is set above
 
324
 * DRIZZLE_VERBOSE_NEVER and the drizzle_set_log_fn() callback is set to NULL,
 
325
 * messages are printed to STDOUT.
 
326
 *
 
327
 * @param[in] drizzle Drizzle structure previously initialized with
 
328
 *  drizzle_create() or drizzle_clone().
 
329
 * @param[in] verbose Verbosity threshold of what to log.
 
330
 */
 
331
DRIZZLE_API
 
332
void drizzle_set_verbose(drizzle_st *drizzle, drizzle_verbose_t verbose);
 
333
 
 
334
/**
 
335
 * Set logging function for a drizzle structure. This function is only called
 
336
 * for log messages that are above the verbosity threshold set with
 
337
 * drizzle_set_verbose().
 
338
 *
 
339
 * @param[in] drizzle Drizzle structure previously initialized with
 
340
 *  drizzle_create() or drizzle_clone().
 
341
 * @param[in] function Function to call when there is a logging message.
 
342
 * @param[in] context Argument to pass into the callback function.
 
343
 */
 
344
DRIZZLE_API
 
345
void drizzle_set_log_fn(drizzle_st *drizzle, drizzle_log_fn *function,
 
346
                        void *context);
 
347
 
 
348
/**
 
349
 * Set a custom I/O event watcher function for a drizzle structure. Used to
 
350
 * integrate libdrizzle with a custom event loop. The callback will be invoked
 
351
 * to register or deregister interest in events for a connection. When the
 
352
 * events are triggered, drizzle_con_set_revents() should be called to
 
353
 * indicate which events are ready. The event loop should stop waiting for
 
354
 * these events, as libdrizzle will call the callback again if it is still
 
355
 * interested. To resume processing, the libdrizzle function that returned
 
356
 * DRIZZLE_RETURN_IO_WAIT should be called again. See drizzle_event_watch_fn().
 
357
 *
 
358
 * @param[in] drizzle Drizzle structure previously initialized with
 
359
 *  drizzle_create() or drizzle_clone().
 
360
 * @param[in] function Function to call when there is an I/O event.
 
361
 * @param[in] context Argument to pass into the callback function.
 
362
 */
 
363
DRIZZLE_API
 
364
void drizzle_set_event_watch_fn(drizzle_st *drizzle,
 
365
                                drizzle_event_watch_fn *function,
 
366
                                void *context);
 
367
 
 
368
/**
 
369
 * Initialize a connection structure. Always check the return value even if
 
370
 * passing in a pre-allocated structure. Some other initialization may have
 
371
 * failed.
 
372
 *
 
373
 * @param[in] drizzle Drizzle structure previously initialized with
 
374
 *  drizzle_create() or drizzle_clone().
 
375
 * @param[in] con Caller allocated structure, or NULL to allocate one.
 
376
 * @return On success, a pointer to the (possibly allocated) structure. On
 
377
 *  failure this will be NULL.
 
378
 */
 
379
DRIZZLE_API
 
380
drizzle_con_st *drizzle_con_create(drizzle_st *drizzle, drizzle_con_st *con);
 
381
 
 
382
/**
 
383
 * Clone a connection structure.
 
384
 *
 
385
 * @param[in] drizzle Drizzle structure previously initialized with
 
386
 *  drizzle_create() or drizzle_clone().
 
387
 * @param[in] con Caller allocated structure, or NULL to allocate one.
 
388
 * @param[in] from Connection structure to use as a source to clone from.
 
389
 * @return Same return as drizzle_con_create().
 
390
 */
 
391
DRIZZLE_API
 
392
drizzle_con_st *drizzle_con_clone(drizzle_st *drizzle, drizzle_con_st *con,
 
393
                                  const drizzle_con_st *from);
 
394
 
 
395
/**
 
396
 * Free a connection structure.
 
397
 *
 
398
 * @param[in] con Connection structure previously initialized with
 
399
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
400
 */
 
401
DRIZZLE_API
 
402
void drizzle_con_free(drizzle_con_st *con);
 
403
 
 
404
/**
 
405
 * Free all connections in a drizzle structure.
 
406
 *
 
407
 * @param[in] drizzle Drizzle structure previously initialized with
 
408
 *  drizzle_create() or drizzle_clone().
 
409
 */
 
410
DRIZZLE_API
 
411
void drizzle_con_free_all(drizzle_st *drizzle);
 
412
 
 
413
/**
 
414
 * Wait for I/O on connections.
 
415
 *
 
416
 * @param[in] drizzle Drizzle structure previously initialized with
 
417
 *  drizzle_create() or drizzle_clone().
 
418
 * @return Standard drizzle return value.
 
419
 */
 
420
DRIZZLE_API
 
421
drizzle_return_t drizzle_con_wait(drizzle_st *drizzle);
 
422
 
 
423
/**
 
424
 * Get next connection that is ready for I/O.
 
425
 *
 
426
 * @param[in] drizzle Drizzle structure previously initialized with
 
427
 *  drizzle_create() or drizzle_clone().
 
428
 * @return Connection that is ready for I/O, or NULL if there are none.
 
429
 */
 
430
DRIZZLE_API
 
431
drizzle_con_st *drizzle_con_ready(drizzle_st *drizzle);
 
432
 
 
433
/** @} */
 
434
 
 
435
#ifdef  __cplusplus
 
436
}
 
437
#endif
 
438
 
 
439
#endif /* __DRIZZLE_H */