gg_formats.h File Reference

Geometry handling functions: formats. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
GAIAGEO_DECLARE int	gaiaEndianArch (void)
	Test CPU endianness. More...
GAIAGEO_DECLARE short	gaiaImport16 (const unsigned char *p, int little_endian, int little_endian_arch)
	Import an INT-16 value in endian-aware fashion. More...
GAIAGEO_DECLARE int	gaiaImport32 (const unsigned char *p, int little_endian, int little_endian_arch)
	Import an INT-32 value in endian-aware fashion. More...
GAIAGEO_DECLARE unsigned int	gaiaImportU32 (const unsigned char *p, int little_endian, int little_endian_arch)
	Import an UINT-32 value in endian-aware fashion. More...
GAIAGEO_DECLARE float	gaiaImportF32 (const unsigned char *p, int little_endian, int little_endian_arch)
	Import a FLOAT-32 value in endian-aware fashion. More...
GAIAGEO_DECLARE double	gaiaImport64 (const unsigned char *p, int little_endian, int little_endian_arch)
	Import an DOUBLE-64 in endian-aware fashion. More...
GAIAGEO_DECLARE sqlite3_int64	gaiaImportI64 (const unsigned char *p, int little_endian, int little_endian_arch)
	Import an INT-64 in endian-aware fashion. More...
GAIAGEO_DECLARE void	gaiaExport16 (unsigned char *p, short value, int little_endian, int little_endian_arch)
	Export an INT-16 value in endian-aware fashion. More...
GAIAGEO_DECLARE void	gaiaExport32 (unsigned char *p, int value, int little_endian, int little_endian_arch)
	Export an INT-32 value in endian-aware fashion. More...
GAIAGEO_DECLARE void	gaiaExportU32 (unsigned char *p, unsigned int value, int little_endian, int little_endian_arch)
	Export an UINT-32 value in endian-aware fashion. More...
GAIAGEO_DECLARE void	gaiaExportF32 (unsigned char *p, float value, int little_endian, int little_endian_arch)
	Export a FLOAT-32 value in endian-aware fashion. More...
GAIAGEO_DECLARE void	gaiaExport64 (unsigned char *p, double value, int little_endian, int little_endian_arch)
	Export a DOUBLE value in endian-aware fashion. More...
GAIAGEO_DECLARE void	gaiaExportI64 (unsigned char *p, sqlite3_int64 value, int little_endian, int little_endian_arch)
	Export an INT-64 value in endian-aware fashion. More...
GAIAGEO_DECLARE void	gaiaOutBufferInitialize (gaiaOutBufferPtr buf)
	Initializes a dynamically growing Text output buffer. More...
GAIAGEO_DECLARE void	gaiaOutBufferReset (gaiaOutBufferPtr buf)
	Resets a dynamically growing Text output buffer to its initial (empty) state. More...
GAIAGEO_DECLARE void	gaiaAppendToOutBuffer (gaiaOutBufferPtr buf, const char *text)
	Appends a text string at the end of Text output buffer. More...
GAIAGEO_DECLARE void	gaiaMakePoint (double x, double y, int srid, unsigned char **result, int *size)
	Creates a BLOB-Geometry representing a Point. More...
GAIAGEO_DECLARE void	gaiaMakePointZ (double x, double y, double z, int srid, unsigned char **result, int *size)
	Creates a BLOB-Geometry representing a PointZ. More...
GAIAGEO_DECLARE void	gaiaMakePointM (double x, double y, double m, int srid, unsigned char **result, int *size)
	Creates a BLOB-Geometry representing a PointM. More...
GAIAGEO_DECLARE void	gaiaMakePointZM (double x, double y, double z, double m, int srid, unsigned char **result, int *size)
	Creates a BLOB-Geometry representing a PointZM. More...
GAIAGEO_DECLARE void	gaiaMakeLine (gaiaGeomCollPtr geom1, gaiaGeomCollPtr geom2, unsigned char **result, int *size)
	Creates a BLOB-Geometry representing a Segment (2-Points Linestring) More...
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaFromSpatiaLiteBlobWkb (const unsigned char *blob, unsigned int size)
	Creates a Geometry object from the corresponding BLOB-Geometry. More...
GAIAGEO_DECLARE void	gaiaToSpatiaLiteBlobWkb (gaiaGeomCollPtr geom, unsigned char **result, int *size)
	Creates a BLOB-Geometry corresponding to a Geometry object. More...
GAIAGEO_DECLARE void	gaiaToCompressedBlobWkb (gaiaGeomCollPtr geom, unsigned char **result, int *size)
	Creates a Compressed BLOB-Geometry corresponding to a Geometry object. More...
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaFromWkb (const unsigned char *blob, unsigned int size)
	Creates a Geometry object from WKB notation. More...
GAIAGEO_DECLARE void	gaiaToWkb (gaiaGeomCollPtr geom, unsigned char **result, int *size)
	Encodes a Geometry object into WKB notation. More...
GAIAGEO_DECLARE char *	gaiaToHexWkb (gaiaGeomCollPtr geom)
	Encodes a Geometry object into (hex) WKB notation. More...
GAIAGEO_DECLARE void	gaiaToEWKB (gaiaOutBufferPtr out_buf, gaiaGeomCollPtr geom)
	Encodes a Geometry object into EWKB notation. More...
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaFromEWKB (const unsigned char *in_buffer)
	Creates a Geometry object from EWKB notation. More...
GAIAGEO_DECLARE unsigned char *	gaiaParseHexEWKB (const unsigned char *blob_hex, int *blob_size)
	Translates an EWKB notation from hexadecimal into binary. More...
GAIAGEO_DECLARE int	gaiaEwkbGetPoint (gaiaGeomCollPtr geom, unsigned char *blob, int offset, int blob_size, int endian, int endian_arch, int dims)
	Attempts to decode a Point from within an EWKB binary buffer. More...
GAIAGEO_DECLARE int	gaiaEwkbGetLinestring (gaiaGeomCollPtr geom, unsigned char *blob, int offset, int blob_size, int endian, int endian_arch, int dims)
	Attempts to decode a Point from within an EWKB binary buffer. More...
GAIAGEO_DECLARE int	gaiaEwkbGetPolygon (gaiaGeomCollPtr geom, unsigned char *blob, int offset, int blob_size, int endian, int endian_arch, int dims)
	Attempts to decode a Polygon from within an EWKB binary buffer. More...
GAIAGEO_DECLARE int	gaiaEwkbGetMultiGeometry (gaiaGeomCollPtr geom, unsigned char *blob, int offset, int blob_size, int endian, int endian_arch, int dims)
	Attempts to decode a MultiGeometry from within an EWKB binary buffer. More...
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaFromFgf (const unsigned char *blob, unsigned int size)
	Creates a Geometry object from FGF notation. More...
GAIAGEO_DECLARE void	gaiaToFgf (gaiaGeomCollPtr geom, unsigned char **result, int *size, int coord_dims)
	Encodes a Geometry object into FGF notation. More...
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaParseWkt (const unsigned char *in_buffer, short type)
	Creates a Geometry object from WKT notation. More...
GAIAGEO_DECLARE void	gaiaOutWkt (gaiaOutBufferPtr out_buf, gaiaGeomCollPtr geom)
	Encodes a Geometry object into WKT notation. More...
GAIAGEO_DECLARE void	gaiaOutWktStrict (gaiaOutBufferPtr out_buf, gaiaGeomCollPtr geom, int precision)
	Encodes a Geometry object into strict 2D WKT notation. More...
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaParseEWKT (const unsigned char *in_buffer)
	Creates a Geometry object from EWKT notation. More...
GAIAGEO_DECLARE void	gaiaToEWKT (gaiaOutBufferPtr out_buf, gaiaGeomCollPtr geom)
	Encodes a Geometry object into EWKT notation. More...
GAIAGEO_DECLARE void	gaiaOutPointZ (gaiaOutBufferPtr out_buf, gaiaPointPtr point)
	Encodes a WKT 3D Point [XYZ]. More...
GAIAGEO_DECLARE void	gaiaOutLinestringZ (gaiaOutBufferPtr out_buf, gaiaLinestringPtr linestring)
	Encodes a WKT 3D Linestring [XYZ]. More...
