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.18 1997/03/12 21:23:16 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 #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   char *pgpass;
 129   char *pgauth;
 130   PGlobjfuncs *lobjfuncs; /* Backend function OID's for large object access */
 131 } PGconn;
 132
 133 #define CMDSTATUS_LEN 40
 134
 135 /* PGresult encapsulates the result of a query */
 136 /* unlike the old libpq, we assume that queries only return in one group */
 137 typedef struct pg_result{
 138   int ntups;
 139   int numAttributes;
 140   PGresAttDesc *attDescs;
 141   PGresAttValue* *tuples; /* each PGresTuple is an array of PGresAttValue's */
 142   int tupArrSize;         /* size of tuples array allocated */
 143   ExecStatusType resultStatus;
 144   char cmdStatus[CMDSTATUS_LEN]; /* cmd status from the last insert query*/
 145   int binary; /* binary tuple values if binary == 1, otherwise ASCII */
 146   PGconn* conn;
 147 } PGresult;
 148
 149 typedef char pqbool;
 150   /* We can't use the conventional "bool", because we are designed to be
 151      included in a user's program, and user may already have that type
 152      defined.  Pqbool, on the other hand, is unlikely to be used.
 153      */
 154
 155 struct _PQprintOpt {
 156     pqbool header;         /* print output field headings and row count */
 157     pqbool align;          /* fill align the fields */
 158     pqbool standard;       /* old brain dead format */
 159     pqbool html3;          /* output html tables */
 160     pqbool expanded;       /* expand tables */
 161     pqbool pager;          /* use pager for output if needed */
 162     char *fieldSep;      /* field separator */
 163     char *tableOpt;      /* insert to HTML <table ...> */
 164     char *caption;       /* HTML <caption> */
 165     char **fieldName;    /* null terminated array of repalcement field names */
 166 };
 167
 168 typedef struct _PQprintOpt PQprintOpt;
 169
 170 /* ----------------
 171  * Structure for the conninfo parameter definitions of PQconnectdb()
 172  * ----------------
 173  */
 174 struct _PQconninfoOption {
 175     char        *keyword;       /* The keyword of the option            */
 176     char        *environ;       /* Fallback environment variable name   */
 177     char        *compiled;      /* Fallback compiled in default value   */
 178     char        *val;           /* Options value                        */
 179     char        *label;         /* Label for field in connect dialog    */
 180     char        *dispchar;      /* Character to display for this field  */
 181                                 /* in a connect dialog. Values are:     */
 182                                 /*    ""   Display entered value as is  */
 183                                 /*    "*"  Password field - hide value  */
 184                                 /*    "D"  Debug options - don't        */
 185                                 /*         create a field by default    */
 186     int         dispsize;       /* Field size in characters for dialog  */
 187 };
 188
 189 typedef struct _PQconninfoOption PQconninfoOption;
 190
 191 /* ===  in fe-connect.c === */
 192   /* make a new client connection to the backend */
 193 extern PGconn* PQconnectdb(const char* conninfo);
 194 extern PQconninfoOption *PQconndefaults(void);
 195 extern PGconn* PQsetdb(const char* pghost, const char* pgport, const char* pgoptions,
 196                        const char* pgtty, const char* dbName);
 197   /* close the current connection and free the PGconn data structure */
 198 extern void PQfinish(PGconn* conn);
 199   /* close the current connection and restablish a new one with the same
 200      parameters */
 201 extern void PQreset(PGconn* conn);
 202
 203 extern char* PQdb(PGconn* conn);
 204 extern char* PQuser(PGconn* conn);
 205 extern char* PQhost(PGconn* conn);
 206 extern char* PQoptions(PGconn* conn);
 207 extern char* PQport(PGconn* conn);
 208 extern char* PQtty(PGconn* conn);
 209 extern ConnStatusType PQstatus(PGconn* conn);
 210 extern char* PQerrorMessage(PGconn* conn);
 211 extern void PQtrace(PGconn *conn, FILE* debug_port);
 212 extern void PQuntrace(PGconn *conn);
 213
 214 /* === in fe-exec.c === */
 215 extern PGresult* PQexec(PGconn* conn, const char* query);
 216 extern int PQgetline(PGconn *conn, char* string, int length);
 217 extern int PQendcopy(PGconn *conn);
 218 extern void PQputline(PGconn *conn, const char* string);
 219 extern ExecStatusType PQresultStatus(PGresult* res);
 220 extern int PQntuples(PGresult *res);
 221 extern int PQnfields(PGresult *res);
 222 extern char* PQfname(PGresult *res, int field_num);
 223 extern int PQfnumber(PGresult *res, const char* field_name);
 224 extern Oid PQftype(PGresult *res, int field_num);
 225 extern short PQfsize(PGresult *res, int field_num);
 226 extern char* PQcmdStatus(PGresult *res);
 227 extern const char* PQoidStatus(PGresult *res);
 228 extern char* PQgetvalue(PGresult *res, int tup_num, int field_num);
 229 extern int PQgetlength(PGresult *res, int tup_num, int field_num);
 230 extern int PQgetisnull(PGresult *res, int tup_num, int field_num);
 231 extern void PQclear(PGresult* res);
 232 /* PQdisplayTuples() is a better version of PQprintTuples() */
 233 extern void PQdisplayTuples(PGresult *res,
 234                             FILE *fp,      /* where to send the output */
 235                             int fillAlign, /* pad the fields with spaces */
 236                             const char *fieldSep,  /* field separator */
 237                             int printHeader, /* display headers? */
 238                             int quiet);
 239 extern void PQprintTuples(PGresult* res,
 240                           FILE* fout,      /* output stream */
 241                           int printAttName,/* print attribute names or not*/
 242                           int terseOutput, /* delimiter bars or not?*/
 243                           int width        /* width of column,
 244                                               if 0, use variable width */
 245                           );
 246 extern void PQprint(FILE* fout,      /* output stream */
 247                     PGresult* res,
 248                     PQprintOpt *ps   /* option structure */
 249                     );
 250 extern PGnotify* PQnotifies(PGconn *conn);
 251 extern PGresult* PQfn(PGconn* conn,
 252                       int fnid,
 253                       int *result_buf,
 254                       int *result_len,
 255                       int result_is_int,
 256                       PQArgBlock *args,
 257                       int nargs);
 258 /* === in fe-auth.c === */
 259 extern MsgType fe_getauthsvc(char* PQerrormsg);
 260 extern void fe_setauthsvc(const char *name, char* PQerrormsg);
 261 extern char *fe_getauthname(char* PQerrormsg);
 262
 263 /* === in fe-misc.c === */
 264 /* pqGets and pqPuts gets and sends strings to the file stream
 265    returns 0 if successful
 266    if debug is non-null, debugging output is sent to that stream
 267 */
 268 extern int pqGets(char* s, int maxlen, FILE* stream, FILE* debug);
 269 extern int pqGetnchar(char* s, int maxlen, FILE* stream, FILE* debug);
 270 extern int pqPutnchar(const char* s, int maxlen, FILE* stream, FILE* debug);
 271 extern int pqPuts(const char* s, FILE* stream, FILE* debug );
 272 extern int pqGetc(FILE* stream, FILE *debug);
 273 /* get a n-byte integer from the stream into result */
 274 /* returns 0 if successful */
 275 extern int pqGetInt(int* result, int bytes, FILE* stream, FILE *debug );
 276 /* put a n-byte integer into the stream */
 277 /* returns 0 if successful */
 278 extern int pqPutInt(const int n, int bytes, FILE* stream, FILE *debug );
 279 extern void pqFlush(FILE* stream, FILE* debug);
 280
 281 /* === in fe-lobj.c === */
 282 int lo_open(PGconn* conn, Oid lobjId, int mode);
 283 int lo_close(PGconn *conn, int fd);
 284 int lo_read(PGconn *conn, int fd, char *buf, int len);
 285 int lo_write(PGconn *conn, int fd, char *buf, int len);
 286 int lo_lseek(PGconn *conn, int fd, int offset, int whence);
 287 Oid lo_creat(PGconn *conn, int mode);
 288 int lo_tell(PGconn *conn, int fd);
 289 int lo_unlink(PGconn *conn, Oid lobjId);
 290 Oid lo_import(PGconn *conn, char *filename);
 291 int lo_export(PGconn *conn, Oid lobjId, char *filename);
 292 /* max length of message to send  */
 293 #define MAX_MESSAGE_LEN 8193
 294
 295 /* maximum number of fields in a tuple */
 296 #define BYTELEN 8
 297 #define MAX_FIELDS 512
 298
 299 /* fall back options if they are not specified by arguments or defined
 300    by environment variables */
 301 #define DefaultHost     "localhost"
 302 #define DefaultTty      ""
 303 #define DefaultOption   ""
 304
 305 typedef void *TUPLE;
 306 #define palloc malloc
 307 #define pfree free
 308
 309 #if defined(sunos4)
 310 extern char *sys_errlist[];
 311 #define strerror(A) (sys_errlist[(A)])
 312 #endif /* sunos4 */
 313
 314 #ifdef __cplusplus
 315 };
 316 #endif
 317
 318 #endif /* LIBPQ_FE_H */
 319