db_postgres: fix doxygen errors, small extensions and cleanups in comments
[sip-router] / modules / db_postgres / pg_fld.h
1 /* 
2  * Portions Copyright (C) 2001-2003 FhG FOKUS
3  * Copyright (C) 2003 August.Net Services, LLC
4  * Portions Copyright (C) 2005-2008 iptelorg GmbH
5  *
6  * This file is part of SER, a free SIP server.
7  *
8  * SER is free software; you can redistribute it and/or modify it under the
9  * terms of the GNU General Public License as published by the Free Software
10  * Foundation; either version 2 of the License, or (at your option) any later
11  * version
12  *
13  * For a license to use the ser software under conditions other than those
14  * described here, or to purchase support for this software, please contact
15  * iptel.org by e-mail at the following addresses: info@iptel.org
16  *
17  * SER is distributed in the hope that it will be useful, but WITHOUT ANY
18  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
19  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
20  * details.
21  *
22  * You should have received a copy of the GNU General Public License along
23  * with this program; if not, write to the Free Software Foundation, Inc., 59
24  * Temple Place, Suite 330, Boston, MA 02111-1307 USA
25  */
26
27 #ifndef _PG_FLD_H
28 #define _PG_FLD_H
29
30
31 /*!
32  * \file
33  * \brief DB_POSTGRES :: Implementation of pg_fld data structure
34  * 
35  * Implementation of pg_fld data structure representing PostgreSQL fields and related functions.
36  * \ingroup db_postgres
37  * Module: \ref db_postgres
38  */
39
40 #include "pg_oid.h"
41 #include "pg_cmd.h"
42 #include "../../ut.h"
43 #include "../../lib/srdb2/db_gen.h"
44 #include "../../lib/srdb2/db_fld.h"
45 #include <libpq-fe.h>
46
47 struct pg_fld {
48         db_drv_t gen;
49
50         /**
51          * A union of varius data types from db_fld, postgres expects binary
52          * data in network byte order so we use these variables as temporary
53          * buffer to store values after the conversion.
54          */
55         union {
56                 int          int4[2]; /**< Integer value in network byte order */
57                 short        int2[4];
58                 float        flt;     /**< Float value in network byte order */
59                 double       dbl;     /**< Double value in network byte order */
60                 time_t       time;    /**< Unix timestamp in network byte order */
61                 unsigned int bitmap;  /**< Bitmap value in network byte order */ 
62                 long long    int8;    /**< 8-byte integer value in network byte order */
63                 char         byte[8];
64         } v;
65         char buf[INT2STR_MAX_LEN]; /**< Buffer for int2str conversions */
66         Oid oid;                   /**< Type of the field on the server */
67 };
68
69
70 /** Creates a new PostgreSQL specific payload.
71  * This function creates a new PostgreSQL specific payload structure and
72  * attaches the structure to the generic db_fld structure.
73  * @param fld A generic db_fld structure to be exended.
74  * @param table Name of the table on the server.
75  * @return 0 on success, negative number on error.
76  */
77 int pg_fld(db_fld_t* fld, char* table);
78
79 int pg_resolve_param_oids(db_fld_t* vals, db_fld_t* match, 
80                                                   int n1, int n2, PGresult* res);
81
82 int pg_resolve_result_oids(db_fld_t* fld, int n, PGresult* res);
83
84
85 /** Converts arrays of db_fld fields to PostgreSQL parameters.
86  * The function converts fields in SER db_fld format to parameters suitable
87  * for PostgreSQL API functions.
88  * @param dst An array of pointers to values in PostgreSQL format. The
89  *               function will store pointers to converted values there.
90  * @param off offset 
91  * @param types A type conversion table.
92  * @param src An array of db_fld fields to be converted.
93  * @param flags Connection flags controlling how values are converted.
94  * @todo Implement support for bit fields with size bigger than 32 
95  * @todo Implement support for varbit properly to remove leading zeroes
96  * @todo Check if timezones are handled properly
97  * @todo Support for DB_NONE in pg_pg2fld and pg_check_pg2fld
98  * @todo local->UTC conversion (also check the SQL command in ser-oob)
99  */
100 int pg_fld2pg(struct pg_params* dst, int off, pg_type_t* types, 
101                           db_fld_t* src, unsigned int flags);
102
103
104 /** Converts fields from result in PGresult format into SER format.
105  * The function converts fields from PostgreSQL result (PGresult structure)
106  * into the internal format used in SER. The function converts one row at a
107  * time.
108  * @param dst The destination array of db_fld fields to be filled with converted
109  *            values.
110  * @param src A PostgreSQL result structure to be converted into SER format.
111  * @param row Number of the row to be converted.
112  * @param types A type conversion table.
113  * @param flags Connection flags controlling how values are converted.
114  * @retval 0 on success
115  * @retval A negative number on error.
116  * @todo UTC->local conversion
117  */
118 int pg_pg2fld(db_fld_t* dst, PGresult* src, int row, pg_type_t* types, 
119                           unsigned int flags);
120
121
122 /** Checks if all db_fld fields have types compatible with corresponding field 
123  * types on the server.
124  * The functions checks whether all db_fld fields in the last parameter are
125  * compatible with column types on the server, for conversion to postgres format.
126  * @param fld An array of db_fld fields to be checked.
127  * @param types An array used to map internal field types to Oids.
128  * @retval 0 on success
129  * @retval A negative number on error.
130  */
131 int pg_check_fld2pg(db_fld_t* fld, pg_type_t* types);
132
133 /** Checks if all db_fld fields have types compatible with corresponding field 
134  * types on the server.
135  * The functions checks whether all db_fld fields in the last parameter are
136  * compatible with column types on the server, for conversion to interal DB format.
137  * @param fld An array of db_fld fields to be checked.
138  * @param types An array used to map internal field types to Oids.
139  * @retval 0 on success
140  * @retval A negative number on error.
141  */
142 int pg_check_pg2fld(db_fld_t* fld, pg_type_t* types);
143
144
145 #endif /* _PG_FLD_H */