GAIAGEO_DECLARE void	gaiaOutPolygonZ (gaiaOutBufferPtr out_buf, gaiaPolygonPtr polygon)
	Encodes a WKT 3D Polygon [XYZ]. More...
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaParseKml (const unsigned char *in_buffer)
	Creates a Geometry object from KML notation. More...
GAIAGEO_DECLARE void	gaiaOutBareKml (gaiaOutBufferPtr out_buf, gaiaGeomCollPtr geom, int precision)
	Encodes a Geometry object into KML notation. More...
GAIAGEO_DECLARE void	gaiaOutFullKml (gaiaOutBufferPtr out_buf, const char *name, const char *desc, gaiaGeomCollPtr geom, int precision)
	Encodes a Geometry object into KML notation. More...
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaParseGml (const unsigned char *in_buffer, sqlite3 *sqlite_handle)
	Creates a Geometry object from GML notation. More...
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaParseGml_r (const void *p_cache, const unsigned char *in_buffer, sqlite3 *sqlite_handle)
	Creates a Geometry object from GML notation. More...
GAIAGEO_DECLARE void	gaiaOutGml (gaiaOutBufferPtr out_buf, int version, int precision, gaiaGeomCollPtr geom)
	Encodes a Geometry object into GML notation. More...
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaParseGeoJSON (const unsigned char *in_buffer)
	Creates a Geometry object from GeoJSON notation. More...
GAIAGEO_DECLARE void	gaiaOutGeoJSON (gaiaOutBufferPtr out_buf, gaiaGeomCollPtr geom, int precision, int options)
	Encodes a Geometry object into GeoJSON notation. More...
GAIAGEO_DECLARE void	gaiaOutSvg (gaiaOutBufferPtr out_buf, gaiaGeomCollPtr geom, int relative, int precision)
	Encodes a Geometry object into SVG notation. More...
GAIAGEO_DECLARE gaiaValuePtr	gaiaCloneValue (gaiaValuePtr org)
	Allocates a new DBF Field Value object [duplicating an existing one]. More...
GAIAGEO_DECLARE void	gaiaFreeValue (gaiaValuePtr p)
	Resets a DBF Field Value object to its initial empty state. More...
GAIAGEO_DECLARE gaiaDbfFieldPtr	gaiaAllocDbfField (char *name, unsigned char type, int offset, unsigned char length, unsigned char decimals)
	Allocates a new DBF Field object. More...
GAIAGEO_DECLARE void	gaiaFreeDbfField (gaiaDbfFieldPtr p)
	Destroys a DBF Field object. More...
GAIAGEO_DECLARE gaiaDbfFieldPtr	gaiaCloneDbfField (gaiaDbfFieldPtr org)
	Allocates a new DBF Field object [duplicating an existing one]. More...
GAIAGEO_DECLARE void	gaiaSetNullValue (gaiaDbfFieldPtr field)
	Sets a NULL current value for a DBF Field object. More...
GAIAGEO_DECLARE void	gaiaSetIntValue (gaiaDbfFieldPtr field, sqlite3_int64 value)
	Sets an INTEGER current value for a DBF Field object. More...
GAIAGEO_DECLARE void	gaiaSetDoubleValue (gaiaDbfFieldPtr field, double value)
	Sets a DOUBLE current value for a DBF Field object. More...
GAIAGEO_DECLARE void	gaiaSetStrValue (gaiaDbfFieldPtr field, char *str)
	Sets a TEXT current value for a DBF Field object. More...
GAIAGEO_DECLARE gaiaDbfListPtr	gaiaAllocDbfList (void)
	Creates an initially empty DBF List object. More...
GAIAGEO_DECLARE void	gaiaFreeDbfList (gaiaDbfListPtr list)
	Destroys a DBF List object. More...
GAIAGEO_DECLARE int	gaiaIsValidDbfList (gaiaDbfListPtr list)
	Checks a DBF List object for validity. More...
GAIAGEO_DECLARE gaiaDbfFieldPtr	gaiaAddDbfField (gaiaDbfListPtr list, char *name, unsigned char type, int offset, unsigned char length, unsigned char decimals)
	Inserts a further DBF Field object into a DBF List object. More...
GAIAGEO_DECLARE void	gaiaResetDbfEntity (gaiaDbfListPtr list)
	Resets a DBF List object to its initial empty state. More...
GAIAGEO_DECLARE gaiaDbfListPtr	gaiaCloneDbfEntity (gaiaDbfListPtr org)
	Allocates a new DBF List object [duplicating an existing one]. More...
GAIAGEO_DECLARE gaiaShapefilePtr	gaiaAllocShapefile (void)
	Allocates a new Shapefile object. More...
GAIAGEO_DECLARE void	gaiaFreeShapefile (gaiaShapefilePtr shp)
	Destroys a Shapefile object. More...
GAIAGEO_DECLARE void	gaiaOpenShpRead (gaiaShapefilePtr shp, const char *path, const char *charFrom, const char *charTo)
	Open a Shapefile in read mode. More...
GAIAGEO_DECLARE void	gaiaOpenShpWrite (gaiaShapefilePtr shp, const char *path, int shape, gaiaDbfListPtr list, const char *charFrom, const char *charTo)
	Open a Shapefile in read mode. More...
GAIAGEO_DECLARE int	gaiaReadShpEntity (gaiaShapefilePtr shp, int current_row, int srid)
	Reads a feature from a Shapefile object. More...
GAIAGEO_DECLARE void	gaiaShpAnalyze (gaiaShapefilePtr shp)
	Prescans a Shapefile object gathering informations. More...
GAIAGEO_DECLARE int	gaiaWriteShpEntity (gaiaShapefilePtr shp, gaiaDbfListPtr entity)
	Writes a feature into a Shapefile object. More...
GAIAGEO_DECLARE void	gaiaFlushShpHeaders (gaiaShapefilePtr shp)
	Writes into an output Shapefile any required header / footer. More...
GAIAGEO_DECLARE gaiaDbfPtr	gaiaAllocDbf (void)
	Allocates a new DBF File object. More...
GAIAGEO_DECLARE void	gaiaFreeDbf (gaiaDbfPtr dbf)
	Destroys a DBF File object. More...
GAIAGEO_DECLARE void	gaiaOpenDbfRead (gaiaDbfPtr dbf, const char *path, const char *charFrom, const char *charTo)
	Open a DBF File in read mode. More...
GAIAGEO_DECLARE void	gaiaOpenDbfWrite (gaiaDbfPtr dbf, const char *path, const char *charFrom, const char *charTo)
	Open a DBF File in write mode. More...
GAIAGEO_DECLARE int	gaiaReadDbfEntity (gaiaDbfPtr dbf, int current_row, int *deleted)
	Reads a record from a DBF File object. More...
GAIAGEO_DECLARE int	gaiaWriteDbfEntity (gaiaDbfPtr dbf, gaiaDbfListPtr entity)
	Writes a record into a DBF File object. More...
GAIAGEO_DECLARE void	gaiaFlushDbfHeader (gaiaDbfPtr dbf)
	Writes into an output DBF File any required header / footer. More...
GAIAGEO_DECLARE gaiaTextReaderPtr	gaiaTextReaderAlloc (const char *path, char field_separator, char text_separator, char decimal_separator, int first_line_titles, const char *encoding)
	Creates a Text Reader object. More...
GAIAGEO_DECLARE void	gaiaTextReaderDestroy (gaiaTextReaderPtr reader)
	Destroys a Text Reader object. More...
GAIAGEO_DECLARE int	gaiaTextReaderParse (gaiaTextReaderPtr reader)
	Prescans the external file associated to a Text Reade object. More...
GAIAGEO_DECLARE int	gaiaTextReaderGetRow (gaiaTextReaderPtr reader, int row_num)
	Reads a line from a Text Reader object. More...
GAIAGEO_DECLARE int	gaiaTextReaderFetchField (gaiaTextReaderPtr reader, int field_num, int *type, const char **value)
	Retrieves an individual field value from the current Line. More...

Detailed Description

