db_postgres: fix doxygen errors, small extensions and cleanups in comments
[sip-router] / modules / db_postgres / pg_cmd.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_CMD_H
28 #define _PG_CMD_H
29
30
31 /*!
32  * \file
33  * \brief DB_POSTGRES :: * Declaration of pg_cmd data structure
34  * 
35  * Declaration of pg_cmd data structure  that contains PostgreSQL specific data
36  * stored in db_cmd structures and related functions.
37  * \ingroup db_postgres
38  * Module: \ref db_postgres
39  */
40
41 #include "pg_oid.h"
42
43 #include "../../lib/srdb2/db_drv.h"
44 #include "../../lib/srdb2/db_cmd.h"
45 #include "../../lib/srdb2/db_res.h"
46 #include "../../str.h"
47
48 #include <stdarg.h>
49 #include <libpq-fe.h>
50
51 struct pg_params {
52         int n;
53         const char** val;
54         int* len;
55         int* fmt;
56 };
57
58
59 /** Extension structure of db_cmd adding PostgreSQL specific data.
60  * This data structure extends the generic data structure db_cmd in the
61  * database API with data specific to the postgresql driver.
62  */
63 struct pg_cmd {
64         db_drv_t gen; /**< Generic part of the data structure (must be first */
65         char* name;   /**< Name of the prepared query on the server */
66         str sql_cmd;  /**< Database command represented in SQL language */
67
68         struct pg_params params;
69         PGresult* types;
70 };
71
72
73 /** Creates a new pg_cmd data structure.
74  * This function allocates and initializes memory for a new pg_cmd data
75  * structure. The data structure is then attached to the generic db_cmd
76  * structure in cmd parameter.
77  * @param cmd A generic db_cmd structure to which the newly created pg_cmd
78  *            structure will be attached.
79  */
80 int pg_cmd(db_cmd_t* cmd);
81
82
83 /** The main execution function in postgres SER driver.
84  * This is the main execution function in this driver. It is executed whenever
85  * a SER module calls db_exec and the target database of the commands is
86  * PostgreSQL. The function contains all the necessary logic to detect reset
87  * or disconnected database connections and uploads commands to the server if
88  * necessary.
89  * @param res A pointer to (optional) result structure if the command returns
90  *            a result.
91  * @param cmd executed command
92  * @retval 0 if executed successfully
93  * @retval A negative number if the database server failed to execute command
94  * @retval A positive number if there was an error on client side (SER)
95  */
96 int pg_cmd_exec(db_res_t* res, db_cmd_t* cmd);
97
98
99 /** Retrieves the first record from a result set received from PostgreSQL server.
100  * This function is executed whenever a SER module calls db_first to retrieve
101  * the first record from a result. The function retrieves the first record
102  * from a PGresult structure and converts the fields from PostgreSQL to
103  * internal SER representation.
104  * 
105  * @param res A result set retrieved from PostgreSQL server.
106  * @retval 0 If executed successfully.
107  * @retval 1 If the result is empty.
108  * @retval A negative number on error.
109  */
110 int pg_cmd_first(db_res_t* res);
111
112
113 /** Retrieves the next record from a result set received from PostgreSQL server.
114  * This function is executed whenever a SER module calls db_next to retrieve
115  * the first record from a result. The function advances current cursor
116  * position in the result, retrieves the next record from a PGresult structure
117  * and converts the fields from PostgreSQL to internal SER representation.
118  * 
119  * @param res A result set retrieved from PostgreSQL server.
120  * @retval 0 If executed successfully.
121  * @retval 1 If there are no more records in the result.
122  * @retval A negative number on error.
123  */
124 int pg_cmd_next(db_res_t* res);
125
126
127 /** Retrieves the value of an db_cmd option.
128  * This function is called when a SER module uses db_getopt to retrieve the
129  * value of db_cmd parameter.
130  * @param cmd A db_cmd structure representing the command.
131  * @param optname Name of the option.
132  * @param ap A pointer the result variable.
133  * @retval 0 on success.
134  * @retval A positive number of the option is not supported/implemented.
135  * @retval A negative number on error.
136  */
137 int pg_getopt(db_cmd_t* cmd, char* optname, va_list ap);
138
139
140 /** Sets the value of an db_cmd option.
141  * This function is called when a SER module uses db_setopt to set the
142  * value of db_cmd parameter.
143  * @param cmd A db_cmd structure representing the command.
144  * @param optname Name of the option.
145  * @param ap A variable with the value to be set.
146  * @retval 0 on success.
147  * @retval A positive number of the option is not supported/implemented.
148  * @retval A negative number on error.
149  */
150 int pg_setopt(db_cmd_t* cmd, char* optname, va_list ap);
151
152 #endif /* _PG_CMD_H */