libpq-int.h 14.4 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.
 *
Bruce Momjian's avatar
Bruce Momjian committed
12
 * Portions Copyright (c) 1996-2002, 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.64 2003/04/24 21:16:44 tgl Exp $
16 17 18 19 20 21 22
 *
 *-------------------------------------------------------------------------
 */

#ifndef LIBPQ_INT_H
#define LIBPQ_INT_H

23
#include <time.h>
Tom Lane's avatar
Tom Lane committed
24
#include <sys/types.h>
25 26 27
#ifndef WIN32
#include <sys/time.h>
#endif
28

29
#if defined(WIN32) && (!defined(ssize_t))
Bruce Momjian's avatar
Bruce Momjian committed
30 31 32
typedef int ssize_t;			/* ssize_t doesn't exist in VC (atleast
								 * not VC6) */
#endif
33

34
/* We assume libpq-fe.h has already been included. */
35
#include "postgres_fe.h"
36

37
/* include stuff common to fe and be */
38
#include "libpq/pqcomm.h"
39
#include "lib/dllist.h"
40 41 42
/* include stuff found in fe only */
#include "pqexpbuffer.h"

43
#ifdef USE_SSL
44 45
#include <openssl/ssl.h>
#include <openssl/err.h>
46 47
#endif

48 49 50 51 52
/* 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
53
 * for most sorts of protocol changes.	So, when you change libpq
54 55 56 57 58
 * 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.
 */

59
#define PG_PROTOCOL_LIBPQ	PG_PROTOCOL(3,103) /* XXX temporary value */
60

61 62 63 64
/*
 * POSTGRES backend dependent Constants.
 */

Bruce Momjian's avatar
Bruce Momjian committed
65
#define PQERRORMSG_LENGTH 1024
66 67
#define CMDSTATUS_LEN 40

68 69
/*
 * PGresult and the subsidiary types PGresAttDesc, PGresAttValue
70 71 72 73 74
 * 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.
 */
75 76 77 78

/* 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
79
 * head of the block --- it's a union, not a struct!
80
 */
Bruce Momjian's avatar
Bruce Momjian committed
81
typedef union pgresult_data PGresult_data;
82

Bruce Momjian's avatar
Bruce Momjian committed
83 84 85 86 87
union pgresult_data
{
	PGresult_data *next;		/* link to next block, or NULL */
	char		space[1];		/* dummy for accessing block as bytes */
};
88 89 90

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

Bruce Momjian's avatar
Bruce Momjian committed
91 92 93 94 95 96
typedef struct pgresAttDesc
{
	char	   *name;			/* type name */
	Oid			typid;			/* type id */
	int			typlen;			/* type size */
	int			atttypmod;		/* type-specific modifier info */
97
}	PGresAttDesc;
98

99 100 101 102 103
/* 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
104
   particularly useful for text tuples ... with a binary value, the
105 106 107 108 109 110 111 112
   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).
113 114 115 116
 */

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

Bruce Momjian's avatar
Bruce Momjian committed
117 118 119 120 121
typedef struct pgresAttValue
{
	int			len;			/* length in bytes of the value */
	char	   *value;			/* actual value, plus terminating zero
								 * byte */
122
}	PGresAttValue;
Bruce Momjian's avatar
Bruce Momjian committed
123 124 125 126 127 128 129

