pqformat.c 9.79 KB
Newer Older
1 2 3 4 5 6 7 8 9 10
/*-------------------------------------------------------------------------
 *
 * pqformat.c
 *		Routines for formatting and parsing frontend/backend messages
 *
 * Outgoing messages are built up in a StringInfo buffer (which is expansible)
 * and then sent in a single call to pq_putmessage.  This module provides data
 * formatting/conversion routines that are needed to produce valid messages.
 * Note in particular the distinction between "raw data" and "text"; raw data
 * is message protocol characters and binary values that are not subject to
11 12
 * character set conversion, while text is converted by character encoding
 * rules.
13
 *
14 15 16
 * Incoming messages are similarly read into a StringInfo buffer, via
 * pq_getmessage, and then parsed and converted from that using the routines
 * in this module.
17
 *
Bruce Momjian's avatar
Bruce Momjian committed
18
 * Portions Copyright (c) 1996-2002, PostgreSQL Global Development Group
Bruce Momjian's avatar
Add:  
Bruce Momjian committed
19
 * Portions Copyright (c) 1994, Regents of the University of California
20
 *
21
 *	$Header: /cvsroot/pgsql/src/backend/libpq/pqformat.c,v 1.28 2003/04/22 00:08:06 tgl Exp $
22 23 24 25 26
 *
 *-------------------------------------------------------------------------
 */
/*
 * INTERFACE ROUTINES
27
 * Message assembly and output:
Bruce Momjian's avatar
Bruce Momjian committed
28
 *		pq_beginmessage - initialize StringInfo buffer
29 30 31
 *		pq_sendbyte		- append a raw byte to a StringInfo buffer
 *		pq_sendint		- append a binary integer to a StringInfo buffer
 *		pq_sendbytes	- append raw data to a StringInfo buffer
32 33
 *		pq_sendcountedtext - append a text string (with character set conversion)
 *		pq_sendstring	- append a null-terminated text string (with conversion)
34 35 36
 *		pq_endmessage	- send the completed message to the frontend
 * Note: it is also possible to append data to the StringInfo buffer using
 * the regular StringInfo routines, but this is discouraged since required
37
 * character set conversion may not occur.
38
 *
39
 * Special-case message output:
40
 *		pq_puttextmessage - generate a character set-converted message in one step
41
 *		pq_putemptymessage - convenience routine for message with empty body
42
 *
43 44 45 46 47 48 49
 * Message parsing after input:
 *		pq_getmsgbyte	- get a raw byte from a message buffer
 *		pq_getmsgint	- get a binary integer from a message buffer
 *		pq_getmsgbytes	- get raw data from a message buffer
 *		pq_copymsgbytes	- copy raw data from a message buffer
 *		pq_getmsgstring	- get a null-terminated text string (with conversion)
 *		pq_getmsgend	- verify message fully consumed
50
 */
51

52 53
#include "postgres.h"

54 55
#include <errno.h>
#include <sys/param.h>
56 57 58 59 60
#include <netinet/in.h>
#include <arpa/inet.h>
#ifdef HAVE_ENDIAN_H
#include <endian.h>
#endif
61

62
#include "libpq/libpq.h"
Bruce Momjian's avatar
Bruce Momjian committed
63 64
#include "libpq/pqformat.h"
#include "mb/pg_wchar.h"
65 66


67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82
/* --------------------------------
 *		pq_beginmessage		- initialize for sending a message
 * --------------------------------
 */
void
pq_beginmessage(StringInfo buf, char msgtype)
{
	initStringInfo(buf);
	/*
	 * We stash the message type into the buffer's cursor field, expecting
	 * that the pq_sendXXX routines won't touch it.  We could alternatively
	 * make it the first byte of the buffer contents, but this seems easier.
	 */
	buf->cursor = msgtype;
}

83 84 85 86 87 88 89
/* --------------------------------
 *		pq_sendbyte		- append a raw byte to a StringInfo buffer
 * --------------------------------
 */
void
pq_sendbyte(StringInfo buf, int byt)
{
90
	appendStringInfoCharMacro(buf, byt);
91 92 93 94 95 96 97 98 99 100 101 102 103
}

/* --------------------------------
 *		pq_sendbytes	- append raw data to a StringInfo buffer
 * --------------------------------
 */
void
pq_sendbytes(StringInfo buf, const char *data, int datalen)
{
	appendBinaryStringInfo(buf, data, datalen);
}

