2057 lines
69 KiB
C
2057 lines
69 KiB
C
/*
|
|
gg_formats.h -- Gaia common support for geometries: formats
|
|
|
|
version 5.1.0, 2023 August 4
|
|
|
|
Author: Sandro Furieri a.furieri@lqt.it
|
|
|
|
------------------------------------------------------------------------------
|
|
|
|
Version: MPL 1.1/GPL 2.0/LGPL 2.1
|
|
|
|
The contents of this file are subject to the Mozilla Public License Version
|
|
1.1 (the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
http://www.mozilla.org/MPL/
|
|
|
|
Software distributed under the License is distributed on an "AS IS" basis,
|
|
WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
|
|
for the specific language governing rights and limitations under the
|
|
License.
|
|
|
|
The Original Code is the SpatiaLite library
|
|
|
|
The Initial Developer of the Original Code is Alessandro Furieri
|
|
|
|
Portions created by the Initial Developer are Copyright (C) 2008-2023
|
|
the Initial Developer. All Rights Reserved.
|
|
|
|
Contributor(s):
|
|
Klaus Foerster klaus.foerster@svg.cc
|
|
|
|
Alternatively, the contents of this file may be used under the terms of
|
|
either the GNU General Public License Version 2 or later (the "GPL"), or
|
|
the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
|
|
in which case the provisions of the GPL or the LGPL are applicable instead
|
|
of those above. If you wish to allow use of your version of this file only
|
|
under the terms of either the GPL or the LGPL, and not to allow others to
|
|
use your version of this file under the terms of the MPL, indicate your
|
|
decision by deleting the provisions above and replace them with the notice
|
|
and other provisions required by the GPL or the LGPL. If you do not delete
|
|
the provisions above, a recipient may use your version of this file under
|
|
the terms of any one of the MPL, the GPL or the LGPL.
|
|
|
|
*/
|
|
|
|
|
|
/**
|
|
\file gg_formats.h
|
|
|
|
Geometry handling functions: formats
|
|
*/
|
|
|
|
#ifndef _GG_FORMATS_H
|
|
#ifndef DOXYGEN_SHOULD_SKIP_THIS
|
|
#define _GG_FORMATS_H
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
extern "C"
|
|
{
|
|
#endif
|
|
|
|
/* function prototypes */
|
|
|
|
/**
|
|
Test CPU endianness
|
|
|
|
\return 0 if big-endian: any other value if little-endian
|
|
*/
|
|
GAIAGEO_DECLARE int gaiaEndianArch (void);
|
|
|
|
/**
|
|
Import an INT-16 value in endian-aware fashion
|
|
|
|
\param p endian-dependent representation (input buffer).
|
|
\param little_endian 0 if the input buffer is big-endian: any other value
|
|
for little-endian.
|
|
\param little_endian_arch the value returned by gaiaEndianArch()
|
|
|
|
\return the internal SHORT value
|
|
|
|
\sa gaiaEndianArch, gaiaExport16
|
|
|
|
\note you are expected to pass an input buffer corresponding to an
|
|
allocation size of (at least) 2 bytes.
|
|
*/
|
|
GAIAGEO_DECLARE short gaiaImport16 (const unsigned char *p,
|
|
int little_endian,
|
|
int little_endian_arch);
|
|
|
|
/**
|
|
Import an INT-32 value in endian-aware fashion
|
|
|
|
\param p endian-dependent representation (input buffer).
|
|
\param little_endian 0 if the input buffer is big-endian: any other value
|
|
for little-endian.
|
|
\param little_endian_arch the value returned by gaiaEndianArch()
|
|
|
|
\return the internal INT value
|
|
|
|
\sa gaiaEndianArch, gaiaExport32
|
|
|
|
\note you are expected to pass an input buffer corresponding to an
|
|
allocation size of (at least) 4 bytes.
|
|
*/
|
|
GAIAGEO_DECLARE int gaiaImport32 (const unsigned char *p,
|
|
int little_endian,
|
|
int little_endian_arch);
|
|
|
|
/**
|
|
Import an UINT-32 value in endian-aware fashion
|
|
|
|
\param p endian-dependent representation (input buffer).
|
|
\param little_endian 0 if the input buffer is big-endian: any other value
|
|
for little-endian.
|
|
\param little_endian_arch the value returned by gaiaEndianArch()
|
|
|
|
\return the internal UINT value
|
|
|
|
\sa gaiaEndianArch, gaiaExportU32
|
|
|
|
\note you are expected to pass an input buffer corresponding to an
|
|
allocation size of (at least) 4 bytes.
|
|
*/
|
|
GAIAGEO_DECLARE unsigned int gaiaImportU32 (const unsigned char *p,
|
|
int little_endian,
|
|
int little_endian_arch);
|
|
|
|
/**
|
|
Import a FLOAT-32 value in endian-aware fashion
|
|
|
|
\param p endian-dependent representation (input buffer).
|
|
\param little_endian 0 if the input buffer is big-endian: any other value
|
|
for little-endian.
|
|
\param little_endian_arch the value returned by gaiaEndianArch()
|
|
|
|
\return the internal FLOAT value
|
|
|
|
\sa gaiaEndianArch, gaiaExportF32
|
|
|
|
\note you are expected to pass an input buffer corresponding to an
|
|
allocation size of (at least) 4 bytes.
|
|
*/
|
|
GAIAGEO_DECLARE float gaiaImportF32 (const unsigned char *p,
|
|
int little_endian,
|
|
int little_endian_arch);
|
|
|
|
/**
|
|
Import an DOUBLE-64 in endian-aware fashion
|
|
|
|
\param p endian-dependent representation (input buffer).
|
|
\param little_endian 0 if the input buffer is big-endian: any other value
|
|
for little-endian.
|
|
\param little_endian_arch the value returned by gaiaEndianArch()
|
|
|
|
\return the internal DOUBLE value
|
|
|
|
\sa gaiaEndianArch, gaiaExport64
|
|
|
|
\note you are expected to pass an input buffer corresponding to an
|
|
allocation size of (at least) 8 bytes.
|
|
*/
|
|
GAIAGEO_DECLARE double gaiaImport64 (const unsigned char *p,
|
|
int little_endian,
|
|
int little_endian_arch);
|
|
|
|
/**
|
|
Import an INT-64 in endian-aware fashion
|
|
|
|
\param p endian-dependent representation (input buffer).
|
|
\param little_endian 0 if the input buffer is big-endian: any other value
|
|
for little-endian.
|
|
\param little_endian_arch the value returned by gaiaEndianArch()
|
|
|
|
\return the internal INT-64 value
|
|
|
|
\sa gaiaEndianArch, gaiaExportI64
|
|
|
|
\note you are expected to pass an input buffer corresponding to an
|
|
allocation size of (at least) 8 bytes.
|
|
*/
|
|
GAIAGEO_DECLARE sqlite3_int64 gaiaImportI64 (const unsigned char *p,
|
|
int little_endian,
|
|
int little_endian_arch);
|
|
|
|
/**
|
|
Export an INT-16 value in endian-aware fashion
|
|
|
|
\param p endian-dependent representation (output buffer).
|
|
\param value the internal value to be exported.
|
|
\param little_endian 0 if the output buffer has to be big-endian: any other value
|
|
for little-endian.
|
|
\param little_endian_arch the value returned by gaiaEndianArch()
|
|
|
|
\sa gaiaEndianArch, gaiaImport16
|
|
|
|
\note you are expected to pass an output buffer corresponding to an
|
|
allocation size of (at least) 2 bytes.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaExport16 (unsigned char *p, short value,
|
|
int little_endian,
|
|
int little_endian_arch);
|
|
|
|
/**
|
|
Export an INT-32 value in endian-aware fashion
|
|
|
|
\param p endian-dependent representation (output buffer).
|
|
\param value the internal value to be exported.
|
|
\param little_endian 0 if the output buffer has to be big-endian: any other value
|
|
for little-endian.
|
|
\param little_endian_arch the value returned by gaiaEndianArch()
|
|
|
|
\sa gaiaEndianArch, gaiaImport32
|
|
|
|
\note you are expected to pass an output buffer corresponding to an
|
|
allocation size of (at least) 4 bytes.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaExport32 (unsigned char *p, int value,
|
|
int little_endian,
|
|
int little_endian_arch);
|
|
|
|
/**
|
|
Export an UINT-32 value in endian-aware fashion
|
|
|
|
\param p endian-dependent representation (output buffer).
|
|
\param value the internal value to be exported.
|
|
\param little_endian 0 if the output buffer has to be big-endian: any other value
|
|
for little-endian.
|
|
\param little_endian_arch the value returned by gaiaEndianArch()
|
|
|
|
\sa gaiaEndianArch, gaiaImportU32
|
|
|
|
\note you are expected to pass an output buffer corresponding to an
|
|
allocation size of (at least) 4 bytes.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaExportU32 (unsigned char *p, unsigned int value,
|
|
int little_endian,
|
|
int little_endian_arch);
|
|
|
|
/**
|
|
Export a FLOAT-32 value in endian-aware fashion
|
|
|
|
\param p endian-dependent representation (output buffer).
|
|
\param value the internal value to be exported.
|
|
\param little_endian 0 if the output buffer has to be big-endian: any other value
|
|
for little-endian.
|
|
\param little_endian_arch the value returned by gaiaEndianArch()
|
|
|
|
\sa gaiaEndianArch, gaiaImportF32
|
|
|
|
\note you are expected to pass an output buffer corresponding to an
|
|
allocation size of (at least) 4 bytes.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaExportF32 (unsigned char *p, float value,
|
|
int little_endian,
|
|
int little_endian_arch);
|
|
|
|
/**
|
|
Export a DOUBLE value in endian-aware fashion
|
|
|
|
\param p endian-dependent representation (output buffer).
|
|
\param value the internal value to be exported.
|
|
\param little_endian 0 if the output buffer has to be big-endian: any other value
|
|
for little-endian.
|
|
\param little_endian_arch the value returned by gaiaEndianArch()
|
|
|
|
\sa gaiaEndianArch, gaiaImport64
|
|
|
|
\note you are expected to pass an output buffer corresponding to an
|
|
allocation size of (at least) 8 bytes.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaExport64 (unsigned char *p, double value,
|
|
int little_endian,
|
|
int little_endian_arch);
|
|
|
|
/**
|
|
Export an INT-64 value in endian-aware fashion
|
|
|
|
\param p endian-dependent representation (output buffer).
|
|
\param value the internal value to be exported.
|
|
\param little_endian 0 if the output buffer has to be big-endian: any other value
|
|
for little-endian.
|
|
\param little_endian_arch the value returned by gaiaEndianArch()
|
|
|
|
\sa gaiaEndianArch, gaiaImportI64
|
|
|
|
\note you are expected to pass an output buffer corresponding to an
|
|
allocation size of (at least) 8 bytes.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaExportI64 (unsigned char *p, sqlite3_int64 value,
|
|
int little_endian,
|
|
int little_endian_arch);
|
|
|
|
/**
|
|
Initializes a dynamically growing Text output buffer
|
|
|
|
\param buf pointer to gaiaOutBufferStruct structure
|
|
|
|
\sa gaiaOutBufferReset, gaiaAppendToOutBuffer
|
|
|
|
\note Text notations representing Geometry objects may easily require
|
|
a huge storage amount: the gaiaOutBufferStruct automatically supports
|
|
a dynamically growing output buffer.
|
|
\n 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.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutBufferInitialize (gaiaOutBufferPtr buf);
|
|
|
|
/**
|
|
Resets a dynamically growing Text output buffer to its initial (empty) state
|
|
|
|
\param buf pointer to gaiaOutBufferStruct structure
|
|
|
|
\sa gaiaOutBufferInitialize, gaiaAppendToOutBuffer
|
|
|
|
\note You are required to initialize this structure before attempting
|
|
any further operation:
|
|
this function will release any related memory allocation.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutBufferReset (gaiaOutBufferPtr buf);
|
|
|
|
/**
|
|
Appends a text string at the end of Text output buffer
|
|
|
|
\param buf pointer to gaiaOutBufferStruct structure.
|
|
\param text the text string to be appended.
|
|
|
|
\sa 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 void gaiaAppendToOutBuffer (gaiaOutBufferPtr buf,
|
|
const char *text);
|
|
|
|
/**
|
|
Creates a BLOB-Geometry representing a Point (BLOB-Geometry)
|
|
|
|
\param x Point X coordinate.
|
|
\param y Point Y coordinate.
|
|
\param srid the SRID to be set for the Point.
|
|
\param result on completion will containt a pointer to BLOB-Geometry:
|
|
NULL on failure.
|
|
\param size on completion this variable will contain the BLOB's size (in bytes)
|
|
|
|
\sa gaiaFromSpatiaLiteBlobWkb, gaiaMakePointEx
|
|
|
|
\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 PointZ (BLOB-Geometry)
|
|
|
|
\param x Point X coordinate.
|
|
\param y Point Y coordinate.
|
|
\param z Point Z coordinate.
|
|
\param srid the SRID to be set for the Point.
|
|
\param result on completion will containt a pointer to BLOB-Geometry:
|
|
NULL on failure.
|
|
\param size on completion this variable will contain the BLOB's size (in bytes)
|
|
|
|
\sa gaiaFromSpatiaLiteBlobWkb, gaiaMakePointZEx
|
|
|
|
\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 PointM (BLOB-Geometry)
|
|
|
|
\param x Point X coordinate.
|
|
\param y Point Y coordinate.
|
|
\param m Point M coordinate.
|
|
\param srid the SRID to be set for the Point.
|
|
\param result on completion will containt a pointer to BLOB-Geometry:
|
|
NULL on failure.
|
|
\param size on completion this variable will contain the BLOB's size (in bytes)
|
|
|
|
\sa gaiaFromSpatiaLiteBlobWkb, gaiaMakePointMEx
|
|
|
|
\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 PointZM (BLOB-Geometry)
|
|
|
|
\param x Point X coordinate.
|
|
\param y Point Y coordinate.
|
|
\param z Point Z coordinate.
|
|
\param m Point M coordinate.
|
|
\param srid the SRID to be set for the Point.
|
|
\param result on completion will containt a pointer to BLOB-Geometry:
|
|
NULL on failure.
|
|
\param size on completion this variable will contain the BLOB's size (in bytes)
|
|
|
|
\sa gaiaFromSpatiaLiteBlobWkb, gaiaMakePointZMEx
|
|
|
|
\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 Point (BLOB-Geometry or BLOB-TinyPoint)
|
|
|
|
\param tiny_point if set to TRUE the POINT Geometry will be encoded
|
|
by using the TinyPoint BLOB format.
|
|
\param x Point X coordinate.
|
|
\param y Point Y coordinate.
|
|
\param srid the SRID to be set for the Point.
|
|
\param result on completion will containt a pointer to BLOB-Geometry:
|
|
NULL on failure.
|
|
\param size on completion this variable will contain the BLOB's size (in bytes)
|
|
|
|
\sa gaiaFromSpatiaLiteBlobWkb, gaiaMakePoint
|
|
|
|
\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 gaiaMakePointEx (int tiny_point, double x, double y,
|
|
int srid, unsigned char **result,
|
|
int *size);
|
|
|
|
/**
|
|
Creates a BLOB-Geometry representing a PointZ (BLOB-Geometry or BLOB-TinyPoint)
|
|
|
|
\param tiny_point if set to TRUE the POINT Geometry will be encoded
|
|
by using the TinyPoint BLOB format.
|
|
\param x Point X coordinate.
|
|
\param y Point Y coordinate.
|
|
\param z Point Z coordinate.
|
|
\param srid the SRID to be set for the Point.
|
|
\param result on completion will containt a pointer to BLOB-Geometry:
|
|
NULL on failure.
|
|
\param size on completion this variable will contain the BLOB's size (in bytes)
|
|
|
|
\sa gaiaFromSpatiaLiteBlobWkb, gaiaMakePointZ
|
|
|
|
\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 gaiaMakePointZEx (int tiny_point, double x, double y,
|
|
double z, int srid,
|
|
unsigned char **result, int *size);
|
|
|
|
/**
|
|
Creates a BLOB-Geometry representing a PointM (BLOB-Geometry or BLOB-TinyPoint)
|
|
|
|
\param tiny_point if set to TRUE the POINT Geometry will be encoded
|
|
by using the TinyPoint BLOB format.
|
|
\param x Point X coordinate.
|
|
\param y Point Y coordinate.
|
|
\param m Point M coordinate.
|
|
\param srid the SRID to be set for the Point.
|
|
\param result on completion will containt a pointer to BLOB-Geometry:
|
|
NULL on failure.
|
|
\param size on completion this variable will contain the BLOB's size (in bytes)
|
|
|
|
\sa gaiaFromSpatiaLiteBlobWkb, gaiaMakePointM
|
|
|
|
\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 gaiaMakePointMEx (int tiny_point, double x, double y,
|
|
double m, int srid,
|
|
unsigned char **result, int *size);
|
|
|
|
/**
|
|
Creates a BLOB-Geometry representing a PointZM (BLOB-Geometry or BLOB-TinyPoint)
|
|
|
|
\param tiny_point if set to TRUE the POINT Geometry will be encoded
|
|
by using the TinyPoint BLOB format.
|
|
\param x Point X coordinate.
|
|
\param y Point Y coordinate.
|
|
\param z Point Z coordinate.
|
|
\param m Point M coordinate.
|
|
\param srid the SRID to be set for the Point.
|
|
\param result on completion will containt a pointer to BLOB-Geometry:
|
|
NULL on failure.
|
|
\param size on completion this variable will contain the BLOB's size (in bytes)
|
|
|
|
\sa gaiaFromSpatiaLiteBlobWkb, gaiaMakePointZM
|
|
|
|
\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 gaiaMakePointZMEx (int tiny_point, double x, double y,
|
|
double z, double m, int srid,
|
|
unsigned char **result, int *size);
|
|
|
|
/**
|
|
Creates a BLOB-Geometry representing a Segment (2-Points Linestring)
|
|
|
|
\param geom1 pointer to first Geometry object (expected to represent a Point).
|
|
\param geom2 pointer to second Geometry object (expected to represent a Point).
|
|
\param result on completion will containt a pointer to BLOB-Geometry:
|
|
NULL on failure.
|
|
\param size on completion this variable will contain the BLOB's size (in bytes)
|
|
|
|
\sa 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 gaiaMakeLine (gaiaGeomCollPtr geom1,
|
|
gaiaGeomCollPtr geom2,
|
|
unsigned char **result, int *size);
|
|
|
|
/**
|
|
Creates a Geometry object from the corresponding BLOB-Geometry
|
|
|
|
\param blob pointer to BLOB-Geometry
|
|
\param size the BLOB's size
|
|
|
|
\return the pointer to the newly created Geometry object: NULL on failure
|
|
|
|
\sa gaiaFreeGeomColl, gaiaToSpatiaLiteBlobWkb, gaiaToCompressedBlobWkb,
|
|
gaiaFromSpatiaLiteBlobWkbEx
|
|
|
|
\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
|
|
|
|
\param blob pointer to BLOB-Geometry
|
|
\param size the BLOB's size
|
|
\param gpkg_mode is set to TRUE will accept only GPKG Geometry-BLOBs
|
|
\param gpkg_amphibious is set to TRUE will indifferenctly accept
|
|
either SpatiaLite Geometry-BLOBs or GPKG Geometry-BLOBs
|
|
|
|
\return the pointer to the newly created Geometry object: NULL on failure
|
|
|
|
\sa 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.
|
|
*/
|
|
GAIAGEO_DECLARE gaiaGeomCollPtr gaiaFromSpatiaLiteBlobWkbEx (const
|
|
unsigned char
|
|
*blob,
|
|
unsigned int
|
|
size,
|
|
int
|
|
gpkg_mode,
|
|
int
|
|
gpkg_amphibious);
|
|
|
|
/**
|
|
Creates a BLOB-Geometry corresponding to a Geometry object
|
|
|
|
\param geom pointer to the Geometry object.
|
|
\param result on completion will containt a pointer to BLOB-Geometry:
|
|
NULL on failure.
|
|
\param size on completion this variable will contain the BLOB's size (in bytes)
|
|
|
|
\sa 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].
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaToSpatiaLiteBlobWkb (gaiaGeomCollPtr geom,
|
|
unsigned char **result,
|
|
int *size);
|
|
|
|
/**
|
|
Creates a BLOB-Geometry corresponding to a Geometry object
|
|
|
|
\param geom pointer to the Geometry object.
|
|
\param result on completion will containt a pointer to BLOB-Geometry:
|
|
NULL on failure.
|
|
\param size on completion this variable will contain the BLOB's size (in bytes)
|
|
\param gpkg_mode if set to TRUE will always return GPKG Geometry-BLOBs
|
|
|
|
\sa gaiaFromSpatiaLiteBlobWkb, gaiaToCompressedBlobWkb,
|
|
gaiaToSpatiaLiteBlobWkbEx2
|
|
|
|
\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 gaiaToSpatiaLiteBlobWkbEx (gaiaGeomCollPtr geom,
|
|
unsigned char **result,
|
|
int *size, int gpkg_mode);
|
|
|
|
/**
|
|
Creates a BLOB-Geometry corresponding to a Geometry object
|
|
|
|
\param geom pointer to the Geometry object.
|
|
\param result on completion will containt a pointer to BLOB-Geometry:
|
|
NULL on failure.
|
|
\param size on completion this variable will contain the BLOB's size (in bytes)
|
|
\param gpkg_mode if set to TRUE will always return GPKG Geometry-BLOBs
|
|
\param tiny_point if set to TRUE all POINT Geometries will be encoded
|
|
by using the TinyPoint BLOB format.
|
|
|
|
\sa gaiaFromSpatiaLiteBlobWkb, gaiaToCompressedBlobWkb,
|
|
gaiaToSpatiaLiteBlobWkbEx
|
|
|
|
\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 gaiaToSpatiaLiteBlobWkbEx2 (gaiaGeomCollPtr geom,
|
|
unsigned char **result,
|
|
int *size, int gpkg_mode,
|
|
int tiny_point);
|
|
|
|
/**
|
|
Creates a Compressed BLOB-Geometry corresponding to a Geometry object
|
|
|
|
\param geom pointer to the Geometry object.
|
|
\param result on completion will containt a pointer to Compressed BLOB-Geometry:
|
|
NULL on failure.
|
|
\param size on completion this variable will contain the BLOB's size (in bytes)
|
|
|
|
\sa gaiaFromSpatiaLiteBlobWkb, gaiaToSpatiaLiteBlobWkb
|
|
|
|
\note this function will apply compression to any Linestring / Ring found
|
|
within the Geometry to be encoded.
|
|
\n 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 gaiaToCompressedBlobWkb (gaiaGeomCollPtr geom,
|
|
unsigned char **result,
|
|
int *size);
|
|
|
|
/**
|
|
Creates a Geometry object from WKB notation
|
|
|
|
\param blob pointer to WKB buffer
|
|
\param size the BLOB's size (in bytes)
|
|
|
|
\return the pointer to the newly created Geometry object: NULL on failure.
|
|
|
|
\sa 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 gaiaGeomCollPtr gaiaFromWkb (const unsigned char *blob,
|
|
unsigned int size);
|
|
|
|
/**
|
|
Encodes a Geometry object into WKB notation
|
|
|
|
\param geom pointer to Geometry object
|
|
\param result on completion will containt a pointer to the WKB buffer [BLOB]:
|
|
NULL on failure.
|
|
\param size on completion this variable will contain the BLOB's size (in bytes)
|
|
|
|
\sa 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.
|
|
\n Anyway, 2D WKB is surely standard and safely interoperable.
|
|
\n 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 gaiaToWkb (gaiaGeomCollPtr geom,
|
|
unsigned char **result, int *size);
|
|
|
|
/**
|
|
Encodes a Geometry object into (hex) WKB notation
|
|
|
|
\param geom pointer to Geometry object
|
|
|
|
\return the pointer to a text buffer containing WKB translated into plain
|
|
hexadecimal: NULL on failure.
|
|
|
|
\sa 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 char *gaiaToHexWkb (gaiaGeomCollPtr geom);
|
|
|
|
/**
|
|
Encodes a Geometry object into EWKB notation
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param geom pointer to Geometry object
|
|
|
|
\sa 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 gaiaToEWKB (gaiaOutBufferPtr out_buf,
|
|
gaiaGeomCollPtr geom);
|
|
|
|
/**
|
|
Creates a Geometry object from EWKB notation
|
|
|
|
\param in_buffer pointer to EWKB buffer
|
|
|
|
\return the pointer to the newly created Geometry object: NULL on failure.
|
|
|
|
\sa 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 gaiaFromEWKB (const unsigned char
|
|
*in_buffer);
|
|
|
|
/**
|
|
Translates an EWKB notation from hexadecimal into binary
|
|
|
|
\param blob_hex pointer to EWKB input buffer (hexadecimal text string)
|
|
\param blob_size lenght (in bytes) of the input buffer; if succesfull will
|
|
contain the lenght of the returned output buffer.
|
|
|
|
\return the pointer to the newly created EWKB binary buffer: NULL on failure.
|
|
|
|
\sa gaiaToWkb, gaiaToHexWkb, gaiaFromEWKB, gaiaToEWKB
|
|
|
|
\note you are responsible to destroy (before or after) any buffer allocated by
|
|
gaiaParseHexEWKB()
|
|
*/
|
|
GAIAGEO_DECLARE unsigned char *gaiaParseHexEWKB (const unsigned char
|
|
*blob_hex, int *blob_size);
|
|
|
|
/**
|
|
Attempts to decode a Point from within an EWKB binary buffer
|
|
|
|
\param geom pointer to an existing Geometry object; if succesfull the parsed Point
|
|
will be inserted into this Geometry
|
|
\param blob pointer to EWKB input buffer
|
|
\param offset the offset (in bytes) on the input buffer where the Point definition is expected to start.
|
|
\param blob_size lenght (in bytes) of the input buffer.
|
|
\param endian (boolean) states if the EWKB input buffer is little- or big-endian encode.
|
|
\param endian_arch (boolean) states if the target CPU has a little- or big-endian architecture.
|
|
\param dims dimensions: one of GAIA_XY, GAIA_XY_Z, GAIA_XY_M or GAIA_XY_Z_M
|
|
|
|
\return -1 on failure; otherwise the offset where the next object starts.
|
|
|
|
\sa gaiaEwkbGetLinestring, gaiaEwkbGetPolygon, gaiaEwkbGetMultiGeometry
|
|
|
|
\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
|
|
|
|
\param geom pointer to an existing Geometry object; if succesfull the parsed Linestring
|
|
will be inserted into this Geometry
|
|
\param blob pointer to EWKB input buffer
|
|
\param offset the offset (in bytes) on the input buffer where the Point definition is expected to start.
|
|
\param blob_size lenght (in bytes) of the input buffer.
|
|
\param endian (boolean) states if the EWKB input buffer is little- or big-endian encode.
|
|
\param endian_arch (boolean) states if the target CPU has a little- or big-endian architecture.
|
|
\param dims dimensions: one of GAIA_XY, GAIA_XY_Z, GAIA_XY_M or GAIA_XY_Z_M
|
|
|
|
\return -1 on failure; otherwise the offset where the next object starts.
|
|
|
|
\sa gaiaEwkbGetPoint, gaiaEwkbGetPolygon, gaiaEwkbGetMultiGeometry
|
|
|
|
\note these functions are mainly intended for internal usage.
|
|
*/
|
|
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 Polygon from within an EWKB binary buffer
|
|
|
|
\param geom pointer to an existing Geometry object; if succesfull the parsed Polygon
|
|
will be inserted into this Geometry
|
|
\param blob pointer to EWKB input buffer
|
|
\param offset the offset (in bytes) on the input buffer where the Point definition is expected to start.
|
|
\param blob_size lenght (in bytes) of the input buffer.
|
|
\param endian (boolean) states if the EWKB input buffer is little- or big-endian encode.
|
|
\param endian_arch (boolean) states if the target CPU has a little- or big-endian architecture.
|
|
\param dims dimensions: one of GAIA_XY, GAIA_XY_Z, GAIA_XY_M or GAIA_XY_Z_M
|
|
|
|
\return -1 on failure; otherwise the offset where the next object starts.
|
|
|
|
\sa gaiaEwkbGetPoint, gaiaEwkbGetPolygon, gaiaEwkbGetMultiGeometry
|
|
*/
|
|
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 MultiGeometry from within an EWKB binary buffer
|
|
|
|
\param geom pointer to an existing Geometry object; if succesfull the parsed MultiGeometry
|
|
will be inserted into this Geometry
|
|
\param blob pointer to EWKB input buffer
|
|
\param offset the offset (in bytes) on the input buffer where the Point definition is expected to start.
|
|
\param blob_size lenght (in bytes) of the input buffer.
|
|
\param endian (boolean) states if the EWKB input buffer is little- or big-endian encode.
|
|
\param endian_arch (boolean) states if the target CPU has a little- or big-endian architecture.
|
|
\param dims dimensions: one of GAIA_XY, GAIA_XY_Z, GAIA_XY_M or GAIA_XY_Z_M
|
|
|
|
\return -1 on failure; otherwise the offset where the next object starts.
|
|
|
|
\sa gaiaEwkbGetPoint, gaiaEwkbGetLinestring, gaiaEwkbGetPolygon
|
|
|
|
\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);
|
|
|
|
/**
|
|
Creates a Geometry object from FGF notation
|
|
|
|
\param blob pointer to FGF buffer
|
|
\param size the BLOB's size (in bytes)
|
|
|
|
\return the pointer to the newly created Geometry object: NULL on failure.
|
|
|
|
\sa 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 gaiaFromFgf (const unsigned char *blob,
|
|
unsigned int size);
|
|
|
|
/**
|
|
Encodes a Geometry object into FGF notation
|
|
|
|
\param geom pointer to Geometry object
|
|
\param result on completion will containt a pointer to the FGF buffer [BLOB]:
|
|
NULL on failure.
|
|
\param size on completion this variable will contain the BLOB's size (in bytes)
|
|
\param coord_dims one of: GAIA_XY, GAIA_XY_Z, GAIA_XY_M, GAIA_XY_ZM
|
|
|
|
\sa 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 void gaiaToFgf (gaiaGeomCollPtr geom,
|
|
unsigned char **result, int *size,
|
|
int coord_dims);
|
|
|
|
/**
|
|
Creates a Geometry object from WKT notation
|
|
|
|
\param in_buffer pointer to WKT buffer
|
|
\param type the expected Geometry Class Type
|
|
\n if actual type defined in WKT doesn't corresponds to this, an error will
|
|
be raised.
|
|
|
|
\return the pointer to the newly created Geometry object: NULL on failure
|
|
|
|
\sa 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 gaiaGeomCollPtr gaiaParseWkt (const unsigned char
|
|
*in_buffer, short type);
|
|
|
|
/**
|
|
Encodes a Geometry object into WKT notation
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param geom pointer to Geometry object
|
|
|
|
\sa gaiaParseWkt, gaiaOutWktStrict, gaiaParseEWKT, gaiaToEWKT,
|
|
gaiaOutWktEx
|
|
|
|
\note this function will apply 3D WKT encoding as internally intended by
|
|
SpatiaLite: not necessarily intended by other OGC-like implementations.
|
|
\n Anyway, 2D WKT is surely standard and safely interoperable.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutWkt (gaiaOutBufferPtr out_buf,
|
|
gaiaGeomCollPtr geom);
|
|
|
|
/**
|
|
Encodes a Geometry object into WKT notation
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param geom pointer to Geometry object
|
|
\param precision decimal digits to be used for coordinates
|
|
|
|
\sa 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.
|
|
\n Anyway, 2D WKT is surely standard and safely interoperable.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutWktEx (gaiaOutBufferPtr out_buf,
|
|
gaiaGeomCollPtr geom, int precision);
|
|
|
|
/**
|
|
Encodes a Geometry object into strict 2D WKT notation
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param geom pointer to Geometry object
|
|
\param precision decimal digits to be used for coordinates
|
|
|
|
\sa gaiaParseWkt, gaiaOutWkt, gaiaParseEWKT, gaiaToEWKT
|
|
|
|
\note this function will apply strict 2D WKT encoding, so to be surely
|
|
standard and safely interoperable.
|
|
\n Dimensions will be automatically casted to 2D [XY] when required.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutWktStrict (gaiaOutBufferPtr out_buf,
|
|
gaiaGeomCollPtr geom, int precision);
|
|
|
|
/**
|
|
Creates a Geometry object from EWKT notation
|
|
|
|
\param in_buffer pointer to EWKT buffer
|
|
|
|
\return the pointer to the newly created Geometry object: NULL on failure
|
|
|
|
\sa 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 gaiaParseEWKT (const unsigned char
|
|
*in_buffer);
|
|
|
|
/**
|
|
Encodes a Geometry object into EWKT notation
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param geom pointer to Geometry object
|
|
|
|
\sa gaiaParseWkt, gaiaOutWkt, gaiaOutWktStrict, gaiaParseEWKT
|
|
|
|
\note this function will apply PostGIS own EWKT encoding.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaToEWKT (gaiaOutBufferPtr out_buf,
|
|
gaiaGeomCollPtr geom);
|
|
|
|
/**
|
|
Encodes a WKT 3D Point [XYZ]
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param point pointer to Point object
|
|
|
|
\sa gaiaOutLinestringZ, gaiaOutPolygonZ, gaiaOutPointZex
|
|
|
|
\remark mainly intended for internal usage.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutPointZ (gaiaOutBufferPtr out_buf,
|
|
gaiaPointPtr point);
|
|
|
|
/**
|
|
Encodes a WKT 3D Point [XYZ]
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param point pointer to Point object
|
|
\param precision decimal digits to be used for coordinates
|
|
|
|
\sa gaiaOutLinestringZ, gaiaOutPolygonZ
|
|
|
|
\remark mainly intended for internal usage.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutPointZex (gaiaOutBufferPtr out_buf,
|
|
gaiaPointPtr point, int precision);
|
|
|
|
/**
|
|
Encodes a WKT 3D Linestring [XYZ]
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param linestring pointer to Linestring object
|
|
|
|
\sa gaiaOutPointZ, gaiaOutPolygonZ, gaiaOutLinestringZex
|
|
|
|
\remark mainly intended for internal usage.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutLinestringZ (gaiaOutBufferPtr out_buf,
|
|
gaiaLinestringPtr linestring);
|
|
|
|
/**
|
|
Encodes a WKT 3D Linestring [XYZ]
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param linestring pointer to Linestring object
|
|
\param precision decimal digits to be used for coordinates
|
|
|
|
\sa gaiaOutPointZ, gaiaOutPolygonZ
|
|
|
|
\remark mainly intended for internal usage.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutLinestringZex (gaiaOutBufferPtr out_buf,
|
|
gaiaLinestringPtr linestring,
|
|
int precision);
|
|
|
|
/**
|
|
Encodes a WKT 3D Polygon [XYZ]
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param polygon pointer to Point object
|
|
|
|
\sa gaiaOutPointZ, gaiaOutLinestringZ, gaiaOutPolygonZex
|
|
|
|
\remark mainly intended for internal usage.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutPolygonZ (gaiaOutBufferPtr out_buf,
|
|
gaiaPolygonPtr polygon);
|
|
|
|
/**
|
|
Encodes a WKT 3D Polygon [XYZ]
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param polygon pointer to Point object
|
|
\param precision decimal digits to be used for coordinates
|
|
|
|
\sa gaiaOutPointZ, gaiaOutLinestringZ
|
|
|
|
\remark mainly intended for internal usage.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutPolygonZex (gaiaOutBufferPtr out_buf,
|
|
gaiaPolygonPtr polygon,
|
|
int precision);
|
|
|
|
/**
|
|
Creates a Geometry object from KML notation
|
|
|
|
\param in_buffer pointer to KML buffer
|
|
|
|
\return the pointer to the newly created Geometry object: NULL on failure
|
|
|
|
\sa 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 gaiaParseKml (const unsigned char
|
|
*in_buffer);
|
|
|
|
/**
|
|
Encodes a Geometry object into KML notation
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param geom pointer to Geometry object
|
|
\param precision decimal digits to be used for coordinates
|
|
|
|
\sa gaiaParseKml, gaiaOutFullKml
|
|
|
|
\note this function will export the simplest KML notation (no descriptions).
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutBareKml (gaiaOutBufferPtr out_buf,
|
|
gaiaGeomCollPtr geom, int precision);
|
|
|
|
/**
|
|
Encodes a Geometry object into KML notation
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param name text string to be set as KML \e name
|
|
\param desc text string to se set as KML \e description
|
|
\param geom pointer to Geometry object
|
|
\param precision decimal digits to be used for coordinates
|
|
|
|
\sa gaiaParseKml, gaiaOutBareKml
|
|
|
|
\note this function will export the simplest KML notation (no descriptions).
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutFullKml (gaiaOutBufferPtr out_buf,
|
|
const char *name, const char *desc,
|
|
gaiaGeomCollPtr geom, int precision);
|
|
|
|
/**
|
|
Creates a Geometry object from GML notation
|
|
|
|
\param in_buffer pointer to GML buffer
|
|
\param sqlite_handle handle to current DB connection
|
|
|
|
\return the pointer to the newly created Geometry object: NULL on failure
|
|
|
|
\sa 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.\n
|
|
not reentrant and thread unsafe.
|
|
*/
|
|
GAIAGEO_DECLARE gaiaGeomCollPtr gaiaParseGml (const unsigned char
|
|
*in_buffer,
|
|
sqlite3 * sqlite_handle);
|
|
|
|
/**
|
|
Creates a Geometry object from GML notation
|
|
|
|
\param p_cache a memory pointer returned by spatialite_alloc_connection()
|
|
\param in_buffer pointer to GML buffer
|
|
\param sqlite_handle handle to current DB connection
|
|
|
|
\return the pointer to the newly created Geometry object: NULL on failure
|
|
|
|
\sa 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.\n
|
|
reentrant and thread-safe.
|
|
*/
|
|
GAIAGEO_DECLARE gaiaGeomCollPtr gaiaParseGml_r (const void *p_cache,
|
|
const unsigned char
|
|
*in_buffer,
|
|
sqlite3 * sqlite_handle);
|
|
|
|
/**
|
|
Encodes a Geometry object into GML notation
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param version GML version
|
|
\params flippd if TURE the X and Y axes order will be: Y first, X second
|
|
\param precision decimal digits to be used for coordinates
|
|
\param geom pointer to Geometry object
|
|
|
|
\sa gaiaParseGml. gaiaOutGml
|
|
|
|
\note if \e version is set to \b 3, then GMLv3 will be used;
|
|
in any other case GMLv2 will be assumed by default.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutGml_ex (gaiaOutBufferPtr out_buf, int version,
|
|
int flipped, int precision,
|
|
gaiaGeomCollPtr geom);
|
|
|
|
/**
|
|
Encodes a Geometry object into GML notation
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param version GML version
|
|
\param precision decimal digits to be used for coordinates
|
|
\param geom pointer to Geometry object
|
|
|
|
\sa gaiaParseGml, gaiaOutGml_ex
|
|
|
|
\note it's simply an alias for gaiaOutGml_ex with FLIPPED set to FALSE.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutGml (gaiaOutBufferPtr out_buf, int version,
|
|
int precision, gaiaGeomCollPtr geom);
|
|
|
|
/**
|
|
Creates a Geometry object from GeoJSON notation
|
|
|
|
\param in_buffer pointer to GeoJSON buffer
|
|
|
|
\return the pointer to the newly created Geometry object: NULL on failure
|
|
|
|
\sa 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 gaiaParseGeoJSON (const unsigned char
|
|
*in_buffer);
|
|
|
|
/**
|
|
Encodes a Geometry object into GeoJSON notation
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param geom pointer to Geometry object
|
|
\param precision decimal digits to be used for coordinates
|
|
\param options GeoJSON specific options
|
|
|
|
\sa gaiaParseGeoJSON
|
|
|
|
\note \e options can assume the following values:
|
|
\li 1 = BBOX, no CRS
|
|
\li 2 = no BBOX, short form CRS
|
|
\li 3 = BBOX, short form CRS
|
|
\li 4 = no BBOX, long form CRS
|
|
\li 5 = BBOX, long form CRS
|
|
\li any other value: no BBOX and no CRS
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutGeoJSON (gaiaOutBufferPtr out_buf,
|
|
gaiaGeomCollPtr geom, int precision,
|
|
int options);
|
|
/**
|
|
Encodes a Geometry object into SVG notation
|
|
|
|
\param out_buf pointer to dynamically growing Text buffer
|
|
\param geom pointer to Geometry object
|
|
\param relative flag: relative or absolute coordinates
|
|
\param precision decimal digits to be used for coordinates
|
|
|
|
\note if \e relative is set to \b 1, then SVG relative coords will be used:
|
|
in any other case SVG absolute coords will be assumed by default.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOutSvg (gaiaOutBufferPtr out_buf,
|
|
gaiaGeomCollPtr geom, int relative,
|
|
int precision);
|
|
|
|
/**
|
|
Allocates a new DBF Field Value object [duplicating an existing one]
|
|
|
|
\param org pointer to input DBF Field Value object.
|
|
|
|
\return the pointer to newly created DBF Field object.
|
|
|
|
\sa gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField, gaiaCloneValue,
|
|
gaiaSetNullValue, gaiaSetIntValue, gaiaSetDoubleValue,
|
|
gaiaSetStrValue
|
|
|
|
\note the newly created object is an exact copy of the original one.
|
|
*/
|
|
GAIAGEO_DECLARE gaiaValuePtr gaiaCloneValue (gaiaValuePtr org);
|
|
|
|
/**
|
|
Resets a DBF Field Value object to its initial empty state
|
|
|
|
\param p pointer to DBF Field Value object
|
|
|
|
\sa gaiaAllocDbfField, gaiaCloneDbfField, gaiaCloneValue,
|
|
gaiaSetNullValue, gaiaSetIntValue, gaiaSetDoubleValue,
|
|
gaiaSetStrValue, gaiaResetDbfEntity
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaFreeValue (gaiaValuePtr p);
|
|
|
|
/**
|
|
Allocates a new DBF Field object
|
|
|
|
\param name text string: DBF Field name.
|
|
\param type identifier of the corresponding DBF data type.
|
|
\param offset corresponding offset into the DBF I/O buffer.
|
|
\param length max field length (in bytes).
|
|
\param decimals precision: number of decimal digits.
|
|
|
|
\return the pointer to newly created DBF Field object.
|
|
|
|
\sa 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.
|
|
\n supported DBF data types are:
|
|
\li 'C' text string [default]
|
|
\li 'N' numeric
|
|
\li 'D' date
|
|
\li 'L' boolean
|
|
*/
|
|
GAIAGEO_DECLARE gaiaDbfFieldPtr gaiaAllocDbfField (char *name,
|
|
unsigned char type,
|
|
int offset,
|
|
unsigned char length,
|
|
unsigned char decimals);
|
|
|
|
/**
|
|
Destroys a DBF Field object
|
|
|
|
\param p pointer to DBF Field object
|
|
|
|
\sa gaiaAllocDbfField, gaiaCloneDbfField, gaiaCloneValue,
|
|
gaiaFreeValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetDoubleValue,
|
|
gaiaSetStrValue
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaFreeDbfField (gaiaDbfFieldPtr p);
|
|
|
|
/**
|
|
Allocates a new DBF Field object [duplicating an existing one]
|
|
|
|
\param org pointer to input DBF Field object.
|
|
|
|
\return the pointer to newly created DBF Field object.
|
|
|
|
\sa 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 gaiaDbfFieldPtr gaiaCloneDbfField (gaiaDbfFieldPtr org);
|
|
|
|
/**
|
|
Sets a NULL current value for a DBF Field object
|
|
|
|
\param field pointer to DBF Field object
|
|
|
|
\sa gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField,
|
|
gaiaFreeValue, gaiaSetIntValue, gaiaSetDoubleValue,
|
|
gaiaSetStrValue
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaSetNullValue (gaiaDbfFieldPtr field);
|
|
|
|
/**
|
|
Sets an INTEGER current value for a DBF Field object
|
|
|
|
\param field pointer to DBF Field object.
|
|
\param value integer value to be set.
|
|
|
|
\sa gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField,
|
|
gaiaFreeValue, gaiaSetNullValue, gaiaSetDoubleValue,
|
|
gaiaSetStrValue
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaSetIntValue (gaiaDbfFieldPtr field,
|
|
sqlite3_int64 value);
|
|
|
|
/**
|
|
Sets a DOUBLE current value for a DBF Field object
|
|
|
|
\param field pointer to DBF Field object.
|
|
\param value double value to be set.
|
|
|
|
\sa gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField,
|
|
gaiaFreeValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetStrValue
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaSetDoubleValue (gaiaDbfFieldPtr field,
|
|
double value);
|
|
|
|
/**
|
|
Sets a TEXT current value for a DBF Field object
|
|
|
|
\param field pointer to DBF Field object.
|
|
\param str text string value to be set.
|
|
|
|
\sa gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField,
|
|
gaiaFreeValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetDoubleValue
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaSetStrValue (gaiaDbfFieldPtr field, char *str);
|
|
|
|
/**
|
|
Creates an initially empty DBF List object
|
|
|
|
\return the pointer to newly allocated DBF List object: NULL on failure.
|
|
|
|
\sa 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 gaiaDbfListPtr gaiaAllocDbfList (void);
|
|
|
|
/**
|
|
Destroys a DBF List object
|
|
|
|
\param list pointer to the DBF List object
|
|
|
|
\sa 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 gaiaFreeDbfList (gaiaDbfListPtr list);
|
|
|
|
/**
|
|
Checks a DBF List object for validity
|
|
|
|
\param list pointer to the DBF List object.
|
|
|
|
\return 0 if not valid: any other value if valid.
|
|
|
|
\sa gaiaAllocDbfList, gaiaFreeDbfList, gaiaIsValidDbfList,
|
|
gaiaResetDbfEntity, gaiaCloneDbfEntity, gaiaAddDbfField
|
|
*/
|
|
GAIAGEO_DECLARE int gaiaIsValidDbfList (gaiaDbfListPtr list);
|
|
|
|
/**
|
|
Inserts a further DBF Field object into a DBF List object
|
|
|
|
\param list pointer to the DBF List object.
|
|
\param name text string: DBF Field name.
|
|
\param type identifier of the corresponding DBF data type.
|
|
\param offset corresponding offset into the DBF I/O buffer.
|
|
\param length max field length (in bytes).
|
|
\param decimals precision: number of decimal digits.
|
|
|
|
\return the pointer to newly created DBF Field object.
|
|
|
|
\sa gaiaAllocDbfField
|
|
|
|
\note supported DBF data types are:
|
|
\li 'C' text string [default]
|
|
\li 'N' numeric
|
|
\li 'D' date
|
|
\li 'L' boolean
|
|
*/
|
|
GAIAGEO_DECLARE gaiaDbfFieldPtr gaiaAddDbfField (gaiaDbfListPtr list,
|
|
char *name,
|
|
unsigned char type,
|
|
int offset,
|
|
unsigned char length,
|
|
unsigned char decimals);
|
|
|
|
/**
|
|
Resets a DBF List object to its initial empty state
|
|
|
|
\param list pointer to the DBF List object.
|
|
|
|
\sa gaiaFreeValue
|
|
|
|
\note any DBF Field associated to the List object will be reset to its
|
|
initial empty state (i.e. \e no \e value at all).
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaResetDbfEntity (gaiaDbfListPtr list);
|
|
|
|
/**
|
|
Allocates a new DBF List object [duplicating an existing one]
|
|
|
|
\param org pointer to input DBF List object.
|
|
|
|
\return the pointer to newly created DBF List object.
|
|
|
|
\sa gaiaCloneDbfField, gaiaCloneValue,
|
|
|
|
\note the newly created object is an exact copy of the original one.
|
|
\n this including any currently set Field Value.
|
|
*/
|
|
GAIAGEO_DECLARE gaiaDbfListPtr gaiaCloneDbfEntity (gaiaDbfListPtr org);
|
|
|
|
/**
|
|
Allocates a new Shapefile object.
|
|
|
|
\return the pointer to newly created Shapefile object.
|
|
|
|
\sa gaiaFreeShapefile, gaiaOpenShpRead, gaiaOpenShpWrite,
|
|
gaiaReadShpEntity, gaiaShpAnalyze, gaiaWriteShpEntity, gaiaFlushShpHeaders
|
|
|
|
\note you are responsible to destroy (before or after) any allocated Shapefile.
|
|
\n you should phisically open the Shapefile in \e read or \e write mode
|
|
before performing any actual I/O operation.
|
|
*/
|
|
GAIAGEO_DECLARE gaiaShapefilePtr gaiaAllocShapefile (void);
|
|
|
|
/**
|
|
Destroys a Shapefile object
|
|
|
|
\param shp pointer to the Shapefile object.
|
|
|
|
\sa 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 \e write mode.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaFreeShapefile (gaiaShapefilePtr shp);
|
|
|
|
/**
|
|
Open a Shapefile in read mode
|
|
|
|
\param shp pointer to the Shapefile object.
|
|
\param path \e abstract pathname to the corresponding file-system files.
|
|
\param charFrom GNU ICONV name identifying the input charset encoding.
|
|
\param charTo GNU ICONV name identifying the output charset encoding.
|
|
|
|
\sa gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpWrite,
|
|
gaiaReadShpEntity, gaiaShpAnalyze, gaiaWriteShpEntity, gaiaFlushShpHeaders
|
|
|
|
\note on failure the object member \e Valid will be set to 0; and the
|
|
object member \e LastError will contain the appropriate error message.
|
|
\n the \e abstract pathname should not contain any suffix at all.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOpenShpRead (gaiaShapefilePtr shp,
|
|
const char *path,
|
|
const char *charFrom,
|
|
const char *charTo);
|
|
|
|
/**
|
|
Open a Shapefile in write mode - extended
|
|
|
|
\param shp pointer to the Shapefile object.
|
|
\param path \e abstract pathname to the corresponding file-system files.
|
|
\param 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
|
|
\param list pointer to DBF List object representing the corresponding
|
|
data attributes.
|
|
\param charFrom GNU ICONV name identifying the input charset encoding.
|
|
\param charTo GNU ICONV name identifying the output charset encoding.
|
|
\param colname_case one between GAIA_DBF_COLNAME_LOWERCASE,
|
|
GAIA_DBF_COLNAME_UPPERCASE or GAIA_DBF_COLNAME_CASE_IGNORE.
|
|
|
|
\sa gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead,
|
|
gaiaReadShpEntity, gaiaShpAnalyze, gaiaWriteShpEntity, gaiaFlushShpHeaders,
|
|
gaiaOpenShpWrite
|
|
|
|
\note on failure the object member \e Valid will be set to 0; and the
|
|
object member \e LastError will contain the appropriate error message.
|
|
\n the \e abstract pathname should not contain any suffix at all.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOpenShpWriteEx (gaiaShapefilePtr shp,
|
|
const char *path, int shape,
|
|
gaiaDbfListPtr list,
|
|
const char *charFrom,
|
|
const char *charTo,
|
|
int colname_case);
|
|
|
|
/**
|
|
Open a Shapefile in write mode
|
|
|
|
\param shp pointer to the Shapefile object.
|
|
\param path \e abstract pathname to the corresponding file-system files.
|
|
\param 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
|
|
\param list pointer to DBF List object representing the corresponding
|
|
data attributes.
|
|
\param charFrom GNU ICONV name identifying the input charset encoding.
|
|
\param charTo GNU ICONV name identifying the output charset encoding.
|
|
|
|
\sa gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead,
|
|
gaiaReadShpEntity, gaiaShpAnalyze, gaiaWriteShpEntity, gaiaFlushShpHeaders,
|
|
gaiaOpenShpWriteEx
|
|
|
|
\note simply calls gaiaOpenShpWriteEx() by specifying GAIA_DBF_COLNAME_LOWERCASE
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOpenShpWrite (gaiaShapefilePtr shp,
|
|
const char *path, int shape,
|
|
gaiaDbfListPtr list,
|
|
const char *charFrom,
|
|
const char *charTo);
|
|
|
|
/**
|
|
Reads a feature from a Shapefile object
|
|
|
|
\param shp pointer to the Shapefile object.
|
|
\param current_row the row number identifying the feature to be read.
|
|
\param srid feature's SRID
|
|
|
|
\return 0 on failure: any other value on success.
|
|
-1 when the corresponding DBF record is marked as DELETED.
|
|
|
|
\sa gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead, gaiaOpenShpWrite,
|
|
gaiaShpAnalyze, gaiaWriteShpEntity, gaiaFlushShpHeaders
|
|
|
|
\note on completion the Shapefile's \e Dbf member will contain the feature
|
|
read:
|
|
\li the \e Dbf->Geometry member will contain the corresponding Geometry
|
|
\li and the \e Dbf->First member will point to the linked list containing
|
|
the corresponding data attributes [both data formats and values].
|
|
|
|
\remark the Shapefile object should be opened in \e read mode.
|
|
*/
|
|
GAIAGEO_DECLARE int gaiaReadShpEntity (gaiaShapefilePtr shp,
|
|
int current_row, int srid);
|
|
|
|
/**
|
|
Reads a feature from a Shapefile object
|
|
|
|
\param shp pointer to the Shapefile object.
|
|
\param current_row the row number identifying the feature to be read.
|
|
\param srid feature's SRID
|
|
\param text_dates is TRUE all DBF dates will be considered as TEXT
|
|
|
|
\return 0 on failure: any other value on success.
|
|
|
|
\sa gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead, gaiaOpenShpWrite,
|
|
gaiaShpAnalyze, gaiaWriteShpEntity, gaiaFlushShpHeaders
|
|
|
|
\note on completion the Shapefile's \e Dbf member will contain the feature
|
|
read:
|
|
\li the \e Dbf->Geometry member will contain the corresponding Geometry
|
|
\li and the \e Dbf->First member will point to the linked list containing
|
|
the corresponding data attributes [both data formats and values].
|
|
|
|
\remark the Shapefile object should be opened in \e read mode.
|
|
*/
|
|
GAIAGEO_DECLARE int gaiaReadShpEntity_ex (gaiaShapefilePtr shp,
|
|
int current_row, int srid,
|
|
int text_dates);
|
|
|
|
/**
|
|
Prescans a Shapefile object gathering informations
|
|
|
|
\param shp pointer to the Shapefile object.
|
|
|
|
\sa gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead, gaiaOpenShpWrite,
|
|
gaiaReadShpEntity, gaiaWriteShpEntity, gaiaFlushShpHeaders
|
|
|
|
\note on completion the Shapefile's \e EffectiveType will containt the
|
|
Geometry type corresponding to features actually found.
|
|
|
|
\remark the Shapefile object should be opened in \e read mode.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaShpAnalyze (gaiaShapefilePtr shp);
|
|
|
|
/**
|
|
Writes a feature into a Shapefile object
|
|
|
|
\param shp pointer to the Shapefile object.
|
|
\param entity pointer to DBF List object containing both Geometry and Field
|
|
values.
|
|
|
|
\return 0 on failure: any other value on success.
|
|
|
|
\sa gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead, gaiaOpenShpWrite,
|
|
gaiaReadShpEntity, gaiaShpAnalyze, gaiaFlushShpHeaders
|
|
|
|
\remark the Shapefile object should be opened in \e write mode.
|
|
*/
|
|
GAIAGEO_DECLARE int gaiaWriteShpEntity (gaiaShapefilePtr shp,
|
|
gaiaDbfListPtr entity);
|
|
|
|
/**
|
|
Writes into an output Shapefile any required header / footer
|
|
|
|
\param shp pointer to the Shapefile object.
|
|
|
|
\sa gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead, gaiaOpenShpWrite,
|
|
gaiaReadShpEntity, gaiaShpAnalyze, gaiaWriteShpEntity
|
|
|
|
\note forgetting to call gaiaFlushShpHeader for any Shapefile opened in
|
|
\e write mode immediately before destroying the object, will surely
|
|
cause severe file corruption.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaFlushShpHeaders (gaiaShapefilePtr shp);
|
|
|
|
/**
|
|
Allocates a new DBF File object.
|
|
|
|
\return the pointer to newly created DBF File object.
|
|
|
|
\sa gaiaFreeDbf, gaiaOpenDbfRead, gaiaOpenDbfWrite,
|
|
gaiaReadDbfEntity, gaiaWriteDbfEntity, gaiaFlushDbfHeader
|
|
|
|
\note you are responsible to destroy (before or after) any allocated DBF File.
|
|
\n you should phisically open the DBF File in \e read or \e write mode
|
|
before performing any actual I/O operation.
|
|
*/
|
|
GAIAGEO_DECLARE gaiaDbfPtr gaiaAllocDbf (void);
|
|
|
|
/**
|
|
Destroys a DBF File object
|
|
|
|
\param dbf pointer to the DBF File object.
|
|
|
|
\sa 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 \e write mode.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaFreeDbf (gaiaDbfPtr dbf);
|
|
|
|
/**
|
|
Open a DBF File in read mode
|
|
|
|
\param dbf pointer to the DBF File object.
|
|
\param path pathname to the corresponding file-system file.
|
|
\param charFrom GNU ICONV name identifying the input charset encoding.
|
|
\param charTo GNU ICONV name identifying the output charset encoding.
|
|
|
|
\sa gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfWrite, gaiaOpenZipDbf,
|
|
gaiaReadDbfEntity, gaiaWriteDbfEntity, gaiaFlushDbfHeader
|
|
|
|
\note on failure the object member \e Valid will be set to 0; and the
|
|
object member \e LastError will contain the appropriate error message.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOpenDbfRead (gaiaDbfPtr dbf,
|
|
const char *path,
|
|
const char *charFrom,
|
|
const char *charTo);
|
|
|
|
/**
|
|
Open a DBF File contained within a Zipfile (just for checking its fields)
|
|
|
|
\param zip_path path of the Zipfile.
|
|
\param filename filename of the DB file within the Zipfile.
|
|
\param charFrom GNU ICONV name identifying the input charset encoding.
|
|
\param charTo GNU ICONV name identifying the output charset encoding.
|
|
|
|
\return dbf pointer to the DBF File object. NULL on error.
|
|
|
|
\sa gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfWrite,
|
|
gaiaReadDbfEntity, gaiaWriteDbfEntity, gaiaFlushDbfHeader
|
|
|
|
\note you are responsible to destroy (before or after) any allocated DBF File.
|
|
\n you should phisically open the DBF File in \e read or \e write mode
|
|
before performing any actual I/O operation.
|
|
*/
|
|
GAIAGEO_DECLARE gaiaDbfPtr gaiaOpenZipDbf (const char *zip_path,
|
|
const char *filename,
|
|
const char *charFrom,
|
|
const char *charTo);
|
|
|
|
/**
|
|
Open a DBF File in write mode,- extended
|
|
|
|
\param dbf pointer to the DBF File object.
|
|
\param path pathname to the corresponding file-system file.
|
|
\param charFrom GNU ICONV name identifying the input charset encoding.
|
|
\param charTo GNU ICONV name identifying the output charset encoding.
|
|
\param colname_case one between GAIA_DBF_COLNAME_LOWERCASE,
|
|
GAIA_DBF_COLNAME_UPPERCASE or GAIA_DBF_COLNAME_CASE_IGNORE.
|
|
|
|
\sa gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfRead,
|
|
gaiaReadDbfEntity, gaiaWriteDbfEntity, gaiaFlushDbfHeader,
|
|
gaiaOpenDbfWrite
|
|
|
|
\note on failure the object member \e Valid will be set to 0; and the
|
|
object member \e LastError will contain the appropriate error message.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOpenDbfWriteEx (gaiaDbfPtr dbf,
|
|
const char *path,
|
|
const char *charFrom,
|
|
const char *charTo,
|
|
int colname_case);
|
|
|
|
/**
|
|
Open a DBF File in write mode
|
|
|
|
\param dbf pointer to the DBF File object.
|
|
\param path pathname to the corresponding file-system file.
|
|
\param charFrom GNU ICONV name identifying the input charset encoding.
|
|
\param charTo GNU ICONV name identifying the output charset encoding.
|
|
|
|
\sa gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfRead,
|
|
gaiaReadDbfEntity, gaiaWriteDbfEntity, gaiaFlushDbfHeader,
|
|
gaiaOpenDbfWriteEx
|
|
|
|
|
|
\note simply calls gaiaOpenDbfWriteEx() by specifying GAIA_DBF_COLNAME_LOWERCASE
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaOpenDbfWrite (gaiaDbfPtr dbf,
|
|
const char *path,
|
|
const char *charFrom,
|
|
const char *charTo);
|
|
|
|
/**
|
|
Reads a record from a DBF File object
|
|
|
|
\param dbf pointer to the DBF File object.
|
|
\param current_row the row number identifying the record to be read.
|
|
\param 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
|
|
\e logically \e deleted.
|
|
|
|
\return 0 on failure: any other value on success.
|
|
|
|
\sa gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfRead, gaiaOpenDbfWrite,
|
|
gaiaFlushDbfHeader
|
|
|
|
\note on completion the DBF File \e First member will point to the
|
|
linked list containing the corresponding data attributes [both data
|
|
formats and values].
|
|
|
|
\remark the DBF File object should be opened in \e read mode.
|
|
*/
|
|
GAIAGEO_DECLARE int gaiaReadDbfEntity (gaiaDbfPtr dbf, int current_row,
|
|
int *deleted);
|
|
|
|
/**
|
|
Reads a record from a DBF File object
|
|
|
|
\param dbf pointer to the DBF File object.
|
|
\param current_row the row number identifying the record to be read.
|
|
\param deleted on completion this variable will contain 0 if the record
|
|
\param text_dates is TRUE all DBF dates will be considered as TEXT
|
|
just read is valid: any other value if the record just read is marked as
|
|
\e logically \e deleted.
|
|
|
|
\return 0 on failure: any other value on success.
|
|
|
|
\sa gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfRead, gaiaOpenDbfWrite,
|
|
gaiaFlushDbfHeader
|
|
|
|
\note on completion the DBF File \e First member will point to the
|
|
linked list containing the corresponding data attributes [both data
|
|
formats and values].
|
|
|
|
\remark the DBF File object should be opened in \e read mode.
|
|
*/
|
|
GAIAGEO_DECLARE int gaiaReadDbfEntity_ex (gaiaDbfPtr dbf, int current_row,
|
|
int *deleted, int text_dates);
|
|
|
|
/**
|
|
Writes a record into a DBF File object
|
|
|
|
\param dbf pointer to the DBF File object.
|
|
\param entity pointer to DBF List object containing Fields and corresponding
|
|
values.
|
|
|
|
\return 0 on failure: any other value on success.
|
|
|
|
\sa gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfRead, gaiaOpenDbfWrite,
|
|
gaiaReadDbfEntity, gaiaFlushDbfHeader
|
|
|
|
\remark the DBF File object should be opened in \e write mode.
|
|
*/
|
|
GAIAGEO_DECLARE int gaiaWriteDbfEntity (gaiaDbfPtr dbf,
|
|
gaiaDbfListPtr entity);
|
|
|
|
/**
|
|
Writes into an output DBF File any required header / footer
|
|
|
|
\param dbf pointer to the DBF File object.
|
|
|
|
\sa gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfRead, gaiaOpenDbfWrite,
|
|
gaiaReadDbfEntity, gaiaWriteDbfEntity
|
|
|
|
\note forgetting to call gaiaFlushDbfHeader for any DBF File opened in
|
|
\e write mode immediately before destroying the object, will surely
|
|
cause severe file corruption.
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaFlushDbfHeader (gaiaDbfPtr dbf);
|
|
|
|
/**
|
|
Reads from a Memory File
|
|
|
|
\param ptr pointer to the output buffer.
|
|
\param bytes numeber of bytes to read.
|
|
\param mem pointer to the Memory File object.
|
|
|
|
\return the number of bytes read.
|
|
|
|
\sa gaiaMemFseek
|
|
*/
|
|
GAIAGEO_DECLARE size_t gaiaMemRead (void *ptr, size_t bytes,
|
|
gaiaMemFilePtr mem);
|
|
|
|
/**
|
|
Repositioning a Memory File
|
|
|
|
\param mem pointer to the Memry File object.
|
|
\param offset file offset relative to the start of file
|
|
|
|
\return 0 on success; -1 on failure.
|
|
|
|
\sa gaiaFseek
|
|
*/
|
|
GAIAGEO_DECLARE int gaiaMemFseek (gaiaMemFilePtr mem, off_t offset);
|
|
|
|
/**
|
|
Attempting to get a WKT from the .PRJ member of a given zipped Shapefile
|
|
|
|
\param zip_path absolute or relativ pathname leading to the Zipfile.
|
|
\param basename name of the Shapefile (excluding any .shp, .shx or .dbf suffix)
|
|
|
|
\return the returned WKT expression from the .prj member of the zipped Shapefile
|
|
or NULL on failure
|
|
|
|
\note the WKT expression corresponds to dynamically allocated memory:
|
|
so you are responsible to free() it before or after.
|
|
*/
|
|
GAIAGEO_DECLARE char *gaiaReadWktFromZipShp (const char *zip_path,
|
|
const char *basename);
|
|
|
|
/**
|
|
Will return the number of Shapefiles from within a given Zipfile
|
|
|
|
\param zip_path absolute or relativ pathname leading to the Zipfile.
|
|
\param count on success will contain the number of Shapefiles
|
|
|
|
\return 0 on failure; any other value on success.
|
|
*/
|
|
GAIAGEO_DECLARE int gaiaZipfileNumSHP (const char *zip_path, int *count);
|
|
|
|
/**
|
|
Will return the basename of the Nth Shapefile from within a given Zipfile
|
|
|
|
\param zip_path absolute or relativ pathname leading to the Zipfile.
|
|
\param idx index (1-based) of the Shapefile
|
|
|
|
\return the basename of the Nth Shapefile
|
|
or NULL on failure
|
|
|
|
\note the returned basename corresponds to dynamically allocated memory:
|
|
so you are responsible to free() it before or after.
|
|
*/
|
|
GAIAGEO_DECLARE char *gaiaZipfileShpN (const char *zip_path, int idx);
|
|
|
|
/**
|
|
Will return the number of DBF files from within a given Zipfile
|
|
|
|
\param zip_path absolute or relativ pathname leading to the Zipfile.
|
|
\param count on success will contain the number of DBF files
|
|
|
|
\return 0 on failure; any other value on success.
|
|
*/
|
|
GAIAGEO_DECLARE int gaiaZipfileNumDBF (const char *zip_path, int *count);
|
|
|
|
/**
|
|
Will return the filename of the Nth DBF file from within a given Zipfile
|
|
|
|
\param zip_path absolute or relativ pathname leading to the Zipfile.
|
|
\param idx index (1-based) of the DBF file
|
|
|
|
\return the filename of the Nth DBF file
|
|
or NULL on failure
|
|
|
|
\note the returned filename corresponds to dynamically allocated memory:
|
|
so you are responsible to free() it before or after.
|
|
*/
|
|
GAIAGEO_DECLARE char *gaiaZipfileDbfN (const char *zip_path, int idx);
|
|
|
|
|
|
#ifndef OMIT_ICONV /* ICONV enabled: supporting text reader */
|
|
|
|
/**
|
|
Creates a Text Reader object
|
|
|
|
\param path to the corresponding file-system file.
|
|
\param field_separator the character acting as a separator between adjacent
|
|
fields.
|
|
\param text_separator the character used to quote text strings.
|
|
\param decimal_separator the character used as a separator between integer
|
|
and decimal digits for real numeric values.
|
|
\param first_line_titles 0 if the first line contains regular values:
|
|
any other value if the first line contains column names.
|
|
\param encoding GNU ICONV name identifying the input charset encoding.
|
|
|
|
\return the pointer to the newly created Text Reader object: NULL on failure
|
|
|
|
\sa gaiaTextReaderDestroy, gaiaTextReaderParse,
|
|
gaiaTextReaderGetRow, gaiaTextReaderFetchField
|
|
|
|
\note you are responsible to destroy (before or after) any allocated Text
|
|
Reader object.
|
|
*/
|
|
GAIAGEO_DECLARE gaiaTextReaderPtr gaiaTextReaderAlloc (const char *path,
|
|
char
|
|
field_separator,
|
|
char
|
|
text_separator,
|
|
char
|
|
decimal_separator,
|
|
int
|
|
first_line_titles,
|
|
const char
|
|
*encoding);
|
|
|
|
/**
|
|
Destroys a Text Reader object
|
|
|
|
\param reader pointer to Text Reader object.
|
|
|
|
\sa gaiaTextReaderAlloc, gaiaTextReaderParse,
|
|
gaiaTextReaderGetRow, gaiaTextReaderFetchField
|
|
*/
|
|
GAIAGEO_DECLARE void gaiaTextReaderDestroy (gaiaTextReaderPtr reader);
|
|
|
|
/**
|
|
Prescans the external file associated to a Text Reade object
|
|
|
|
\param reader pointer to Text Reader object.
|
|
|
|
\return 0 on failure: any other value on success.
|
|
|
|
\sa gaiaTextReaderAlloc, gaiaTextReaderDestroy,
|
|
gaiaTextReaderGetRow, gaiaTextReaderFetchField
|
|
|
|
\note this preliminary step is required so to ensure:
|
|
\li file consistency: checking expected formatting rules.
|
|
\li identifying the number / type / name of fields [aka columns].
|
|
\li identifying the actual number of lines within the file.
|
|
*/
|
|
GAIAGEO_DECLARE int gaiaTextReaderParse (gaiaTextReaderPtr reader);
|
|
|
|
/**
|
|
Reads a line from a Text Reader object
|
|
|
|
\param reader pointer to Text Reader object.
|
|
\param row_num the Line Number identifying the Line to be read.
|
|
|
|
\return 0 on failure: any other value on success.
|
|
|
|
\sa 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 gaiaTextReaderGetRow (gaiaTextReaderPtr reader,
|
|
int row_num);
|
|
|
|
/**
|
|
Retrieves an individual field value from the current Line
|
|
|
|
\param reader pointer to Text Reader object.
|
|
\param field_num relative field [aka column] index: first field has index 0.
|
|
\param type on completion this variable will contain the value type.
|
|
\param value on completion this variable will contain the current field value.
|
|
|
|
\return 0 on failure: any other value on success.
|
|
|
|
\sa gaiaTextReaderAlloc, gaiaTextReaderDestroy, gaiaTextReaderParse,
|
|
gaiaTextReaderGetRow
|
|
*/
|
|
GAIAGEO_DECLARE int gaiaTextReaderFetchField (gaiaTextReaderPtr reader,
|
|
int field_num, int *type,
|
|
const char **value);
|
|
|
|
#endif /* end ICONV (text reader) */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* _GG_FORMATS_H */
|