libpq-int.h 12.6 KB
Newer Older
1 2
/*-------------------------------------------------------------------------
 *
3
 * libpq-int.h
4 5 6
 *	  This file contains internal definitions meant to be used only by
 *	  the frontend libpq library, not by applications that call it.
 *
7 8 9 10 11
 *	  An application can include this file if it wants to bypass the
 *	  official API defined by libpq-fe.h, but code that does so is much
 *	  more likely to break across PostgreSQL releases than code that uses
 *	  only the official API.
 *
12
 * Portions Copyright (c) 1996-2001, PostgreSQL Global Development Group
Bruce Momjian's avatar
Add:  
Bruce Momjian committed
13
 * Portions Copyright (c) 1994, Regents of the University of California
14
 *
15
 * $Id: libpq-int.h,v 1.46 2002/03/05 06:07:27 momjian Exp $
16 17 18 19 20 21 22 23
 *
 *-------------------------------------------------------------------------
 */

#ifndef LIBPQ_INT_H
#define LIBPQ_INT_H

/* 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 30 31
/* include stuff found in fe only */
#include "pqexpbuffer.h"

32
#ifdef USE_SSL
33 34
#include <openssl/ssl.h>
#include <openssl/err.h>
35 36
#endif

37 38 39 40 41
/* libpq supports this version of the frontend/backend protocol.
 *
 * NB: we used to use PG_PROTOCOL_LATEST from the backend pqcomm.h file,
 * but that's not really the right thing: just recompiling libpq
 * 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 44 45 46 47
 * to support a different protocol revision, you have to change this
 * constant too.  PG_PROTOCOL_EARLIEST and PG_PROTOCOL_LATEST in
 * pqcomm.h describe what the backend knows, not what libpq knows.
 */

48
#define PG_PROTOCOL_LIBPQ	PG_PROTOCOL(2,0)
49

50 51 52 53
/*
 * POSTGRES backend dependent Constants.
 */

Bruce Momjian's avatar
Bruce Momjian committed
54
#define PQERRORMSG_LENGTH 1024
55 56
#define CMDSTATUS_LEN 40

57 58
/*
 * PGresult and the subsidiary types PGresAttDesc, PGresAttValue
59 60 61 62 63
 * represent the result of a query (or more precisely, of a single SQL
 * command --- a query string given to PQexec can contain multiple commands).
 * Note we assume that a single command can return at most one tuple group,
 * hence there is no need for multiple descriptor sets.
 */
64 65 66 67

/* Subsidiary-storage management structure for PGresult.
 * See space management routines in fe-exec.c for details.
 * 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
 */
Bruce Momjian's avatar
Bruce Momjian committed
70
typedef union pgresult_data PGresult_data;
71

Bruce Momjian's avatar
Bruce Momjian committed
72 73 74 75 76
union pgresult_data
{
	PGresult_data *next;		/* link to next block, or NULL */
	char		space[1];		/* dummy for accessing block as bytes */
};
77 78 79

/* Data about a single attribute (column) of a query result */

Bruce Momjian's avatar
Bruce Momjian committed
80 81 82 83 84 85
typedef struct pgresAttDesc
{
	char	   *name;			/* type name */
	Oid			typid;			/* type id */
	int			typlen;			/* type size */
	int			atttypmod;		/* type-specific modifier info */
86
}	PGresAttDesc;
87

88 89 90 91 92 93 94 95 96 97 98 99 100 101
/* Data for a single attribute of a single tuple */

/* We use char* for Attribute values.
   The value pointer always points to a null-terminated area; we add a
   null (zero) byte after whatever the backend sends us.  This is only
   particularly useful for ASCII tuples ... with a binary value, the
   value might have embedded nulls, so the application can't use C string
   operators on it.  But we add a null anyway for consistency.
   Note that the value itself does not contain a length word.

   A NULL attribute is a special case in two ways: its len field is NULL_LEN
   and its value field points to null_field in the owning PGresult.  All the
   NULL attributes in a query result point to the same place (there's no need
   to store a null string separately for each one).
102 103 104 105
 */

