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