.TH "PQregisterResult" 3 2011 "libpqtypes" "libpqtypes Manual"
.SH NAME
PQregisterResult \- Registers sub-classes, composites and user-defined types found within a PGresult.
.SH SYNOPSIS
.LP
\fB#include <libpqtypes.h>
.br
int PQregisterResult(PGconn *\fIconn\fP, int \fIwhich\fP, PGregisterType *\fItypes\fP,
.br
                    int \fIcount\fP, PGresult *\fIres\fP);
\fP
.SH DESCRIPTION
.LP
The \fIPQregisterResult\fP() function registers the types found within
a given PGresult, thus this function makes no calls to a PostgreSQL server
since the result data is already available.

The \fIwhich\fP argument can be PQT_COMPOSITE or PQT_USERDEFINED,
but not PQT_SUBCLASS.  The only reason being sub-classes don't talk to
the server so they have no result set.

The \fItypes\fP argument is an array containing \fIcount\fP types
to register.  This array must be identical to what was provided to
the originating PQregisterTypes call.

The \fIres\fP argument is a PGresult normally created by calling
PQregisterTypes followed by PQgetResult.  However, it is possible to
create your own result via PQmakeEmptyPGresult, PQsetResultAttrs,
PQsetvalue and call this function.  This approach is a bit risky being
how the result set generated by type lookup queries are internal and
subject to change.

.SH EXAMPLES
.LP
.SS Using PQregisterResult
The example registers two composite types asynchronously.  It is worth
noting that the PGresult obtained via PQgetResult can be cached by an
application and used when creating new connections, as a way to avoid
repeatedly performing type lookups with the server.
.RS
.nf
.LP
\fBPGregisterType comp_types[] = {
	{"myschema.simple", NULL, NULL},
	{"complex", NULL, NULL}
};

/* asynchronous registration */
if (PQregisterTypes(conn, PQT_COMPOSITE, comp_types, 2, 1))
{
	/* example of a typical event loop */
	for(;;)
	{
		int n;
		fd_set set;
		int fd = PQsocket(conn);
		struct timeval tv = {0, 500000};

		FD_ZERO(&set);
		FD_SET(fd, &set);
		n = select(fd + 1, &set, NULL, NULL, &tv); //or kqueue,epoll,poll,etc..

		if (n == -1)
		{
			//error
		}
		else if (n == 0)
		{
			//timeout, do other work ....
		}
		else
		{
			PGresult *res;

			PQconsumeInput(conn);
			if(!PQisBusy(conn))
			{
				/* done */
				if(!(res = PQgetResult(conn)))
					break;

				n = PQregisterResult(conn, PQT_COMPOSITE, comp_types, 2, res);

				/* This could also be cached and reused with PQregisterResult */
				PQclear(res);

				if (!n)
					//error, consult PQgeterror()
			}
		}
	}
}
\fP
.fi
.RE
.SH RETURN VALUE
.LP
On success, a non-zero value is returned.  On error, zero is
returned and \fIPQgeterror(3)\fP will contain an error message.
.SH EXAMPLES
.LP
None.
.SH AUTHOR
.LP
A contribution of eSilo, LLC. for the PostgreSQL Database Management System.
Written by Andrew Chernow.
.SH REPORTING BUGS
.LP
Report bugs to <libpqtypes@esilo.com>.
.SH COPYRIGHT
.LP
Copyright (c) 2011 eSilo, LLC. All rights reserved.
.br
This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or  FITNESS
FOR A PARTICULAR PURPOSE.
.SH SEE ALSO
.LP
\fIPQregisterTypes(3)\fP, \fIpqt-handlers(3)\fP, \fIPQputf(3)\fP, \fIPQgetf(3)\fP