/* --------------------------------
104
 *		pq_sendcountedtext - append a text string (with character set conversion)
105
 *
106 107 108 109
 * The data sent to the frontend by this routine is a 4-byte count field
 * (the count includes itself, by convention) followed by the string.
 * The passed text string need not be null-terminated, and the data sent
 * to the frontend isn't either.
110 111 112
 * --------------------------------
 */
void
113
pq_sendcountedtext(StringInfo buf, const char *str, int slen)
114
{
115
	char	   *p;
Bruce Momjian's avatar
Bruce Momjian committed
116

117
	p = (char *) pg_server_to_client((unsigned char *) str, slen);
118 119
	if (p != str)				/* actual conversion has been done? */
	{
120 121 122 123 124
		slen = strlen(p);
		pq_sendint(buf, slen + 4, 4);
		appendBinaryStringInfo(buf, p, slen);
		pfree(p);
		return;
125 126
	}
	pq_sendint(buf, slen + 4, 4);
127 128 129 130
	appendBinaryStringInfo(buf, str, slen);
}

/* --------------------------------
131
 *		pq_sendstring	- append a null-terminated text string (with conversion)
132
 *
133 134
 * NB: passed text string must be null-terminated, and so is the data
 * sent to the frontend.
135 136 137
 * --------------------------------
 */
void
138
pq_sendstring(StringInfo buf, const char *str)
139
{
Bruce Momjian's avatar
Bruce Momjian committed
140
	int			slen = strlen(str);
141

142
	char	   *p;
Bruce Momjian's avatar
Bruce Momjian committed
143

144
	p = (char *) pg_server_to_client((unsigned char *) str, slen);
145 146
	if (p != str)				/* actual conversion has been done? */
	{
147 148 149 150
		slen = strlen(p);
		appendBinaryStringInfo(buf, p, slen + 1);
		pfree(p);
		return;
151
	}
Bruce Momjian's avatar
Bruce Momjian committed
152
	appendBinaryStringInfo(buf, str, slen + 1);
153 154 155 156 157 158 159 160 161
}

/* --------------------------------
 *		pq_sendint		- append a binary integer to a StringInfo buffer
 * --------------------------------
 */
void
pq_sendint(StringInfo buf, int i, int b)
{
Bruce Momjian's avatar
Bruce Momjian committed
162 163 164
	unsigned char n8;
	uint16		n16;
	uint32		n32;
165 166 167 168 169 170 171 172

	switch (b)
	{
		case 1:
			n8 = (unsigned char) i;
			appendBinaryStringInfo(buf, (char *) &n8, 1);
			break;
		case 2:
173
			n16 = htons((uint16) i);
174 175 176
			appendBinaryStringInfo(buf, (char *) &n16, 2);
			break;
		case 4:
177
			n32 = htonl((uint32) i);
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195
			appendBinaryStringInfo(buf, (char *) &n32, 4);
			break;
		default:
			elog(ERROR, "pq_sendint: unsupported size %d", b);
			break;
	}
}

/* --------------------------------
 *		pq_endmessage	- send the completed message to the frontend
 *
 * The data buffer is pfree()d, but if the StringInfo was allocated with
 * makeStringInfo then the caller must still pfree it.
 * --------------------------------
 */
void
pq_endmessage(StringInfo buf)
{
196 197
	/* msgtype was saved in cursor field */
	(void) pq_putmessage(buf->cursor, buf->data, buf->len);
198
	/* no need to complain about any failure, since pqcomm.c already did */
199 200 201 202
	pfree(buf->data);
	buf->data = NULL;
}

203
/* --------------------------------
204
 *		pq_puttextmessage - generate a character set-converted message in one step
205 206
 *
 *		This is the same as the pqcomm.c routine pq_putmessage, except that
207
 *		the message body is a null-terminated string to which encoding
208 209 210
 *		conversion applies.
 * --------------------------------
 */
211
void
212 213
pq_puttextmessage(char msgtype, const char *str)
{
Bruce Momjian's avatar
Bruce Momjian committed
214
	int			slen = strlen(str);
215
	char	   *p;
Bruce Momjian's avatar
Bruce Momjian committed
216

217
	p = (char *) pg_server_to_client((unsigned char *) str, slen);
218 219
	if (p != str)				/* actual conversion has been done? */
	{
220
		(void) pq_putmessage(msgtype, p, strlen(p) + 1);
221
		pfree(p);
222
		return;
223
	}
224 225 226 227 228 229 230 231 232 233 234 235
	(void) pq_putmessage(msgtype, str, slen + 1);
}