struct pg_result
{
	int			ntups;
	int			numAttributes;
	PGresAttDesc *attDescs;
	PGresAttValue **tuples;		/* each PGresTuple is an array of
130
								 * PGresAttValue's */
Bruce Momjian's avatar
Bruce Momjian committed
131 132 133
	int			tupArrSize;		/* size of tuples array allocated */
	ExecStatusType resultStatus;
	char		cmdStatus[CMDSTATUS_LEN];		/* cmd status from the
134
												 * last query */
Bruce Momjian's avatar
Bruce Momjian committed
135
	int			binary;			/* binary tuple values if binary == 1,
136
								 * otherwise text */
137

138
	/*
139 140 141 142 143
	 * 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.
144 145 146
	 */
	PGconn	   *xconn;			/* connection we did the query on, if any */

147 148 149
	/*
	 * These fields are copied from the originating PGconn, so that
	 * operations on the PGresult don't have to reference the PGconn.
150
	 */
151
	PQnoticeProcessor noticeHook;		/* notice/error message processor */
152
	void	   *noticeArg;
153
	int			client_encoding;	/* encoding id */
154

155 156 157 158 159 160
	/*
	 * Error information (all NULL if not an error result).  errMsg is the
	 * "overall" error message returned by PQresultErrorMessage.  If we
	 * got a field-ized error from the server then the additional fields
	 * may be set.
	 */
Bruce Momjian's avatar
Bruce Momjian committed
161 162
	char	   *errMsg;			/* error message, or NULL if no error */

163 164 165 166 167 168 169 170 171 172 173
	char	   *errSeverity;	/* severity code */
	char	   *errCode;		/* SQLSTATE code */
	char	   *errPrimary;		/* primary message text */
	char	   *errDetail;		/* detail text */
	char	   *errHint;		/* hint text */
	char	   *errPosition;	/* cursor position */
	char	   *errContext;		/* location information */
	char	   *errFilename;	/* source-code file name */
	char	   *errLineno;		/* source-code line number */
	char	   *errFuncname;	/* source-code function name */

Bruce Momjian's avatar
Bruce Momjian committed
174 175 176 177 178 179 180 181 182 183 184 185
	/* 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 */
};
186 187

/* PGAsyncStatusType defines the state of the query-execution state machine */
Bruce Momjian's avatar
Bruce Momjian committed
188 189
typedef enum
{
190 191 192 193 194
	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 */
195
}	PGAsyncStatusType;
196

197 198 199
/* PGSetenvStatusType defines the state of the PQSetenv state machine */
typedef enum
{
200 201 202
	SETENV_STATE_ENCODINGS_SEND,	/* About to send an "encodings" query */
	SETENV_STATE_ENCODINGS_WAIT,	/* Waiting for query to complete	  */
	SETENV_STATE_IDLE
203
}	PGSetenvStatusType;
204

205
/* large-object-access data ... allocated only if large-object code is used. */
Bruce Momjian's avatar
Bruce Momjian committed
206 207 208 209 210 211 212 213 214 215
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		*/
216
}	PGlobjfuncs;
217 218 219 220

/* PGconn stores all the state data associated with a single connection
 * to a backend.
 */
Bruce Momjian's avatar
Bruce Momjian committed
221 222 223 224
struct pg_conn
{
	/* Saved values of connection options */
	char	   *pghost;			/* the machine on which the server is
225
								 * running */
226
	char	   *pghostaddr;		/* the IPv4 address of the machine on
227 228
								 * which the server is running, in IPv4
								 * numbers-and-dots notation. Takes
229
								 * precedence over above. */
Bruce Momjian's avatar
Bruce Momjian committed
230
	char	   *pgport;			/* the server's communication port */
231 232 233
	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
234
	char	   *pgtty;			/* tty on which the backend messages is
235 236
								 * displayed (OBSOLETE, NOT USED) */
	char	   *connect_timeout; /* connection timeout (numeric string) */
Bruce Momjian's avatar
Bruce Momjian committed
237 238 239 240 241 242 243 244 245 246 247 248 249 250 251
	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;
252 253 254 255
	char		copy_is_binary;	/* 1 = copy binary, 0 = copy text */
	int			copy_already_done; /* # bytes already returned in COPY OUT */
	int			nonblocking;	/* whether this connection is using a
								 * blocking socket to the backend or not */
Bruce Momjian's avatar
Bruce Momjian committed
256 257 258 259 260 261 262 263 264 265 266 267
	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 */
268 269
	char		md5Salt[4];		/* password salt received from backend */
	char		cryptSalt[2];	/* password salt received from backend */
270
	int			client_encoding; /* encoding id */
Bruce Momjian's avatar
Bruce Momjian committed
271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287
	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 */

