← Back to branch summary

~ubuntu-branches/ubuntu/quantal/drizzle/quantal

« back to all changes in this revision

Viewing changes to libdrizzle-1.0/drizzle.h

  • Committer: Package Import Robot
  • Author(s): Clint Byrum
  • Date: 2012-06-19 10:46:49 UTC
  • mfrom: (1.2.11) (2.1.16 sid)
  • Revision ID: package-import@ubuntu.com-20120619104649-9ij634mxm4x8pp4l
Tags: 1:7.1.36-stable-1ubuntu1
https://launchpad.net/bugs/987575
* Merge from Debian unstable. (LP: #987575)
  Remaining changes:
  - Added upstart script.
* debian/drizzle.upstart: dropped logger since upstart logs job
  output now.

Show diffs side-by-side

added added

removed removed

Lines of Context:
libdrizzle-1.0/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
#pragma once
 
38
 
 
39
/**
 
40
 * @file
 
41
 * @brief Drizzle Declarations
 
42
 */
 
43
 
 
44
#include <inttypes.h>
 
45
#include <sys/types.h>
 
46
 
 
47
#ifdef _WIN32
 
48
# define WIN32_LEAN_AND_MEAN
 
49
 
 
50
# include <Windows.h>
 
51
# include <winsock2.h>
 
52
# include <ws2tcpip.h>
 
53
# include <io.h>
 
54
 
 
55
# undef close
 
56
# define close _close
 
57
typedef unsigned int in_port_t;
 
58
typedef long ssize_t;
 
59
 
 
60
# define snprintf _snprintf
 
61
# define inline __inline
 
62
 
 
63
struct sockaddr_un
 
64
{
 
65
  short int sun_family;
 
66
  char sun_path[108];
 
67
};
 
68
 
 
69
# define poll WSAPoll
 
70
//# define pollfd WSAPOLLFD
 
71
 
 
72
#if defined(__GNUC__)
 
73
# include <stdbool.h>
 
74
#else
 
75
# if !defined(__cplusplus)
 
76
typedef enum { false = 0, true = 1 } _Bool;
 
77
typedef _Bool bool;
 
78
#endif 
 
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-1.0/visibility.h>
 
97
#include <libdrizzle-1.0/constants.h>
 
98
#include <libdrizzle-1.0/structs.h>
 
99
#include <libdrizzle-1.0/conn.h>
 
100
#include <libdrizzle-1.0/result.h>
 
101
#include <libdrizzle-1.0/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