#define NULL_LEN		(-1)	/* pg_result len for NULL value */

Bruce Momjian's avatar
Bruce Momjian committed
106 107 108 109 110
typedef struct pgresAttValue
{
	int			len;			/* length in bytes of the value */
	char	   *value;			/* actual value, plus terminating zero
								 * byte */
111
}	PGresAttValue;
Bruce Momjian's avatar
Bruce Momjian committed
112 113 114 115 116 117 118

struct pg_result
{
	int			ntups;
	int			numAttributes;
	PGresAttDesc *attDescs;
	PGresAttValue **tuples;		/* each PGresTuple is an array of
119
								 * PGresAttValue's */
Bruce Momjian's avatar
Bruce Momjian committed
120 121 122
	int			tupArrSize;		/* size of tuples array allocated */
	ExecStatusType resultStatus;
	char		cmdStatus[CMDSTATUS_LEN];		/* cmd status from the
123
												 * last query */
Bruce Momjian's avatar
Bruce Momjian committed
124
	int			binary;			/* binary tuple values if binary == 1,
125
								 * otherwise ASCII */
126

127
	/*
128 129 130 131 132
	 * The conn link in PGresult is no longer used by any libpq code. It
	 * should be removed entirely, because it could be a dangling link
	 * (the application could keep the PGresult around longer than it
	 * keeps the PGconn!)  But there may be apps out there that depend on
	 * it, so we will leave it here at least for a release or so.
133 134 135
	 */
	PGconn	   *xconn;			/* connection we did the query on, if any */

136 137 138
	/*
	 * These fields are copied from the originating PGconn, so that
	 * 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

Bruce Momjian's avatar
Bruce Momjian committed
145 146 147 148 149 150 151 152 153 154 155 156 157 158
	char	   *errMsg;			/* error message, or NULL if no error */

	/* All NULL attributes in the query result point to this null string */
	char		null_field[1];

	/*
	 * Space management information.  Note that attDescs and errMsg, if
	 * not null, point into allocated blocks.  But tuples points to a
	 * separately malloc'd block, so that we can realloc it.
	 */
	PGresult_data *curBlock;	/* most recently allocated block */
	int			curOffset;		/* start offset of free space in block */
	int			spaceLeft;		/* number of free bytes remaining in block */
};
159 160

/* PGAsyncStatusType defines the state of the query-execution state machine */
Bruce Momjian's avatar
Bruce Momjian committed
161 162
typedef enum
{
163 164 165 166 167
	PGASYNC_IDLE,				/* nothing's happening, dude */
	PGASYNC_BUSY,				/* query in progress */
	PGASYNC_READY,				/* result ready for PQgetResult */
	PGASYNC_COPY_IN,			/* Copy In data transfer in progress */
	PGASYNC_COPY_OUT			/* Copy Out data transfer in progress */
168
}	PGAsyncStatusType;
169

170 171 172
/* PGSetenvStatusType defines the state of the PQSetenv state machine */
typedef enum
{
173 174
	SETENV_STATE_OPTION_SEND,	/* About to send an Environment Option */
	SETENV_STATE_OPTION_WAIT,	/* Waiting for above send to complete  */
175
	/* these next two are only used in MULTIBYTE mode */
176 177 178
	SETENV_STATE_ENCODINGS_SEND,	/* About to send an "encodings" query */
	SETENV_STATE_ENCODINGS_WAIT,	/* Waiting for query to complete	  */
	SETENV_STATE_IDLE
179
}	PGSetenvStatusType;
180

181
/* large-object-access data ... allocated only if large-object code is used. */
Bruce Momjian's avatar
Bruce Momjian committed
182 183 184 185 186 187 188 189 190 191
typedef struct pgLobjfuncs
{
	Oid			fn_lo_open;		/* OID of backend function lo_open		*/
	Oid			fn_lo_close;	/* OID of backend function lo_close		*/
	Oid			fn_lo_creat;	/* OID of backend function lo_creat		*/
	Oid			fn_lo_unlink;	/* OID of backend function lo_unlink	*/
	Oid			fn_lo_lseek;	/* OID of backend function lo_lseek		*/
	Oid			fn_lo_tell;		/* OID of backend function lo_tell		*/
	Oid			fn_lo_read;		/* OID of backend function LOread		*/
	Oid			fn_lo_write;	/* OID of backend function LOwrite		*/
192
}	PGlobjfuncs;
193 194 195 196

