|
Eneboo - Documentación para desarrolladores
|
src/libpq/libpq-fe.h
Ir a la documentación de este archivo.
00001 /*------------------------------------------------------------------------- 00002 * 00003 * libpq-fe.h 00004 * This file contains definitions for structures and 00005 * externs for functions used by frontend postgres applications. 00006 * 00007 * Portions Copyright (c) 1996-2005, PostgreSQL Global Development Group 00008 * Portions Copyright (c) 1994, Regents of the University of California 00009 * 00010 * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-fe.h,v 1.120.2.2 2006/05/21 20:19:44 tgl Exp $ 00011 * 00012 *------------------------------------------------------------------------- 00013 */ 00014 00015 #ifndef LIBPQ_FE_H 00016 #define LIBPQ_FE_H 00017 00018 #ifdef __cplusplus 00019 extern "C" 00020 { 00021 #endif 00022 00023 #include <stdio.h> 00024 00025 /* 00026 * postgres_ext.h defines the backend's externally visible types, 00027 * such as Oid. 00028 */ 00029 #include "postgres_ext.h" 00030 00031 /* SSL type is needed here only to declare PQgetssl() */ 00032 #ifdef USE_SSL 00033 #include <openssl/ssl.h> 00034 #endif 00035 00036 /* Application-visible enum types */ 00037 00038 typedef enum 00039 { 00040 /* 00041 * Although it is okay to add to this list, values which become unused 00042 * should never be removed, nor should constants be redefined - that would 00043 * break compatibility with existing code. 00044 */ 00045 CONNECTION_OK, 00046 CONNECTION_BAD, 00047 /* Non-blocking mode only below here */ 00048 00049 /* 00050 * The existence of these should never be relied upon - they should only 00051 * be used for user feedback or similar purposes. 00052 */ 00053 CONNECTION_STARTED, /* Waiting for connection to be made. */ 00054 CONNECTION_MADE, /* Connection OK; waiting to send. */ 00055 CONNECTION_AWAITING_RESPONSE, /* Waiting for a response from the 00056 * postmaster. */ 00057 CONNECTION_AUTH_OK, /* Received authentication; waiting for 00058 * backend startup. */ 00059 CONNECTION_SETENV, /* Negotiating environment. */ 00060 CONNECTION_SSL_STARTUP, /* Negotiating SSL. */ 00061 CONNECTION_NEEDED /* Internal state: connect() needed */ 00062 } ConnStatusType; 00063 00064 typedef enum 00065 { 00066 PGRES_POLLING_FAILED = 0, 00067 PGRES_POLLING_READING, /* These two indicate that one may */ 00068 PGRES_POLLING_WRITING, /* use select before polling again. */ 00069 PGRES_POLLING_OK, 00070 PGRES_POLLING_ACTIVE /* unused; keep for awhile for backwards 00071 * compatibility */ 00072 } PostgresPollingStatusType; 00073 00074 typedef enum 00075 { 00076 PGRES_EMPTY_QUERY = 0, /* empty query string was executed */ 00077 PGRES_COMMAND_OK, /* a query command that doesn't return 00078 * anything was executed properly by the 00079 * backend */ 00080 PGRES_TUPLES_OK, /* a query command that returns tuples was 00081 * executed properly by the backend, PGresult 00082 * contains the result tuples */ 00083 PGRES_COPY_OUT, /* Copy Out data transfer in progress */ 00084 PGRES_COPY_IN, /* Copy In data transfer in progress */ 00085 PGRES_BAD_RESPONSE, /* an unexpected response was recv'd from the 00086 * backend */ 00087 PGRES_NONFATAL_ERROR, /* notice or warning message */ 00088 PGRES_FATAL_ERROR /* query failed */ 00089 } ExecStatusType; 00090 00091 typedef enum 00092 { 00093 PQTRANS_IDLE, /* connection idle */ 00094 PQTRANS_ACTIVE, /* command in progress */ 00095 PQTRANS_INTRANS, /* idle, within transaction block */ 00096 PQTRANS_INERROR, /* idle, within failed transaction */ 00097 PQTRANS_UNKNOWN /* cannot determine status */ 00098 } PGTransactionStatusType; 00099 00100 typedef enum 00101 { 00102 PQERRORS_TERSE, /* single-line error messages */ 00103 PQERRORS_DEFAULT, /* recommended style */ 00104 PQERRORS_VERBOSE /* all the facts, ma'am */ 00105 } PGVerbosity; 00106 00107 /* PGconn encapsulates a connection to the backend. 00108 * The contents of this struct are not supposed to be known to applications. 00109 */ 00110 typedef struct pg_conn PGconn; 00111 00112 /* PGresult encapsulates the result of a query (or more precisely, of a single 00113 * SQL command --- a query string given to PQsendQuery can contain multiple 00114 * commands and thus return multiple PGresult objects). 00115 * The contents of this struct are not supposed to be known to applications. 00116 */ 00117 typedef struct pg_result PGresult; 00118 00119 /* PGcancel encapsulates the information needed to cancel a running 00120 * query on an existing connection. 00121 * The contents of this struct are not supposed to be known to applications. 00122 */ 00123 typedef struct pg_cancel PGcancel; 00124 00125 /* PGnotify represents the occurrence of a NOTIFY message. 00126 * Ideally this would be an opaque typedef, but it's so simple that it's 00127 * unlikely to change. 00128 * NOTE: in Postgres 6.4 and later, the be_pid is the notifying backend's, 00129 * whereas in earlier versions it was always your own backend's PID. 00130 */ 00131 typedef struct pgNotify 00132 { 00133 char *relname; /* notification condition name */ 00134 int be_pid; /* process ID of server process */ 00135 char *extra; /* notification parameter */ 00136 /* Fields below here are private to libpq; apps should not use 'em */ 00137 struct pgNotify *next; /* list link */ 00138 } PGnotify; 00139 00140 /* Function types for notice-handling callbacks */ 00141 typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res); 00142 typedef void (*PQnoticeProcessor) (void *arg, const char *message); 00143 00144 /* Print options for PQprint() */ 00145 typedef char pqbool; 00146 00147 typedef struct _PQprintOpt 00148 { 00149 pqbool header; /* print output field headings and row count */ 00150 pqbool align; /* fill align the fields */ 00151 pqbool standard; /* old brain dead format */ 00152 pqbool html3; /* output html tables */ 00153 pqbool expanded; /* expand tables */ 00154 pqbool pager; /* use pager for output if needed */ 00155 char *fieldSep; /* field separator */ 00156 char *tableOpt; /* insert to HTML <table ...> */ 00157 char *caption; /* HTML <caption> */ 00158 char **fieldName; /* null terminated array of replacement field 00159 * names */ 00160 } PQprintOpt; 00161 00162 /* ---------------- 00163 * Structure for the conninfo parameter definitions returned by PQconndefaults 00164 * 00165 * All fields except "val" point at static strings which must not be altered. 00166 * "val" is either NULL or a malloc'd current-value string. PQconninfoFree() 00167 * will release both the val strings and the PQconninfoOption array itself. 00168 * ---------------- 00169 */ 00170 typedef struct _PQconninfoOption 00171 { 00172 char *keyword; /* The keyword of the option */ 00173 char *envvar; /* Fallback environment variable name */ 00174 char *compiled; /* Fallback compiled in default value */ 00175 char *val; /* Option's current value, or NULL */ 00176 char *label; /* Label for field in connect dialog */ 00177 char *dispchar; /* Character to display for this field in a 00178 * connect dialog. Values are: "" Display 00179 * entered value as is "*" Password field - 00180 * hide value "D" Debug option - don't show 00181 * by default */ 00182 int dispsize; /* Field size in characters for dialog */ 00183 } PQconninfoOption; 00184 00185 /* ---------------- 00186 * PQArgBlock -- structure for PQfn() arguments 00187 * ---------------- 00188 */ 00189 typedef struct 00190 { 00191 int len; 00192 int isint; 00193 union 00194 { 00195 int *ptr; /* can't use void (dec compiler barfs) */ 00196 int integer; 00197 } u; 00198 } PQArgBlock; 00199 00200 /* ---------------- 00201 * Exported functions of libpq 00202 * ---------------- 00203 */ 00204 00205 /* === in fe-connect.c === */ 00206 00207 /* make a new client connection to the backend */ 00208 /* Asynchronous (non-blocking) */ 00209 extern PGconn *PQconnectStart(const char *conninfo); 00210 extern PostgresPollingStatusType PQconnectPoll(PGconn *conn); 00211 00212 /* Synchronous (blocking) */ 00213 extern PGconn *PQconnectdb(const char *conninfo); 00214 extern PGconn *PQsetdbLogin(const char *pghost, const char *pgport, 00215 const char *pgoptions, const char *pgtty, 00216 const char *dbName, 00217 const char *login, const char *pwd); 00218 00219 #define PQsetdb(M_PGHOST,M_PGPORT,M_PGOPT,M_PGTTY,M_DBNAME) \ 00220 PQsetdbLogin(M_PGHOST, M_PGPORT, M_PGOPT, M_PGTTY, M_DBNAME, NULL, NULL) 00221 00222 /* close the current connection and free the PGconn data structure */ 00223 extern void PQfinish(PGconn *conn); 00224 00225 /* get info about connection options known to PQconnectdb */ 00226 extern PQconninfoOption *PQconndefaults(void); 00227 00228 /* free the data structure returned by PQconndefaults() */ 00229 extern void PQconninfoFree(PQconninfoOption *connOptions); 00230 00231 /* 00232 * close the current connection and restablish a new one with the same 00233 * parameters 00234 */ 00235 /* Asynchronous (non-blocking) */ 00236 extern int PQresetStart(PGconn *conn); 00237 extern PostgresPollingStatusType PQresetPoll(PGconn *conn); 00238 00239 /* Synchronous (blocking) */ 00240 extern void PQreset(PGconn *conn); 00241 00242 /* request a cancel structure */ 00243 extern PGcancel *PQgetCancel(PGconn *conn); 00244 00245 /* free a cancel structure */ 00246 extern void PQfreeCancel(PGcancel *cancel); 00247 00248 /* issue a cancel request */ 00249 extern int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize); 00250 00251 /* backwards compatible version of PQcancel; not thread-safe */ 00252 extern int PQrequestCancel(PGconn *conn); 00253 00254 /* Accessor functions for PGconn objects */ 00255 extern char *PQdb(const PGconn *conn); 00256 extern char *PQuser(const PGconn *conn); 00257 extern char *PQpass(const PGconn *conn); 00258 extern char *PQhost(const PGconn *conn); 00259 extern char *PQport(const PGconn *conn); 00260 extern char *PQtty(const PGconn *conn); 00261 extern char *PQoptions(const PGconn *conn); 00262 extern ConnStatusType PQstatus(const PGconn *conn); 00263 extern PGTransactionStatusType PQtransactionStatus(const PGconn *conn); 00264 extern const char *PQparameterStatus(const PGconn *conn, 00265 const char *paramName); 00266 extern int PQprotocolVersion(const PGconn *conn); 00267 extern int PQserverVersion(const PGconn *conn); 00268 extern char *PQerrorMessage(const PGconn *conn); 00269 extern int PQsocket(const PGconn *conn); 00270 extern int PQbackendPID(const PGconn *conn); 00271 extern int PQclientEncoding(const PGconn *conn); 00272 extern int PQsetClientEncoding(PGconn *conn, const char *encoding); 00273 00274 #ifdef USE_SSL 00275 /* Get the SSL structure associated with a connection */ 00276 extern SSL *PQgetssl(PGconn *conn); 00277 #else 00278 extern void *PQgetssl(PGconn *conn); 00279 #endif 00280 00281 /* Tell libpq whether it needs to initialize OpenSSL */ 00282 extern void PQinitSSL(int do_init); 00283 00284 /* Set verbosity for PQerrorMessage and PQresultErrorMessage */ 00285 extern PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); 00286 00287 /* Enable/disable tracing */ 00288 extern void PQtrace(PGconn *conn, FILE *debug_port); 00289 extern void PQuntrace(PGconn *conn); 00290 00291 /* Override default notice handling routines */ 00292 extern PQnoticeReceiver PQsetNoticeReceiver(PGconn *conn, 00293 PQnoticeReceiver proc, 00294 void *arg); 00295 extern PQnoticeProcessor PQsetNoticeProcessor(PGconn *conn, 00296 PQnoticeProcessor proc, 00297 void *arg); 00298 00299 /* 00300 * Used to set callback that prevents concurrent access to 00301 * non-thread safe functions that libpq needs. 00302 * The default implementation uses a libpq internal mutex. 00303 * Only required for multithreaded apps that use kerberos 00304 * both within their app and for postgresql connections. 00305 */ 00306 typedef void (*pgthreadlock_t) (int acquire); 00307 00308 extern pgthreadlock_t PQregisterThreadLock(pgthreadlock_t newhandler); 00309 00310 /* === in fe-exec.c === */ 00311 00312 /* Simple synchronous query */ 00313 extern PGresult *PQexec(PGconn *conn, const char *query); 00314 extern PGresult *PQexecParams(PGconn *conn, 00315 const char *command, 00316 int nParams, 00317 const Oid *paramTypes, 00318 const char *const * paramValues, 00319 const int *paramLengths, 00320 const int *paramFormats, 00321 int resultFormat); 00322 extern PGresult *PQprepare(PGconn *conn, const char *stmtName, 00323 const char *query, int nParams, 00324 const Oid *paramTypes); 00325 extern PGresult *PQexecPrepared(PGconn *conn, 00326 const char *stmtName, 00327 int nParams, 00328 const char *const * paramValues, 00329 const int *paramLengths, 00330 const int *paramFormats, 00331 int resultFormat); 00332 00333 /* Interface for multiple-result or asynchronous queries */ 00334 extern int PQsendQuery(PGconn *conn, const char *query); 00335 extern int PQsendQueryParams(PGconn *conn, 00336 const char *command, 00337 int nParams, 00338 const Oid *paramTypes, 00339 const char *const * paramValues, 00340 const int *paramLengths, 00341 const int *paramFormats, 00342 int resultFormat); 00343 extern int PQsendPrepare(PGconn *conn, const char *stmtName, 00344 const char *query, int nParams, 00345 const Oid *paramTypes); 00346 extern int PQsendQueryPrepared(PGconn *conn, 00347 const char *stmtName, 00348 int nParams, 00349 const char *const * paramValues, 00350 const int *paramLengths, 00351 const int *paramFormats, 00352 int resultFormat); 00353 extern PGresult *PQgetResult(PGconn *conn); 00354 00355 /* Routines for managing an asynchronous query */ 00356 extern int PQisBusy(PGconn *conn); 00357 extern int PQconsumeInput(PGconn *conn); 00358 00359 /* LISTEN/NOTIFY support */ 00360 extern PGnotify *PQnotifies(PGconn *conn); 00361 00362 /* Routines for copy in/out */ 00363 extern int PQputCopyData(PGconn *conn, const char *buffer, int nbytes); 00364 extern int PQputCopyEnd(PGconn *conn, const char *errormsg); 00365 extern int PQgetCopyData(PGconn *conn, char **buffer, int async); 00366 00367 /* Deprecated routines for copy in/out */ 00368 extern int PQgetline(PGconn *conn, char *string, int length); 00369 extern int PQputline(PGconn *conn, const char *string); 00370 extern int PQgetlineAsync(PGconn *conn, char *buffer, int bufsize); 00371 extern int PQputnbytes(PGconn *conn, const char *buffer, int nbytes); 00372 extern int PQendcopy(PGconn *conn); 00373 00374 /* Set blocking/nonblocking connection to the backend */ 00375 extern int PQsetnonblocking(PGconn *conn, int arg); 00376 extern int PQisnonblocking(const PGconn *conn); 00377 00378 /* Force the write buffer to be written (or at least try) */ 00379 extern int PQflush(PGconn *conn); 00380 00381 /* 00382 * "Fast path" interface --- not really recommended for application 00383 * use 00384 */ 00385 extern PGresult *PQfn(PGconn *conn, 00386 int fnid, 00387 int *result_buf, 00388 int *result_len, 00389 int result_is_int, 00390 const PQArgBlock *args, 00391 int nargs); 00392 00393 /* Accessor functions for PGresult objects */ 00394 extern ExecStatusType PQresultStatus(const PGresult *res); 00395 extern char *PQresStatus(ExecStatusType status); 00396 extern char *PQresultErrorMessage(const PGresult *res); 00397 extern char *PQresultErrorField(const PGresult *res, int fieldcode); 00398 extern int PQntuples(const PGresult *res); 00399 extern int PQnfields(const PGresult *res); 00400 extern int PQbinaryTuples(const PGresult *res); 00401 extern char *PQfname(const PGresult *res, int field_num); 00402 extern int PQfnumber(const PGresult *res, const char *field_name); 00403 extern Oid PQftable(const PGresult *res, int field_num); 00404 extern int PQftablecol(const PGresult *res, int field_num); 00405 extern int PQfformat(const PGresult *res, int field_num); 00406 extern Oid PQftype(const PGresult *res, int field_num); 00407 extern int PQfsize(const PGresult *res, int field_num); 00408 extern int PQfmod(const PGresult *res, int field_num); 00409 extern char *PQcmdStatus(PGresult *res); 00410 extern char *PQoidStatus(const PGresult *res); /* old and ugly */ 00411 extern Oid PQoidValue(const PGresult *res); /* new and improved */ 00412 extern char *PQcmdTuples(PGresult *res); 00413 extern char *PQgetvalue(const PGresult *res, int tup_num, int field_num); 00414 extern int PQgetlength(const PGresult *res, int tup_num, int field_num); 00415 extern int PQgetisnull(const PGresult *res, int tup_num, int field_num); 00416 00417 /* Delete a PGresult */ 00418 extern void PQclear(PGresult *res); 00419 00420 /* For freeing other alloc'd results, such as PGnotify structs */ 00421 extern void PQfreemem(void *ptr); 00422 00423 /* Exists for backward compatibility. bjm 2003-03-24 */ 00424 #define PQfreeNotify(ptr) PQfreemem(ptr) 00425 00426 /* Define the string so all uses are consistent. */ 00427 #define PQnoPasswordSupplied "fe_sendauth: no password supplied\n" 00428 00429 /* 00430 * Make an empty PGresult with given status (some apps find this 00431 * useful). If conn is not NULL and status indicates an error, the 00432 * conn's errorMessage is copied. 00433 */ 00434 extern PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); 00435 00436 00437 /* Quoting strings before inclusion in queries. */ 00438 extern size_t PQescapeStringConn(PGconn *conn, 00439 char *to, const char *from, size_t length, 00440 int *error); 00441 extern unsigned char *PQescapeByteaConn(PGconn *conn, 00442 const unsigned char *from, size_t from_length, 00443 size_t *to_length); 00444 extern unsigned char *PQunescapeBytea(const unsigned char *strtext, 00445 size_t *retbuflen); 00446 /* These forms are deprecated! */ 00447 extern size_t PQescapeString(char *to, const char *from, size_t length); 00448 extern unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length, 00449 size_t *to_length); 00450 00451 00452 00453 /* === in fe-print.c === */ 00454 00455 extern void 00456 PQprint(FILE *fout, /* output stream */ 00457 const PGresult *res, 00458 const PQprintOpt *ps); /* option structure */ 00459 00460 /* 00461 * really old printing routines 00462 */ 00463 extern void 00464 PQdisplayTuples(const PGresult *res, 00465 FILE *fp, /* where to send the output */ 00466 int fillAlign, /* pad the fields with spaces */ 00467 const char *fieldSep, /* field separator */ 00468 int printHeader, /* display headers? */ 00469 int quiet); 00470 00471 extern void 00472 PQprintTuples(const PGresult *res, 00473 FILE *fout, /* output stream */ 00474 int printAttName, /* print attribute names */ 00475 int terseOutput, /* delimiter bars */ 00476 int width); /* width of column, if 0, use variable width */ 00477 00478 00479 /* === in fe-lobj.c === */ 00480 00481 /* Large-object access routines */ 00482 extern int lo_open(PGconn *conn, Oid lobjId, int mode); 00483 extern int lo_close(PGconn *conn, int fd); 00484 extern int lo_read(PGconn *conn, int fd, char *buf, size_t len); 00485 extern int lo_write(PGconn *conn, int fd, char *buf, size_t len); 00486 extern int lo_lseek(PGconn *conn, int fd, int offset, int whence); 00487 extern Oid lo_creat(PGconn *conn, int mode); 00488 extern Oid lo_create(PGconn *conn, Oid lobjId); 00489 extern int lo_tell(PGconn *conn, int fd); 00490 extern int lo_unlink(PGconn *conn, Oid lobjId); 00491 extern Oid lo_import(PGconn *conn, const char *filename); 00492 extern int lo_export(PGconn *conn, Oid lobjId, const char *filename); 00493 00494 /* === in fe-misc.c === */ 00495 00496 /* Determine length of multibyte encoded char at *s */ 00497 extern int PQmblen(const char *s, int encoding); 00498 00499 /* Determine display length of multibyte encoded char at *s */ 00500 extern int PQdsplen(const char *s, int encoding); 00501 00502 /* Get encoding id from environment variable PGCLIENTENCODING */ 00503 extern int PQenv2encoding(void); 00504 00505 #ifdef __cplusplus 00506 } 00507 #endif 00508 00509 #endif /* LIBPQ_FE_H */
