granicus.if.org Git - postgresql/blob - src/interfaces/libpq/libpq-int.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * libpq-int.h
   4  *        This file contains internal definitions meant to be used only by
   5  *        the frontend libpq library, not by applications that call it.
   6  *
   7  *        An application can include this file if it wants to bypass the
   8  *        official API defined by libpq-fe.h, but code that does so is much
   9  *        more likely to break across PostgreSQL releases than code that uses
  10  *        only the official API.
  11  *
  12  * Portions Copyright (c) 1996-2001, PostgreSQL Global Development Group
  13  * Portions Copyright (c) 1994, Regents of the University of California
  14  *
  15  * $Id: libpq-int.h,v 1.35 2001/07/06 19:04:23 petere Exp $
  16  *
  17  *-------------------------------------------------------------------------
  18  */
  19
  20 #ifndef LIBPQ_INT_H
  21 #define LIBPQ_INT_H
  22
  23 /* We assume libpq-fe.h has already been included. */
  24 #include "postgres_fe.h"
  25
  26 /* include stuff common to fe and be */
  27 #include "libpq/pqcomm.h"
  28 #include "lib/dllist.h"
  29 /* include stuff found in fe only */
  30 #include "pqexpbuffer.h"
  31
  32 #ifdef USE_SSL
  33 #include <openssl/ssl.h>
  34 #include <openssl/err.h>
  35 #endif
  36
  37 /* libpq supports this version of the frontend/backend protocol.
  38  *
  39  * NB: we used to use PG_PROTOCOL_LATEST from the backend pqcomm.h file,
  40  * but that's not really the right thing: just recompiling libpq
  41  * against a more recent backend isn't going to magically update it
  42  * for most sorts of protocol changes.  So, when you change libpq
  43  * to support a different protocol revision, you have to change this
  44  * constant too.  PG_PROTOCOL_EARLIEST and PG_PROTOCOL_LATEST in
  45  * pqcomm.h describe what the backend knows, not what libpq knows.
  46  */
  47
  48 #define PG_PROTOCOL_LIBPQ       PG_PROTOCOL(2,0)
  49
  50 /*
  51  * POSTGRES backend dependent Constants.
  52  */
  53
  54 #define PQERRORMSG_LENGTH 1024
  55 #define CMDSTATUS_LEN 40
  56
  57 /*
  58  * PGresult and the subsidiary types PGresAttDesc, PGresAttValue
  59  * represent the result of a query (or more precisely, of a single SQL
  60  * command --- a query string given to PQexec can contain multiple commands).
  61  * Note we assume that a single command can return at most one tuple group,
  62  * hence there is no need for multiple descriptor sets.
  63  */
  64
  65 /* Subsidiary-storage management structure for PGresult.
  66  * See space management routines in fe-exec.c for details.
  67  * Note that space[k] refers to the k'th byte starting from the physical
  68  * head of the block --- it's a union, not a struct!
  69  */
  70 typedef union pgresult_data PGresult_data;
  71
  72 union pgresult_data
  73 {
  74         PGresult_data *next;            /* link to next block, or NULL */
  75         char            space[1];               /* dummy for accessing block as bytes */
  76 };
  77
  78 /* Data about a single attribute (column) of a query result */
  79
  80 typedef struct pgresAttDesc
  81 {
  82         char       *name;                       /* type name */
  83         Oid                     typid;                  /* type id */
  84         int                     typlen;                 /* type size */
  85         int                     atttypmod;              /* type-specific modifier info */
  86 }                       PGresAttDesc;
  87
  88 /* Data for a single attribute of a single tuple */
  89
  90 /* We use char* for Attribute values.
  91    The value pointer always points to a null-terminated area; we add a
  92    null (zero) byte after whatever the backend sends us.  This is only
  93    particularly useful for ASCII tuples ... with a binary value, the
  94    value might have embedded nulls, so the application can't use C string
  95    operators on it.  But we add a null anyway for consistency.
  96    Note that the value itself does not contain a length word.
  97
  98    A NULL attribute is a special case in two ways: its len field is NULL_LEN
  99    and its value field points to null_field in the owning PGresult.  All the
 100    NULL attributes in a query result point to the same place (there's no need
 101    to store a null string separately for each one).
 102  */
 103
 104 #define NULL_LEN                (-1)    /* pg_result len for NULL value */
 105
 106 typedef struct pgresAttValue
 107 {
 108         int                     len;                    /* length in bytes of the value */
 109         char       *value;                      /* actual value, plus terminating zero
 110                                                                  * byte */
 111 }                       PGresAttValue;
 112
 113 struct pg_result
 114 {
 115         int                     ntups;
 116         int                     numAttributes;
 117         PGresAttDesc *attDescs;
 118         PGresAttValue **tuples;         /* each PGresTuple is an array of
 119                                                                  * PGresAttValue's */
 120         int                     tupArrSize;             /* size of tuples array allocated */
 121         ExecStatusType resultStatus;
 122         char            cmdStatus[CMDSTATUS_LEN];               /* cmd status from the
 123                                                                                                  * last query */
 124         int                     binary;                 /* binary tuple values if binary == 1,
 125                                                                  * otherwise ASCII */
 126
 127         /*
 128          * The conn link in PGresult is no longer used by any libpq code. It
 129          * should be removed entirely, because it could be a dangling link
 130          * (the application could keep the PGresult around longer than it
 131          * keeps the PGconn!)  But there may be apps out there that depend on
 132          * it, so we will leave it here at least for a release or so.
 133          */
 134         PGconn     *xconn;                      /* connection we did the query on, if any */
 135
 136         /*
 137          * These fields are copied from the originating PGconn, so that
 138          * operations on the PGresult don't have to reference the PGconn.
 139          */
 140         PQnoticeProcessor noticeHook;           /* notice/error message processor */
 141         void       *noticeArg;
 142         int                     client_encoding;/* encoding id */
 143
 144
 145         char       *errMsg;                     /* error message, or NULL if no error */
 146
 147         /* All NULL attributes in the query result point to this null string */
 148         char            null_field[1];
 149
 150         /*
 151          * Space management information.  Note that attDescs and errMsg, if
 152          * not null, point into allocated blocks.  But tuples points to a
 153          * separately malloc'd block, so that we can realloc it.
 154          */
 155         PGresult_data *curBlock;        /* most recently allocated block */
 156         int                     curOffset;              /* start offset of free space in block */
 157         int                     spaceLeft;              /* number of free bytes remaining in block */
 158 };
 159
 160 /* PGAsyncStatusType defines the state of the query-execution state machine */
 161 typedef enum
 162 {
 163         PGASYNC_IDLE,                           /* nothing's happening, dude */
 164         PGASYNC_BUSY,                           /* query in progress */
 165         PGASYNC_READY,                          /* result ready for PQgetResult */
 166         PGASYNC_COPY_IN,                        /* Copy In data transfer in progress */
 167         PGASYNC_COPY_OUT                        /* Copy Out data transfer in progress */
 168 }                       PGAsyncStatusType;
 169
 170 /* PGSetenvStatusType defines the state of the PQSetenv state machine */
 171 typedef enum
 172 {
 173         SETENV_STATE_OPTION_SEND,       /* About to send an Environment Option */
 174         SETENV_STATE_OPTION_WAIT,       /* Waiting for above send to complete  */
 175         /* these next two are only used in MULTIBYTE mode */
 176         SETENV_STATE_ENCODINGS_SEND,/* About to send an "encodings" query */
 177         SETENV_STATE_ENCODINGS_WAIT,/* Waiting for query to complete      */
 178         SETENV_STATE_IDLE
 179 }                       PGSetenvStatusType;
 180
 181 /* large-object-access data ... allocated only if large-object code is used. */
 182 typedef struct pgLobjfuncs
 183 {
 184         Oid                     fn_lo_open;             /* OID of backend function lo_open              */
 185         Oid                     fn_lo_close;    /* OID of backend function lo_close             */
 186         Oid                     fn_lo_creat;    /* OID of backend function lo_creat             */
 187         Oid                     fn_lo_unlink;   /* OID of backend function lo_unlink    */
 188         Oid                     fn_lo_lseek;    /* OID of backend function lo_lseek             */
 189         Oid                     fn_lo_tell;             /* OID of backend function lo_tell              */
 190         Oid                     fn_lo_read;             /* OID of backend function LOread               */
 191         Oid                     fn_lo_write;    /* OID of backend function LOwrite              */
 192 }                       PGlobjfuncs;
 193
 194 /* PGconn stores all the state data associated with a single connection
 195  * to a backend.
 196  */
 197 struct pg_conn
 198 {
 199         /* Saved values of connection options */
 200         char       *pghost;                     /* the machine on which the server is
 201                                                                  * running */
 202         char       *pghostaddr;         /* the IPv4 address of the machine on
 203                                                                  * which the server is running, in IPv4
 204                                                                  * numbers-and-dots notation. Takes
 205                                                                  * precedence over above. */
 206         char       *pgport;                     /* the server's communication port */
 207         char       *pgunixsocket;       /* the Unix-domain socket that the server
 208                                                                  * is listening on; if NULL, uses a
 209                                                                  * default constructed from pgport */
 210         char       *pgtty;                      /* tty on which the backend messages is
 211                                                                  * displayed (NOT ACTUALLY USED???) */
 212         char       *pgoptions;          /* options to start the backend with */
 213         char       *dbName;                     /* database name */
 214         char       *pguser;                     /* Postgres username and password, if any */
 215         char       *pgpass;
 216
 217         /* Optional file to write trace info to */
 218         FILE       *Pfdebug;
 219
 220         /* Callback procedure for notice/error message processing */
 221         PQnoticeProcessor noticeHook;
 222         void       *noticeArg;
 223
 224         /* Status indicators */
 225         ConnStatusType status;
 226         PGAsyncStatusType asyncStatus;
 227         Dllist     *notifyList;         /* Notify msgs not yet handed to
 228                                                                  * application */
 229
 230         /* Connection data */
 231         int                     sock;                   /* Unix FD for socket, -1 if not connected */
 232         SockAddr        laddr;                  /* Local address */
 233         SockAddr        raddr;                  /* Remote address */
 234         int                     raddr_len;              /* Length of remote address */
 235
 236         /* Miscellaneous stuff */
 237         int                     be_pid;                 /* PID of backend --- needed for cancels */
 238         int                     be_key;                 /* key of backend --- needed for cancels */
 239         char            salt[2];                /* password salt received from backend */
 240         PGlobjfuncs *lobjfuncs;         /* private state for large-object access
 241                                                                  * fns */
 242
 243         /* Buffer for data received from backend and not yet processed */
 244         char       *inBuffer;           /* currently allocated buffer */
 245         int                     inBufSize;              /* allocated size of buffer */
 246         int                     inStart;                /* offset to first unconsumed data in
 247                                                                  * buffer */
 248         int                     inCursor;               /* next byte to tentatively consume */
 249         int                     inEnd;                  /* offset to first position after avail
 250                                                                  * data */
 251
 252         int                     nonblocking;    /* whether this connection is using a
 253                                                                  * blocking socket to the backend or not */
 254
 255         /* Buffer for data not yet sent to backend */
 256         char       *outBuffer;          /* currently allocated buffer */
 257         int                     outBufSize;             /* allocated size of buffer */
 258         int                     outCount;               /* number of chars waiting in buffer */
 259
 260         /* Status for asynchronous result construction */
 261         PGresult   *result;                     /* result being constructed */
 262         PGresAttValue *curTuple;        /* tuple currently being read */
 263
 264         /* Status for sending environment info.  Used during PQSetenv only. */
 265         PGSetenvStatusType setenv_state;
 266         const struct EnvironmentOptions *next_eo;
 267
 268 #ifdef USE_SSL
 269         bool            allow_ssl_try;  /* Allowed to try SSL negotiation */
 270         bool            require_ssl;    /* Require SSL to make connection */
 271         SSL                *ssl;                        /* SSL status, if have SSL connection */
 272 #endif
 273
 274         /* Buffer for current error message */
 275         PQExpBufferData errorMessage;           /* expansible string */
 276
 277         /* Buffer for receiving various parts of messages */
 278         PQExpBufferData workBuffer; /* expansible string */
 279
 280         int                     client_encoding;/* encoding id */
 281 };
 282
 283 /* String descriptions of the ExecStatusTypes.
 284  * direct use of this array is deprecated; call PQresStatus() instead.
 285  */
 286 extern char *const pgresStatus[];
 287
 288 /* ----------------
 289  * Internal functions of libpq
 290  * Functions declared here need to be visible across files of libpq,
 291  * but are not intended to be called by applications.  We use the
 292  * convention "pqXXX" for internal functions, vs. the "PQxxx" names
 293  * used for application-visible routines.
 294  * ----------------
 295  */
 296
 297 /* === in fe-connect.c === */
 298
 299 extern int      pqPacketSend(PGconn *conn, const char *buf, size_t len);
 300
 301 /* === in fe-exec.c === */
 302
 303 extern void pqSetResultError(PGresult *res, const char *msg);
 304 extern void *pqResultAlloc(PGresult *res, size_t nBytes, bool isBinary);
 305 extern char *pqResultStrdup(PGresult *res, const char *str);
 306 extern void pqClearAsyncResult(PGconn *conn);
 307
 308 /* === in fe-misc.c === */
 309
 310  /*
 311   * "Get" and "Put" routines return 0 if successful, EOF if not. Note that
 312   * for Get, EOF merely means the buffer is exhausted, not that there is
 313   * necessarily any error.
 314   */
 315 extern int      pqGetc(char *result, PGconn *conn);
 316 extern int      pqPutc(char c, PGconn *conn);
 317 extern int      pqGets(PQExpBuffer buf, PGconn *conn);
 318 extern int      pqPuts(const char *s, PGconn *conn);
 319 extern int      pqGetnchar(char *s, size_t len, PGconn *conn);
 320 extern int      pqPutnchar(const char *s, size_t len, PGconn *conn);
 321 extern int      pqGetInt(int *result, size_t bytes, PGconn *conn);
 322 extern int      pqPutInt(int value, size_t bytes, PGconn *conn);
 323 extern int      pqReadData(PGconn *conn);
 324 extern int      pqFlush(PGconn *conn);
 325 extern int      pqWait(int forRead, int forWrite, PGconn *conn);
 326 extern int      pqReadReady(PGconn *conn);
 327 extern int      pqWriteReady(PGconn *conn);
 328
 329 /* bits in a byte */
 330 #define BYTELEN 8
 331
 332 /* fall back options if they are not specified by arguments or defined
 333    by environment variables */
 334 #define DefaultHost             "localhost"
 335 #define DefaultTty              ""
 336 #define DefaultOption   ""
 337 #define DefaultAuthtype           ""
 338 #define DefaultPassword           ""
 339
 340 /*
 341  * this is so that we can check is a connection is non-blocking internally
 342  * without the overhead of a function call
 343  */
 344 #define pqIsnonblocking(conn)   ((conn)->nonblocking)
 345
 346 #endif   /* LIBPQ_INT_H */