root/trunk/dep/include/postgre/libpq-fe.h @ 2

Revision 2, 18.0 kB (checked in by yumileroy, 17 years ago)

[svn] * Proper SVN structure

Original author: Neo2003
Date: 2008-10-02 16:23:55-05:00
Line 
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-2008, 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.141 2008/01/01 19:46:00 momjian Exp $
11 *
12 *-------------------------------------------------------------------------
13 */
14
15#ifndef LIBPQ_FE_H
16#define LIBPQ_FE_H
17
18#ifdef __cplusplus
19extern          "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
33typedef 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
59typedef 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
69typedef 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
86typedef 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
95typedef 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 */
105typedef 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 */
112typedef 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 */
118typedef 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 */
126typedef 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 */
136typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);
137typedef void (*PQnoticeProcessor) (void *arg, const char *message);
138
139/* Print options for PQprint() */
140typedef char pqbool;
141
142typedef 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 */
165typedef 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 */
184typedef 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) */
204extern PGconn *PQconnectStart(const char *conninfo);
205extern PostgresPollingStatusType PQconnectPoll(PGconn *conn);
206
207/* Synchronous (blocking) */
208extern PGconn *PQconnectdb(const char *conninfo);
209extern 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 */
218extern void PQfinish(PGconn *conn);
219
220/* get info about connection options known to PQconnectdb */
221extern PQconninfoOption *PQconndefaults(void);
222
223/* free the data structure returned by PQconndefaults() */
224extern 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) */
231extern int      PQresetStart(PGconn *conn);
232extern PostgresPollingStatusType PQresetPoll(PGconn *conn);
233
234/* Synchronous (blocking) */
235extern void PQreset(PGconn *conn);
236
237/* request a cancel structure */
238extern PGcancel *PQgetCancel(PGconn *conn);
239
240/* free a cancel structure */
241extern void PQfreeCancel(PGcancel *cancel);
242
243/* issue a cancel request */
244extern int      PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
245
246/* backwards compatible version of PQcancel; not thread-safe */
247extern int      PQrequestCancel(PGconn *conn);
248
249/* Accessor functions for PGconn objects */
250extern char *PQdb(const PGconn *conn);
251extern char *PQuser(const PGconn *conn);
252extern char *PQpass(const PGconn *conn);
253extern char *PQhost(const PGconn *conn);
254extern char *PQport(const PGconn *conn);
255extern char *PQtty(const PGconn *conn);
256extern char *PQoptions(const PGconn *conn);
257extern ConnStatusType PQstatus(const PGconn *conn);
258extern PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
259extern const char *PQparameterStatus(const PGconn *conn,
260                                  const char *paramName);
261extern int      PQprotocolVersion(const PGconn *conn);
262extern int      PQserverVersion(const PGconn *conn);
263extern char *PQerrorMessage(const PGconn *conn);
264extern int      PQsocket(const PGconn *conn);
265extern int      PQbackendPID(const PGconn *conn);
266extern int      PQconnectionNeedsPassword(const PGconn *conn);
267extern int      PQconnectionUsedPassword(const PGconn *conn);
268extern int      PQclientEncoding(const PGconn *conn);
269extern int      PQsetClientEncoding(PGconn *conn, const char *encoding);
270
271/* Get the OpenSSL structure associated with a connection. Returns NULL for
272 * unencrypted connections or if any other TLS library is in use. */
273extern void *PQgetssl(PGconn *conn);
274
275/* Tell libpq whether it needs to initialize OpenSSL */
276extern void PQinitSSL(int do_init);
277
278/* Set verbosity for PQerrorMessage and PQresultErrorMessage */
279extern PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
280
281/* Enable/disable tracing */
282extern void PQtrace(PGconn *conn, FILE *debug_port);
283extern void PQuntrace(PGconn *conn);
284
285/* Override default notice handling routines */
286extern PQnoticeReceiver PQsetNoticeReceiver(PGconn *conn,
287                                        PQnoticeReceiver proc,
288                                        void *arg);
289extern PQnoticeProcessor PQsetNoticeProcessor(PGconn *conn,
290                                         PQnoticeProcessor proc,
291                                         void *arg);
292
293/*
294 *         Used to set callback that prevents concurrent access to
295 *         non-thread safe functions that libpq needs.
296 *         The default implementation uses a libpq internal mutex.
297 *         Only required for multithreaded apps that use kerberos
298 *         both within their app and for postgresql connections.
299 */
300typedef void (*pgthreadlock_t) (int acquire);
301
302extern pgthreadlock_t PQregisterThreadLock(pgthreadlock_t newhandler);
303
304/* === in fe-exec.c === */
305
306/* Simple synchronous query */
307extern PGresult *PQexec(PGconn *conn, const char *query);
308extern PGresult *PQexecParams(PGconn *conn,
309                         const char *command,
310                         int nParams,
311                         const Oid *paramTypes,
312                         const char *const * paramValues,
313                         const int *paramLengths,
314                         const int *paramFormats,
315                         int resultFormat);
316extern PGresult *PQprepare(PGconn *conn, const char *stmtName,
317                  const char *query, int nParams,
318                  const Oid *paramTypes);
319extern PGresult *PQexecPrepared(PGconn *conn,
320                           const char *stmtName,
321                           int nParams,
322                           const char *const * paramValues,
323                           const int *paramLengths,
324                           const int *paramFormats,
325                           int resultFormat);
326
327/* Interface for multiple-result or asynchronous queries */
328extern int      PQsendQuery(PGconn *conn, const char *query);
329extern int PQsendQueryParams(PGconn *conn,
330                                  const char *command,
331                                  int nParams,
332                                  const Oid *paramTypes,
333                                  const char *const * paramValues,
334                                  const int *paramLengths,
335                                  const int *paramFormats,
336                                  int resultFormat);
337extern int PQsendPrepare(PGconn *conn, const char *stmtName,
338                          const char *query, int nParams,
339                          const Oid *paramTypes);
340extern int PQsendQueryPrepared(PGconn *conn,
341                                        const char *stmtName,
342                                        int nParams,
343                                        const char *const * paramValues,
344                                        const int *paramLengths,
345                                        const int *paramFormats,
346                                        int resultFormat);
347extern PGresult *PQgetResult(PGconn *conn);
348
349/* Routines for managing an asynchronous query */
350extern int      PQisBusy(PGconn *conn);
351extern int      PQconsumeInput(PGconn *conn);
352
353/* LISTEN/NOTIFY support */
354extern PGnotify *PQnotifies(PGconn *conn);
355
356/* Routines for copy in/out */
357extern int      PQputCopyData(PGconn *conn, const char *buffer, int nbytes);
358extern int      PQputCopyEnd(PGconn *conn, const char *errormsg);
359extern int      PQgetCopyData(PGconn *conn, char **buffer, int async);
360
361/* Deprecated routines for copy in/out */
362extern int      PQgetline(PGconn *conn, char *string, int length);
363extern int      PQputline(PGconn *conn, const char *string);
364extern int      PQgetlineAsync(PGconn *conn, char *buffer, int bufsize);
365extern int      PQputnbytes(PGconn *conn, const char *buffer, int nbytes);
366extern int      PQendcopy(PGconn *conn);
367
368/* Set blocking/nonblocking connection to the backend */
369extern int      PQsetnonblocking(PGconn *conn, int arg);
370extern int      PQisnonblocking(const PGconn *conn);
371extern int      PQisthreadsafe(void);
372
373/* Force the write buffer to be written (or at least try) */
374extern int      PQflush(PGconn *conn);
375
376/*
377 * "Fast path" interface --- not really recommended for application
378 * use
379 */
380extern PGresult *PQfn(PGconn *conn,
381         int fnid,
382         int *result_buf,
383         int *result_len,
384         int result_is_int,
385         const PQArgBlock *args,
386         int nargs);
387
388/* Accessor functions for PGresult objects */
389extern ExecStatusType PQresultStatus(const PGresult *res);
390extern char *PQresStatus(ExecStatusType status);
391extern char *PQresultErrorMessage(const PGresult *res);
392extern char *PQresultErrorField(const PGresult *res, int fieldcode);
393extern int      PQntuples(const PGresult *res);
394extern int      PQnfields(const PGresult *res);
395extern int      PQbinaryTuples(const PGresult *res);
396extern char *PQfname(const PGresult *res, int field_num);
397extern int      PQfnumber(const PGresult *res, const char *field_name);
398extern Oid      PQftable(const PGresult *res, int field_num);
399extern int      PQftablecol(const PGresult *res, int field_num);
400extern int      PQfformat(const PGresult *res, int field_num);
401extern Oid      PQftype(const PGresult *res, int field_num);
402extern int      PQfsize(const PGresult *res, int field_num);
403extern int      PQfmod(const PGresult *res, int field_num);
404extern char *PQcmdStatus(PGresult *res);
405extern char *PQoidStatus(const PGresult *res);  /* old and ugly */
406extern Oid      PQoidValue(const PGresult *res);        /* new and improved */
407extern char *PQcmdTuples(PGresult *res);
408extern char *PQgetvalue(const PGresult *res, int tup_num, int field_num);
409extern int      PQgetlength(const PGresult *res, int tup_num, int field_num);
410extern int      PQgetisnull(const PGresult *res, int tup_num, int field_num);
411extern int      PQnparams(const PGresult *res);
412extern Oid      PQparamtype(const PGresult *res, int param_num);
413
414/* Describe prepared statements and portals */
415extern PGresult *PQdescribePrepared(PGconn *conn, const char *stmt);
416extern PGresult *PQdescribePortal(PGconn *conn, const char *portal);
417extern int      PQsendDescribePrepared(PGconn *conn, const char *stmt);
418extern int      PQsendDescribePortal(PGconn *conn, const char *portal);
419
420/* Delete a PGresult */
421extern void PQclear(PGresult *res);
422
423/* For freeing other alloc'd results, such as PGnotify structs */
424extern void PQfreemem(void *ptr);
425
426/* Exists for backward compatibility.  bjm 2003-03-24 */
427#define PQfreeNotify(ptr) PQfreemem(ptr)
428
429/* Error when no password was given. */
430/* Note: depending on this is deprecated; use PQconnectionNeedsPassword(). */
431#define PQnoPasswordSupplied    "fe_sendauth: no password supplied\n"
432
433/*
434 * Make an empty PGresult with given status (some apps find this
435 * useful). If conn is not NULL and status indicates an error, the
436 * conn's errorMessage is copied.
437 */
438extern PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
439
440
441/* Quoting strings before inclusion in queries. */
442extern size_t PQescapeStringConn(PGconn *conn,
443                                   char *to, const char *from, size_t length,
444                                   int *error);
445extern unsigned char *PQescapeByteaConn(PGconn *conn,
446                                  const unsigned char *from, size_t from_length,
447                                  size_t *to_length);
448extern unsigned char *PQunescapeBytea(const unsigned char *strtext,
449                                size_t *retbuflen);
450
451/* These forms are deprecated! */
452extern size_t PQescapeString(char *to, const char *from, size_t length);
453extern unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length,
454                          size_t *to_length);
455
456
457
458/* === in fe-print.c === */
459
460extern void
461PQprint(FILE *fout,                             /* output stream */
462                const PGresult *res,
463                const PQprintOpt *ps);  /* option structure */
464
465/*
466 * really old printing routines
467 */
468extern void
469PQdisplayTuples(const PGresult *res,
470                                FILE *fp,               /* where to send the output */
471                                int fillAlign,  /* pad the fields with spaces */
472                                const char *fieldSep,   /* field separator */
473                                int printHeader,        /* display headers? */
474                                int quiet);
475
476extern void
477PQprintTuples(const PGresult *res,
478                          FILE *fout,           /* output stream */
479                          int printAttName, /* print attribute names */
480                          int terseOutput,      /* delimiter bars */
481                          int width);           /* width of column, if 0, use variable width */
482
483
484/* === in fe-lobj.c === */
485
486/* Large-object access routines */
487extern int      lo_open(PGconn *conn, Oid lobjId, int mode);
488extern int      lo_close(PGconn *conn, int fd);
489extern int      lo_read(PGconn *conn, int fd, char *buf, size_t len);
490extern int      lo_write(PGconn *conn, int fd, const char *buf, size_t len);
491extern int      lo_lseek(PGconn *conn, int fd, int offset, int whence);
492extern Oid      lo_creat(PGconn *conn, int mode);
493extern Oid      lo_create(PGconn *conn, Oid lobjId);
494extern int      lo_tell(PGconn *conn, int fd);
495extern int      lo_truncate(PGconn *conn, int fd, size_t len);
496extern int      lo_unlink(PGconn *conn, Oid lobjId);
497extern Oid      lo_import(PGconn *conn, const char *filename);
498extern int      lo_export(PGconn *conn, Oid lobjId, const char *filename);
499
500/* === in fe-misc.c === */
501
502/* Determine length of multibyte encoded char at *s */
503extern int      PQmblen(const char *s, int encoding);
504
505/* Determine display length of multibyte encoded char at *s */
506extern int      PQdsplen(const char *s, int encoding);
507
508/* Get encoding id from environment variable PGCLIENTENCODING */
509extern int      PQenv2encoding(void);
510
511/* === in fe-auth.c === */
512
513extern char *PQencryptPassword(const char *passwd, const char *user);
514
515/* === in encnames.c === */
516
517extern int      pg_char_to_encoding(const char *name);
518extern const char *pg_encoding_to_char(int encoding);
519extern int      pg_valid_server_encoding_id(int encoding);
520
521#ifdef __cplusplus
522}
523#endif
524
525#endif   /* LIBPQ_FE_H */
Note: See TracBrowser for help on using the browser.