/* PGconn stores all the state data associated with a single connection
 * to a backend.
 */
Bruce Momjian's avatar
Bruce Momjian committed
197 198 199 200
struct pg_conn
{
	/* Saved values of connection options */
	char	   *pghost;			/* the machine on which the server is
201
								 * running */
202
	char	   *pghostaddr;		/* the IPv4 address of the machine on
203 204
								 * which the server is running, in IPv4
								 * numbers-and-dots notation. Takes
205
								 * precedence over above. */
Bruce Momjian's avatar
Bruce Momjian committed
206
	char	   *pgport;			/* the server's communication port */
207 208 209
	char	   *pgunixsocket;	/* the Unix-domain socket that the server
								 * is listening on; if NULL, uses a
								 * default constructed from pgport */
Bruce Momjian's avatar
Bruce Momjian committed
210
	char	   *pgtty;			/* tty on which the backend messages is
211
								 * displayed (NOT ACTUALLY USED???) */
Bruce Momjian's avatar
Bruce Momjian committed
212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238
	char	   *pgoptions;		/* options to start the backend with */
	char	   *dbName;			/* database name */
	char	   *pguser;			/* Postgres username and password, if any */
	char	   *pgpass;

	/* Optional file to write trace info to */
	FILE	   *Pfdebug;

	/* Callback procedure for notice/error message processing */
	PQnoticeProcessor noticeHook;
	void	   *noticeArg;

	/* Status indicators */
	ConnStatusType status;
	PGAsyncStatusType asyncStatus;
	Dllist	   *notifyList;		/* Notify msgs not yet handed to
								 * application */

	/* Connection data */
	int			sock;			/* Unix FD for socket, -1 if not connected */
	SockAddr	laddr;			/* Local address */
	SockAddr	raddr;			/* Remote address */
	int			raddr_len;		/* Length of remote address */

	/* Miscellaneous stuff */
	int			be_pid;			/* PID of backend --- needed for cancels */
	int			be_key;			/* key of backend --- needed for cancels */
239 240
	char		md5Salt[4];		/* password salt received from backend */
	char		cryptSalt[2];	/* password salt received from backend */
Bruce Momjian's avatar
Bruce Momjian committed
241 242 243 244 245 246 247 248 249 250 251 252
	PGlobjfuncs *lobjfuncs;		/* private state for large-object access
								 * fns */

	/* Buffer for data received from backend and not yet processed */
	char	   *inBuffer;		/* currently allocated buffer */
	int			inBufSize;		/* allocated size of buffer */
	int			inStart;		/* offset to first unconsumed data in
								 * buffer */
	int			inCursor;		/* next byte to tentatively consume */
	int			inEnd;			/* offset to first position after avail
								 * data */

253 254
	int			nonblocking;	/* whether this connection is using a
								 * blocking socket to the backend or not */
255

Bruce Momjian's avatar
Bruce Momjian committed
256 257 258 259 260 261 262 263 264
	/* Buffer for data not yet sent to backend */
	char	   *outBuffer;		/* currently allocated buffer */
	int			outBufSize;		/* allocated size of buffer */
	int			outCount;		/* number of chars waiting in buffer */

	/* Status for asynchronous result construction */
	PGresult   *result;			/* result being constructed */
	PGresAttValue *curTuple;	/* tuple currently being read */

265
	/* Status for sending environment info.  Used during PQSetenv only. */
266
	PGSetenvStatusType setenv_state;
267
	const struct EnvironmentOptions *next_eo;
268

269
#ifdef USE_SSL
270
	bool		allow_ssl_try;	/* Allowed to try SSL negotiation */
271
	bool		require_ssl;	/* Require SSL to make connection */
272
	SSL		   *ssl;			/* SSL status, if have SSL connection */
273 274
#endif

275
	/* Buffer for current error message */
276
	PQExpBufferData errorMessage;		/* expansible string */
277 278

