granicus.if.org Git - postgresql/blob - src/interfaces/libpq/libpq-fe.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * libpq-fe.h--
   4  *    This file contains definitions for structures and
   5  *    externs for functions used by frontend postgres applications.
   6  *
   7  * Copyright (c) 1994, Regents of the University of California
   8  *
   9  * $Id: libpq-fe.h,v 1.17 1997/01/06 10:11:11 bryanh Exp $
  10  *
  11  *-------------------------------------------------------------------------
  12  */
  13
  14 #ifndef LIBPQ_FE_H
  15 #define LIBPQ_FE_H
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif
  20
  21 #include <stdio.h>
  22 /* ----------------
  23  *      include stuff common to fe and be
  24  * ----------------
  25  */
  26 #include "postgres_ext.h"
  27 #include "libpq/pqcomm.h"
  28 #include "lib/dllist.h"
  29
  30 typedef enum {CONNECTION_OK,
  31               CONNECTION_BAD}  ConnStatusType;
  32
  33 typedef enum {
  34   PGRES_EMPTY_QUERY = 0,
  35   PGRES_COMMAND_OK,  /* a query command that doesn't return */
  36                     /* anything was executed properly by the backend */
  37   PGRES_TUPLES_OK,  /* a query command that returns tuples */
  38                    /* was executed properly by the backend, PGresult */
  39                    /* contains the resulttuples */
  40   PGRES_COPY_OUT,
  41   PGRES_COPY_IN,
  42   PGRES_BAD_RESPONSE, /* an unexpected response was recv'd from the backend */
  43   PGRES_NONFATAL_ERROR,
  44   PGRES_FATAL_ERROR
  45
  46 } ExecStatusType;
  47
  48 /* string descriptions of the ExecStatusTypes */
  49 extern const char* pgresStatus[];
  50
  51 /*
  52  * POSTGRES backend dependent Constants.
  53  */
  54
  55 /* ERROR_MSG_LENGTH should really be the same as ELOG_MAXLEN in utils/elog.h*/
  56 #define ERROR_MSG_LENGTH 4096
  57 #define COMMAND_LENGTH 20
  58 #define REMARK_LENGTH 80
  59 #define PORTAL_NAME_LENGTH 16
  60
  61 /* ----------------
  62  * PQArgBlock --
  63  *      Information (pointer to array of this structure) required
  64  *      for the PQfn() call.
  65  * ----------------
  66  */
  67 typedef struct {
  68     int len;
  69     int isint;
  70     union {
  71         int *ptr;       /* can't use void (dec compiler barfs)  */
  72         int integer;
  73     } u;
  74 } PQArgBlock;
  75
  76 typedef struct pgresAttDesc {
  77   char* name; /* type name */
  78   Oid adtid;  /* type id */
  79   short adtsize; /* type size */
  80 } PGresAttDesc;
  81
  82 /* use char* for Attribute values,
  83    ASCII tuples are guaranteed to be null-terminated
  84    For binary tuples, the first four bytes of the value is the size,
  85    and the bytes afterwards are the value.  The binary value is
  86    not guaranteed to be null-terminated.  In fact, it can have embedded nulls*/
  87
  88 #define NULL_LEN        (-1)    /* pg_result len for NULL value */
  89
  90 typedef struct pgresAttValue {
  91   int len; /* length in bytes of the value */
  92   char *value; /* actual value */
  93 } PGresAttValue;
  94
  95 typedef struct pgNotify {
  96     char relname[NAMEDATALEN];  /* name of relation containing data */
  97     int be_pid;                 /* process id of backend */
  98 } PGnotify;
  99
 100 typedef struct pgLobjfuncs {
 101     Oid fn_lo_open;             /* OID of backend function lo_open      */
 102     Oid fn_lo_close;            /* OID of backend function lo_close     */
 103     Oid fn_lo_creat;            /* OID of backend function lo_creat     */
 104     Oid fn_lo_unlink;           /* OID of backend function lo_unlink    */
 105     Oid fn_lo_lseek;            /* OID of backend function lo_lseek     */
 106     Oid fn_lo_tell;             /* OID of backend function lo_tell      */
 107     Oid fn_lo_read;             /* OID of backend function LOread       */
 108     Oid fn_lo_write;            /* OID of backend function LOwrite      */
 109 } PGlobjfuncs;
 110
 111 /* PGconn encapsulates a connection to the backend */
 112 typedef struct pg_conn{
 113   char *pghost; /* the machine on which the server is running */
 114   char *pgtty;  /* tty on which the backend messages is displayed */
 115   char *pgport; /* the communication port with the backend */
 116   char *pgoptions; /* options to start the backend with */
 117   char *dbName; /* database name */
 118   ConnStatusType status;
 119   char errorMessage[ERROR_MSG_LENGTH];
 120   /* pipes for be/fe communication */
 121   FILE *Pfin;
 122   FILE *Pfout;
 123   FILE *Pfdebug;
 124   void *port; /* really a Port* */
 125   int asyncNotifyWaiting;
 126   Dllist* notifyList;
 127   char *pguser;  /* Postgres username of user who is connected */
 128   PGlobjfuncs *lobjfuncs; /* Backend function OID's for large object access */
 129 } PGconn;
 130
 131 #define CMDSTATUS_LEN 40
 132
 133 /* PGresult encapsulates the result of a query */
 134 /* unlike the old libpq, we assume that queries only return in one group */
 135 typedef struct pg_result{
 136   int ntups;
 137   int numAttributes;
 138   PGresAttDesc *attDescs;
 139   PGresAttValue* *tuples; /* each PGresTuple is an array of PGresAttValue's */
 140   int tupArrSize;         /* size of tuples array allocated */
 141   ExecStatusType resultStatus;
 142   char cmdStatus[CMDSTATUS_LEN]; /* cmd status from the last insert query*/
 143   int binary; /* binary tuple values if binary == 1, otherwise ASCII */
 144   PGconn* conn;
 145 } PGresult;
 146
 147 typedef char pqbool;
 148   /* We can't use the conventional "bool", because we are designed to be
 149      included in a user's program, and user may already have that type
 150      defined.  Pqbool, on the other hand, is unlikely to be used.
 151      */
 152
 153 struct _PQprintOpt {
 154     pqbool header;         /* print output field headings and row count */
 155     pqbool align;          /* fill align the fields */
 156     pqbool standard;       /* old brain dead format */
 157     pqbool html3;          /* output html tables */
 158     pqbool expanded;       /* expand tables */
 159     pqbool pager;          /* use pager for output if needed */
 160     char *fieldSep;      /* field separator */
 161     char *tableOpt;      /* insert to HTML <table ...> */
 162     char *caption;       /* HTML <caption> */
 163     char **fieldName;    /* null terminated array of repalcement field names */
 164 };
 165
 166 typedef struct _PQprintOpt PQprintOpt;
 167
 168 /* ----------------
 169  * Structure for the conninfo parameter definitions of PQconnectdb()
 170  * ----------------
 171  */
 172 struct _PQconninfoOption {
 173     char        *keyword;       /* The keyword of the option            */
 174     char        *environ;       /* Fallback environment variable name   */
 175     char        *compiled;      /* Fallback compiled in default value   */
 176     char        *val;           /* Options value                        */
 177     char        *label;         /* Label for field in connect dialog    */
 178     char        *dispchar;      /* Character to display for this field  */
 179                                 /* in a connect dialog. Values are:     */
 180                                 /*    ""   Display entered value as is  */
 181                                 /*    "*"  Password field - hide value  */
 182                                 /*    "D"  Debug options - don't        */
 183                                 /*         create a field by default    */
 184     int         dispsize;       /* Field size in characters for dialog  */
 185 };
 186
 187 typedef struct _PQconninfoOption PQconninfoOption;
 188
 189 /* ===  in fe-connect.c === */
 190   /* make a new client connection to the backend */
 191 extern PGconn* PQconnectdb(const char* conninfo);
 192 extern PQconninfoOption *PQconndefaults(void);
 193 extern PGconn* PQsetdb(const char* pghost, const char* pgport, const char* pgoptions,
 194                        const char* pgtty, const char* dbName);
 195   /* close the current connection and free the PGconn data structure */
 196 extern void PQfinish(PGconn* conn);
 197   /* close the current connection and restablish a new one with the same
 198      parameters */
 199 extern void PQreset(PGconn* conn);
 200
 201 extern char* PQdb(PGconn* conn);
 202 extern char* PQuser(PGconn* conn);
 203 extern char* PQhost(PGconn* conn);
 204 extern char* PQoptions(PGconn* conn);
 205 extern char* PQport(PGconn* conn);
 206 extern char* PQtty(PGconn* conn);
 207 extern ConnStatusType PQstatus(PGconn* conn);
 208 extern char* PQerrorMessage(PGconn* conn);
 209 extern void PQtrace(PGconn *conn, FILE* debug_port);
 210 extern void PQuntrace(PGconn *conn);
 211
 212 /* === in fe-exec.c === */
 213 extern PGresult* PQexec(PGconn* conn, const char* query);
 214 extern int PQgetline(PGconn *conn, char* string, int length);
 215 extern int PQendcopy(PGconn *conn);
 216 extern void PQputline(PGconn *conn, const char* string);
 217 extern ExecStatusType PQresultStatus(PGresult* res);
 218 extern int PQntuples(PGresult *res);
 219 extern int PQnfields(PGresult *res);
 220 extern char* PQfname(PGresult *res, int field_num);
 221 extern int PQfnumber(PGresult *res, const char* field_name);
 222 extern Oid PQftype(PGresult *res, int field_num);
 223 extern short PQfsize(PGresult *res, int field_num);
 224 extern char* PQcmdStatus(PGresult *res);
 225 extern const char* PQoidStatus(PGresult *res);
 226 extern char* PQgetvalue(PGresult *res, int tup_num, int field_num);
 227 extern int PQgetlength(PGresult *res, int tup_num, int field_num);
 228 extern int PQgetisnull(PGresult *res, int tup_num, int field_num);
 229 extern void PQclear(PGresult* res);
 230 /* PQdisplayTuples() is a better version of PQprintTuples() */
 231 extern void PQdisplayTuples(PGresult *res,
 232                             FILE *fp,      /* where to send the output */
 233                             int fillAlign, /* pad the fields with spaces */
 234                             const char *fieldSep,  /* field separator */
 235                             int printHeader, /* display headers? */
 236                             int quiet);
 237 extern void PQprintTuples(PGresult* res,
 238                           FILE* fout,      /* output stream */
 239                           int printAttName,/* print attribute names or not*/
 240                           int terseOutput, /* delimiter bars or not?*/
 241                           int width        /* width of column,
 242                                               if 0, use variable width */
 243                           );
 244 extern void PQprint(FILE* fout,      /* output stream */
 245                     PGresult* res,
 246                     PQprintOpt *ps   /* option structure */
 247                     );
 248 extern PGnotify* PQnotifies(PGconn *conn);
 249 extern PGresult* PQfn(PGconn* conn,
 250                       int fnid,
 251                       int *result_buf,
 252                       int *result_len,
 253                       int result_is_int,
 254                       PQArgBlock *args,
 255                       int nargs);
 256 /* === in fe-auth.c === */
 257 extern MsgType fe_getauthsvc(char* PQerrormsg);
 258 extern void fe_setauthsvc(const char *name, char* PQerrormsg);
 259 extern char *fe_getauthname(char* PQerrormsg);
 260
 261 /* === in fe-misc.c === */
 262 /* pqGets and pqPuts gets and sends strings to the file stream
 263    returns 0 if successful
 264    if debug is non-null, debugging output is sent to that stream
 265 */
 266 extern int pqGets(char* s, int maxlen, FILE* stream, FILE* debug);
 267 extern int pqGetnchar(char* s, int maxlen, FILE* stream, FILE* debug);
 268 extern int pqPutnchar(const char* s, int maxlen, FILE* stream, FILE* debug);
 269 extern int pqPuts(const char* s, FILE* stream, FILE* debug );
 270 extern int pqGetc(FILE* stream, FILE *debug);
 271 /* get a n-byte integer from the stream into result */
 272 /* returns 0 if successful */
 273 extern int pqGetInt(int* result, int bytes, FILE* stream, FILE *debug );
 274 /* put a n-byte integer into the stream */
 275 /* returns 0 if successful */
 276 extern int pqPutInt(const int n, int bytes, FILE* stream, FILE *debug );
 277 extern void pqFlush(FILE* stream, FILE* debug);
 278
 279 /* === in fe-lobj.c === */
 280 int lo_open(PGconn* conn, Oid lobjId, int mode);
 281 int lo_close(PGconn *conn, int fd);
 282 int lo_read(PGconn *conn, int fd, char *buf, int len);
 283 int lo_write(PGconn *conn, int fd, char *buf, int len);
 284 int lo_lseek(PGconn *conn, int fd, int offset, int whence);
 285 Oid lo_creat(PGconn *conn, int mode);
 286 int lo_tell(PGconn *conn, int fd);
 287 int lo_unlink(PGconn *conn, Oid lobjId);
 288 Oid lo_import(PGconn *conn, char *filename);
 289 int lo_export(PGconn *conn, Oid lobjId, char *filename);
 290 /* max length of message to send  */
 291 #define MAX_MESSAGE_LEN 8193
 292
 293 /* maximum number of fields in a tuple */
 294 #define BYTELEN 8
 295 #define MAX_FIELDS 512
 296
 297 /* fall back options if they are not specified by arguments or defined
 298    by environment variables */
 299 #define DefaultHost     "localhost"
 300 #define DefaultTty      ""
 301 #define DefaultOption   ""
 302
 303 typedef void *TUPLE;
 304 #define palloc malloc
 305 #define pfree free
 306
 307 #if defined(sunos4)
 308 extern char *sys_errlist[];
 309 #define strerror(A) (sys_errlist[(A)])
 310 #endif /* sunos4 */
 311
 312 #ifdef __cplusplus
 313 };
 314 #endif
 315
 316 #endif /* LIBPQ_FE_H */
 317