← Back to branch summary

~drizzle-trunk/drizzle/development

« back to all changes in this revision

Viewing changes to libdrizzle/drizzle.h

Removed/replaced DBUG symbols and TRUE/FALSE

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
 
 * 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 */