libpqtypes - libpqtypes.h

Home Page

array.c
datetime.c
error.c
events.c
exec.c
geo.c
getaddrinfo.h
handler.c
libpqtypes-int.h
libpqtypes.h
misc.c
network.c
numerics.c
param.c
port.c
record.c
regression-test.c
spec.c
utils.c
varlena.c
  1 
  2 /*
  3  * libpqtypes.h
  4  *   Public header for libpqtypes.  Contains the entire public API.
  5  *
  6  * Copyright (c) 2011 eSilo, LLC. All rights reserved.
  7  * This is free software; see the source for copying conditions.  There is
  8  * NO warranty; not even for MERCHANTABILITY or  FITNESS FOR A  PARTICULAR
  9  * PURPOSE.
 10  */
 11 
 12 #ifndef LIBPQTYPES_H
 13 #define LIBPQTYPES_H
 14 
 15 #include <libpq-fe.h>
 16 #include <time.h>
 17 #include <stdarg.h>
 18 
 19 #ifdef __cplusplus
 20 extern "C" {
 21 #endif
 22 
 23 #if defined(_MSC_VER) || defined(__MINGW32__) || defined(__CYGWIN__)
 24 # define PQT_EXPORT __declspec(dllexport)
 25 #else
 26 # define PQT_EXPORT extern
 27 #endif
 28 
 29 /* MSVC 6 must use `i64', everything else uses `LL'. */
 30 #if !defined(_MSC_VER) || _MSC_VER > 1200
 31 # define PQT_INT64CONST(x) ((PGint8) x##LL)
 32 #else
 33 # define PQT_INT64CONST(x) ((PGint8) x##i64)
 34 #endif
 35 
 36 enum
 37 {
 38   PQT_SUBCLASS,
 39   PQT_COMPOSITE,
 40   PQT_USERDEFINED
 41 };
 42 
 43 typedef struct pg_param PGparam;
 44 typedef struct pg_typeargs PGtypeArgs;
 45 typedef int (*PGtypeProc)(PGtypeArgs *args);
 46 
 47 /* For use with a PQregisterXXX function */
 48 typedef struct
 49 {
 50   const char *typname;
 51   PGtypeProc typput;
 52   PGtypeProc typget;
 53 } PGregisterType;
 54 
 55 typedef struct
 56 {
 57   int sversion;
 58   int pversion;
 59   char datestyle[48];
 60   int integer_datetimes;
 61 } PGtypeFormatInfo;
 62 
 63 /* Record Attribute Description, its columns */
 64 typedef struct
 65 {
 66   Oid attoid;
 67   int attlen;
 68   int atttypmod;
 69   char attname[65];
 70 } PGrecordAttDesc;
 71 
 72 /* Type handler for putf and getf functions.  The char fixed length buffers
 73  * used to be allocated pointers.  This was a performance problem when
 74  * many type handlers are registered and one uses getf on a composite or
 75  * an array.  These types require generating a PGresult and duplicating
 76  * the type handlers.  Saved 40% by not having to deep copy the strings.
 77  */
 78 typedef struct pg_typhandler
 79 {
 80   int id;
 81   char typschema[65];
 82   char typname[65];
 83   int typlen;
 84   Oid typoid;
 85   Oid typoid_array;
 86   PGtypeProc typput;
 87   PGtypeProc typget;
 88   int base_id;
 89 
 90   /* For composites, contains each attribute of a composite */
 91   int nattrs;
 92   int freeAttDescs;
 93   PGrecordAttDesc attDescsBuf[16];
 94   PGrecordAttDesc *attDescs;
 95 } PGtypeHandler;
 96 
 97 /* Values required during a type handler put ot get operation. */
 98 struct pg_typeargs
 99 {
100   int is_put;
101   const PGtypeFormatInfo *fmtinfo;
102   int is_ptr;
103   int format;
104   va_list ap;
105   int typpos;
106   PGtypeHandler *typhandler;
107   int (*errorf)(PGtypeArgs *args, const char *format, ...);
108   int (*super)(PGtypeArgs *args, ...);
109 
110   struct
111   {
112     PGparam *param;
113     char *out;
114     char *__allocated_out; /* leave me alone! */
115     int outl;
116     int (*expandBuffer)(PGtypeArgs *args, int new_len);
117   } put;
118 
119   struct
120   {
121     PGresult *result;
122     int tup_num;
123     int field_num;
124   } get;
125 };
126 
127 
128 /* ----------------
129  * Variable Length types
130  * ----------------
131  */
132 
133 typedef char *PGtext;
134 typedef char *PGvarchar;
135 typedef char *PGbpchar;
136 typedef char *PGuuid;
137 typedef struct
138 {
139   int len;
140   char *data;
141 } PGbytea;
142 
143 /* ----------------
144  * Numeric types
145  * ----------------
146  */
147 
148 typedef signed char PGchar;
149 typedef int PGbool;
150 typedef short PGint2;
151 typedef int PGint4;
152 typedef float PGfloat4;
153 typedef double PGfloat8;
154 typedef char *PGnumeric;
155 
156 /* Defined by an end-user if the system is missing long long. */
157 #ifdef PQT_LONG_LONG
158   typedef PQT_LONG_LONG PGint8;
159   typedef PQT_LONG_LONG PGmoney;
160 
161 /* MinGW and MSVC can use __int64 */
162 #elif defined(__MINGW32__) || defined(_MSC_VER)
163   typedef __int64 PGint8;
164   typedef __int64 PGmoney;
165 
166 /* Cygwin and Unixes. */
167 #else
168   typedef long long PGint8;
169   typedef long long PGmoney;
170 #endif
171 
172 /* ----------------
173  * Geometric type structures
174  * ----------------
175  */
176 
177 typedef struct
178 {
179   double x;
180   double y;
181 } PGpoint;
182 
183 typedef struct
184 {
185   PGpoint pts[2];
186 } PGlseg;
187 
188 typedef struct
189 {
190   PGpoint high;
191   PGpoint low;
192 } PGbox;
193 
194 typedef struct
195 {
196   PGpoint center;
197   double radius;
198 } PGcircle;
199 
200 typedef struct
201 {
202   int npts;
203   int closed;
204   PGpoint *pts; /* for getf, only valid while PGresult is. */
205 } PGpath;
206 
207 typedef struct
208 {
209   int npts;
210   PGpoint *pts; /* for getf, only valid while PGresult is. */
211 } PGpolygon;
212 
213 /* ----------------
214  * Network type structures
215  * ----------------
216  */
217 
218 /* This struct works with CIDR as well. */
219 typedef struct
220 {
221   int mask;
222   int is_cidr;
223   int sa_buf_len;
224 
225   /* sockaddr buffer, can be casted to sockaddr, sockaddr_in,
226    * sockaddr_in6 or sockaddr_stroage.
227    */
228   char sa_buf[128];
229 } PGinet;
230 
231 typedef struct
232 {
233   int a;
234   int b;
235   int c;
236   int d;
237   int e;
238   int f;
239 } PGmacaddr;
240 
241 /* ----------------
242  * Date & Time structures
243  * ----------------
244  */
245 
246 typedef struct
247 {
248   int years;
249   int mons;
250   int days;
251   int hours;
252   int mins;
253   int secs;
254   int usecs;
255 } PGinterval;
256 
257 typedef struct
258 {
259   int isbc;
260   int year;
261   int mon;
262   int mday;
263   int jday;
264   int yday;
265   int wday;
266 } PGdate;
267 
268 typedef struct
269 {
270   int hour;
271   int min;
272   int sec;
273   int usec;
274   int withtz;
275   int isdst;
276   int gmtoff;
277   char tzabbr[16];
278 } PGtime;
279 
280 typedef struct
281 {
282   PGint8 epoch;
283   PGdate date;
284   PGtime time;
285 } PGtimestamp;
286 
287 /* ----------------
288  * Array structures
289  * ----------------
290  */
291 
292 #ifndef MAXDIM
293 # define MAXDIM 6
294 #endif
295 
296 typedef struct
297 {
298   int ndims;
299   int lbound[MAXDIM];
300   int dims[MAXDIM];
301   PGparam *param;
302   PGresult *res;
303 } PGarray;
304 
305 /* ----------------
306  * Public API funcs
307  * ----------------
308  */
309 
310 /* === in events.c === */
311 
312 /* Deprecated, see PQinitTypes */
313 PQT_EXPORT int
314 PQtypesRegister(PGconn *conn);
315 
316 /* === in error.c === */
317 
318 PQT_EXPORT char *
319 PQgeterror(void);
320 
321 /* PQseterror(NULL) will clear the error message */
322 PQT_EXPORT void
323 PQseterror(const char *format, ...);
324 
325 /* Gets the error field for the last executed query.  This only
326  * pertains to PQparamExec and PQparamExecPrepared.  When using a
327  * standard libpq function like PQexec, PQresultErrorField should be used.
328  */
329 PQT_EXPORT char *
330 PQgetErrorField(int fieldcode);
331 
332 /* === in spec.c === */
333 
334 /* Set 'format' argument to NULL to clear a single prepared specifier. */
335 PQT_EXPORT int
336 PQspecPrepare(PGconn *conn, const char *name, const char *format, int is_stmt);
337 
338 PQT_EXPORT int
339 PQclearSpecs(PGconn *conn);
340 
341 /* === in handler.c === */
342 
343 /* Initialize type support on the given connection */
344 PQT_EXPORT int
345 PQinitTypes(PGconn *conn);
346 
347 /* Deprecated, see PQregisterTypes */
348 PQT_EXPORT int
349 PQregisterSubClasses(PGconn *conn, PGregisterType *types, int count);
350 
351 /* Deprecated, see PQregisterTypes */
352 PQT_EXPORT int
353 PQregisterComposites(PGconn *conn, PGregisterType *types, int count);
354 
355 /* Deprecated, see PQregisterTypes */
356 PQT_EXPORT int
357 PQregisterUserDefinedTypes(PGconn *conn, PGregisterType *types, int count);
358 
359 /* Registers PQT_SUBCLASS, PQT_COMPOSITE or PQT_USERDEFINED
360  * (the 'which' argument) for use with libpqtypes.
361  *
362  * For asynchronous type registration, set the 'async' argument to a
363  * non-zero value.  This value is ignored when 'which' is PQT_SUBCLASS,
364  * since subclass registration does not execute any commands against the
365  * server.  Use the standard PQconsumeInput, PQisBusy and PQgetResult
366  * to properly obtain a PGresult, which must be passed to PQregisterResult
367  * to complete the registration.
368  */
369 PQT_EXPORT int
370 PQregisterTypes(PGconn *conn, int which, PGregisterType *types,
371   int count, int async);
372 
373 /* Registers a set of 'which' types found in the given PGresult.  Caller
374  * is responsible for clearing the result 'res'.  Useful for performing
375  * asynchronous type registration or for caching type result data to
376  * avoid lookups on a new connection.  If PQregisterTypes is ran in async
377  * mode, the PGresult obtained via PGgetResult can be cached by an
378  * application and provided to this function for new connections.
379  *
380  * Types and count should be identical to what was originally supplied
381  * to PQregisterTypes.
382  *
383  * NOTE: although a PGconn is a required argument, it is never used
384  * to perform any network operation (non-blocking safe).
385  *
386  * PQT_SUBCLASS is not supported and will result in an error if supplied.
387  */
388 PQT_EXPORT int
389 PQregisterResult(PGconn *conn, int which, PGregisterType *types,
390   int count, PGresult *res);
391 
392 /* Clears all type handlers registered on 'conn'.  This is useful after a
393  * PQreset or PQresetPoll to optionally allow one to re-register types via
394  * PQregisterTypes.
395  */
396 PQT_EXPORT int
397 PQclearTypes(PGconn *conn);
398 
399 /* === in param.c === */
400 
401 PQT_EXPORT PGparam *
402 PQparamCreate(const PGconn *conn);
403 
404 PQT_EXPORT PGparam *
405 PQparamDup(PGparam *param);
406 
407 PQT_EXPORT int
408 PQparamCount(PGparam *param);
409 
410 PQT_EXPORT void
411 PQparamReset(PGparam *param);
412 
413 PQT_EXPORT void
414 PQparamClear(PGparam *param);
415 
416 PQT_EXPORT int
417 PQputf(PGparam *param, const char *format, ...);
418 
419 PQT_EXPORT int
420 PQputvf(PGparam *param, char *stmtBuf, size_t stmtBufLen,
421   const char *format, va_list ap);
422 
423 /* === in exec.c === */
424 
425 PQT_EXPORT int
426 PQgetf(const PGresult *res, int tup_num, const char *format, ...);
427 
428 PQT_EXPORT int
429 PQgetvf(const PGresult *res, int tup_num, const char *format, va_list ap);
430 
431 PQT_EXPORT PGresult *
432 PQexecf(PGconn *conn, const char *cmdspec, ...);
433 
434 PQT_EXPORT PGresult *
435 PQexecvf(PGconn *conn, const char *cmdspec, va_list ap);
436 
437 PQT_EXPORT int
438 PQsendf(PGconn *conn, const char *cmdspec, ...);
439 
440 PQT_EXPORT int
441 PQsendvf(PGconn *conn, const char *cmdspec, va_list ap);
442 
443 PQT_EXPORT PGresult *
444 PQparamExec(PGconn *conn, PGparam *param,
445   const char *command, int resultFormat);
446 
447 PQT_EXPORT int
448 PQparamSendQuery(PGconn *conn, PGparam *param,
449   const char *command, int resultFormat);
450 
451 PQT_EXPORT PGresult *
452 PQparamExecPrepared(PGconn *conn, PGparam *param,
453   const char *stmtName, int resultFormat);
454 
455 PQT_EXPORT int
456 PQparamSendQueryPrepared(PGconn *conn, PGparam *param,
457   const char *stmtName, int resultFormat);
458 
459 /* === in datetime.c === */
460 
461 PQT_EXPORT void
462 PQlocalTZInfo(time_t *t, int *gmtoff, int *isdst, char **tzabbrp);
463 
464 #ifdef __cplusplus
465 }
466 #endif
467 #endif /* !LIBPQTYPES_H */