	/* Buffer for receiving various parts of messages */
279
	PQExpBufferData workBuffer; /* expansible string */
Tatsuo Ishii's avatar
Tatsuo Ishii committed
280

281
	int			client_encoding;	/* encoding id */
Bruce Momjian's avatar
Bruce Momjian committed
282
};
283

284 285 286 287 288
/* String descriptions of the ExecStatusTypes.
 * direct use of this array is deprecated; call PQresStatus() instead.
 */
extern char *const pgresStatus[];

289 290 291 292 293 294 295 296 297 298 299
/* ----------------
 * Internal functions of libpq
 * Functions declared here need to be visible across files of libpq,
 * but are not intended to be called by applications.  We use the
 * convention "pqXXX" for internal functions, vs. the "PQxxx" names
 * used for application-visible routines.
 * ----------------
 */

/* === in fe-connect.c === */

300
extern int	pqPacketSend(PGconn *conn, const char *buf, size_t len);
301 302 303

/* === in fe-exec.c === */

304
extern void pqSetResultError(PGresult *res, const char *msg);
Bruce Momjian's avatar
Bruce Momjian committed
305
extern void *pqResultAlloc(PGresult *res, size_t nBytes, bool isBinary);
Bruce Momjian's avatar
Bruce Momjian committed
306
extern char *pqResultStrdup(PGresult *res, const char *str);
307
extern void pqClearAsyncResult(PGconn *conn);
308 309 310

/* === in fe-misc.c === */

311 312 313 314 315 316
 /*
  * "Get" and "Put" routines return 0 if successful, EOF if not. Note that
  * for Get, EOF merely means the buffer is exhausted, not that there is
  * necessarily any error.
  */
extern int	pqGetc(char *result, PGconn *conn);
317
extern int	pqPutc(char c, PGconn *conn);
318
extern int	pqGets(PQExpBuffer buf, PGconn *conn);
319
extern int	pqPuts(const char *s, PGconn *conn);
Bruce Momjian's avatar
Bruce Momjian committed
320 321 322 323
extern int	pqGetnchar(char *s, size_t len, PGconn *conn);
extern int	pqPutnchar(const char *s, size_t len, PGconn *conn);
extern int	pqGetInt(int *result, size_t bytes, PGconn *conn);
extern int	pqPutInt(int value, size_t bytes, PGconn *conn);
324 325
extern int	pqReadData(PGconn *conn);
extern int	pqFlush(PGconn *conn);
326
extern int	pqSendSome(PGconn *conn);
327
extern int	pqWait(int forRead, int forWrite, PGconn *conn);
328 329
extern int	pqReadReady(PGconn *conn);
extern int	pqWriteReady(PGconn *conn);
330 331 332 333 334 335 336 337 338 339 340 341

/* bits in a byte */
#define BYTELEN 8

/* fall back options if they are not specified by arguments or defined
   by environment variables */
#define DefaultHost		"localhost"
#define DefaultTty		""
#define DefaultOption	""
#define DefaultAuthtype		  ""
#define DefaultPassword		  ""

342
/*
343 344 345
 * this is so that we can check is a connection is non-blocking internally
 * without the overhead of a function call
 */
346
#define pqIsnonblocking(conn)	((conn)->nonblocking)
347

348
#ifdef ENABLE_NLS
349 350
extern char *
libpq_gettext(const char *msgid)
351
__attribute__((format_arg(1)));
352

353 354 355
#else
#define libpq_gettext(x) (x)
#endif
356

357 358 359 360 361 362 363 364 365 366 367 368
/*
 * These macros are needed to let error-handling code be portable between
 * Unix and Windows.  (ugh)
 */
#ifdef WIN32
#define SOCK_ERRNO (WSAGetLastError())
#define SOCK_STRERROR winsock_strerror
#else
#define SOCK_ERRNO errno
#define SOCK_STRERROR strerror
#endif

369
#endif   /* LIBPQ_INT_H */