PQregisterTypeHandler(3)       libpqtypes Manual      PQregisterTypeHandler(3)



NAME
       PQregisterTypeHandler  -  Registers  a  type  handler  for user-defined
       types, composites, aliases or sub-classes.

SYNOPSIS
       #include <libpqtypes.h>

       typedef int (*PGtypeProc)(PGtypeArgs *args);
       int PQregisterTypeHandler(PGconn *conn, const char *typname,
                                 PGtypeProc put, PGtypeProc get);

NOTE TO READER
       This document does not explain how to implement a  type  handler,  only
       how  to  register  one.  To learn how to implement a type handler, `man
       pqt-handlers(3)'.  The pqt-handlers(3) man page contains example imple-
       mentations  of  type  handlers  as  well  as documents all typedefs and
       structures used by them.

DESCRIPTION
       The PQregisterTypeHandler() function allows the  application  developer
       to  register their own data type handlers at runtime.  This can be sim-
       ple aliases, composites, user-defined types or sub-classes.

       The typname argument describes either a fully qualified type name or an
       inheritence  relationship:  ex.  "myint=int4" where myint inherits from
       int4.  This cannot be NULL.  The '=' is called the  inheritence  opera-
       tor.

       The  put and get arguments are PGtypeProc callbacks.  When a registered
       type is encountered within a type  specifier  string  by  PQputf(3)  or
       PQgetf(3), its put and get routine is called.

       Alias Registration
       When  both  put  and  get  arguments  are  NULL and typname contains an
       inheritence operator, the registration is considered  an  alias.   This
       means  the type being registered will behave identically to the type it
       is inheriting from.

              /* Register an int4 alias under the built-in pqt schema.
               * Allows referencing %int4 as %d, printf-like.
               */
              PQregisterTypeHandler(conn, "pqt.d=pg_catalog.int4", NULL, NULL);

              /* use the 'd' alias to put an 'int4' */
              PQputf(param, "%d", 2893744);

       Sub-class Registration
       When either the put or get argument is not-NULL and typname contains an
       inheritence operator, the registration is considered a sub-class.  This
       means the type being registered will inherit the base type's  low-level
       data  conversion  routines.   This allows an application to convert its
       structures into libpqtypes structures, like PGtimestamp, prior  to  the
       base  type handler converting the libpqtypes structure to the backend's
       external format.

              /* Register timestamp sub-class named epoch.  The goal is to allow
               * an application to put and/or get timestamps as time_t epoch values,
               * rather than putting or getting via PGtimestamp.
               */
              PQregisterTypeHandler(conn, "pqt.epoch=pg_catalog.timestamp",
                   epoch_put, epoch_get);

              /* Put an epoch value */
              PQputf(param, "%epoch", time(NULL));

              /* Get an epoch value */
              time_t t;
              PGresult *res = PQexec(conn, "SELECT my_timestamp FROM t");
              PQgetf(res, tup_num, "%epoch", field_num, &t);

       Composite Registration
       When both put and get arguments are NULL and typname does  not  contain
       an  inheritence  operator,  the registration is considered a composite.
       Composites cannot be sub-classed and cannot be handled by user provided
       PGtypeProc  routines.  Although, the fields within a composite can have
       their own PGtypeProc routines. The composite is verified with the back-
       end.

              /* Register the 'invoice' composite that's in the billing schema. */
              PQregisterTypeHandler(conn, "billing.invoice", NULL, NULL);

              /* An invoice compsoite contains: int4, int4, text.
               * We have to first pack the invoice fields into a PGparam.
               */
              PGparam *inv_param = PQparamCreate(conn);
              PQputf(inv_param, "%int4 %int4 %text", 23, 90, "invoice text");

              /* Now pack the inv_param into a single parameter of
               * another param.
               */
              PGparam *param = PQparamCreate(conn);
              PQputf(param, "%invoice", inv_param);
              PQparamClear(inv_param); /* not needed anymore */
              //PQparamExec(conn, param, ...);

       User-defined Types Registration
       When  either  the  put or get argument is not-NULL and typname does not
       contain an inheritence operator, the registration is considered a user-
       defined  type.   User-defined  types are custom types in a backend that
       implement their own C procedures for  in/out/send/recv.   The  type  is
       verified with the backend.

              /* Register the 'rgb' user-defined type that's in the
               * graphics schema.
               */
              PQregisterTypeHandler(conn, "graphics.rgb", rgb_put, rgb_get);


RETURN VALUE
       On  success,  a non-zero value is returned.  On error, zero is returned
       and PQgeterror(3) will contain an error message.

EXAMPLES
       None.

AUTHOR
       A contribution of eSilo, LLC. for the  PostgreSQL  Database  Management
       System.  Written by Andrew Chernow and Merlin Moncure.

REPORTING BUGS
       Report bugs to <libpqtypes@esilo.com>.

COPYRIGHT
       Copyright (c) 2008 eSilo, LLC. All rights reserved.
       This is free software; see the source for copying conditions.  There is
       NO warranty; not even for MERCHANTABILITY or  FITNESS FOR A  PARTICULAR
       PURPOSE.

SEE ALSO
       pqt-handlers(3), PQputf(3), PQgetf(3)



libpqtypes                           2008             PQregisterTypeHandler(3)

libpqtypes home page