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  * Portions Copyright (c) 1996-2001, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * $Id: libpq-fe.h,v 1.71 2001/03/22 04:01:27 momjian Exp $
  11  *
  12  *-------------------------------------------------------------------------
  13  */
  14
  15 #ifndef LIBPQ_FE_H
  16 #define LIBPQ_FE_H
  17
  18 #ifdef __cplusplus
  19 extern          "C"
  20 {
  21 #endif
  22
  23 #include <stdio.h>
  24 /* postgres_ext.h defines the backend's externally visible types,
  25  * such as Oid.
  26  */
  27 #include "postgres_ext.h"
  28 #ifdef USE_SSL
  29 #include <openssl/ssl.h>
  30 #endif
  31
  32 /* Application-visible enum types */
  33
  34         typedef enum
  35         {
  36
  37                 /*
  38                  * Although you may decide to change this list in some way, values
  39                  * which become unused should never be removed, nor should
  40                  * constants be redefined - that would break compatibility with
  41                  * existing code.
  42                  */
  43                 CONNECTION_OK,
  44                 CONNECTION_BAD,
  45                 /* Non-blocking mode only below here */
  46
  47                 /*
  48                  * The existence of these should never be relied upon - they
  49                  * should only be used for user feedback or similar purposes.
  50                  */
  51                 CONNECTION_STARTED,             /* Waiting for connection to be made.  */
  52                 CONNECTION_MADE,                /* Connection OK; waiting to send.         */
  53                 CONNECTION_AWAITING_RESPONSE,   /* Waiting for a response from the
  54                                                                                  * postmaster.            */
  55                 CONNECTION_AUTH_OK,             /* Received authentication; waiting for
  56                                                                  * backend startup. */
  57                 CONNECTION_SETENV               /* Negotiating environment.    */
  58         } ConnStatusType;
  59
  60         typedef enum
  61         {
  62                 PGRES_POLLING_FAILED = 0,
  63                 PGRES_POLLING_READING,  /* These two indicate that one may        */
  64                 PGRES_POLLING_WRITING,  /* use select before polling again.   */
  65                 PGRES_POLLING_OK,
  66                 PGRES_POLLING_ACTIVE    /* Can call poll function immediately. */
  67         } PostgresPollingStatusType;
  68
  69         typedef enum
  70         {
  71                 PGRES_EMPTY_QUERY = 0,
  72                 PGRES_COMMAND_OK,               /* a query command that doesn't return
  73                                                                  * anything was executed properly by the
  74                                                                  * backend */
  75                 PGRES_TUPLES_OK,                /* a query command that returns tuples was
  76                                                                  * executed properly by the backend,
  77                                                                  * PGresult contains the result tuples */
  78                 PGRES_COPY_OUT,                 /* Copy Out data transfer in progress */
  79                 PGRES_COPY_IN,                  /* Copy In data transfer in progress */
  80                 PGRES_BAD_RESPONSE,             /* an unexpected response was recv'd from
  81                                                                  * the backend */
  82                 PGRES_NONFATAL_ERROR,
  83                 PGRES_FATAL_ERROR
  84         } ExecStatusType;
  85
  86 /* PGconn encapsulates a connection to the backend.
  87  * The contents of this struct are not supposed to be known to applications.
  88  */
  89         typedef struct pg_conn PGconn;
  90
  91 /* PGresult encapsulates the result of a query (or more precisely, of a single
  92  * SQL command --- a query string given to PQsendQuery can contain multiple
  93  * commands and thus return multiple PGresult objects).
  94  * The contents of this struct are not supposed to be known to applications.
  95  */
  96         typedef struct pg_result PGresult;
  97
  98 /* PGnotify represents the occurrence of a NOTIFY message.
  99  * Ideally this would be an opaque typedef, but it's so simple that it's
 100  * unlikely to change.
 101  * NOTE: in Postgres 6.4 and later, the be_pid is the notifying backend's,
 102  * whereas in earlier versions it was always your own backend's PID.
 103  */
 104         typedef struct pgNotify
 105         {
 106                 char            relname[NAMEDATALEN];           /* name of relation
 107                                                                                                  * containing data */
 108                 int                     be_pid;         /* process id of backend */
 109         } PGnotify;
 110
 111 /* PQnoticeProcessor is the function type for the notice-message callback.
 112  */
 113         typedef void (*PQnoticeProcessor) (void *arg, const char *message);
 114
 115 /* Print options for PQprint() */
 116         typedef char pqbool;
 117
 118         typedef struct _PQprintOpt
 119         {
 120                 pqbool          header;         /* print output field headings and row
 121                                                                  * count */
 122                 pqbool          align;          /* fill align the fields */
 123                 pqbool          standard;       /* old brain dead format */
 124                 pqbool          html3;          /* output html tables */
 125                 pqbool          expanded;       /* expand tables */
 126                 pqbool          pager;          /* use pager for output if needed */
 127                 char       *fieldSep;   /* field separator */
 128                 char       *tableOpt;   /* insert to HTML <table ...> */
 129                 char       *caption;    /* HTML <caption> */
 130                 char      **fieldName;  /* null terminated array of repalcement
 131                                                                  * field names */
 132         } PQprintOpt;
 133
 134 /* ----------------
 135  * Structure for the conninfo parameter definitions returned by PQconndefaults
 136  *
 137  * All fields except "val" point at static strings which must not be altered.
 138  * "val" is either NULL or a malloc'd current-value string.  PQconninfoFree()
 139  * will release both the val strings and the PQconninfoOption array itself.
 140  * ----------------
 141  */
 142         typedef struct _PQconninfoOption
 143         {
 144                 char       *keyword;    /* The keyword of the option                    */
 145                 char       *envvar;             /* Fallback environment variable name   */
 146                 char       *compiled;   /* Fallback compiled in default value   */
 147                 char       *val;                /* Option's current value, or NULL               */
 148                 char       *label;              /* Label for field in connect dialog    */
 149                 char       *dispchar;   /* Character to display for this field in
 150                                                                  * a connect dialog. Values are: ""
 151                                                                  * Display entered value as is "*"
 152                                                                  * Password field - hide value "D"      Debug
 153                                                                  * option - don't show by default */
 154                 int                     dispsize;       /* Field size in characters for dialog  */
 155         } PQconninfoOption;
 156
 157 /* ----------------
 158  * PQArgBlock -- structure for PQfn() arguments
 159  * ----------------
 160  */
 161         typedef struct
 162         {
 163                 int                     len;
 164                 int                     isint;
 165                 union
 166                 {
 167                         int                *ptr;        /* can't use void (dec compiler barfs)   */
 168                         int                     integer;
 169                 }                       u;
 170         } PQArgBlock;
 171
 172 /* ----------------
 173  * Exported functions of libpq
 174  * ----------------
 175  */
 176
 177 /* ===  in fe-connect.c === */
 178
 179         /* make a new client connection to the backend */
 180         /* Asynchronous (non-blocking) */
 181         extern PGconn *PQconnectStart(const char *conninfo);
 182         extern PostgresPollingStatusType PQconnectPoll(PGconn *conn);
 183         /* Synchronous (blocking) */
 184         extern PGconn *PQconnectdb(const char *conninfo);
 185         extern PGconn *PQsetdbLogin(const char *pghost, const char *pgport,
 186                                                                 const char *pgoptions, const char *pgtty,
 187                                                                                         const char *dbName,
 188                                                                          const char *login, const char *pwd);
 189 #define PQsetdb(M_PGHOST,M_PGPORT,M_PGOPT,M_PGTTY,M_DBNAME)  \
 190         PQsetdbLogin(M_PGHOST, M_PGPORT, M_PGOPT, M_PGTTY, M_DBNAME, NULL, NULL)
 191
 192         /* close the current connection and free the PGconn data structure */
 193         extern void PQfinish(PGconn *conn);
 194
 195         /* get info about connection options known to PQconnectdb */
 196         extern PQconninfoOption *PQconndefaults(void);
 197
 198         /* free the data structure returned by PQconndefaults() */
 199         extern void PQconninfoFree(PQconninfoOption *connOptions);
 200
 201         /*
 202          * close the current connection and restablish a new one with the same
 203          * parameters
 204          */
 205         /* Asynchronous (non-blocking) */
 206         extern int      PQresetStart(PGconn *conn);
 207         extern PostgresPollingStatusType PQresetPoll(PGconn *conn);
 208         /* Synchronous (blocking) */
 209         extern void PQreset(PGconn *conn);
 210
 211         /* issue a cancel request */
 212         extern int      PQrequestCancel(PGconn *conn);
 213
 214         /* Accessor functions for PGconn objects */
 215         extern char *PQdb(const PGconn *conn);
 216         extern char *PQuser(const PGconn *conn);
 217         extern char *PQpass(const PGconn *conn);
 218         extern char *PQhost(const PGconn *conn);
 219         extern char *PQport(const PGconn *conn);
 220         extern char *PQtty(const PGconn *conn);
 221         extern char *PQoptions(const PGconn *conn);
 222         extern ConnStatusType PQstatus(const PGconn *conn);
 223         extern char *PQerrorMessage(const PGconn *conn);
 224         extern int      PQsocket(const PGconn *conn);
 225         extern int      PQbackendPID(const PGconn *conn);
 226         extern int      PQclientEncoding(const PGconn *conn);
 227         extern int      PQsetClientEncoding(PGconn *conn, const char *encoding);
 228 #ifdef USE_SSL
 229         /* Get the SSL structure associated with a connection */
 230         extern SSL *PQgetssl(PGconn *conn);
 231 #endif
 232
 233
 234         /* Enable/disable tracing */
 235         extern void PQtrace(PGconn *conn, FILE *debug_port);
 236         extern void PQuntrace(PGconn *conn);
 237
 238         /* Override default notice processor */
 239         extern PQnoticeProcessor PQsetNoticeProcessor(PGconn *conn, PQnoticeProcessor proc, void *arg);
 240
 241 /* === in fe-exec.c === */
 242
 243         /* Simple synchronous query */
 244         extern PGresult *PQexec(PGconn *conn, const char *query);
 245         extern PGnotify *PQnotifies(PGconn *conn);
 246
 247         /* Interface for multiple-result or asynchronous queries */
 248         extern int      PQsendQuery(PGconn *conn, const char *query);
 249         extern PGresult *PQgetResult(PGconn *conn);
 250
 251         /* Routines for managing an asychronous query */
 252         extern int      PQisBusy(PGconn *conn);
 253         extern int      PQconsumeInput(PGconn *conn);
 254
 255         /* Routines for copy in/out */
 256         extern int      PQgetline(PGconn *conn, char *string, int length);
 257         extern int      PQputline(PGconn *conn, const char *string);
 258         extern int      PQgetlineAsync(PGconn *conn, char *buffer, int bufsize);
 259         extern int      PQputnbytes(PGconn *conn, const char *buffer, int nbytes);
 260         extern int      PQendcopy(PGconn *conn);
 261
 262         /* Set blocking/nonblocking connection to the backend */
 263         extern int      PQsetnonblocking(PGconn *conn, int arg);
 264         extern int      PQisnonblocking(const PGconn *conn);
 265
 266         /* Force the write buffer to be written (or at least try) */
 267         extern int      PQflush(PGconn *conn);
 268
 269         /*
 270          * "Fast path" interface --- not really recommended for application
 271          * use
 272          */
 273         extern PGresult *PQfn(PGconn *conn,
 274                                                                           int fnid,
 275                                                                           int *result_buf,
 276                                                                           int *result_len,
 277                                                                           int result_is_int,
 278                                                                           const PQArgBlock *args,
 279                                                                           int nargs);
 280
 281         /* Accessor functions for PGresult objects */
 282         extern ExecStatusType PQresultStatus(const PGresult *res);
 283         extern char *PQresStatus(ExecStatusType status);
 284         extern char *PQresultErrorMessage(const PGresult *res);
 285         extern int      PQntuples(const PGresult *res);
 286         extern int      PQnfields(const PGresult *res);
 287         extern int      PQbinaryTuples(const PGresult *res);
 288         extern char *PQfname(const PGresult *res, int field_num);
 289         extern int      PQfnumber(const PGresult *res, const char *field_name);
 290         extern Oid      PQftype(const PGresult *res, int field_num);
 291         extern int      PQfsize(const PGresult *res, int field_num);
 292         extern int      PQfmod(const PGresult *res, int field_num);
 293         extern char *PQcmdStatus(PGresult *res);
 294         extern char *PQoidStatus(const PGresult *res);          /* old and ugly */
 295         extern Oid      PQoidValue(const PGresult *res);                /* new and improved */
 296         extern char *PQcmdTuples(PGresult *res);
 297         extern char *PQgetvalue(const PGresult *res, int tup_num, int field_num);
 298         extern int      PQgetlength(const PGresult *res, int tup_num, int field_num);
 299         extern int      PQgetisnull(const PGresult *res, int tup_num, int field_num);
 300
 301         /* Delete a PGresult */
 302         extern void PQclear(PGresult *res);
 303
 304         /*
 305          * Make an empty PGresult with given status (some apps find this
 306          * useful). If conn is not NULL and status indicates an error, the
 307          * conn's errorMessage is copied.
 308          */
 309         extern PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
 310
 311 /* === in fe-print.c === */
 312
 313         extern void PQprint(FILE *fout,         /* output stream */
 314                                                                         const PGresult *res,
 315                                                                         const PQprintOpt *ps);          /* option structure */
 316
 317         /*
 318          * really old printing routines
 319          */
 320         extern void PQdisplayTuples(const PGresult *res,
 321                                                                                         FILE *fp,       /* where to send the
 322                                                                                                                  * output */
 323                                                                                         int fillAlign,          /* pad the fields with
 324                                                                                                                                  * spaces */
 325                                                                                         const char *fieldSep,           /* field separator */
 326                                                                                         int printHeader,        /* display headers? */
 327                                                                                         int quiet);
 328
 329         extern void PQprintTuples(const PGresult *res,
 330                                                                                   FILE *fout,   /* output stream */
 331                                                                                   int printAttName,             /* print attribute names */
 332                                                                                   int terseOutput,              /* delimiter bars */
 333                                                                                   int width);   /* width of column, if
 334                                                                                                                  * 0, use variable width */
 335
 336
 337 /* === in fe-lobj.c === */
 338
 339         /* Large-object access routines */
 340         extern int      lo_open(PGconn *conn, Oid lobjId, int mode);
 341         extern int      lo_close(PGconn *conn, int fd);
 342         extern int      lo_read(PGconn *conn, int fd, char *buf, size_t len);
 343         extern int      lo_write(PGconn *conn, int fd, char *buf, size_t len);
 344         extern int      lo_lseek(PGconn *conn, int fd, int offset, int whence);
 345         extern Oid      lo_creat(PGconn *conn, int mode);
 346         extern int      lo_tell(PGconn *conn, int fd);
 347         extern int      lo_unlink(PGconn *conn, Oid lobjId);
 348         extern Oid      lo_import(PGconn *conn, const char *filename);
 349         extern int      lo_export(PGconn *conn, Oid lobjId, const char *filename);
 350
 351 /* === in fe-misc.c === */
 352
 353         /* Determine length of multibyte encoded char at *s */
 354         extern int      PQmblen(const unsigned char *s, int encoding);
 355
 356         /* Get encoding id from environment variable PGCLIENTENCODING */
 357         extern int      PQenv2encoding(void);
 358
 359 #ifdef __cplusplus
 360 }
 361
 362 #endif
 363
 364 #endif   /* LIBPQ_FE_H */