Geometry handling functions: formats.

Function Documentation

GAIAGEO_DECLARE gaiaDbfFieldPtr gaiaAddDbfField	(	gaiaDbfListPtr	list,
		char *	name,
		unsigned char	type,
		int	offset,
		unsigned char	length,
		unsigned char	decimals
	)

Inserts a further DBF Field object into a DBF List object.

Parameters

list	pointer to the DBF List object.
name	text string: DBF Field name.
type	identifier of the corresponding DBF data type.
offset	corresponding offset into the DBF I/O buffer.
length	max field length (in bytes).
decimals	precision: number of decimal digits.

Returns

the pointer to newly created DBF Field object.

See Also

gaiaAllocDbfField

Note

supported DBF data types are:

• 'C' text string [default]
• 'N' numeric
• 'D' date
• 'L' boolean

GAIAGEO_DECLARE gaiaDbfPtr gaiaAllocDbf

(

void

)

Allocates a new DBF File object.

Returns

the pointer to newly created DBF File object.

See Also

gaiaFreeDbf, gaiaOpenDbfRead, gaiaOpenDbfWrite, gaiaReadDbfEntity, gaiaWriteDbfEntity, gaiaFlushDbfHeader

Note

you are responsible to destroy (before or after) any allocated DBF File.
you should phisically open the DBF File in read or write mode before performing any actual I/O operation.

GAIAGEO_DECLARE gaiaDbfFieldPtr gaiaAllocDbfField	(	char *	name,
		unsigned char	type,
		int	offset,
		unsigned char	length,
		unsigned char	decimals
	)

Allocates a new DBF Field object.

Parameters

name	text string: DBF Field name.
type	identifier of the corresponding DBF data type.
offset	corresponding offset into the DBF I/O buffer.
length	max field length (in bytes).
decimals	precision: number of decimal digits.

Returns

the pointer to newly created DBF Field object.

See Also

gaiaFreeDbfField, gaiaCloneDbfField, gaiaFreeValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetDoubleValue, gaiaSetStrValue

Note

you are responsible to destroy (before or after) any allocated DBF Field, unless you've passed ownership to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.
supported DBF data types are:

• 'C' text string [default]
• 'N' numeric
• 'D' date
• 'L' boolean

GAIAGEO_DECLARE gaiaDbfListPtr gaiaAllocDbfList

(

void

)

Creates an initially empty DBF List object.

Returns

the pointer to newly allocated DBF List object: NULL on failure.

See Also

gaiaFreeDbfList, gaiaIsValidDbfList, gaiaResetDbfEntity, gaiaCloneDbfEntity, gaiaAddDbfField

Note

you are responsible to destroy (before or after) any allocated DBF List, unless you've passed ownership to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaShapefilePtr gaiaAllocShapefile

(

void

)

Allocates a new Shapefile object.

Returns

the pointer to newly created Shapefile object.

See Also

gaiaFreeShapefile, gaiaOpenShpRead, gaiaOpenShpWrite, gaiaReadShpEntity, gaiaShpAnalyze, gaiaWriteShpEntity, gaiaFlushShpHeaders

Note

you are responsible to destroy (before or after) any allocated Shapefile.
you should phisically open the Shapefile in read or write mode before performing any actual I/O operation.

GAIAGEO_DECLARE void gaiaAppendToOutBuffer	(	gaiaOutBufferPtr	buf,
		const char *	text
	)

Appends a text string at the end of Text output buffer.

Parameters

buf	pointer to gaiaOutBufferStruct structure.
text	the text string to be appended.

See Also

gaiaOutBufferInitialize, gaiaOutBufferReset

Note

You are required to initialize this structure before attempting any further operation: the dynamically growing Text buffer will be automatically allocated and/or extended as required.

GAIAGEO_DECLARE gaiaDbfListPtr gaiaCloneDbfEntity

(

gaiaDbfListPtr

org

)

Allocates a new DBF List object [duplicating an existing one].

Parameters

org	pointer to input DBF List object.

Returns

the pointer to newly created DBF List object.

See Also

gaiaCloneDbfField, gaiaCloneValue,

Note

the newly created object is an exact copy of the original one.
this including any currently set Field Value.

GAIAGEO_DECLARE gaiaDbfFieldPtr gaiaCloneDbfField

(

gaiaDbfFieldPtr

org

)

Allocates a new DBF Field object [duplicating an existing one].

Parameters

org	pointer to input DBF Field object.

Returns

the pointer to newly created DBF Field object.

See Also

gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField, gaiaFreeValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetDoubleValue, gaiaSetStrValue

Note

the newly created object is an exact copy of the original one [this including an evantual Field Value].

GAIAGEO_DECLARE gaiaValuePtr gaiaCloneValue

(

gaiaValuePtr

org

)

Allocates a new DBF Field Value object [duplicating an existing one].

Parameters

org	pointer to input DBF Field Value object.

Returns

the pointer to newly created DBF Field object.

See Also

gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField, gaiaCloneValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetDoubleValue, gaiaSetStrValue

Note

the newly created object is an exact copy of the original one.

GAIAGEO_DECLARE int gaiaEndianArch

(

void

)

Test CPU endianness.

Returns

0 if big-endian: any other value if little-endian

GAIAGEO_DECLARE int gaiaEwkbGetLinestring	(	gaiaGeomCollPtr	geom,
		unsigned char *	blob,
		int	offset,
		int	blob_size,
		int	endian,
		int	endian_arch,
		int	dims
	)

Attempts to decode a Point from within an EWKB binary buffer.

Parameters

geom	pointer to an existing Geometry object; if succesfull the parsed Linestring will be inserted into this Geometry
blob	pointer to EWKB input buffer
offset	the offset (in bytes) on the input buffer where the Point definition is expected to start.
blob_size	lenght (in bytes) of the input buffer.
endian	(boolean) states if the EWKB input buffer is little- or big-endian encode.
endian_arch	(boolean) states if the target CPU has a little- or big-endian architecture.
dims	dimensions: one of GAIA_XY, GAIA_XY_Z, GAIA_XY_M or GAIA_XY_Z_M

Returns

-1 on failure; otherwise the offset where the next object starts.

See Also

gaiaEwkbGetPoint, gaiaEwkbGetPolygon, gaiaEwkbGetMultiGeometry

Note

these functions are mainly intended for internal usage.

GAIAGEO_DECLARE int gaiaEwkbGetMultiGeometry	(	gaiaGeomCollPtr	geom,
		unsigned char *	blob,
		int	offset,
		int	blob_size,
		int	endian,
		int	endian_arch,
		int	dims
	)

Attempts to decode a MultiGeometry from within an EWKB binary buffer.

Parameters

geom	pointer to an existing Geometry object; if succesfull the parsed MultiGeometry will be inserted into this Geometry
blob	pointer to EWKB input buffer
offset	the offset (in bytes) on the input buffer where the Point definition is expected to start.
blob_size	lenght (in bytes) of the input buffer.
endian	(boolean) states if the EWKB input buffer is little- or big-endian encode.
endian_arch	(boolean) states if the target CPU has a little- or big-endian architecture.
dims	dimensions: one of GAIA_XY, GAIA_XY_Z, GAIA_XY_M or GAIA_XY_Z_M

Returns

-1 on failure; otherwise the offset where the next object starts.

See Also

gaiaEwkbGetPoint, gaiaEwkbGetLinestring, gaiaEwkbGetPolygon

Note

these functions are mainly intended for internal usage.

GAIAGEO_DECLARE int gaiaEwkbGetPoint	(	gaiaGeomCollPtr	geom,
		unsigned char *	blob,
		int	offset,
		int	blob_size,
		int	endian,
		int	endian_arch,
		int	dims
	)

Attempts to decode a Point from within an EWKB binary buffer.

Parameters

geom	pointer to an existing Geometry object; if succesfull the parsed Point will be inserted into this Geometry
blob	pointer to EWKB input buffer
offset	the offset (in bytes) on the input buffer where the Point definition is expected to start.
blob_size	lenght (in bytes) of the input buffer.
endian	(boolean) states if the EWKB input buffer is little- or big-endian encode.
endian_arch	(boolean) states if the target CPU has a little- or big-endian architecture.
dims	dimensions: one of GAIA_XY, GAIA_XY_Z, GAIA_XY_M or GAIA_XY_Z_M

