~drizzle-trunk/drizzle/development

« back to all changes in this revision

Viewing changes to libdrizzle/conn.h

Added libdrizzle to the tree.

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
 * 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 Connection Declarations
 
14
 */
 
15
 
 
16
#ifndef __DRIZZLE_CONN_H
 
17
#define __DRIZZLE_CONN_H
 
18
 
 
19
#ifdef __cplusplus
 
20
extern "C" {
 
21
#endif
 
22
 
 
23
/**
 
24
 * @addtogroup drizzle_con Connection Declarations
 
25
 * @ingroup drizzle_client_interface
 
26
 * @ingroup drizzle_server_interface
 
27
 * @{
 
28
 */
 
29
 
 
30
/**
 
31
 * Get file descriptor for connection.
 
32
 *
 
33
 * @param[in] con Connection structure previously initialized with
 
34
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
35
 * @return File descriptor of connection, or -1 if not active.
 
36
 */
 
37
DRIZZLE_API
 
38
int drizzle_con_fd(const drizzle_con_st *con);
 
39
 
 
40
/**
 
41
 * Use given file descriptor for connction.
 
42
 *
 
43
 * @param[in] con Connection structure previously initialized with
 
44
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
45
 * @param[in] fd File descriptor for connection.
 
46
 * @return Standard drizzle return value.
 
47
 */
 
48
DRIZZLE_API
 
49
drizzle_return_t drizzle_con_set_fd(drizzle_con_st *con, int fd);
 
50
 
 
51
/**
 
52
 * Close a connection.
 
53
 *
 
54
 * @param[in] con Connection structure previously initialized with
 
55
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
56
 */
 
57
DRIZZLE_API
 
58
void drizzle_con_close(drizzle_con_st *con);
 
59
 
 
60
/**
 
61
 * Set events to be watched for a connection.
 
62
 *
 
63
 * @param[in] con Connection structure previously initialized with
 
64
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
65
 * @param[in] events Bitfield of poll() events to watch.
 
66
 * @return Standard drizzle return value.
 
67
 */
 
68
DRIZZLE_API
 
69
drizzle_return_t drizzle_con_set_events(drizzle_con_st *con, short events);
 
70
 
 
71
/**
 
72
 * Set events that are ready for a connection. This is used with the external
 
73
 * event callbacks. See drizzle_set_event_watch_fn().
 
74
 *
 
75
 * @param[in] con Connection structure previously initialized with
 
76
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
77
 * @param[in] revents Bitfield of poll() events that were detected.
 
78
 * @return Standard drizzle return value.
 
79
 */
 
80
DRIZZLE_API
 
81
drizzle_return_t drizzle_con_set_revents(drizzle_con_st *con, short revents);
 
82
 
 
83
/**
 
84
 * Get the drizzle_st struct that the connection belongs to.
 
85
 *
 
86
 * @param[in] con Connection structure previously initialized with
 
87
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
88
 * @return Drizzle object that this connection is part of.
 
89
 */
 
90
DRIZZLE_API
 
91
drizzle_st *drizzle_con_drizzle(const drizzle_con_st *con);
 
92
 
 
93
/**
 
94
 * Return an error string for last error encountered.
 
95
 *
 
96
 * @param[in] con Connection structure previously initialized with
 
97
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
98
 * @return Pointer to static buffer in library that holds an error string.
 
99
 */
 
100
DRIZZLE_API
 
101
const char *drizzle_con_error(const drizzle_con_st *con);
 
102
 
 
103
/**
 
104
 * Value of errno in the case of a DRIZZLE_RETURN_ERRNO return value.
 
105
 *
 
106
 * @param[in] con Connection structure previously initialized with
 
107
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
108
 * @return An errno value as defined in your system errno.h file.
 
109
 */
 
110
DRIZZLE_API
 
111
int drizzle_con_errno(const drizzle_con_st *con);
 
112
 
 
113
/**
 
114
 * Get server defined error code for the last result read.
 
115
 *
 
116
 * @param[in] con Connection structure previously initialized with
 
117
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
118
 * @return An error code given back in the server response.
 
119
 */
 
120
DRIZZLE_API
 
121
uint16_t drizzle_con_error_code(const drizzle_con_st *con);
 
122
 
 
123
/**
 
124
 * Get SQL state code for the last result read.
 
125
 *
 
126
 * @param[in] con Connection structure previously initialized with
 
127
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
128
 * @return A SQLSTATE code given back in the server response.
 
129
 */
 
130
DRIZZLE_API
 
131
const char *drizzle_con_sqlstate(const drizzle_con_st *con);
 
132
 
 
133
/**
 
134
 * Get options for a connection.
 
135
 *
 
136
 * @param[in] con Connection structure previously initialized with
 
137
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
138
 * @return Options set for the connection structure.
 
139
 */
 
140
DRIZZLE_API
 
141
drizzle_con_options_t drizzle_con_options(const drizzle_con_st *con);
 
142
 
 
143
/**
 
144
 * Set options for a connection.
 
145
 *
 
146
 * @param[in] con Connection structure previously initialized with
 
147
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
148
 * @param[in] options Available options for connection structure to set.
 
149
 */
 
150
DRIZZLE_API
 
151
void drizzle_con_set_options(drizzle_con_st *con,
 
152
                             drizzle_con_options_t options);
 
153
 
 
154
/**
 
155
 * Add options for a connection.
 
156
 *
 
157
 * @param[in] con Connection structure previously initialized with
 
158
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
159
 * @param[in] options Available options for connection structure to set.
 
160
 */
 
161
DRIZZLE_API
 
162
void drizzle_con_add_options(drizzle_con_st *con,
 
163
                             drizzle_con_options_t options);
 
164
 
 
165
/**
 
166
 * Remove options for a connection.
 
167
 *
 
168
 * @param[in] con Connection structure previously initialized with
 
169
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
170
 * @param[in] options Available options for connection structure to remove.
 
171
 */
 
172
DRIZZLE_API
 
173
void drizzle_con_remove_options(drizzle_con_st *con,
 
174
                                drizzle_con_options_t options);
 
175
 
 
176
/**
 
177
 * Get TCP host for a connection.
 
178
 *
 
179
 * @param[in] con Connection structure previously initialized with
 
180
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
181
 * @return Host this connection is configured for, or NULL if not set.
 
182
 */
 
183
DRIZZLE_API
 
184
const char *drizzle_con_host(const drizzle_con_st *con);
 
185
 
 
186
/**
 
187
 * Get TCP port for a connection.
 
188
 *
 
189
 * @param[in] con Connection structure previously initialized with
 
190
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
191
 * @return Port this connection is configured for, 0 if not set.
 
192
 */
 
193
DRIZZLE_API
 
194
in_port_t drizzle_con_port(const drizzle_con_st *con);
 
195
 
 
196
/**
 
197
 * Set TCP host and port for a connection.
 
198
 *
 
199
 * @param[in] con Connection structure previously initialized with
 
200
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
201
 * @param[in] host Host to use for this connection, NULL for default value.
 
202
 * @param[in] port Port to use for this connection, 0 for default value.
 
203
 */
 
204
DRIZZLE_API
 
205
void drizzle_con_set_tcp(drizzle_con_st *con, const char *host, in_port_t port);
 
206
 
 
207
/**
 
208
 * Get unix domain socket for a connection.
 
209
 *
 
210
 * @param[in] con Connection structure previously initialized with
 
211
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
212
 * @return Unix domain socket set for this connection, NULL if not set.
 
213
 */
 
214
DRIZZLE_API
 
215
const char *drizzle_con_uds(const drizzle_con_st *con);
 
216
 
 
217
/**
 
218
 * Set unix domain socket for a connection.
 
219
 *
 
220
 * @param[in] con Connection structure previously initialized with
 
221
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
222
 * @param[in] uds Unix domain socket to use for this connection, NULL for
 
223
 *  defailt value.
 
224
 */
 
225
DRIZZLE_API
 
226
void drizzle_con_set_uds(drizzle_con_st *con, const char *uds);
 
227
 
 
228
/**
 
229
 * Get username for a connection.
 
230
 *
 
231
 * @param[in] con Connection structure previously initialized with
 
232
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
233
 * @return User associated with this connection.
 
234
 */
 
235
DRIZZLE_API
 
236
const char *drizzle_con_user(const drizzle_con_st *con);
 
237
 
 
238
/**
 
239
 * Get password for a connection.
 
240
 *
 
241
 * @param[in] con Connection structure previously initialized with
 
242
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
243
 * @return Password associated with this connection.
 
244
 */
 
245
DRIZZLE_API
 
246
const char *drizzle_con_password(const drizzle_con_st *con);
 
247
 
 
248
/**
 
249
 * Set username and password for a connection.
 
250
 *
 
251
 * @param[in] con Connection structure previously initialized with
 
252
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
253
 * @param[in] user Username to use for this connection.
 
254
 * @param[in] password Password to use for this connection.
 
255
 */
 
256
DRIZZLE_API
 
257
void drizzle_con_set_auth(drizzle_con_st *con, const char *user,
 
258
                          const char *password);
 
259
 
 
260
/**
 
261
 * Get database for a connection.
 
262
 *
 
263
 * @param[in] con Connection structure previously initialized with
 
264
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
265
 * @return Database associated with this connection.
 
266
 */
 
267
DRIZZLE_API
 
268
const char *drizzle_con_db(const drizzle_con_st *con);
 
269
 
 
270
/**
 
271
 * Set database for a connection.
 
272
 *
 
273
 * @param[in] con Connection structure previously initialized with
 
274
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
275
 * @param[in] db Database to use with this connection.
 
276
 */
 
277
DRIZZLE_API
 
278
void drizzle_con_set_db(drizzle_con_st *con, const char *db);
 
279
 
 
280
/**
 
281
 * Get application context pointer for a connection.
 
282
 *
 
283
 * @param[in] con Connection structure previously initialized with
 
284
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
285
 * @return Application context with this connection.
 
286
 */
 
287
DRIZZLE_API
 
288
void *drizzle_con_context(const drizzle_con_st *con);
 
289
 
 
290
/**
 
291
 * Set application context pointer for a connection.
 
292
 *
 
293
 * @param[in] con Connection structure previously initialized with
 
294
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
295
 * @param[in] context Application context to use with this connection.
 
296
 */
 
297
DRIZZLE_API
 
298
void drizzle_con_set_context(drizzle_con_st *con, void *context);
 
299
 
 
300
/**
 
301
 * Set callback function when the context pointer should be freed.
 
302
 *
 
303
 * @param[in] con Connection structure previously initialized with
 
304
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
305
 * @param[in] function Function to call to clean up connection context.
 
306
 */
 
307
DRIZZLE_API
 
308
void drizzle_con_set_context_free_fn(drizzle_con_st *con,
 
309
                                     drizzle_con_context_free_fn *function);
 
310
 
 
311
/**
 
312
 * Get protocol version for a connection.
 
313
 *
 
314
 * @param[in] con Connection structure previously initialized with
 
315
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
316
 * @return Protocol version for connection.
 
317
 */
 
318
DRIZZLE_API
 
319
uint8_t drizzle_con_protocol_version(const drizzle_con_st *con);
 
320
 
 
321
/**
 
322
 * Get server version string for a connection.
 
323
 *
 
324
 * @param[in] con Connection structure previously initialized with
 
325
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
326
 * @return Server version string for connection.
 
327
 */
 
328
DRIZZLE_API
 
329
const char *drizzle_con_server_version(const drizzle_con_st *con);
 
330
 
 
331
/**
 
332
 * Get server version number for a connection.
 
333
 *
 
334
 * @param[in] con Connection structure previously initialized with
 
335
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
336
 * @return Server version number for connection.
 
337
 */
 
338
DRIZZLE_API
 
339
uint32_t drizzle_con_server_version_number(const drizzle_con_st *con);
 
340
 
 
341
/**
 
342
 * Get thread ID for a connection.
 
343
 *
 
344
 * @param[in] con Connection structure previously initialized with
 
345
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
346
 * @return Thread ID for connection.
 
347
 */
 
348
DRIZZLE_API
 
349
uint32_t drizzle_con_thread_id(const drizzle_con_st *con);
 
350
 
 
351
/**
 
352
 * Get scramble buffer for a connection.
 
353
 *
 
354
 * @param[in] con Connection structure previously initialized with
 
355
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
356
 * @return Scramble buffer for connection.
 
357
 */
 
358
DRIZZLE_API
 
359
const uint8_t *drizzle_con_scramble(const drizzle_con_st *con);
 
360
 
 
361
/**
 
362
 * Get capabilities for a connection.
 
363
 *
 
364
 * @param[in] con Connection structure previously initialized with
 
365
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
366
 * @return Capabilities for connection.
 
367
 */
 
368
DRIZZLE_API
 
369
drizzle_capabilities_t drizzle_con_capabilities(const drizzle_con_st *con);
 
370
 
 
371
/**
 
372
 * Get character set for a connection.
 
373
 *
 
374
 * @param[in] con Connection structure previously initialized with
 
375
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
376
 * @return Character set for connection.
 
377
 */
 
378
DRIZZLE_API
 
379
drizzle_charset_t drizzle_con_charset(const drizzle_con_st *con);
 
380
 
 
381
/**
 
382
 * Get status for a connection.
 
383
 *
 
384
 * @param[in] con Connection structure previously initialized with
 
385
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
386
 * @return Status for connection.
 
387
 */
 
388
DRIZZLE_API
 
389
drizzle_con_status_t drizzle_con_status(const drizzle_con_st *con);
 
390
 
 
391
/**
 
392
 * Get max packet size for a connection.
 
393
 *
 
394
 * @param[in] con Connection structure previously initialized with
 
395
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
396
 * @return Max packet size for connection.
 
397
 */
 
398
DRIZZLE_API
 
399
uint32_t drizzle_con_max_packet_size(const drizzle_con_st *con);
 
400
 
 
401
/** @} */
 
402
 
 
403
#ifdef __cplusplus
 
404
}
 
405
#endif
 
406
 
 
407
#endif /* __DRIZZLE_CONN_H */