1398d16b76484b295da8230684d9f0c680601a06
[sip-router] / modules / db_postgres / pg_cmd.h
1 /* 
2  * $Id$ 
3  *
4  * PostgreSQL Database Driver for SER
5  *
6  * Portions Copyright (C) 2001-2003 FhG FOKUS
7  * Copyright (C) 2003 August.Net Services, LLC
8  * Portions Copyright (C) 2005-2008 iptelorg GmbH
9  *
10  * This file is part of SER, a free SIP server.
11  *
12  * SER is free software; you can redistribute it and/or modify it under the
13  * terms of the GNU General Public License as published by the Free Software
14  * Foundation; either version 2 of the License, or (at your option) any later
15  * version
16  *
17  * For a license to use the ser software under conditions other than those
18  * described here, or to purchase support for this software, please contact
19  * iptel.org by e-mail at the following addresses: info@iptel.org
20  *
21  * SER is distributed in the hope that it will be useful, but WITHOUT ANY
22  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
23  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
24  * details.
25  *
26  * You should have received a copy of the GNU General Public License along
27  * with this program; if not, write to the Free Software Foundation, Inc., 59
28  * Temple Place, Suite 330, Boston, MA 02111-1307 USA
29  */
30
31 #ifndef _PG_CMD_H
32 #define _PG_CMD_H
33
34 /** \addtogroup postgres
35  * @{ 
36  */
37
38 /** \file 
39  * Declaration of pg_cmd data structure that contains PostgreSQL specific data
40  * stored in db_cmd structures and related functions.
41  */
42
43 #include "pg_oid.h"
44
45 #include "../../lib/srdb2/db_drv.h"
46 #include "../../lib/srdb2/db_cmd.h"
47 #include "../../lib/srdb2/db_res.h"
48 #include "../../str.h"
49
50 #include <stdarg.h>
51 #include <libpq-fe.h>
52
53 struct pg_params {
54         int n;
55         const char** val;
56         int* len;
57         int* fmt;
58 };
59
60
61 /** Extension structure of db_cmd adding PostgreSQL specific data.
62  * This data structure extends the generic data structure db_cmd in the
63  * database API with data specific to the postgresql driver.
64  */
65 struct pg_cmd {
66         db_drv_t gen; /**< Generic part of the data structure (must be first */
67         char* name;   /**< Name of the prepared query on the server */
68         str sql_cmd;  /**< Database command represented in SQL language */
69
70         struct pg_params params;
71         PGresult* types;
72 };
73
74
75 /** Creates a new pg_cmd data structure.
76  * This function allocates and initializes memory for a new pg_cmd data
77  * structure. The data structure is then attached to the generic db_cmd
78  * structure in cmd parameter.
79  * @param cmd A generic db_cmd structure to which the newly created pg_cmd
80  *            structure will be attached.
81  */
82 int pg_cmd(db_cmd_t* cmd);
83
84
85 /** The main execution function in postgres SER driver.
86  * This is the main execution function in this driver. It is executed whenever
87  * a SER module calls db_exec and the target database of the commands is
88  * PostgreSQL. The function contains all the necessary logic to detect reset
89  * or disconnected database connections and uploads commands to the server if
90  * necessary.
91  * @param res A pointer to (optional) result structure if the command returns
92  *            a result.
93  * @retval 0 if executed successfully
94  * @retval A negative number if the database server failed to execute command
95  * @retval A positive number if there was an error on client side (SER)
96  */
97 int pg_cmd_exec(db_res_t* res, db_cmd_t* cmd);
98
99
100 /** Retrieves the first record from a result set received from PostgreSQL server.
101  * This function is executed whenever a SER module calls db_first to retrieve
102  * the first record from a result. The function retrieves the first record
103  * from a PGresult structure and converts the fields from PostgreSQL to
104  * internal SER representation.
105  * 
106  * @param res A result set retrieved from PostgreSQL server.
107  * @retval 0 If executed successfully.
108  * @retval 1 If the result is empty.
109  * @retival A negative number on error.
110  */
111 int pg_cmd_first(db_res_t* res);
112
113
114 /** Retrieves the next record from a result set received from PostgreSQL server.
115  * This function is executed whenever a SER module calls db_next to retrieve
116  * the first record from a result. The function advances current cursor
117  * position in the result, retrieves the next record from a PGresult structure
118  * and converts the fields from PostgreSQL to internal SER representation.
119  * 
120  * @param res A result set retrieved from PostgreSQL server.
121  * @retval 0 If executed successfully.
122  * @retval 1 If there are no more records in the result.
123  * @retival A negative number on error.
124  */
125 int pg_cmd_next(db_res_t* res);
126
127
128 /** Retrieves the value of an db_cmd option.
129  * This function is called when a SER module uses db_getopt to retrieve the
130  * value of db_cmd parameter.
131  * @param cmd A db_cmd structure representing the command.
132  * @param optname Name of the option.
133  * @param ap A pointer the result variable.
134  * @retval 0 on success.
135  * @retval A positive number of the option is not supported/implemented.
136  * @retval A negative number on error.
137  */
138 int pg_getopt(db_cmd_t* cmd, char* optname, va_list ap);
139
140
141 /** Sets the value of an db_cmd option.
142  * This function is called when a SER module uses db_setopt to set the
143  * value of db_cmd parameter.
144  * @param cmd A db_cmd structure representing the command.
145  * @param optname Name of the option.
146  * @param ap A variable with the value to be set.
147  * @retval 0 on success.
148  * @retval A positive number of the option is not supported/implemented.
149  * @retval A negative number on error.
150  */
151 int pg_setopt(db_cmd_t* cmd, char* optname, va_list ap);
152
153 /** @} */
154
155 #endif /* _PG_CMD_H */