Returns

-1 on failure; otherwise the offset where the next object starts.

See Also

gaiaEwkbGetLinestring, gaiaEwkbGetPolygon, gaiaEwkbGetMultiGeometry

Note

these functions are mainly intended for internal usage.

GAIAGEO_DECLARE int gaiaEwkbGetPolygon	(	gaiaGeomCollPtr	geom,
		unsigned char *	blob,
		int	offset,
		int	blob_size,
		int	endian,
		int	endian_arch,
		int	dims
	)

Attempts to decode a Polygon from within an EWKB binary buffer.

Parameters

geom	pointer to an existing Geometry object; if succesfull the parsed Polygon will be inserted into this Geometry
blob	pointer to EWKB input buffer
offset	the offset (in bytes) on the input buffer where the Point definition is expected to start.
blob_size	lenght (in bytes) of the input buffer.
endian	(boolean) states if the EWKB input buffer is little- or big-endian encode.
endian_arch	(boolean) states if the target CPU has a little- or big-endian architecture.
dims	dimensions: one of GAIA_XY, GAIA_XY_Z, GAIA_XY_M or GAIA_XY_Z_M

Returns

-1 on failure; otherwise the offset where the next object starts.

See Also

gaiaEwkbGetPoint, gaiaEwkbGetPolygon, gaiaEwkbGetMultiGeometry

GAIAGEO_DECLARE void gaiaExport16	(	unsigned char *	p,
		short	value,
		int	little_endian,
		int	little_endian_arch
	)

Export an INT-16 value in endian-aware fashion.

Parameters

p	endian-dependent representation (output buffer).
value	the internal value to be exported.
little_endian	0 if the output buffer has to be big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

See Also

gaiaEndianArch, gaiaImport16

Note

you are expected to pass an output buffer corresponding to an allocation size of (at least) 2 bytes.

GAIAGEO_DECLARE void gaiaExport32	(	unsigned char *	p,
		int	value,
		int	little_endian,
		int	little_endian_arch
	)

Export an INT-32 value in endian-aware fashion.

Parameters

p	endian-dependent representation (output buffer).
value	the internal value to be exported.
little_endian	0 if the output buffer has to be big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

See Also

gaiaEndianArch, gaiaImport32

Note

you are expected to pass an output buffer corresponding to an allocation size of (at least) 4 bytes.

GAIAGEO_DECLARE void gaiaExport64	(	unsigned char *	p,
		double	value,
		int	little_endian,
		int	little_endian_arch
	)

Export a DOUBLE value in endian-aware fashion.

Parameters

p	endian-dependent representation (output buffer).
value	the internal value to be exported.
little_endian	0 if the output buffer has to be big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

See Also

gaiaEndianArch, gaiaImport64

Note

you are expected to pass an output buffer corresponding to an allocation size of (at least) 8 bytes.

GAIAGEO_DECLARE void gaiaExportF32	(	unsigned char *	p,
		float	value,
		int	little_endian,
		int	little_endian_arch
	)

Export a FLOAT-32 value in endian-aware fashion.

Parameters

p	endian-dependent representation (output buffer).
value	the internal value to be exported.
little_endian	0 if the output buffer has to be big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

See Also

gaiaEndianArch, gaiaImportF32

Note

you are expected to pass an output buffer corresponding to an allocation size of (at least) 4 bytes.

GAIAGEO_DECLARE void gaiaExportI64	(	unsigned char *	p,
		sqlite3_int64	value,
		int	little_endian,
		int	little_endian_arch
	)

Export an INT-64 value in endian-aware fashion.

Parameters

p	endian-dependent representation (output buffer).
value	the internal value to be exported.
little_endian	0 if the output buffer has to be big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

See Also

gaiaEndianArch, gaiaImportI64

Note

you are expected to pass an output buffer corresponding to an allocation size of (at least) 8 bytes.

GAIAGEO_DECLARE void gaiaExportU32	(	unsigned char *	p,
		unsigned int	value,
		int	little_endian,
		int	little_endian_arch
	)

Export an UINT-32 value in endian-aware fashion.

Parameters

p	endian-dependent representation (output buffer).
value	the internal value to be exported.
little_endian	0 if the output buffer has to be big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

See Also

gaiaEndianArch, gaiaImportU32

Note

you are expected to pass an output buffer corresponding to an allocation size of (at least) 4 bytes.

GAIAGEO_DECLARE void gaiaFlushDbfHeader

(

gaiaDbfPtr

dbf

)

Writes into an output DBF File any required header / footer.

Parameters

dbf	pointer to the DBF File object.

See Also

gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfRead, gaiaOpenDbfWrite, gaiaReadDbfEntity, gaiaWriteDbfEntity

Note

forgetting to call gaiaFlushDbfHeader for any DBF File opened in write mode immediately before destroying the object, will surely cause severe file corruption.

GAIAGEO_DECLARE void gaiaFlushShpHeaders

(

gaiaShapefilePtr

shp

)

Writes into an output Shapefile any required header / footer.

Parameters

shp	pointer to the Shapefile object.

See Also

gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead, gaiaOpenShpWrite, gaiaReadShpEntity, gaiaShpAnalyze, gaiaWriteShpEntity

Note

forgetting to call gaiaFlushShpHeader for any Shapefile opened in write mode immediately before destroying the object, will surely cause severe file corruption.

GAIAGEO_DECLARE void gaiaFreeDbf

(

gaiaDbfPtr

dbf

)

Destroys a DBF File object.

Parameters

dbf	pointer to the DBF File object.

See Also

gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfWrite, gaiaReadDbfEntity, gaiaWriteDbfEntity, gaiaFlushDbfHeader

Note

destroying the Shapefile object will close any related file: anyway you a responsible to explicitly call gaiaFlushShpHeader before destroyng a Shapefile opened in write mode.

GAIAGEO_DECLARE void gaiaFreeDbfField

(

gaiaDbfFieldPtr

p

)

Destroys a DBF Field object.

Parameters

p	pointer to DBF Field object

See Also

gaiaAllocDbfField, gaiaCloneDbfField, gaiaCloneValue, gaiaFreeValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetDoubleValue, gaiaSetStrValue

GAIAGEO_DECLARE void gaiaFreeDbfList

(

gaiaDbfListPtr

list

)

Destroys a DBF List object.

Parameters

list	pointer to the DBF List object

See Also

gaiaAllocDbfList, gaiaIsValidDbfList, gaiaResetDbfEntity, gaiaCloneDbfEntity, gaiaAddDbfField

Note

attempting to destroy any DBF List object whose ownnership has already been transferred to some other (higher order) object is a serious error, and will easily cause severe memory corruption.

GAIAGEO_DECLARE void gaiaFreeShapefile

(

gaiaShapefilePtr

shp

)

Destroys a Shapefile object.

Parameters

shp	pointer to the Shapefile object.

See Also

gaiaAllocShapefile, gaiaOpenShpRead, gaiaOpenShpWrite, gaiaReadShpEntity, gaiaShpAnalyze, gaiaWriteShpEntity, gaiaFlushShpHeaders

Note

destroying the Shapefile object will close any related file: anyway you a responsible to explicitly call gaiaFlushShpHeader before destroyng a Shapefile opened in write mode.

GAIAGEO_DECLARE void gaiaFreeValue

(

gaiaValuePtr

p

)

Resets a DBF Field Value object to its initial empty state.

Parameters

p	pointer to DBF Field Value object

See Also

gaiaAllocDbfField, gaiaCloneDbfField, gaiaCloneValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetDoubleValue, gaiaSetStrValue, gaiaResetDbfEntity

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaFromEWKB

(

const unsigned char *

in_buffer

)

Creates a Geometry object from EWKB notation.

Parameters

in_buffer

pointer to EWKB buffer

Returns

the pointer to the newly created Geometry object: NULL on failure.

See Also

