libpqtypes - libpqtypes.h

Home Page

  1 
  2 /*
  3  * libpqtypes.h
  4  *   Public header for libpqtypes.  Contains the entire public API.
  5  *
  6  * Copyright (c) 2009 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 typedef struct pg_param PGparam;
 37 typedef struct pg_typeargs PGtypeArgs;
 38 typedef int (*PGtypeProc)(PGtypeArgs *args);
 39 
 40 /* For use with a PQregisterXXX function */
 41 typedef struct
 42 {
 43   const char *typname;
 44   PGtypeProc typput;
 45   PGtypeProc typget;
 46 } PGregisterType;
 47 
 48 typedef struct
 49 {
 50   int sversion;
 51   int pversion;
 52   char datestyle[48];
 53   int integer_datetimes;
 54 } PGtypeFormatInfo;
 55 
 56 /* Record Attribute Description, its columns */
 57 typedef struct
 58 {
 59   Oid attoid;
 60   int attlen;
 61   int atttypmod;
 62   char attname[65];
 63 } PGrecordAttDesc;
 64 
 65 /* Type handler for putf and getf functions.  The char fixed length buffers
 66  * used to be allocated pointers.  This was a performance problem when
 67  * many type handlers are registered and one uses getf on a composite or
 68  * an array.  These types require generating a PGresult and duplicating
 69  * the type handlers.  Saved 40% by not having to deep copy the strings.
 70  */
 71 typedef struct pg_typhandler
 72 {
 73   int id;
 74   char typschema[65];
 75   char typname[65];
 76   int typlen;
 77   Oid typoid;
 78   Oid typoid_array;
 79   PGtypeProc typput;
 80   PGtypeProc typget;
 81   int base_id;
 82 
 83   /* For composites, contains each attribute of a composite */
 84   int nattrs;
 85   int freeAttDescs;
 86   PGrecordAttDesc attDescsBuf[16];
 87   PGrecordAttDesc *attDescs;
 88 
 89   /* For PQresets so we can recall register functions. */
 90   int regtype;
 91   char orig_typname[300];
 92   PGtypeProc orig_typput;
 93   PGtypeProc orig_typget;
 94 } PGtypeHandler;
 95 
 96 /* Values required during a type handler put ot get operation. */
 97 struct pg_typeargs
 98 {
 99   int is_put;
100   const PGtypeFormatInfo *fmtinfo;
101   int is_ptr;
102   int format;
103   va_list ap;
104   int typpos;
105   PGtypeHandler *typhandler;
106   int (*errorf)(PGtypeArgs *args, const char *format, ...);
107   int (*super)(PGtypeArgs *args, ...);
108 
109   struct
110   {
111     PGparam *param;
112     char *out;
113     char *__allocated_out; /* leave me alone! */
114     int outl;
115     int (*expandBuffer)(PGtypeArgs *args, int new_len);
116   } put;
117 
118   struct
119   {
120     PGresult *result;
121     int tup_num;
122     int field_num;
123   } get;
124 };
125 
126 
127 /* ----------------
128  * Variable Length types
129  * ----------------
130  */
131 
132 typedef char *PGtext;
133 typedef char *PGvarchar;
134 typedef char *PGbpchar;
135 typedef char *PGuuid;
136 typedef struct
137 {
138   int len;
139   char *data;
140 } PGbytea;
141 
142 /* ----------------
143  * Numeric types
144  * ----------------
145  */
146 
147 typedef signed char PGchar;
148 typedef int PGbool;
149 typedef short PGint2;
150 typedef int PGint4;
151 typedef float PGfloat4;
152 typedef double PGfloat8;
153 typedef char *PGnumeric;
154 
155 /* Defined by an end-user if the system is missing long long. */
156 #ifdef PQT_LONG_LONG
157   typedef PQT_LONG_LONG PGint8;
158   typedef PQT_LONG_LONG PGmoney;
159 
160 /* MinGW and MSVC can use __int64 */
161 #elif defined(__MINGW32__) || defined(_MSC_VER)
162   typedef __int64 PGint8;
163   typedef __int64 PGmoney;
164 
165 /* Cygwin and Unixes. */
166 #else
167   typedef long long PGint8;
168   typedef long long PGmoney;
169 #endif
170 
171 /* ----------------
172  * Geometric type structures
173  * ----------------
174  */
175 
176 typedef struct
177 {
178   double x;
179   double y;
180 } PGpoint;
181 
182 typedef struct
183 {
184   PGpoint pts[2];
185 } PGlseg;
186 
187 typedef struct
188 {
189   PGpoint high;
190   PGpoint low;
191 } PGbox;
192 
193 typedef struct
194 {
195   PGpoint center;
196   double radius;
197 } PGcircle;
198 
199 typedef struct
200 {
201   int npts;
202   int closed;
203   PGpoint *pts; /* for getf, only valid while PGresult is. */
204 } PGpath;
205 
206 typedef struct
207 {
208   int npts;
209   PGpoint *pts; /* for getf, only valid while PGresult is. */
210 } PGpolygon;
211 
212 /* ----------------
213  * Network type structures
214  * ----------------
215  */
216 
217 /* This struct works with CIDR as well. */
218 typedef struct
219 {
220   int mask;
221   int is_cidr;
222   int sa_buf_len;
223 
224   /* sockaddr buffer, can be casted to sockaddr, sockaddr_in,
225    * sockaddr_in6 or sockaddr_stroage.
226    */
227   char sa_buf[128];
228 } PGinet;
229 
230 typedef struct
231 {
232   int a;
233   int b;
234   int c;
235   int d;
236   int e;
237   int f;
238 } PGmacaddr;
239 
240 /* ----------------
241  * Date & Time structures
242  * ----------------
243  */
244 
245 typedef struct
246 {
247   int years;
248   int mons;
249   int days;
250   int hours;
251   int mins;
252   int secs;
253   int usecs;
254 } PGinterval;
255 
256 typedef struct
257 {
258   int isbc;
259   int year;
260   int mon;
261   int mday;
262   int jday;
263   int yday;
264   int wday;
265 } PGdate;
266 
267 typedef struct
268 {
269   int hour;
270   int min;
271   int sec;
272   int usec;
273   int withtz;
274   int isdst;
275   int gmtoff;
276   char tzabbr[16];
277 } PGtime;
278 
279 typedef struct
280 {
281   PGint8 epoch;
282   PGdate date;
283   PGtime time;
284 } PGtimestamp;
285 
286 /* ----------------
287  * Array structures
288  * ----------------
289  */
290 
291 #ifndef MAXDIM
292 # define MAXDIM 6
293 #endif
294 
295 typedef struct
296 {
297   int ndims;
298   int lbound[MAXDIM];
299   int dims[MAXDIM];
300   PGparam *param;
301   PGresult *res;
302 } PGarray;
303 
304 /* ----------------
305  * Public API funcs
306  * ----------------
307  */
308 
309 /* === in events.c === */
310 
311 PQT_EXPORT int
312 PQtypesRegister(PGconn *conn);
313 
314 /* === in error.c === */
315 
316 PQT_EXPORT char *
317 PQgeterror(void);
318 
319 /* PQseterror(NULL) will clear the error message */
320 PQT_EXPORT void
321 PQseterror(const char *format, ...);
322 
323 /* Gets the error field for the last executed query.  This only
324  * pertains to PQparamExec and PQparamExecPrepared.  When using a
325  * standard libpq function like PQexec, PQresultErrorField should be used.
326  */
327 PQT_EXPORT char *
328 PQgetErrorField(int fieldcode);
329 
330 /* === in spec.c === */
331 
332 PQT_EXPORT int
333 PQspecPrepare(PGconn *conn, const char *name, const char *format, int is_stmt);
334 
335 /* === in handler.c === */
336 
337 /* Deprecated, here for compatibility.  Please use PQregisterSubClasses,
338  * PQregisterUserDefinedTypes or PQregisterComposites.
339  */
340 PQT_EXPORT int
341 PQregisterTypeHandler(PGconn *conn, const char *typname,
342   PGtypeProc put, PGtypeProc get);
343 
344 PQT_EXPORT int
345 PQregisterSubClasses(PGconn *conn, PGregisterType *types, int count);
346 
347 PQT_EXPORT int
348 PQregisterComposites(PGconn *conn, PGregisterType *types, int count);
349 
350 PQT_EXPORT int
351 PQregisterUserDefinedTypes(PGconn *conn, PGregisterType *types, int count);
352 
353 /* === in param.c === */
354 
355 PQT_EXPORT PGparam *
356 PQparamCreate(const PGconn *conn);
357 
358 PQT_EXPORT int
359 PQparamCount(PGparam *param);
360 
361 PQT_EXPORT void
362 PQparamReset(PGparam *param);
363 
364 PQT_EXPORT void
365 PQparamClear(PGparam *param);
366 
367 PQT_EXPORT int
368 PQputf(PGparam *param, const char *format, ...);
369 
370 PQT_EXPORT int
371 PQputvf(PGparam *param, char *stmtBuf, size_t stmtBufLen,
372   const char *format, va_list ap);
373 
374 /* === in exec.c === */
375 
376 PQT_EXPORT int
377 PQgetf(const PGresult *res, int tup_num, const char *format, ...);
378 
379 PQT_EXPORT int
380 PQgetvf(const PGresult *res, int tup_num, const char *format, va_list ap);
381 
382 PQT_EXPORT PGresult *
383 PQexecf(PGconn *conn, const char *cmdspec, ...);
384 
385 PQT_EXPORT PGresult *
386 PQexecvf(PGconn *conn, const char *cmdspec, va_list ap);
387 
388 PQT_EXPORT int
389 PQsendf(PGconn *conn, const char *cmdspec, ...);
390 
391 PQT_EXPORT int
392 PQsendvf(PGconn *conn, const char *cmdspec, va_list ap);
393 
394 PQT_EXPORT PGresult *
395 PQparamExec(PGconn *conn, PGparam *param,
396   const char *command, int resultFormat);
397 
398 PQT_EXPORT int
399 PQparamSendQuery(PGconn *conn, PGparam *param,
400   const char *command, int resultFormat);
401 
402 PQT_EXPORT PGresult *
403 PQparamExecPrepared(PGconn *conn, PGparam *param,
404   const char *stmtName, int resultFormat);
405 
406 PQT_EXPORT int
407 PQparamSendQueryPrepared(PGconn *conn, PGparam *param,
408   const char *stmtName, int resultFormat);
409 
410 /* === in datetime.c === */
411 
412 PQT_EXPORT void
413 PQlocalTZInfo(time_t *t, int *gmtoff, int *isdst, char **tzabbrp);
414 
415 #ifdef __cplusplus
416 }
417 #endif
418 #endif /* !LIBPQTYPES_H */