1 /* 2 * Copyright (C) 2001 - 2003 Rodrigo Moya <rodrigo@gnome-db.org> 3 * Copyright (C) 2002 - 2003 Gonzalo Paniagua Javier <gonzalo@gnome-db.org> 4 * Copyright (C) 2002 - 2013 Vivien Malerba <malerba@gnome-db.org> 5 * Copyright (C) 2003 Akira TAGOH <tagoh@gnome-db.org> 6 * Copyright (C) 2003 Danilo Schoeneberg <dschoene@src.gnome.org> 7 * Copyright (C) 2003 Laurent Sansonetti <laurent@datarescue.be> 8 * Copyright (C) 2004 - 2011 Murray Cumming <murrayc@murrayc.com> 9 * Copyright (C) 2004 Paisa Seeluangsawat <paisa@users.sf.net> 10 * Copyright (C) 2008 Przemysław Grzegorczyk <pgrzegorczyk@gmail.com> 11 * Copyright (C) 2009 Bas Driessen <bas.driessen@xobas.com> 12 * Copyright (C) 2011 Daniel Espinosa <despinosa@src.gnome.org> 13 * 14 * This library is free software; you can redistribute it and/or 15 * modify it under the terms of the GNU Lesser General Public 16 * License as published by the Free Software Foundation; either 17 * version 2 of the License, or (at your option) any later version. 18 * 19 * This library is distributed in the hope that it will be useful, 20 * but WITHOUT ANY WARRANTY; without even the implied warranty of 21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 22 * Lesser General Public License for more details. 23 * 24 * You should have received a copy of the GNU Lesser General Public 25 * License along with this library; if not, write to the 26 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 27 * Boston, MA 02110-1301, USA. 28 */ 29 30 #ifndef __GDA_VALUE_H__ 31 #define __GDA_VALUE_H__ 32 33 #include <time.h> 34 #include <glib.h> 35 #include <glib-object.h> 36 #include <libxml/tree.h> 37 #include <libgda/gda-decl.h> 38 39 G_BEGIN_DECLS 40 41 #define GDA_TIMEZONE_INVALID (2*12*60*60) 42 43 /* Definition of the GType's values used in GValue*/ 44 #define GDA_TYPE_NULL (gda_null_get_type()) 45 #define GDA_TYPE_DEFAULT (gda_default_get_type()) 46 #define GDA_TYPE_BINARY (gda_binary_get_type()) 47 #define GDA_TYPE_BLOB (gda_blob_get_type()) 48 #define GDA_TYPE_GEOMETRIC_POINT (gda_geometricpoint_get_type()) 49 #define GDA_TYPE_NUMERIC (gda_numeric_get_type()) 50 #define GDA_TYPE_SHORT (gda_short_get_type()) 51 #define GDA_TYPE_USHORT (gda_ushort_get_type()) 52 #define GDA_TYPE_TIME (gda_time_get_type()) 53 #define GDA_TYPE_TIMESTAMP (gda_timestamp_get_type()) 54 55 56 /* Definition of the GDA_VALUE_HOLDS macros */ 57 #define GDA_VALUE_HOLDS_NULL(value) G_VALUE_HOLDS(value, GDA_TYPE_NULL) 58 #define GDA_VALUE_HOLDS_DEFAULT(value) G_VALUE_HOLDS(value, GDA_TYPE_DEFAULT) 59 #define GDA_VALUE_HOLDS_BINARY(value) G_VALUE_HOLDS(value, GDA_TYPE_BINARY) 60 #define GDA_VALUE_HOLDS_BLOB(value) G_VALUE_HOLDS(value, GDA_TYPE_BLOB) 61 #define GDA_VALUE_HOLDS_GEOMETRIC_POINT(value) G_VALUE_HOLDS(value, GDA_TYPE_GEOMETRIC_POINT) 62 #define GDA_VALUE_HOLDS_NUMERIC(value) G_VALUE_HOLDS(value, GDA_TYPE_NUMERIC) 63 #define GDA_VALUE_HOLDS_SHORT(value) G_VALUE_HOLDS(value, GDA_TYPE_SHORT) 64 #define GDA_VALUE_HOLDS_USHORT(value) G_VALUE_HOLDS(value, GDA_TYPE_USHORT) 65 #define GDA_VALUE_HOLDS_TIME(value) G_VALUE_HOLDS(value, GDA_TYPE_TIME) 66 #define GDA_VALUE_HOLDS_TIMESTAMP(value) G_VALUE_HOLDS(value, GDA_TYPE_TIMESTAMP) 67 68 /** 69 * GdaGeometricPoint: 70 * @x: 71 * @y: 72 */ 73 typedef struct { 74 gdouble x; 75 gdouble y; 76 } GdaGeometricPoint; 77 78 79 typedef struct _GdaNumeric GdaNumeric; 80 # ifdef GSEAL_ENABLE 81 # else 82 struct _GdaNumeric { 83 gchar* GSEAL(number); 84 glong GSEAL(precision); 85 glong GSEAL(width); 86 87 /*< private >*/ 88 gpointer reserved; /* reserved for future usage with GMP (http://gmplib.org/) */ 89 }; 90 #endif 91 92 /** 93 * GdaTime: 94 * @hour: hour representation of the time, as a number between 0 and 23 95 * @minute: minute representation of the time, as a number between 0 and 59 96 * @second: second representation of the time, as a number between 0 and 59 97 * @fraction: fractionnal part of the seconds, in millionth' of second 98 * @timezone: number of seconds added to the GMT timezone 99 * 100 * Represents a time information. 101 */ 102 typedef struct { 103 gushort hour; 104 gushort minute; 105 gushort second; 106 gulong fraction; 107 glong timezone; 108 } GdaTime; 109 110 /** 111 * GdaTimestamp: 112 * @year: year representation of the time stamp 113 * @month: month representation of the time stamp, as a number between 1 and 12 114 * @day: day representation of the time stamp, as a number between 1 and 31 115 * @hour: hour representation of the time stamp, as a number between 0 and 23 116 * @minute: minute representation of the time stamp, as a number between 0 and 59 117 * @second: second representation of the time stamp, as a number between 0 and 59 118 * @fraction: fractionnal part of the seconds, in millionth' of second 119 * @timezone: number of seconds added to the GMT timezone 120 * 121 * Represents an instant (a time stamp) 122 */ 123 typedef struct { 124 gshort year; 125 gushort month; 126 gushort day; 127 gushort hour; 128 gushort minute; 129 gushort second; 130 gulong fraction; 131 glong timezone; 132 } GdaTimestamp; 133 134 /** 135 * GdaBinary: 136 * @data: (array): the actual data as an array 137 * @binary_length: length of @data 138 */ 139 typedef struct { 140 guchar *data; 141 glong binary_length; 142 } GdaBinary; 143 144 /** 145 * GdaBlob: 146 * @data: data buffer, as a #GdaBinary 147 * @op: (allow-none): a pointer to a #GdaBlopOp, or %NULL 148 * 149 * Represents some binary data, accessed through a #GdaBlobOp object. 150 * @op is generally set up by database providers when giving access to an existing BLOB in 151 * a database, but can be modified if needed using gda_blob_set_op(). 152 */ 153 typedef struct { 154 GdaBinary data; 155 GdaBlobOp *op; 156 } GdaBlob; 157 158 #define gda_value_isa(value, type) (G_VALUE_HOLDS(value, type)) 159 160 /** 161 * SECTION:gda-value 162 * @short_description: Assorted functions for dealing with #GValue values 163 * @title: A single Value 164 * @stability: Stable 165 * @see_also: #GValue and #GdaBlobOp 166 * 167 * &LIBGDA; manages each individual value within an opaque #GValue structure. Any GValue type can be used, 168 * and &LIBGDA; adds a few more data types usually found in DBMS such as NUMERIC, TIME, TIMESTAMP, GEOMETRIC POINT, BINARY and BLOB. 169 * 170 * Libgda makes a distinction between binary and blob types 171 * <itemizedlist> 172 * <listitem><para>binary data can be inserted into an SQL statement using a 173 * (DBMS dependent) syntax, such as "X'ABCD'" syntax for SQLite or the binary strings syntax for PostgreSQL. Binary data 174 * is manipulated using a #GdaBinary structure (which is basically a bytes buffer and a length attribute). 175 * </para></listitem> 176 * <listitem><para>blob data are a special feature that some DBMS have which requires some non SQL code to manipulate them. 177 * Usually only a reference is stored in each table containing a blob, and the actual blob data resides somewhere on the disk 178 * (while still being managed transparently by the database). For example PotsgreSQL stores blobs as files on the disk and 179 * references them using object identifiers (Oid). Blob data 180 * is manipulated using a #GdaBlob structure which encapsulates a #GdaBinary structure and adds a reference to a 181 * #GdaBlobOp object used to read and write data from and to the blob. 182 * </para></listitem> 183 * </itemizedlist> 184 * Please note that is distinction between binary data and blobs is Libgda only and does not reflect the DBMS's documentations; 185 * for instance MySQL has several BLOB types but Libgda interprets them as binary types. 186 * 187 * Each provider or connection can be queried about its blob support using the gda_server_provider_supports_feature() or 188 * gda_connection_supports_feature() methods. 189 * 190 * There are two special value types which are: 191 * <itemizedlist> 192 * <listitem><para>the GDA_TYPE_NULL value which never changes and acutally represents an SQL NULL value</para></listitem> 193 * <listitem><para>the GDA_TYPE_DEFAULT value which represents a default value which &LIBGDA; does not interpret (such as when a table column's default value is a function call)</para></listitem> 194 * </itemizedlist> 195 */ 196 197 GValue *gda_value_new (GType type); 198 199 GValue *gda_value_new_null (void); 200 GValue *gda_value_new_default (const gchar *default_val); 201 GValue *gda_value_new_binary (const guchar *val, glong size); 202 GValue *gda_value_new_blob (const guchar *val, glong size); 203 GValue *gda_value_new_blob_from_file (const gchar *filename); 204 GValue *gda_value_new_timestamp_from_timet (time_t val); 205 206 GValue *gda_value_new_from_string (const gchar *as_string, GType type); 207 GValue *gda_value_new_from_xml (const xmlNodePtr node); 208 209 void gda_value_free (GValue *value); 210 void gda_value_reset_with_type (GValue *value, GType type); 211 212 gboolean gda_value_is_null (const GValue *value); 213 gboolean gda_value_is_number (const GValue *value); 214 GValue *gda_value_copy (const GValue *value); 215 216 const GdaBinary *gda_value_get_binary (const GValue *value); 217 void gda_value_set_binary (GValue *value, const GdaBinary *binary); 218 void gda_value_take_binary (GValue *value, GdaBinary *binary); 219 220 const GdaBlob *gda_value_get_blob (const GValue *value); 221 void gda_value_set_blob (GValue *value, const GdaBlob *blob); 222 void gda_value_take_blob (GValue *value, GdaBlob *blob); 223 224 const GdaGeometricPoint *gda_value_get_geometric_point (const GValue *value); 225 void gda_value_set_geometric_point (GValue *value, const GdaGeometricPoint *val); 226 void gda_value_set_null (GValue *value); 227 const GdaNumeric *gda_value_get_numeric (const GValue *value); 228 void gda_value_set_numeric (GValue *value, const GdaNumeric *val); 229 gshort gda_value_get_short (const GValue *value); 230 void gda_value_set_short (GValue *value, const gshort val); 231 gushort gda_value_get_ushort (const GValue *value); 232 void gda_value_set_ushort (GValue *value, const gushort val); 233 const GdaTime *gda_value_get_time (const GValue *value); 234 void gda_value_set_time (GValue *value, const GdaTime *val); 235 const GdaTimestamp *gda_value_get_timestamp (const GValue *value); 236 void gda_value_set_timestamp (GValue *value, const GdaTimestamp *val); 237 238 239 240 241 gboolean gda_value_set_from_string (GValue *value, 242 const gchar *as_string, 243 GType type); 244 gboolean gda_value_set_from_value (GValue *value, const GValue *from); 245 246 gint gda_value_differ (const GValue *value1, const GValue *value2); 247 gint gda_value_compare (const GValue *value1, const GValue *value2); 248 gchar *gda_value_stringify (const GValue *value); 249 xmlNodePtr gda_value_to_xml (const GValue *value); 250 251 gchar *gda_binary_to_string (const GdaBinary *bin, guint maxlen); 252 GdaBinary *gda_string_to_binary (const gchar *str); 253 254 gchar *gda_blob_to_string (GdaBlob *blob, guint maxlen); 255 GdaBlob *gda_string_to_blob (const gchar *str); 256 257 /* Custom data types */ 258 259 GType gda_null_get_type (void) G_GNUC_CONST; 260 GType gda_default_get_type (void) G_GNUC_CONST; 261 GType gda_numeric_get_type (void) G_GNUC_CONST; 262 GdaNumeric* gda_numeric_new (void); 263 GdaNumeric* gda_numeric_copy (GdaNumeric *src); 264 void gda_numeric_set_from_string (GdaNumeric *numeric, const gchar* str); 265 void gda_numeric_set_double (GdaNumeric *numeric, gdouble number); 266 gdouble gda_numeric_get_double (const GdaNumeric *numeric); 267 void gda_numeric_set_precision (GdaNumeric *numeric, glong precision); 268 glong gda_numeric_get_precision (const GdaNumeric *numeric); 269 void gda_numeric_set_width (GdaNumeric *numeric, glong width); 270 glong gda_numeric_get_width (const GdaNumeric *numeric); 271 gchar* gda_numeric_get_string (const GdaNumeric *numeric); 272 void gda_numeric_free (GdaNumeric *numeric); 273 274 GType gda_time_get_type (void) G_GNUC_CONST; 275 gpointer gda_time_copy (gpointer boxed); 276 void gda_time_free (gpointer boxed); 277 gboolean gda_time_valid (const GdaTime *time); 278 void gda_time_change_timezone (GdaTime *time, glong ntz); 279 280 GType gda_timestamp_get_type (void) G_GNUC_CONST; 281 gpointer gda_timestamp_copy (gpointer boxed); 282 void gda_timestamp_free (gpointer boxed); 283 gboolean gda_timestamp_valid (const GdaTimestamp *timestamp); 284 void gda_timestamp_change_timezone (GdaTimestamp *ts, glong ntz); 285 286 287 GType gda_geometricpoint_get_type (void) G_GNUC_CONST; 288 gpointer gda_geometricpoint_copy (gpointer boxed); 289 void gda_geometricpoint_free (gpointer boxed); 290 291 GType gda_binary_get_type (void) G_GNUC_CONST; 292 gpointer gda_binary_copy (gpointer boxed); 293 void gda_binary_free (gpointer boxed); 294 295 GType gda_blob_get_type (void) G_GNUC_CONST; 296 gpointer gda_blob_copy (gpointer boxed); 297 void gda_blob_free (gpointer boxed); 298 void gda_blob_set_op (GdaBlob *blob, GdaBlobOp *op); 299 300 GType gda_short_get_type (void) G_GNUC_CONST; 301 GType gda_ushort_get_type (void) G_GNUC_CONST; 302 303 G_END_DECLS 304 305 #endif 306