gaiaToWkb, gaiaToHexWkb, gaiaParseHexEWKB, gaiaToEWKB, gaiaEwkbGetPoint, gaiaEwkbGetLinestring, gaiaEwkbGetPolygon, gaiaEwkbGetMultiGeometry

Note

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaFromFgf	(	const unsigned char *	blob,
		unsigned int	size
	)

Creates a Geometry object from FGF notation.

Parameters

blob	pointer to FGF buffer
size	the BLOB's size (in bytes)

Returns

the pointer to the newly created Geometry object: NULL on failure.

See Also

gaiaToFgf

Note

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaFromSpatiaLiteBlobWkb	(	const unsigned char *	blob,
		unsigned int	size
	)

Creates a Geometry object from the corresponding BLOB-Geometry.

Parameters

blob	pointer to BLOB-Geometry
size	the BLOB's size

Returns

the pointer to the newly created Geometry object: NULL on failure

See Also

gaiaFreeGeomColl, gaiaToSpatiaLiteBlobWkb, gaiaToCompressedBlobWkb

Note

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

Examples:

demo1.c.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaFromWkb	(	const unsigned char *	blob,
		unsigned int	size
	)

Creates a Geometry object from WKB notation.

Parameters

blob	pointer to WKB buffer
size	the BLOB's size (in bytes)

Returns

the pointer to the newly created Geometry object: NULL on failure.

See Also

gaiaToWkb, gaiaToHexWkb, gaiaFromEWKB, gaiaToEWKB

Note

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE short gaiaImport16	(	const unsigned char *	p,
		int	little_endian,
		int	little_endian_arch
	)

Import an INT-16 value in endian-aware fashion.

Parameters

p	endian-dependent representation (input buffer).
little_endian	0 if the input buffer is big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

Returns

the internal SHORT value

See Also

gaiaEndianArch, gaiaExport16

Note

you are expected to pass an input buffer corresponding to an allocation size of (at least) 2 bytes.

GAIAGEO_DECLARE int gaiaImport32	(	const unsigned char *	p,
		int	little_endian,
		int	little_endian_arch
	)

Import an INT-32 value in endian-aware fashion.

Parameters

p	endian-dependent representation (input buffer).
little_endian	0 if the input buffer is big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

Returns

the internal INT value

See Also

gaiaEndianArch, gaiaExport32

Note

you are expected to pass an input buffer corresponding to an allocation size of (at least) 4 bytes.

GAIAGEO_DECLARE double gaiaImport64	(	const unsigned char *	p,
		int	little_endian,
		int	little_endian_arch
	)

Import an DOUBLE-64 in endian-aware fashion.

Parameters

p	endian-dependent representation (input buffer).
little_endian	0 if the input buffer is big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

Returns

the internal DOUBLE value

See Also

gaiaEndianArch, gaiaExport64

Note

you are expected to pass an input buffer corresponding to an allocation size of (at least) 8 bytes.

GAIAGEO_DECLARE float gaiaImportF32	(	const unsigned char *	p,
		int	little_endian,
		int	little_endian_arch
	)

Import a FLOAT-32 value in endian-aware fashion.

Parameters

p	endian-dependent representation (input buffer).
little_endian	0 if the input buffer is big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

Returns

the internal FLOAT value

See Also

gaiaEndianArch, gaiaExportF32

Note

you are expected to pass an input buffer corresponding to an allocation size of (at least) 4 bytes.

GAIAGEO_DECLARE sqlite3_int64 gaiaImportI64	(	const unsigned char *	p,
		int	little_endian,
		int	little_endian_arch
	)

Import an INT-64 in endian-aware fashion.

Parameters

p	endian-dependent representation (input buffer).
little_endian	0 if the input buffer is big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

Returns

the internal INT-64 value

See Also

gaiaEndianArch, gaiaExportI64

Note

you are expected to pass an input buffer corresponding to an allocation size of (at least) 8 bytes.

GAIAGEO_DECLARE unsigned int gaiaImportU32	(	const unsigned char *	p,
		int	little_endian,
		int	little_endian_arch
	)

Import an UINT-32 value in endian-aware fashion.

Parameters

p	endian-dependent representation (input buffer).
little_endian	0 if the input buffer is big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

Returns

the internal UINT value

See Also

gaiaEndianArch, gaiaExportU32

Note

you are expected to pass an input buffer corresponding to an allocation size of (at least) 4 bytes.

GAIAGEO_DECLARE int gaiaIsValidDbfList

(

gaiaDbfListPtr

list

)

Checks a DBF List object for validity.

Parameters

list	pointer to the DBF List object.

Returns

0 if not valid: any other value if valid.

See Also

gaiaAllocDbfList, gaiaFreeDbfList, gaiaIsValidDbfList, gaiaResetDbfEntity, gaiaCloneDbfEntity, gaiaAddDbfField

GAIAGEO_DECLARE void gaiaMakeLine	(	gaiaGeomCollPtr	geom1,
		gaiaGeomCollPtr	geom2,
		unsigned char **	result,
		int *	size
	)

Creates a BLOB-Geometry representing a Segment (2-Points Linestring)

Parameters

geom1	pointer to first Geometry object (expected to represent a Point).
geom2	pointer to second Geometry object (expected to represent a Point).
result	on completion will containt a pointer to BLOB-Geometry: NULL on failure.
size	on completion this variable will contain the BLOB's size (in bytes)

See Also

gaiaFromSpatiaLiteBlobWkb

Note

the BLOB buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

GAIAGEO_DECLARE void gaiaMakePoint	(	double	x,
		double	y,
		int	srid,
		unsigned char **	result,
		int *	size
	)

Creates a BLOB-Geometry representing a Point.

Parameters

x	Point X coordinate.
y	Point Y coordinate.
srid	the SRID to be set for the Point.
result	on completion will containt a pointer to BLOB-Geometry: NULL on failure.
size	on completion this variable will contain the BLOB's size (in bytes)

See Also

gaiaFromSpatiaLiteBlobWkb

Note

the BLOB buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

GAIAGEO_DECLARE void gaiaMakePointM	(	double	x,
		double	y,
		double	m,
		int	srid,
		unsigned char **	result,
		int *	size
	)

Creates a BLOB-Geometry representing a PointM.

Parameters

x	Point X coordinate.
y	Point Y coordinate.
m	Point M coordinate.
srid	the SRID to be set for the Point.
result	on completion will containt a pointer to BLOB-Geometry: NULL on failure.
size	on completion this variable will contain the BLOB's size (in bytes)

See Also

gaiaFromSpatiaLiteBlobWkb

Note

the BLOB buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

GAIAGEO_DECLARE void gaiaMakePointZ	(	double	x,
		double	y,
		double	z,
		int	srid,
		unsigned char **	result,
		int *	size
	)

Creates a BLOB-Geometry representing a PointZ.

Parameters

x	Point X coordinate.
y	Point Y coordinate.
z	Point Z coordinate.
srid	the SRID to be set for the Point.
result	on completion will containt a pointer to BLOB-Geometry: NULL on failure.
size	on completion this variable will contain the BLOB's size (in bytes)

See Also

gaiaFromSpatiaLiteBlobWkb

Note

the BLOB buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

GAIAGEO_DECLARE void gaiaMakePointZM	(	double	x,
		double	y,
		double	z,
		double	m,
		int	srid,
		unsigned char **	result,
		int *	size
	)

Creates a BLOB-Geometry representing a PointZM.

Parameters

x	Point X coordinate.
y	Point Y coordinate.
z	Point Z coordinate.
m	Point M coordinate.
srid	the SRID to be set for the Point.
result	on completion will containt a pointer to BLOB-Geometry: NULL on failure.
size	on completion this variable will contain the BLOB's size (in bytes)

See Also

gaiaFromSpatiaLiteBlobWkb

Note

the BLOB buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

GAIAGEO_DECLARE void gaiaOpenDbfRead	(	gaiaDbfPtr	dbf,
		const char *	path,
		const char *	charFrom,
		const char *	charTo
	)

Open a DBF File in read mode.

Parameters

dbf	pointer to the DBF File object.
path	pathname to the corresponding file-system file.
charFrom	GNU ICONV name identifying the input charset encoding.
charTo	GNU ICONV name identifying the output charset encoding.