/* --------------------------------
 *		pq_putemptymessage - convenience routine for message with empty body
 * --------------------------------
 */
void
pq_putemptymessage(char msgtype)
{
	(void) pq_putmessage(msgtype, NULL, 0);
236 237
}

238

239
/* --------------------------------
240
 *		pq_getmsgbyte	- get a raw byte from a message buffer
241 242 243
 * --------------------------------
 */
int
244 245 246 247 248 249 250 251 252 253 254 255 256 257 258
pq_getmsgbyte(StringInfo msg)
{
	if (msg->cursor >= msg->len)
		elog(ERROR, "pq_getmsgbyte: no data left in message");
	return (unsigned char) msg->data[msg->cursor++];
}

/* --------------------------------
 *		pq_getmsgint	- get a binary integer from a message buffer
 *
 *		Values are treated as unsigned.
 * --------------------------------
 */
unsigned int
pq_getmsgint(StringInfo msg, int b)
259
{
260
	unsigned int result;
Bruce Momjian's avatar
Bruce Momjian committed
261 262 263
	unsigned char n8;
	uint16		n16;
	uint32		n32;
264 265 266 267

	switch (b)
	{
		case 1:
268 269
			pq_copymsgbytes(msg, (char *) &n8, 1);
			result = n8;
270 271
			break;
		case 2:
272 273
			pq_copymsgbytes(msg, (char *) &n16, 2);
			result = ntohs(n16);
274 275
			break;
		case 4:
276 277
			pq_copymsgbytes(msg, (char *) &n32, 4);
			result = ntohl(n32);
278 279
			break;
		default:
280 281
			elog(ERROR, "pq_getmsgint: unsupported size %d", b);
			result = 0;			/* keep compiler quiet */
282 283
			break;
	}
284
	return result;
285 286 287
}

/* --------------------------------
288
 *		pq_getmsgbytes	- get raw data from a message buffer
289
 *
290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307
 *		Returns a pointer directly into the message buffer; note this
 *		may not have any particular alignment.
 * --------------------------------
 */
const char *
pq_getmsgbytes(StringInfo msg, int datalen)
{
	const char *result;

	if (datalen > (msg->len - msg->cursor))
		elog(ERROR, "pq_getmsgbytes: insufficient data left in message");
	result = &msg->data[msg->cursor];
	msg->cursor += datalen;
	return result;
}

/* --------------------------------
 *		pq_copymsgbytes	- copy raw data from a message buffer
308
 *
309 310 311 312 313 314 315 316 317 318 319 320 321 322
 *		Same as above, except data is copied to caller's buffer.
 * --------------------------------
 */
void
pq_copymsgbytes(StringInfo msg, char *buf, int datalen)
{
	if (datalen > (msg->len - msg->cursor))
		elog(ERROR, "pq_copymsgbytes: insufficient data left in message");
	memcpy(buf, &msg->data[msg->cursor], datalen);
	msg->cursor += datalen;
}

/* --------------------------------
 *		pq_getmsgstring	- get a null-terminated text string (with conversion)
323
 *
324 325
 *		May return a pointer directly into the message buffer, or a pointer
 *		to a palloc'd conversion result.
326 327
 * --------------------------------
 */
328 329
const char *
pq_getmsgstring(StringInfo msg)
330
{
331 332
	char   *str;
	int		slen;
333

334 335 336 337 338 339 340 341 342 343
	str = &msg->data[msg->cursor];
	/*
	 * It's safe to use strlen() here because a StringInfo is guaranteed
	 * to have a trailing null byte.  But check we found a null inside
	 * the message.
	 */
	slen = strlen(str);
	if (msg->cursor + slen >= msg->len)
		elog(ERROR, "pq_getmsgstring: invalid string in message");
	msg->cursor += slen + 1;
344

345 346
	return (const char *) pg_client_to_server((unsigned char *) str, slen);
}
347

348 349 350 351 352 353 354 355 356
/* --------------------------------
 *		pq_getmsgend	- verify message fully consumed
 * --------------------------------
 */
void
pq_getmsgend(StringInfo msg)
{
	if (msg->cursor != msg->len)
		elog(ERROR, "pq_getmsgend: invalid message format");
357
}