libpqtypes.h

/*
 * libpqtypes.h
 *   Public header for libpqtypes.  Contains the entire public API.
 *
 * Copyright (c) 2011 eSilo, LLC. All rights reserved.
 * This is free software; see the source for copying conditions.  There is
 * NO warranty; not even for MERCHANTABILITY or  FITNESS FOR A  PARTICULAR
 * PURPOSE.
 */

#ifndef LIBPQTYPES_H
#define LIBPQTYPES_H

#include <libpq-fe.h>
#include <time.h>
#include <stdarg.h>

#ifdef __cplusplus
extern "C" {
#endif

#if defined(_MSC_VER) || defined(__MINGW32__) || defined(__CYGWIN__)
#	define PQT_EXPORT __declspec(dllexport)
#else
#	define PQT_EXPORT extern
#endif

/* MSVC 6 must use `i64', everything else uses `LL'. */
#if !defined(_MSC_VER) || _MSC_VER > 1200
#	define PQT_INT64CONST(x) ((PGint8) x##LL)
#else
#	define PQT_INT64CONST(x) ((PGint8) x##i64)
#endif

enum
{
	PQT_SUBCLASS,
	PQT_COMPOSITE,
	PQT_USERDEFINED
};

typedef struct pg_param PGparam;
typedef struct pg_typeargs PGtypeArgs;
typedef int (*PGtypeProc)(PGtypeArgs *args);

/* ----------------
 * Error info
 * ----------------
 */

#ifndef PGERROR_MSG_MAXLEN
#	define PGERROR_MSG_MAXLEN 2048
#endif

typedef struct
{
	char msg[PGERROR_MSG_MAXLEN];
} PGerror;

/* For use with a PQregisterXXX function */
typedef struct
{
	const char *typname;
	PGtypeProc typput;
	PGtypeProc typget;
} PGregisterType;

typedef struct
{
	int sversion;
	int pversion;
	char datestyle[48];
	int integer_datetimes;
} PGtypeFormatInfo;

/* Record Attribute Description, its columns */
typedef struct
{
	Oid attoid;
	int attlen;
	int atttypmod;
	char attname[65];
} PGrecordAttDesc;

/* Type handler for putf and getf functions.  The char fixed length buffers
 * used to be allocated pointers.  This was a performance problem when
 * many type handlers are registered and one uses getf on a composite or
 * an array.  These types require generating a PGresult and duplicating
 * the type handlers.  Saved 40% by not having to deep copy the strings.
 */
typedef struct pg_typhandler
{
	int id;
	char typschema[65];
	char typname[65];
	int typlen;
	Oid typoid;
	Oid typoid_array;
	PGtypeProc typput;
	PGtypeProc typget;
	int base_id;

	/* For composites, contains each attribute of a composite */
	int nattrs;
	int freeAttDescs;
	PGrecordAttDesc attDescsBuf[16];
	PGrecordAttDesc *attDescs;
} PGtypeHandler;

/* Values required during a type handler put ot get operation. */
struct pg_typeargs
{
	int is_put;
	const PGtypeFormatInfo *fmtinfo;
	int is_ptr;
	PGerror *err;
	int format;
	va_list ap;
	int typpos;
	PGtypeHandler *typhandler;
	int (*errorf)(PGtypeArgs *args, const char *format, ...);
	int (*super)(PGtypeArgs *args, ...);

	struct
	{
		PGparam *param;
		char *out;
		char *__allocated_out; /* leave me alone! */
		int outl;
		int (*expandBuffer)(PGtypeArgs *args, int new_len);
	} put;

	struct
	{
		PGresult *result;
		int tup_num;
		int field_num;
	} get;
};


/* ----------------
 * Variable Length types
 * ----------------
 */

typedef char *PGtext;
typedef char *PGvarchar;
typedef char *PGbpchar;
typedef char *PGuuid;
typedef struct
{
  int len;
  char *data;
} PGbytea;

/* ----------------
 * Numeric types
 * ----------------
 */

typedef signed char PGchar;
typedef int PGbool;
typedef short PGint2;
typedef int PGint4;
typedef float PGfloat4;
typedef double PGfloat8;
typedef char *PGnumeric;

/* Defined by an end-user if the system is missing long long. */
#ifdef PQT_LONG_LONG
	typedef PQT_LONG_LONG PGint8;
	typedef PQT_LONG_LONG PGmoney;

/* MinGW and MSVC can use __int64 */
#elif defined(__MINGW32__) || defined(_MSC_VER)
	typedef __int64 PGint8;
	typedef __int64 PGmoney;

/* Cygwin and Unixes. */
#else
	typedef long long PGint8;
	typedef long long PGmoney;
#endif

/* ----------------
 * Geometric type structures
 * ----------------
 */

typedef struct
{
	double x;
	double y;
} PGpoint;

typedef struct
{
	PGpoint pts[2];
} PGlseg;

typedef struct
{
	PGpoint high;
	PGpoint low;
} PGbox;

typedef struct
{
	PGpoint center;
	double radius;
} PGcircle;

typedef struct
{
	int npts;
	int closed;
	PGpoint *pts; /* for getf, only valid while PGresult is. */
} PGpath;

typedef struct
{
	int npts;
	PGpoint *pts; /* for getf, only valid while PGresult is. */
} PGpolygon;

/* ----------------
 * Network type structures
 * ----------------
 */

/* This struct works with CIDR as well. */
typedef struct
{
	int mask;
	int is_cidr;
	int sa_buf_len;

	/* sockaddr buffer, can be casted to sockaddr, sockaddr_in,
	 * sockaddr_in6 or sockaddr_stroage.
	 */
	char sa_buf[128];
} PGinet;

typedef struct
{
	int a;
	int b;
	int c;
	int d;
	int e;
	int f;
} PGmacaddr;

/* ----------------
 * Date & Time structures
 * ----------------
 */

typedef struct
{
	int years;
	int mons;
	int days;
	int hours;
	int mins;
	int secs;
	int usecs;
} PGinterval;

typedef struct
{
	int isbc;
	int year;
	int mon;
	int mday;
	int jday;
	int yday;
	int wday;
} PGdate;

typedef struct
{
	int hour;
	int min;
	int sec;
	int usec;
	int withtz;
	int isdst;
	int gmtoff;
	char tzabbr[16];
} PGtime;

typedef struct
{
	PGint8 epoch;
	PGdate date;
	PGtime time;
} PGtimestamp;

/* ----------------
 * Array structures
 * ----------------
 */

#ifndef MAXDIM
#	define MAXDIM 6
#endif

typedef struct
{
	int ndims;
	int lbound[MAXDIM];
	int dims[MAXDIM];
	PGparam *param;
	PGresult *res;
} PGarray;

/* ----------------
 * Public API funcs
 * ----------------
 */

/* === in events.c === */

/* Deprecated, see PQinitTypes */
PQT_EXPORT int
PQtypesRegister(PGconn *conn);

/* === in error.c === */

/* PQseterror(NULL) will clear the error message */
PQT_EXPORT void
PQseterror(PGerror *err, const char *format, ...);

/* === in spec.c === */

/* Set 'format' argument to NULL to clear a single prepared specifier. */
PQT_EXPORT int
PQspecPrepare(PGconn *conn, PGerror *err, const char *name, const char *format, int is_stmt);

PQT_EXPORT int
PQclearSpecs(PGconn *conn, PGerror *err);

/* === in handler.c === */

/* Initialize type support on the given connection */
PQT_EXPORT int
PQinitTypes(PGconn *conn);

/* Deprecated, see PQregisterTypes */
PQT_EXPORT int
PQregisterSubClasses(PGconn *conn, PGerror *err, PGregisterType *types, int count);

/* Deprecated, see PQregisterTypes */
PQT_EXPORT int
PQregisterComposites(PGconn *conn, PGerror *err, PGregisterType *types, int count);

/* Deprecated, see PQregisterTypes */
PQT_EXPORT int
PQregisterUserDefinedTypes(PGconn *conn, PGerror *err, PGregisterType *types, int count);

/* Registers PQT_SUBCLASS, PQT_COMPOSITE or PQT_USERDEFINED
 * (the 'which' argument) for use with libpqtypes.
 *
 * For asynchronous type registration, set the 'async' argument to a
 * non-zero value.  This value is ignored when 'which' is PQT_SUBCLASS,
 * since subclass registration does not execute any commands against the
 * server.  Use the standard PQconsumeInput, PQisBusy and PQgetResult
 * to properly obtain a PGresult, which must be passed to PQregisterResult
 * to complete the registration.
 */
PQT_EXPORT int
PQregisterTypes(PGconn *conn, PGerror *err, int which, PGregisterType *types,
	int count, int async);

/* Registers a set of 'which' types found in the given PGresult.  Caller
 * is responsible for clearing the result 'res'.  Useful for performing
 * asynchronous type registration or for caching type result data to
 * avoid lookups on a new connection.  If PQregisterTypes is ran in async
 * mode, the PGresult obtained via PGgetResult can be cached by an
 * application and provided to this function for new connections.
 *
 * Types and count should be identical to what was originally supplied
 * to PQregisterTypes.
 *
 * NOTE: although a PGconn is a required argument, it is never used
 * to perform any network operation (non-blocking safe).
 *
 * PQT_SUBCLASS is not supported and will result in an error if supplied.
 */
PQT_EXPORT int
PQregisterResult(PGconn *conn, PGerror *err, int which, PGregisterType *types,
	int count, PGresult *res);

/* Clears all type handlers registered on 'conn'.  This is useful after a
 * PQreset or PQresetPoll to optionally allow one to re-register types via
 * PQregisterTypes.
 */
PQT_EXPORT int
PQclearTypes(PGconn *conn, PGerror *err);

/* === in param.c === */

PQT_EXPORT PGparam *
PQparamCreate(const PGconn *conn, PGerror *err);

PQT_EXPORT PGparam *
PQparamDup(PGparam *param, PGerror *err);

PQT_EXPORT int
PQparamCount(PGparam *param);

PQT_EXPORT void
PQparamReset(PGparam *param);

PQT_EXPORT void
PQparamClear(PGparam *param);

PQT_EXPORT int
PQputf(PGparam *param, PGerror *err, const char *format, ...);

PQT_EXPORT int
PQputvf(PGparam *param, PGerror *err, char *stmtBuf, size_t stmtBufLen,
	const char *format, va_list ap);

/* === in exec.c === */

PQT_EXPORT int
PQgetf(const PGresult *res, PGerror *err, int tup_num, const char *format, ...);

PQT_EXPORT int
PQgetvf(const PGresult *res, PGerror *err, int tup_num, const char *format, va_list ap);

PQT_EXPORT PGresult *
PQexecf(PGconn *conn, PGerror *err, const char *cmdspec, ...);

PQT_EXPORT PGresult *
PQexecvf(PGconn *conn, PGerror *err, const char *cmdspec, va_list ap);

PQT_EXPORT int
PQsendf(PGconn *conn, PGerror *err, const char *cmdspec, ...);

PQT_EXPORT int
PQsendvf(PGconn *conn, PGerror *err, const char *cmdspec, va_list ap);

PQT_EXPORT PGresult *
PQparamExec(PGconn *conn, PGerror *err, PGparam *param,
	const char *command, int resultFormat);

PQT_EXPORT int
PQparamSendQuery(PGconn *conn, PGerror *err, PGparam *param,
	const char *command, int resultFormat);

PQT_EXPORT PGresult *
PQparamExecPrepared(PGconn *conn, PGerror *err, PGparam *param,
	const char *stmtName, int resultFormat);

PQT_EXPORT int
PQparamSendQueryPrepared(PGconn *conn, PGerror *err, PGparam *param,
	const char *stmtName, int resultFormat);

/* === in datetime.c === */

PQT_EXPORT void
PQlocalTZInfo(time_t *t, int *gmtoff, int *isdst, char **tzabbrp);

#ifdef __cplusplus
}
#endif
#endif /* !LIBPQTYPES_H */