See Also

gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfWrite, gaiaReadDbfEntity, gaiaWriteDbfEntity, gaiaFlushDbfHeader

Note

on failure the object member Valid will be set to 0; and the object member LastError will contain the appropriate error message.

GAIAGEO_DECLARE void gaiaOpenDbfWrite	(	gaiaDbfPtr	dbf,
		const char *	path,
		const char *	charFrom,
		const char *	charTo
	)

Open a DBF File in write mode.

Parameters

dbf	pointer to the DBF File object.
path	pathname to the corresponding file-system file.
charFrom	GNU ICONV name identifying the input charset encoding.
charTo	GNU ICONV name identifying the output charset encoding.

See Also

gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfRead, gaiaReadDbfEntity, gaiaWriteDbfEntity, gaiaFlushDbfHeader

Note

on failure the object member Valid will be set to 0; and the object member LastError will contain the appropriate error message.

GAIAGEO_DECLARE void gaiaOpenShpRead	(	gaiaShapefilePtr	shp,
		const char *	path,
		const char *	charFrom,
		const char *	charTo
	)

Open a Shapefile in read mode.

Parameters

shp	pointer to the Shapefile object.
path	abstract pathname to the corresponding file-system files.
charFrom	GNU ICONV name identifying the input charset encoding.
charTo	GNU ICONV name identifying the output charset encoding.

See Also

gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpWrite, gaiaReadShpEntity, gaiaShpAnalyze, gaiaWriteShpEntity, gaiaFlushShpHeaders

Note

on failure the object member Valid will be set to 0; and the object member LastError will contain the appropriate error message.
the abstract pathname should not contain any suffix at all.

GAIAGEO_DECLARE void gaiaOpenShpWrite	(	gaiaShapefilePtr	shp,
		const char *	path,
		int	shape,
		gaiaDbfListPtr	list,
		const char *	charFrom,
		const char *	charTo
	)

Open a Shapefile in read mode.

Parameters

shp	pointer to the Shapefile object.
path	abstract pathname to the corresponding file-system files.
shape	the SHAPE code; expected to be one of GAIA_SHP_POINT, GAIA_SHP_POLYLINE, GAIA_SHP_POLYGON, GAIA_SHP_MULTIPOINT, GAIA_SHP_POINTZ, GAIA_SHP_POLYLINEZ, GAIA_SHP_POLYGONZ, GAIA_SHP_MULTIPOINTZ, GAIA_SHP_POINTM, GAIA_SHP_POLYLINEM, GAIA_SHP_POLYGONM, GAIA_SHP_MULTIPOINTM
list	pointer to DBF List object representing the corresponding data attributes.
charFrom	GNU ICONV name identifying the input charset encoding.
charTo	GNU ICONV name identifying the output charset encoding.

See Also

gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead, gaiaReadShpEntity, gaiaShpAnalyze, gaiaWriteShpEntity, gaiaFlushShpHeaders

Note

on failure the object member Valid will be set to 0; and the object member LastError will contain the appropriate error message.
the abstract pathname should not contain any suffix at all.

GAIAGEO_DECLARE void gaiaOutBareKml	(	gaiaOutBufferPtr	out_buf,
		gaiaGeomCollPtr	geom,
		int	precision
	)

Encodes a Geometry object into KML notation.

Parameters

out_buf	pointer to dynamically growing Text buffer
geom	pointer to Geometry object
precision	decimal digits to be used for coordinates

See Also

gaiaParseKml, gaiaOutFullKml

Note

this function will export the simplest KML notation (no descriptions).

GAIAGEO_DECLARE void gaiaOutBufferInitialize

(

gaiaOutBufferPtr

buf

)

Initializes a dynamically growing Text output buffer.

Parameters

buf	pointer to gaiaOutBufferStruct structure

See Also

gaiaOutBufferReset, gaiaAppendToOutBuffer

Note

Text notations representing Geometry objects may easily require a huge storage amount: the gaiaOutBufferStruct automatically supports a dynamically growing output buffer.
You are required to initialize this structure before attempting any further operation; and you are responsible to cleanup any related memory allocation when it's any longer required.

Examples:

demo2.c.

GAIAGEO_DECLARE void gaiaOutBufferReset

(

gaiaOutBufferPtr

buf

)

Resets a dynamically growing Text output buffer to its initial (empty) state.

Parameters

buf	pointer to gaiaOutBufferStruct structure

See Also

gaiaOutBufferInitialize, gaiaAppendToOutBuffer

Note

You are required to initialize this structure before attempting any further operation: this function will release any related memory allocation.

Examples:

demo2.c.

GAIAGEO_DECLARE void gaiaOutFullKml	(	gaiaOutBufferPtr	out_buf,
		const char *	name,
		const char *	desc,
		gaiaGeomCollPtr	geom,
		int	precision
	)

Encodes a Geometry object into KML notation.

Parameters

out_buf	pointer to dynamically growing Text buffer
name	text string to be set as KML name
desc	text string to se set as KML description
geom	pointer to Geometry object
precision	decimal digits to be used for coordinates

See Also

gaiaParseKml, gaiaOutBareKml

Note

this function will export the simplest KML notation (no descriptions).

GAIAGEO_DECLARE void gaiaOutGeoJSON	(	gaiaOutBufferPtr	out_buf,
		gaiaGeomCollPtr	geom,
		int	precision,
		int	options
	)

Encodes a Geometry object into GeoJSON notation.

Parameters

out_buf	pointer to dynamically growing Text buffer
geom	pointer to Geometry object
precision	decimal digits to be used for coordinates
options	GeoJSON specific options

See Also

gaiaParseGeoJSON

Note

options can assume the following values:

• 1 = BBOX, no CRS
• 2 = no BBOX, short form CRS
• 3 = BBOX, short form CRS
• 4 = no BBOX, long form CRS
• 5 = BBOX, long form CRS
• any other value: no BBOX and no CRS

GAIAGEO_DECLARE void gaiaOutGml	(	gaiaOutBufferPtr	out_buf,
		int	version,
		int	precision,
		gaiaGeomCollPtr	geom
	)

Encodes a Geometry object into GML notation.

Parameters

out_buf	pointer to dynamically growing Text buffer
version	GML version
precision	decimal digits to be used for coordinates
geom	pointer to Geometry object

See Also

gaiaParseGml

Note

if version is set to 3, then GMLv3 will be used; in any other case GMLv2 will be assumed by default.

GAIAGEO_DECLARE void gaiaOutLinestringZ	(	gaiaOutBufferPtr	out_buf,
		gaiaLinestringPtr	linestring
	)

Encodes a WKT 3D Linestring [XYZ].

Parameters

out_buf	pointer to dynamically growing Text buffer
linestring	pointer to Linestring object

See Also

gaiaOutPointZ, gaiaOutPolygonZ

Remarks

mainly intended for internal usage.

GAIAGEO_DECLARE void gaiaOutPointZ	(	gaiaOutBufferPtr	out_buf,
		gaiaPointPtr	point
	)

Encodes a WKT 3D Point [XYZ].

Parameters

out_buf	pointer to dynamically growing Text buffer
point	pointer to Point object

See Also

gaiaOutLinestringZ, gaiaOutPolygonZ

Remarks

mainly intended for internal usage.

GAIAGEO_DECLARE void gaiaOutPolygonZ	(	gaiaOutBufferPtr	out_buf,
		gaiaPolygonPtr	polygon
	)

Encodes a WKT 3D Polygon [XYZ].

Parameters

out_buf	pointer to dynamically growing Text buffer
polygon	pointer to Point object

See Also

gaiaOutPointZ, gaiaOutLinestringZ

Remarks

mainly intended for internal usage.

GAIAGEO_DECLARE void gaiaOutSvg	(	gaiaOutBufferPtr	out_buf,
		gaiaGeomCollPtr	geom,
		int	relative,
		int	precision
	)

Encodes a Geometry object into SVG notation.

Parameters

out_buf	pointer to dynamically growing Text buffer
geom	pointer to Geometry object
relative	flag: relative or absolute coordinates
precision	decimal digits to be used for coordinates

Note

