18 * A query handle |
18 * A query handle |
19 */ |
19 */ |
20 struct evsql_query; |
20 struct evsql_query; |
21 |
21 |
22 /* |
22 /* |
|
23 * Parameter type |
|
24 */ |
|
25 enum evsql_param_format { |
|
26 EVSQL_FMT_TEXT, |
|
27 EVSQL_FMT_BINARY, |
|
28 }; |
|
29 |
|
30 enum evsql_param_type { |
|
31 EVSQL_PARAM_INVALID, |
|
32 |
|
33 EVSQL_PARAM_NULL, |
|
34 |
|
35 EVSQL_PARAM_STRING, |
|
36 EVSQL_PARAM_UINT16, |
|
37 EVSQL_PARAM_UINT32, |
|
38 EVSQL_PARAM_UINT64, |
|
39 }; |
|
40 |
|
41 /* |
23 * Query parameter info. |
42 * Query parameter info. |
24 * |
43 * |
25 * Use the EVSQL_PARAM_* macros to define the value of list |
44 * Use the EVSQL_PARAM_* macros to define the value of list |
26 */ |
45 */ |
27 struct evsql_query_params { |
46 struct evsql_query_params { |
28 // nonzero to get results in binary format |
47 // nonzero to get results in binary format |
29 int result_binary; |
48 enum evsql_param_format result_fmt; |
30 |
49 |
31 // the list of parameters, terminated by { 0, 0 } |
50 // the list of parameters, terminated by { 0, 0 } |
32 struct evsql_query_param { |
51 struct evsql_query_param { |
33 // the textual or binary value for this parameter |
52 // the param type |
34 char *value; |
53 enum evsql_param_type type; |
|
54 |
|
55 // pointer to the raw data |
|
56 const char *data_raw; |
|
57 |
|
58 // the value |
|
59 union { |
|
60 uint16_t uint16; |
|
61 uint32_t uint32; |
|
62 uint64_t uint64; |
|
63 } data; |
35 |
64 |
36 // the explicit length of the parameter if it's binary. Must be non-zero for NULL values. |
65 // the explicit length of the parameter if it's binary, zero for text. |
37 int length; |
66 // set to -1 to indicate that the value is still missing |
|
67 ssize_t length; |
38 } list[]; |
68 } list[]; |
39 }; |
69 }; |
40 |
70 |
41 // macros for defining evsql_query_params |
71 // macros for defining evsql_query_params |
42 #define EVSQL_PARAM_NULL { NULL, 1 } |
72 #define EVSQL_PARAMS(result_fmt) { result_fmt, |
43 #define EVSQL_PARAM_TEXT(value) { value, 0 } |
73 #define EVSQL_PARAM(typenam) { EVSQL_PARAM_ ## typenam, NULL } |
44 #define EVSQL_PARAM_BINARY(value, length) { value, length } |
74 #define EVSQL_PARAMS_END { EVSQL_PARAM_INVALID, NULL } \ |
|
75 } // <<< |
45 |
76 |
46 /* |
77 /* |
47 * Result type |
78 * Result type |
48 */ |
79 */ |
|
80 union evsql_result { |
|
81 // libpq |
|
82 PGresult *pq; |
|
83 }; |
|
84 |
49 struct evsql_result_info { |
85 struct evsql_result_info { |
50 struct evsql *evsql; |
86 struct evsql *evsql; |
51 |
87 |
52 int error; |
88 int error; |
53 |
89 |
54 union { |
90 union evsql_result result; |
55 // XXX: libpq |
|
56 PGresult *pq; |
|
57 |
|
58 } result; |
|
59 }; |
91 }; |
60 |
92 |
61 /* |
93 /* |
62 * Callback for handling query-level errors. |
94 * Callback for handling query-level errors. |
63 * |
95 * |
64 * The query has completed, either succesfully or unsuccesfully (look at info.error). |
96 * The query has completed, either succesfully or unsuccesfully (look at info.error). |
65 * info.result contains the result à la the evsql's type. |
97 * info.result contains the result à la the evsql's type. |
66 */ |
98 */ |
67 typedef void (*evsql_query_cb)(struct evsql_result_info info, void *arg); |
99 typedef void (*evsql_query_cb)(const struct evsql_result_info *res, void *arg); |
68 |
100 |
69 /* |
101 /* |
70 * Callback for handling connection-level errors. |
102 * Callback for handling connection-level errors. |
71 * |
103 * |
72 * The SQL context/connection suffered an error. It is not valid anymore, and may not be used. |
104 * The SQL context/connection suffered an error. It is not valid anymore, and may not be used. |
84 struct evsql_query *evsql_query (struct evsql *evsql, const char *command, evsql_query_cb query_fn, void *cb_arg); |
116 struct evsql_query *evsql_query (struct evsql *evsql, const char *command, evsql_query_cb query_fn, void *cb_arg); |
85 |
117 |
86 /* |
118 /* |
87 * Same, but uses the SQL-level support for binding parameters. |
119 * Same, but uses the SQL-level support for binding parameters. |
88 */ |
120 */ |
89 struct evsql_query *evsql_query_params (struct evsql *evsql, const char *command, struct evsql_query_params params, evsql_query_cb query_fn, void *cb_arg); |
121 struct evsql_query *evsql_query_params (struct evsql *evsql, const char *command, const struct evsql_query_params *params, evsql_query_cb query_fn, void *cb_arg); |
|
122 |
|
123 /* |
|
124 * Param-building functions |
|
125 */ |
|
126 int evsql_param_string (struct evsql_query_params *params, size_t param, const char *ptr); |
|
127 int evsql_param_uint32 (struct evsql_query_params *params, size_t param, uint32_t uval); |
|
128 |
|
129 /* |
|
130 * Result-handling functions |
|
131 */ |
|
132 |
|
133 // get error message associated with function |
|
134 const char *evsql_result_error (const struct evsql_result_info *res); |
|
135 |
|
136 // number of rows in the result |
|
137 size_t evsql_result_rows (const struct evsql_result_info *res); |
|
138 |
|
139 // number of columns in the result |
|
140 size_t evsql_result_cols (const struct evsql_result_info *res); |
|
141 |
|
142 // fetch the raw binary value from a result set, and return it via ptr |
|
143 // if size is nonzero, check that the size of the field data matches |
|
144 int evsql_result_binary (const struct evsql_result_info *res, size_t row, size_t col, const char **ptr, size_t size, int nullok); |
|
145 int evsql_result_string (const struct evsql_result_info *res, size_t row, size_t col, const char **ptr, int nullok); |
|
146 |
|
147 // fetch certain kinds of values from a binary result set |
|
148 int evsql_result_uint16 (const struct evsql_result_info *res, size_t row, size_t col, uint16_t *uval, int nullok); |
|
149 int evsql_result_uint32 (const struct evsql_result_info *res, size_t row, size_t col, uint32_t *uval, int nullok); |
|
150 int evsql_result_uint64 (const struct evsql_result_info *res, size_t row, size_t col, uint64_t *uval, int nullok); |
|
151 |
|
152 // release the result set, freeing its memory |
|
153 void evsql_result_free (const struct evsql_result_info *res); |
|
154 |
|
155 // platform-dependant aliases |
|
156 #define evsql_result_ushort evsql_result_uint16 |
|
157 |
|
158 #if _LP64 |
|
159 #define evsql_result_ulong evsql_result_uint64 |
|
160 #else |
|
161 #define evsql_result_ulong evsql_result_uint32 |
|
162 #endif /* _LP64 */ |
90 |
163 |
91 /* |
164 /* |
92 * Close a connection. Callbacks for waiting queries will not be run. |
165 * Close a connection. Callbacks for waiting queries will not be run. |
93 * |
166 * |
94 * XXX: not implemented yet. |
167 * XXX: not implemented yet. |