~drizzle-trunk/drizzle/development

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