if relative is set to 1, then SVG relative coords will be used: in any other case SVG absolute coords will be assumed by default.

GAIAGEO_DECLARE void gaiaOutWkt	(	gaiaOutBufferPtr	out_buf,
		gaiaGeomCollPtr	geom
	)

Encodes a Geometry object into WKT notation.

Parameters

out_buf	pointer to dynamically growing Text buffer
geom	pointer to Geometry object

See Also

gaiaParseWkt, gaiaOutWktStrict, gaiaParseEWKT, gaiaToEWKT

Note

this function will apply 3D WKT encoding as internally intended by SpatiaLite: not necessarily intended by other OGC-like implementations.
Anyway, 2D WKT is surely standard and safely interoperable.

Examples:

demo2.c.

GAIAGEO_DECLARE void gaiaOutWktStrict	(	gaiaOutBufferPtr	out_buf,
		gaiaGeomCollPtr	geom,
		int	precision
	)

Encodes a Geometry object into strict 2D WKT notation.

Parameters

out_buf	pointer to dynamically growing Text buffer
geom	pointer to Geometry object
precision	decimal digits to be used for coordinates

See Also

gaiaParseWkt, gaiaOutWkt, gaiaParseEWKT, gaiaToEWKT

Note

this function will apply strict 2D WKT encoding, so to be surely standard and safely interoperable.
Dimensions will be automatically casted to 2D [XY] when required.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaParseEWKT

(

const unsigned char *

in_buffer

)

Creates a Geometry object from EWKT notation.

Parameters

in_buffer

pointer to EWKT buffer

Returns

the pointer to the newly created Geometry object: NULL on failure

See Also

gaiaParseWkt, gaiaOutWkt, gaiaOutWktStrict, gaiaToEWKT

Note

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaParseGeoJSON

(

const unsigned char *

in_buffer

)

Creates a Geometry object from GeoJSON notation.

Parameters

in_buffer

pointer to GeoJSON buffer

Returns

the pointer to the newly created Geometry object: NULL on failure

See Also

gaiaOutGeoJSON

Note

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaParseGml	(	const unsigned char *	in_buffer,
		sqlite3 *	sqlite_handle
	)

Creates a Geometry object from GML notation.

Parameters

in_buffer	pointer to GML buffer
sqlite_handle	handle to current DB connection

Returns

the pointer to the newly created Geometry object: NULL on failure

See Also

gaiaParseGml_r, gaiaOutGml

Note

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.
not reentrant and thread unsafe.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaParseGml_r	(	const void *	p_cache,
		const unsigned char *	in_buffer,
		sqlite3 *	sqlite_handle
	)

Creates a Geometry object from GML notation.

Parameters

p_cache	a memory pointer returned by spatialite_alloc_connection()
in_buffer	pointer to GML buffer
sqlite_handle	handle to current DB connection

Returns

the pointer to the newly created Geometry object: NULL on failure

See Also

gaiaParseGml, gaiaOutGml

Note

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.
reentrant and thread-safe.

GAIAGEO_DECLARE unsigned char* gaiaParseHexEWKB	(	const unsigned char *	blob_hex,
		int *	blob_size
	)

Translates an EWKB notation from hexadecimal into binary.

Parameters

blob_hex	pointer to EWKB input buffer (hexadecimal text string)
blob_size	lenght (in bytes) of the input buffer; if succesfull will contain the lenght of the returned output buffer.

Returns

the pointer to the newly created EWKB binary buffer: NULL on failure.

See Also

gaiaToWkb, gaiaToHexWkb, gaiaFromEWKB, gaiaToEWKB

Note

you are responsible to destroy (before or after) any buffer allocated by gaiaParseHexEWKB()

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaParseKml

(

const unsigned char *

in_buffer

)

Creates a Geometry object from KML notation.

Parameters

in_buffer

pointer to KML buffer

Returns

the pointer to the newly created Geometry object: NULL on failure

See Also

gaiaOutBareKml, gaiaOutFullKml

Note

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaParseWkt	(	const unsigned char *	in_buffer,
		short	type
	)

Creates a Geometry object from WKT notation.

Parameters

in_buffer	pointer to WKT buffer
type	the expected Geometry Class Type if actual type defined in WKT doesn't corresponds to this, an error will be raised.

Returns

the pointer to the newly created Geometry object: NULL on failure

See Also

gaiaOutWkt, gaiaOutWktStrict, gaiaParseEWKT, gaiaToEWKT

Note

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE int gaiaReadDbfEntity	(	gaiaDbfPtr	dbf,
		int	current_row,
		int *	deleted
	)

Reads a record from a DBF File object.

Parameters

dbf	pointer to the DBF File object.
current_row	the row number identifying the record to be read.
deleted	on completion this variable will contain 0 if the record just read is valid: any other value if the record just read is marked as logically deleted.

Returns

0 on failure: any other value on success.

See Also

gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfRead, gaiaOpenDbfWrite, gaiaFlushDbfHeader

Note

on completion the DBF File First member will point to the linked list containing the corresponding data attributes [both data formats and values].

Remarks

the DBF File object should be opened in read mode.

GAIAGEO_DECLARE int gaiaReadShpEntity	(	gaiaShapefilePtr	shp,
		int	current_row,
		int	srid
	)

Reads a feature from a Shapefile object.

Parameters

shp	pointer to the Shapefile object.
current_row	the row number identifying the feature to be read.
srid	feature's SRID

Returns

0 on failure: any other value on success.

See Also

gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead, gaiaOpenShpWrite, gaiaShpAnalyze, gaiaWriteShpEntity, gaiaFlushShpHeaders

Note

on completion the Shapefile's Dbf member will contain the feature read:

• the Dbf->Geometry member will contain the corresponding Geometry
• and the Dbf->First member will point to the linked list containing the corresponding data attributes [both data formats and values].

Remarks

the Shapefile object should be opened in read mode.

GAIAGEO_DECLARE void gaiaResetDbfEntity

(

gaiaDbfListPtr

list

)

Resets a DBF List object to its initial empty state.

Parameters

list	pointer to the DBF List object.

See Also

gaiaFreeValue

Note

any DBF Field associated to the List object will be reset to its initial empty state (i.e. no value at all).

GAIAGEO_DECLARE void gaiaSetDoubleValue	(	gaiaDbfFieldPtr	field,
		double	value
	)

Sets a DOUBLE current value for a DBF Field object.

Parameters

field	pointer to DBF Field object.
value	double value to be set.

See Also

gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField, gaiaFreeValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetStrValue

GAIAGEO_DECLARE void gaiaSetIntValue	(	gaiaDbfFieldPtr	field,
		sqlite3_int64	value
	)

Sets an INTEGER current value for a DBF Field object.

Parameters

field	pointer to DBF Field object.
value	integer value to be set.

See Also

gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField, gaiaFreeValue, gaiaSetNullValue, gaiaSetDoubleValue, gaiaSetStrValue

GAIAGEO_DECLARE void gaiaSetNullValue

(

gaiaDbfFieldPtr

field

)

Sets a NULL current value for a DBF Field object.

Parameters

field

pointer to DBF Field object

See Also

gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField, gaiaFreeValue, gaiaSetIntValue, gaiaSetDoubleValue, gaiaSetStrValue

GAIAGEO_DECLARE void gaiaSetStrValue	(	gaiaDbfFieldPtr	field,
		char *	str
	)

Sets a TEXT current value for a DBF Field object.

Parameters

field	pointer to DBF Field object.
str	text string value to be set.

See Also

gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField, gaiaFreeValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetDoubleValue

GAIAGEO_DECLARE void gaiaShpAnalyze

(

gaiaShapefilePtr

shp

)

Prescans a Shapefile object gathering informations.

Parameters

shp	pointer to the Shapefile object.

See Also

gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead, gaiaOpenShpWrite, gaiaReadShpEntity, gaiaWriteShpEntity, gaiaFlushShpHeaders

Note

on completion the Shapefile's EffectiveType will containt the Geometry type corresponding to features actually found.

Remarks

the Shapefile object should be opened in read mode.

