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  * Portions Copyright (c) 1996-2006, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-fe.h,v 1.127 2006/04/27 00:53:58 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
  25 /*
  26  * postgres_ext.h defines the backend's externally visible types,
  27  * such as Oid.
  28  */
  29 #include "postgres_ext.h"
  30
  31 /* Application-visible enum types */
  32
  33 typedef enum
  34 {
  35         /*
  36          * Although it is okay to add to this list, values which become unused
  37          * should never be removed, nor should constants be redefined - that would
  38          * break compatibility with existing code.
  39          */
  40         CONNECTION_OK,
  41         CONNECTION_BAD,
  42         /* Non-blocking mode only below here */
  43
  44         /*
  45          * The existence of these should never be relied upon - they should only
  46          * be used for user feedback or similar purposes.
  47          */
  48         CONNECTION_STARTED,                     /* Waiting for connection to be made.  */
  49         CONNECTION_MADE,                        /* Connection OK; waiting to send.         */
  50         CONNECTION_AWAITING_RESPONSE,           /* Waiting for a response from the
  51                                                                                  * postmaster.            */
  52         CONNECTION_AUTH_OK,                     /* Received authentication; waiting for
  53                                                                  * backend startup. */
  54         CONNECTION_SETENV,                      /* Negotiating environment. */
  55         CONNECTION_SSL_STARTUP,         /* Negotiating SSL. */
  56         CONNECTION_NEEDED                       /* Internal state: connect() needed */
  57 } ConnStatusType;
  58
  59 typedef enum
  60 {
  61         PGRES_POLLING_FAILED = 0,
  62         PGRES_POLLING_READING,          /* These two indicate that one may        */
  63         PGRES_POLLING_WRITING,          /* use select before polling again.   */
  64         PGRES_POLLING_OK,
  65         PGRES_POLLING_ACTIVE            /* unused; keep for awhile for backwards
  66                                                                  * compatibility */
  67 } PostgresPollingStatusType;
  68
  69 typedef enum
  70 {
  71         PGRES_EMPTY_QUERY = 0,          /* empty query string was executed */
  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, PGresult
  77                                                                  * 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 the
  81                                                                  * backend */
  82         PGRES_NONFATAL_ERROR,           /* notice or warning message */
  83         PGRES_FATAL_ERROR                       /* query failed */
  84 } ExecStatusType;
  85
  86 typedef enum
  87 {
  88         PQTRANS_IDLE,                           /* connection idle */
  89         PQTRANS_ACTIVE,                         /* command in progress */
  90         PQTRANS_INTRANS,                        /* idle, within transaction block */
  91         PQTRANS_INERROR,                        /* idle, within failed transaction */
  92         PQTRANS_UNKNOWN                         /* cannot determine status */
  93 } PGTransactionStatusType;
  94
  95 typedef enum
  96 {
  97         PQERRORS_TERSE,                         /* single-line error messages */
  98         PQERRORS_DEFAULT,                       /* recommended style */
  99         PQERRORS_VERBOSE                        /* all the facts, ma'am */
 100 } PGVerbosity;
 101
 102 /* PGconn encapsulates a connection to the backend.
 103  * The contents of this struct are not supposed to be known to applications.
 104  */
 105 typedef struct pg_conn PGconn;
 106
 107 /* PGresult encapsulates the result of a query (or more precisely, of a single
 108  * SQL command --- a query string given to PQsendQuery can contain multiple
 109  * commands and thus return multiple PGresult objects).
 110  * The contents of this struct are not supposed to be known to applications.
 111  */
 112 typedef struct pg_result PGresult;
 113
 114 /* PGcancel encapsulates the information needed to cancel a running
 115  * query on an existing connection.
 116  * The contents of this struct are not supposed to be known to applications.
 117  */
 118 typedef struct pg_cancel PGcancel;
 119
 120 /* PGnotify represents the occurrence of a NOTIFY message.
 121  * Ideally this would be an opaque typedef, but it's so simple that it's
 122  * unlikely to change.
 123  * NOTE: in Postgres 6.4 and later, the be_pid is the notifying backend's,
 124  * whereas in earlier versions it was always your own backend's PID.
 125  */
 126 typedef struct pgNotify
 127 {
 128         char       *relname;            /* notification condition name */
 129         int                     be_pid;                 /* process ID of notifying server process */
 130         char       *extra;                      /* notification parameter */
 131         /* Fields below here are private to libpq; apps should not use 'em */
 132         struct pgNotify *next;          /* list link */
 133 } PGnotify;
 134
 135 /* Function types for notice-handling callbacks */
 136 typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);
 137 typedef void (*PQnoticeProcessor) (void *arg, const char *message);
 138
 139 /* Print options for PQprint() */
 140 typedef char pqbool;
 141
 142 typedef struct _PQprintOpt
 143 {
 144         pqbool          header;                 /* print output field headings and row count */
 145         pqbool          align;                  /* fill align the fields */
 146         pqbool          standard;               /* old brain dead format */
 147         pqbool          html3;                  /* output html tables */
 148         pqbool          expanded;               /* expand tables */
 149         pqbool          pager;                  /* use pager for output if needed */
 150         char       *fieldSep;           /* field separator */
 151         char       *tableOpt;           /* insert to HTML <table ...> */
 152         char       *caption;            /* HTML <caption> */
 153         char      **fieldName;          /* null terminated array of replacement field
 154                                                                  * names */
 155 } PQprintOpt;
 156
 157 /* ----------------
 158  * Structure for the conninfo parameter definitions returned by PQconndefaults
 159  *
 160  * All fields except "val" point at static strings which must not be altered.
 161  * "val" is either NULL or a malloc'd current-value string.  PQconninfoFree()
 162  * will release both the val strings and the PQconninfoOption array itself.
 163  * ----------------
 164  */
 165 typedef struct _PQconninfoOption
 166 {
 167         char       *keyword;            /* The keyword of the option                    */
 168         char       *envvar;                     /* Fallback environment variable name   */
 169         char       *compiled;           /* Fallback compiled in default value   */
 170         char       *val;                        /* Option's current value, or NULL               */
 171         char       *label;                      /* Label for field in connect dialog    */
 172         char       *dispchar;           /* Character to display for this field in a
 173                                                                  * connect dialog. Values are: "" Display
 174                                                                  * entered value as is "*" Password field -
 175                                                                  * hide value "D"  Debug option - don't show
 176                                                                  * by default */
 177         int                     dispsize;               /* Field size in characters for dialog  */
 178 } PQconninfoOption;
 179
 180 /* ----------------
 181  * PQArgBlock -- structure for PQfn() arguments
 182  * ----------------
 183  */
 184 typedef struct
 185 {
 186         int                     len;
 187         int                     isint;
 188         union
 189         {
 190                 int                *ptr;                /* can't use void (dec compiler barfs)   */
 191                 int                     integer;
 192         }                       u;
 193 } PQArgBlock;
 194
 195 /* ----------------
 196  * Exported functions of libpq
 197  * ----------------
 198  */
 199
 200 /* ===  in fe-connect.c === */
 201
 202 /* make a new client connection to the backend */
 203 /* Asynchronous (non-blocking) */
 204 extern PGconn *PQconnectStart(const char *conninfo);
 205 extern PostgresPollingStatusType PQconnectPoll(PGconn *conn);
 206
 207 /* Synchronous (blocking) */
 208 extern PGconn *PQconnectdb(const char *conninfo);
 209 extern PGconn *PQsetdbLogin(const char *pghost, const char *pgport,
 210                          const char *pgoptions, const char *pgtty,
 211                          const char *dbName,
 212                          const char *login, const char *pwd);
 213
 214 #define PQsetdb(M_PGHOST,M_PGPORT,M_PGOPT,M_PGTTY,M_DBNAME)  \
 215         PQsetdbLogin(M_PGHOST, M_PGPORT, M_PGOPT, M_PGTTY, M_DBNAME, NULL, NULL)
 216
 217 /* close the current connection and free the PGconn data structure */
 218 extern void PQfinish(PGconn *conn);
 219
 220 /* get info about connection options known to PQconnectdb */
 221 extern PQconninfoOption *PQconndefaults(void);
 222
 223 /* free the data structure returned by PQconndefaults() */
 224 extern void PQconninfoFree(PQconninfoOption *connOptions);
 225
 226 /*
 227  * close the current connection and restablish a new one with the same
 228  * parameters
 229  */
 230 /* Asynchronous (non-blocking) */
 231 extern int      PQresetStart(PGconn *conn);
 232 extern PostgresPollingStatusType PQresetPoll(PGconn *conn);
 233
 234 /* Synchronous (blocking) */
 235 extern void PQreset(PGconn *conn);
 236
 237 /* request a cancel structure */
 238 extern PGcancel *PQgetCancel(PGconn *conn);
 239
 240 /* free a cancel structure */
 241 extern void PQfreeCancel(PGcancel *cancel);
 242
 243 /* issue a cancel request */
 244 extern int      PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
 245
 246 /* backwards compatible version of PQcancel; not thread-safe */
 247 extern int      PQrequestCancel(PGconn *conn);
 248
 249 /* Accessor functions for PGconn objects */
 250 extern char *PQdb(const PGconn *conn);
 251 extern char *PQuser(const PGconn *conn);
 252 extern char *PQpass(const PGconn *conn);
 253 extern char *PQhost(const PGconn *conn);
 254 extern char *PQport(const PGconn *conn);
 255 extern char *PQtty(const PGconn *conn);
 256 extern char *PQoptions(const PGconn *conn);
 257 extern ConnStatusType PQstatus(const PGconn *conn);
 258 extern PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
 259 extern const char *PQparameterStatus(const PGconn *conn,
 260                                   const char *paramName);
 261 extern int      PQprotocolVersion(const PGconn *conn);
 262 extern int      PQserverVersion(const PGconn *conn);
 263 extern char *PQerrorMessage(const PGconn *conn);
 264 extern int      PQsocket(const PGconn *conn);
 265 extern int      PQbackendPID(const PGconn *conn);
 266 extern int      PQclientEncoding(const PGconn *conn);
 267 extern int      PQsetClientEncoding(PGconn *conn, const char *encoding);
 268
 269 /* Get the OpenSSL structure associated with a connection. Returns NULL for
 270  * unencrypted connections or if any other TLS library is in use. */
 271 extern void *PQgetssl(PGconn *conn);
 272
 273 /* Tell libpq whether it needs to initialize OpenSSL */
 274 extern void PQinitSSL(int do_init);
 275
 276 /* Set verbosity for PQerrorMessage and PQresultErrorMessage */
 277 extern PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
 278
 279 /* Enable/disable tracing */
 280 extern void PQtrace(PGconn *conn, FILE *debug_port);
 281 extern void PQuntrace(PGconn *conn);
 282
 283 /* Override default notice handling routines */
 284 extern PQnoticeReceiver PQsetNoticeReceiver(PGconn *conn,
 285                                         PQnoticeReceiver proc,
 286                                         void *arg);
 287 extern PQnoticeProcessor PQsetNoticeProcessor(PGconn *conn,
 288                                          PQnoticeProcessor proc,
 289                                          void *arg);
 290
 291 /*
 292  *         Used to set callback that prevents concurrent access to
 293  *         non-thread safe functions that libpq needs.
 294  *         The default implementation uses a libpq internal mutex.
 295  *         Only required for multithreaded apps that use kerberos
 296  *         both within their app and for postgresql connections.
 297  */
 298 typedef void (*pgthreadlock_t) (int acquire);
 299
 300 extern pgthreadlock_t PQregisterThreadLock(pgthreadlock_t newhandler);
 301
 302 /* === in fe-exec.c === */
 303
 304 /* Simple synchronous query */
 305 extern PGresult *PQexec(PGconn *conn, const char *query);
 306 extern PGresult *PQexecParams(PGconn *conn,
 307                          const char *command,
 308                          int nParams,
 309                          const Oid *paramTypes,
 310                          const char *const * paramValues,
 311                          const int *paramLengths,
 312                          const int *paramFormats,
 313                          int resultFormat);
 314 extern PGresult *PQprepare(PGconn *conn, const char *stmtName,
 315                   const char *query, int nParams,
 316                   const Oid *paramTypes);
 317 extern PGresult *PQexecPrepared(PGconn *conn,
 318                            const char *stmtName,
 319                            int nParams,
 320                            const char *const * paramValues,
 321                            const int *paramLengths,
 322                            const int *paramFormats,
 323                            int resultFormat);
 324
 325 /* Interface for multiple-result or asynchronous queries */
 326 extern int      PQsendQuery(PGconn *conn, const char *query);
 327 extern int PQsendQueryParams(PGconn *conn,
 328                                   const char *command,
 329                                   int nParams,
 330                                   const Oid *paramTypes,
 331                                   const char *const * paramValues,
 332                                   const int *paramLengths,
 333                                   const int *paramFormats,
 334                                   int resultFormat);
 335 extern int PQsendPrepare(PGconn *conn, const char *stmtName,
 336                           const char *query, int nParams,
 337                           const Oid *paramTypes);
 338 extern int PQsendQueryPrepared(PGconn *conn,
 339                                         const char *stmtName,
 340                                         int nParams,
 341                                         const char *const * paramValues,
 342                                         const int *paramLengths,
 343                                         const int *paramFormats,
 344                                         int resultFormat);
 345 extern PGresult *PQgetResult(PGconn *conn);
 346
 347 /* Routines for managing an asynchronous query */
 348 extern int      PQisBusy(PGconn *conn);
 349 extern int      PQconsumeInput(PGconn *conn);
 350
 351 /* LISTEN/NOTIFY support */
 352 extern PGnotify *PQnotifies(PGconn *conn);
 353
 354 /* Routines for copy in/out */
 355 extern int      PQputCopyData(PGconn *conn, const char *buffer, int nbytes);
 356 extern int      PQputCopyEnd(PGconn *conn, const char *errormsg);
 357 extern int      PQgetCopyData(PGconn *conn, char **buffer, int async);
 358
 359 /* Deprecated routines for copy in/out */
 360 extern int      PQgetline(PGconn *conn, char *string, int length);
 361 extern int      PQputline(PGconn *conn, const char *string);
 362 extern int      PQgetlineAsync(PGconn *conn, char *buffer, int bufsize);
 363 extern int      PQputnbytes(PGconn *conn, const char *buffer, int nbytes);
 364 extern int      PQendcopy(PGconn *conn);
 365
 366 /* Set blocking/nonblocking connection to the backend */
 367 extern int      PQsetnonblocking(PGconn *conn, int arg);
 368 extern int      PQisnonblocking(const PGconn *conn);
 369
 370 /* Force the write buffer to be written (or at least try) */
 371 extern int      PQflush(PGconn *conn);
 372
 373 /*
 374  * "Fast path" interface --- not really recommended for application
 375  * use
 376  */
 377 extern PGresult *PQfn(PGconn *conn,
 378          int fnid,
 379          int *result_buf,
 380          int *result_len,
 381          int result_is_int,
 382          const PQArgBlock *args,
 383          int nargs);
 384
 385 /* Accessor functions for PGresult objects */
 386 extern ExecStatusType PQresultStatus(const PGresult *res);
 387 extern char *PQresStatus(ExecStatusType status);
 388 extern char *PQresultErrorMessage(const PGresult *res);
 389 extern char *PQresultErrorField(const PGresult *res, int fieldcode);
 390 extern int      PQntuples(const PGresult *res);
 391 extern int      PQnfields(const PGresult *res);
 392 extern int      PQbinaryTuples(const PGresult *res);
 393 extern char *PQfname(const PGresult *res, int field_num);
 394 extern int      PQfnumber(const PGresult *res, const char *field_name);
 395 extern Oid      PQftable(const PGresult *res, int field_num);
 396 extern int      PQftablecol(const PGresult *res, int field_num);
 397 extern int      PQfformat(const PGresult *res, int field_num);
 398 extern Oid      PQftype(const PGresult *res, int field_num);
 399 extern int      PQfsize(const PGresult *res, int field_num);
 400 extern int      PQfmod(const PGresult *res, int field_num);
 401 extern char *PQcmdStatus(PGresult *res);
 402 extern char *PQoidStatus(const PGresult *res);  /* old and ugly */
 403 extern Oid      PQoidValue(const PGresult *res);        /* new and improved */
 404 extern char *PQcmdTuples(PGresult *res);
 405 extern char *PQgetvalue(const PGresult *res, int tup_num, int field_num);
 406 extern int      PQgetlength(const PGresult *res, int tup_num, int field_num);
 407 extern int      PQgetisnull(const PGresult *res, int tup_num, int field_num);
 408
 409 /* Delete a PGresult */
 410 extern void PQclear(PGresult *res);
 411
 412 /* For freeing other alloc'd results, such as PGnotify structs */
 413 extern void PQfreemem(void *ptr);
 414
 415 /* Exists for backward compatibility.  bjm 2003-03-24 */
 416 #define PQfreeNotify(ptr) PQfreemem(ptr)
 417
 418 /* Define the string so all uses are consistent. */
 419 #define PQnoPasswordSupplied    "fe_sendauth: no password supplied\n"
 420
 421 /*
 422  * Make an empty PGresult with given status (some apps find this
 423  * useful). If conn is not NULL and status indicates an error, the
 424  * conn's errorMessage is copied.
 425  */
 426 extern PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
 427
 428
 429 /* Quoting strings before inclusion in queries. */
 430 extern size_t PQescapeString(char *to, const char *from, size_t length);
 431 extern unsigned char *PQescapeBytea(const unsigned char *bintext, size_t binlen,
 432                           size_t *bytealen);
 433 extern unsigned char *PQunescapeBytea(const unsigned char *strtext,
 434                                 size_t *retbuflen);
 435
 436
 437
 438 /* === in fe-print.c === */
 439
 440 extern void
 441 PQprint(FILE *fout,                             /* output stream */
 442                 const PGresult *res,
 443                 const PQprintOpt *ps);  /* option structure */
 444
 445 /*
 446  * really old printing routines
 447  */
 448 extern void
 449 PQdisplayTuples(const PGresult *res,
 450                                 FILE *fp,               /* where to send the output */
 451                                 int fillAlign,  /* pad the fields with spaces */
 452                                 const char *fieldSep,   /* field separator */
 453                                 int printHeader,        /* display headers? */
 454                                 int quiet);
 455
 456 extern void
 457 PQprintTuples(const PGresult *res,
 458                           FILE *fout,           /* output stream */
 459                           int printAttName, /* print attribute names */
 460                           int terseOutput,      /* delimiter bars */
 461                           int width);           /* width of column, if 0, use variable width */
 462
 463
 464 /* === in fe-lobj.c === */
 465
 466 /* Large-object access routines */
 467 extern int      lo_open(PGconn *conn, Oid lobjId, int mode);
 468 extern int      lo_close(PGconn *conn, int fd);
 469 extern int      lo_read(PGconn *conn, int fd, char *buf, size_t len);
 470 extern int      lo_write(PGconn *conn, int fd, char *buf, size_t len);
 471 extern int      lo_lseek(PGconn *conn, int fd, int offset, int whence);
 472 extern Oid      lo_creat(PGconn *conn, int mode);
 473 extern Oid      lo_create(PGconn *conn, Oid lobjId);
 474 extern int      lo_tell(PGconn *conn, int fd);
 475 extern int      lo_unlink(PGconn *conn, Oid lobjId);
 476 extern Oid      lo_import(PGconn *conn, const char *filename);
 477 extern int      lo_export(PGconn *conn, Oid lobjId, const char *filename);
 478
 479 /* === in fe-misc.c === */
 480
 481 /* Determine length of multibyte encoded char at *s */
 482 extern int      PQmblen(const char *s, int encoding);
 483
 484 /* Determine display length of multibyte encoded char at *s */
 485 extern int      PQdsplen(const char *s, int encoding);
 486
 487 /* Get encoding id from environment variable PGCLIENTENCODING */
 488 extern int      PQenv2encoding(void);
 489
 490 /* === in fe-auth.c === */
 491
 492 extern char *PQencryptPassword(const char *passwd, const char *user);
 493
 494 #ifdef __cplusplus
 495 }
 496 #endif
 497
 498 #endif   /* LIBPQ_FE_H */