	/* 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 */

288 289 290 291
	/* State for constructing messages in outBuffer */
	int			outMsgStart;	/* offset to msg start (length word) */
	int			outMsgEnd;		/* offset to msg end (so far) */

Bruce Momjian's avatar
Bruce Momjian committed
292 293 294 295
	/* Status for asynchronous result construction */
	PGresult   *result;			/* result being constructed */
	PGresAttValue *curTuple;	/* tuple currently being read */

296
	/* Status for sending environment info.  Used during PQSetenv only. */
297
	PGSetenvStatusType setenv_state;
298

299
#ifdef USE_SSL
300
	bool		allow_ssl_try;	/* Allowed to try SSL negotiation */
301
	bool		require_ssl;	/* Require SSL to make connection */
302
	SSL		   *ssl;			/* SSL status, if have SSL connection */
Bruce Momjian's avatar
Bruce Momjian committed
303
	X509	   *peer;			/* X509 cert of server */
Bruce Momjian's avatar
Bruce Momjian committed
304 305
	char		peer_dn[256 + 1];		/* peer distinguished name */
	char		peer_cn[SM_USER + 1];	/* peer common name */
306 307
#endif

308
	/* Buffer for current error message */
309
	PQExpBufferData errorMessage;		/* expansible string */
310 311

	/* Buffer for receiving various parts of messages */
312
	PQExpBufferData workBuffer; /* expansible string */
Bruce Momjian's avatar
Bruce Momjian committed
313
};
314

315 316 317 318 319
/* String descriptions of the ExecStatusTypes.
 * direct use of this array is deprecated; call PQresStatus() instead.
 */
extern char *const pgresStatus[];

320 321 322 323 324 325 326 327 328 329 330
/* ----------------
 * 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 === */

331 332
extern int	pqPacketSend(PGconn *conn, char pack_type,
						 const void *buf, size_t buf_len);
333 334 335

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

336
extern void pqSetResultError(PGresult *res, const char *msg);
Bruce Momjian's avatar
Bruce Momjian committed
337
extern void *pqResultAlloc(PGresult *res, size_t nBytes, bool isBinary);
Bruce Momjian's avatar
Bruce Momjian committed
338
extern char *pqResultStrdup(PGresult *res, const char *str);
339
extern void pqClearAsyncResult(PGconn *conn);
340
extern int	pqGetErrorNotice(PGconn *conn, bool isError);
341 342 343

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

344 345 346 347 348
 /*
  * "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.
  */
349
extern int	pqCheckInBufferSpace(int bytes_needed, PGconn *conn);
350
extern int	pqGetc(char *result, PGconn *conn);
351
extern int	pqPutc(char c, PGconn *conn);
352
extern int	pqGets(PQExpBuffer buf, PGconn *conn);
353
extern int	pqPuts(const char *s, PGconn *conn);
Bruce Momjian's avatar
Bruce Momjian committed
354 355 356 357
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);
358 359
extern int	pqPutMsgStart(char msg_type, PGconn *conn);
extern int	pqPutMsgEnd(PGconn *conn);
360 361 362
extern int	pqReadData(PGconn *conn);
extern int	pqFlush(PGconn *conn);
extern int	pqWait(int forRead, int forWrite, PGconn *conn);
363 364
extern int	pqWaitTimed(int forRead, int forWrite, PGconn *conn, 
						time_t finish_time);
365 366
extern int	pqReadReady(PGconn *conn);
extern int	pqWriteReady(PGconn *conn);
367

368 369
/* === in fe-secure.c === */

Bruce Momjian's avatar
Bruce Momjian committed
370
extern int	pqsecure_initialize(PGconn *);
371
extern void pqsecure_destroy(void);
Bruce Momjian's avatar
Bruce Momjian committed
372
extern int	pqsecure_open_client(PGconn *);
373 374 375 376
extern void pqsecure_close(PGconn *);
extern ssize_t pqsecure_read(PGconn *, void *ptr, size_t len);
extern ssize_t pqsecure_write(PGconn *, const void *ptr, size_t len);

377 378 379 380 381 382 383 384 385 386 387
/* 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		  ""

388
/*
389 390 391
 * this is so that we can check is a connection is non-blocking internally
 * without the overhead of a function call
 */
392
#define pqIsnonblocking(conn)	((conn)->nonblocking)
393

394
#ifdef ENABLE_NLS
395 396
extern char *
libpq_gettext(const char *msgid)
397
__attribute__((format_arg(1)));
398

399 400 401
#else
#define libpq_gettext(x) (x)
#endif
402

403 404 405 406 407 408 409 410 411 412 413 414
/*
 * 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

415
#endif   /* LIBPQ_INT_H */