GAIAGEO_DECLARE gaiaTextReaderPtr gaiaTextReaderAlloc	(	const char *	path,
		char	field_separator,
		char	text_separator,
		char	decimal_separator,
		int	first_line_titles,
		const char *	encoding
	)

Creates a Text Reader object.

Parameters

path	to the corresponding file-system file.
field_separator	the character acting as a separator between adjacent fields.
text_separator	the character used to quote text strings.
decimal_separator	the character used as a separator between integer and decimal digits for real numeric values.
first_line_titles	0 if the first line contains regular values: any other value if the first line contains column names.
encoding	GNU ICONV name identifying the input charset encoding.

Returns

the pointer to the newly created Text Reader object: NULL on failure

See Also

gaiaTextReaderDestroy, gaiaTextReaderParse, gaiaTextReaderGetRow, gaiaTextReaderFetchField

Note

you are responsible to destroy (before or after) any allocated Text Reader object.

GAIAGEO_DECLARE void gaiaTextReaderDestroy

(

gaiaTextReaderPtr

reader

)

Destroys a Text Reader object.

Parameters

reader

pointer to Text Reader object.

See Also

gaiaTextReaderAlloc, gaiaTextReaderParse, gaiaTextReaderGetRow, gaiaTextReaderFetchField

GAIAGEO_DECLARE int gaiaTextReaderFetchField	(	gaiaTextReaderPtr	reader,
		int	field_num,
		int *	type,
		const char **	value
	)

Retrieves an individual field value from the current Line.

Parameters

reader	pointer to Text Reader object.
field_num	relative field [aka column] index: first field has index 0.
type	on completion this variable will contain the value type.
value	on completion this variable will contain the current field value.

Returns

0 on failure: any other value on success.

See Also

gaiaTextReaderAlloc, gaiaTextReaderDestroy, gaiaTextReaderParse, gaiaTextReaderGetRow

GAIAGEO_DECLARE int gaiaTextReaderGetRow	(	gaiaTextReaderPtr	reader,
		int	row_num
	)

Reads a line from a Text Reader object.

Parameters

reader	pointer to Text Reader object.
row_num	the Line Number identifying the Line to be read.

Returns

0 on failure: any other value on success.

See Also

gaiaTextReaderAlloc, gaiaTextReaderDestroy, gaiaTextReaderParse, gaiaTextReaderFetchField

Note

this function will load the requested Line into the current buffer: you can then use gaiaTextReaderFetchField in order to retrieve any individual field [aka column] value.

GAIAGEO_DECLARE int gaiaTextReaderParse

(

gaiaTextReaderPtr

reader

)

Prescans the external file associated to a Text Reade object.

Parameters

reader

pointer to Text Reader object.

Returns

0 on failure: any other value on success.

See Also

gaiaTextReaderAlloc, gaiaTextReaderDestroy, gaiaTextReaderGetRow, gaiaTextReaderFetchField

Note

this preliminary step is required so to ensure:

• file consistency: checking expected formatting rules.
• identifying the number / type / name of fields [aka columns].
• identifying the actual number of lines within the file.

GAIAGEO_DECLARE void gaiaToCompressedBlobWkb	(	gaiaGeomCollPtr	geom,
		unsigned char **	result,
		int *	size
	)

Creates a Compressed BLOB-Geometry corresponding to a Geometry object.

Parameters

geom	pointer to the Geometry object.
result	on completion will containt a pointer to Compressed BLOB-Geometry: NULL on failure.
size	on completion this variable will contain the BLOB's size (in bytes)

See Also

gaiaFromSpatiaLiteBlobWkb, gaiaToSpatiaLiteBlobWkb

Note

this function will apply compression to any Linestring / Ring found within the Geometry to be encoded.
the returned BLOB buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

GAIAGEO_DECLARE void gaiaToEWKB	(	gaiaOutBufferPtr	out_buf,
		gaiaGeomCollPtr	geom
	)

Encodes a Geometry object into EWKB notation.

Parameters

out_buf	pointer to dynamically growing Text buffer
geom	pointer to Geometry object

See Also

gaiaFromWkb, gaiaToWkb, gaiaToHexWkb, gaiaFromEWKB, gaiaToEWKB

Note

this function will produce strictly conformat EWKB; you can safely use this for PostGIS data exchange.

GAIAGEO_DECLARE void gaiaToEWKT	(	gaiaOutBufferPtr	out_buf,
		gaiaGeomCollPtr	geom
	)

Encodes a Geometry object into EWKT notation.

Parameters

out_buf	pointer to dynamically growing Text buffer
geom	pointer to Geometry object

See Also

gaiaParseWkt, gaiaOutWkt, gaiaOutWktStrict, gaiaParseEWKT

Note

this function will apply PostGIS own EWKT encoding.

GAIAGEO_DECLARE void gaiaToFgf	(	gaiaGeomCollPtr	geom,
		unsigned char **	result,
		int *	size,
		int	coord_dims
	)

Encodes a Geometry object into FGF notation.

Parameters

geom	pointer to Geometry object
result	on completion will containt a pointer to the FGF buffer [BLOB]: NULL on failure.
size	on completion this variable will contain the BLOB's size (in bytes)
coord_dims	one of: GAIA_XY, GAIA_XY_Z, GAIA_XY_M, GAIA_XY_ZM

See Also

gaiaFromFgf

Note

the returned BLOB buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

GAIAGEO_DECLARE char* gaiaToHexWkb

(

gaiaGeomCollPtr

geom

)

Encodes a Geometry object into (hex) WKB notation.

Parameters

geom	pointer to Geometry object

Returns

the pointer to a text buffer containing WKB translated into plain hexadecimal: NULL on failure.

See Also

gaiaFromWkb, gaiaToWkb, gaiaFromEWKB, gaiaToEWKB

Note

the returned buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

GAIAGEO_DECLARE void gaiaToSpatiaLiteBlobWkb	(	gaiaGeomCollPtr	geom,
		unsigned char **	result,
		int *	size
	)

Creates a BLOB-Geometry corresponding to a Geometry object.

Parameters

geom	pointer to the Geometry object.
result	on completion will containt a pointer to BLOB-Geometry: NULL on failure.
size	on completion this variable will contain the BLOB's size (in bytes)

See Also

gaiaFromSpatiaLiteBlobWkb, gaiaToCompressedBlobWkb

Note

the BLOB buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

Examples:

demo3.c, and demo4.c.

GAIAGEO_DECLARE void gaiaToWkb	(	gaiaGeomCollPtr	geom,
		unsigned char **	result,
		int *	size
	)

Encodes a Geometry object into WKB notation.

Parameters

geom	pointer to Geometry object
result	on completion will containt a pointer to the WKB buffer [BLOB]: NULL on failure.
size	on completion this variable will contain the BLOB's size (in bytes)

See Also

gaiaFromWkb, gaiaToHexWkb, gaiaFromEWKB, gaiaToEWKB

Note

this function will apply 3D WKB encoding as internally intended by SpatiaLite: not necessarily intended by other OGC-like implementations.
Anyway, 2D WKB is surely standard and safely interoperable.
the returned BLOB buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

GAIAGEO_DECLARE int gaiaWriteDbfEntity	(	gaiaDbfPtr	dbf,
		gaiaDbfListPtr	entity
	)

Writes a record into a DBF File object.

Parameters

dbf	pointer to the DBF File object.
entity	pointer to DBF List object containing Fields and corresponding values.

Returns

0 on failure: any other value on success.

See Also

gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfRead, gaiaOpenDbfWrite, gaiaReadDbfEntity, gaiaFlushDbfHeader

Remarks

the DBF File object should be opened in write mode.

GAIAGEO_DECLARE int gaiaWriteShpEntity	(	gaiaShapefilePtr	shp,
		gaiaDbfListPtr	entity
	)

Writes a feature into a Shapefile object.

Parameters

shp	pointer to the Shapefile object.
entity	pointer to DBF List object containing both Geometry and Field values.

Returns

0 on failure: any other value on success.

See Also

gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead, gaiaOpenShpWrite, gaiaReadShpEntity, gaiaShpAnalyze, gaiaFlushShpHeaders

Remarks

the Shapefile object should be opened in write mode.