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);

DEPRECATED
       THIS FUNCTION IS DEPRECATED.  New applications should  use  PQregister-
       SubClasses,  PQregisterUserDefinedTypes  or PQregisterComposites.  This
       function is now a wrapper to those functions and  will  be  removed  in
       future versions.

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.

       WARNING: PQparamCreate is only aware of types that  have  already  been
       registered.   If  you  need to put a type into a param, make sure it is
       first registered.

       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) 2009 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                           2009             PQregisterTypeHandler(3)

libpqtypes home page