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