capi/geos_c.h.in

   1 /************************************************************************
   2  *
   3  * $Id$
   4  *
   5  * C-Wrapper for GEOS library
   6  *
   7  * Copyright (C) 2005 Refractions Research Inc.
   8  *
   9  * This is free software; you can redistribute and/or modify it under
  10  * the terms of the GNU Lesser General Public Licence as published
  11  * by the Free Software Foundation.
  12  * See the COPYING file for more information.
  13  *
  14  * Author: Sandro Santilli <strk@refractions.net>
  15  *
  16  ***********************************************************************
  17  *
  18  * GENERAL NOTES:
  19  *
  20  *      - Remember to call initGEOS() before any use of this library's
  21  *        functions, and call finishGEOS() when done.
  22  *
  23  *      - Currently you have to explicitly GEOSGeom_destroy() all
  24  *        GEOSGeom objects to avoid memory leaks, and to free()
  25  *        all returned char * (unless const). This might change
  26  *        before first release to ensure greater API stability.
  27  *
  28  ***********************************************************************/
  29
  30 #ifndef GEOS_C_H
  31 #define GEOS_C_H
  32
  33 #ifndef __cplusplus
  34 # include <stddef.h> /* for size_t definition */
  35 #endif
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 /************************************************************************
  42  *
  43  * Version
  44  *
  45  ***********************************************************************/
  46
  47 /*
  48  * Following 'ifdef' hack fixes problem with generating geos_c.h on Windows,
  49  * when building with Visual C++ compiler.
  50  */
  51 #if defined(_MSC_VER)
  52 #include <geos/version.h>
  53 #define GEOS_CAPI_VERSION_MAJOR 1
  54 #define GEOS_CAPI_VERSION_MINOR 3
  55 #define GEOS_CAPI_VERSION_PATCH 3
  56 #define GEOS_CAPI_VERSION "3.0.0rc4-CAPI-1.3.3"
  57 #else
  58 #define GEOS_VERSION_MAJOR @VERSION_MAJOR@
  59 #define GEOS_VERSION_MINOR @VERSION_MINOR@
  60 #define GEOS_VERSION_PATCH @VERSION_PATCH@
  61 #define GEOS_VERSION "@VERSION@"
  62 #define GEOS_JTS_PORT "@JTS_PORT@"
  63
  64 #define GEOS_CAPI_VERSION_MAJOR @CAPI_VERSION_MAJOR@
  65 #define GEOS_CAPI_VERSION_MINOR @CAPI_VERSION_MINOR@
  66 #define GEOS_CAPI_VERSION_PATCH @CAPI_VERSION_PATCH@
  67 #define GEOS_CAPI_VERSION "@VERSION@-CAPI-@CAPI_VERSION@"
  68 #endif
  69
  70 #define GEOS_CAPI_FIRST_INTERFACE GEOS_CAPI_VERSION_MAJOR
  71 #define GEOS_CAPI_LAST_INTERFACE (GEOS_CAPI_VERSION_MAJOR+GEOS_CAPI_VERSION_MINOR)
  72
  73 /************************************************************************
  74  *
  75  * (Abstract) type definitions
  76  *
  77  ***********************************************************************/
  78
  79 typedef void (*GEOSMessageHandler)(const char *fmt, ...);
  80
  81 /* When we're included by geos_c.cpp, those are #defined to the original
  82  * JTS definitions via preprocessor. We don't touch them to allow the
  83  * compiler to cross-check the declarations. However, for all "normal"
  84  * C-API users, we need to define them as "opaque" struct pointers, as
  85  * those clients don't have access to the original C++ headers, by design.
  86  */
  87 #ifndef GEOSGeometry
  88 typedef struct GEOSGeom_t GEOSGeometry;
  89 typedef struct GEOSCoordSeq_t GEOSCoordSequence;
  90 #endif
  91
  92 /* Those are compatibility definitions for source compatibility
  93  * with GEOS 2.X clients relying on that type.
  94  */
  95 typedef GEOSGeometry* GEOSGeom;
  96 typedef GEOSCoordSequence* GEOSCoordSeq;
  97
  98 /* Supported geometry types
  99  * This was renamed from GEOSGeomTypeId in GEOS 2.2.X, which might
 100  * break compatibility, this issue is still under investigation.
 101  */
 102
 103 enum GEOSGeomTypes {
 104         GEOS_POINT,
 105         GEOS_LINESTRING,
 106         GEOS_LINEARRING,
 107         GEOS_POLYGON,
 108         GEOS_MULTIPOINT,
 109         GEOS_MULTILINESTRING,
 110         GEOS_MULTIPOLYGON,
 111         GEOS_GEOMETRYCOLLECTION
 112 };
 113
 114 /* Byte oders exposed via the c api */
 115 enum GEOSByteOrders {
 116         GEOS_WKB_XDR = 0, /* Big Endian */
 117         GEOS_WKB_NDR = 1 /* Little Endian */
 118 };
 119
 120
 121 /************************************************************************
 122  *
 123  * Initialization, cleanup, version
 124  *
 125  ***********************************************************************/
 126
 127 #if defined(_MSC_VER)
 128 #  define GEOS_DLL     __declspec(dllexport)
 129 #else
 130 #  define GEOS_DLL
 131 #endif
 132
 133 extern void GEOS_DLL initGEOS(GEOSMessageHandler notice_function,
 134         GEOSMessageHandler error_function);
 135 extern void GEOS_DLL finishGEOS(void);
 136 extern const char GEOS_DLL *GEOSversion();
 137
 138
 139 /************************************************************************
 140  *
 141  * NOTE - These functions are DEPRECATED.  Please use the new Reader and
 142  * writer APIS!
 143  *
 144  ***********************************************************************/
 145
 146 extern GEOSGeometry GEOS_DLL *GEOSGeomFromWKT(const char *wkt);
 147 extern char GEOS_DLL *GEOSGeomToWKT(const GEOSGeometry* g);
 148
 149 /*
 150  * Specify whether output WKB should be 2d or 3d.
 151  * Return previously set number of dimensions.
 152  */
 153 extern int GEOS_DLL GEOS_getWKBOutputDims();
 154 extern int GEOS_DLL GEOS_setWKBOutputDims(int newDims);
 155
 156 /*
 157  * Specify whether the WKB byte order is big or little endian.
 158  * The return value is the previous byte order.
 159  */
 160 extern int GEOS_DLL GEOS_getWKBByteOrder();
 161 extern int GEOS_DLL GEOS_setWKBByteOrder(int byteOrder);
 162
 163 extern GEOSGeometry GEOS_DLL *GEOSGeomFromWKB_buf(const unsigned char *wkb, size_t size);
 164 extern unsigned char GEOS_DLL *GEOSGeomToWKB_buf(const GEOSGeometry* g, size_t *size);
 165
 166 extern GEOSGeometry GEOS_DLL *GEOSGeomFromHEX_buf(const unsigned char *hex, size_t size);
 167 extern unsigned char GEOS_DLL *GEOSGeomToHEX_buf(const GEOSGeometry* g, size_t *size);
 168
 169 /************************************************************************
 170  *
 171  * Coordinate Sequence functions
 172  *
 173  ***********************************************************************/
 174
 175 /*
 176  * Create a Coordinate sequence with ``size'' coordinates
 177  * of ``dims'' dimensions.
 178  * Return NULL on exception.
 179  */
 180 extern GEOSCoordSequence GEOS_DLL *GEOSCoordSeq_create(unsigned int size, unsigned int dims);
 181
 182 /*
 183  * Clone a Coordinate Sequence.
 184  * Return NULL on exception.
 185  */
 186 extern GEOSCoordSequence GEOS_DLL *GEOSCoordSeq_clone(const GEOSCoordSequence* s);
 187
 188 /*
 189  * Destroy a Coordinate Sequence.
 190  */
 191 extern void GEOS_DLL GEOSCoordSeq_destroy(GEOSCoordSequence* s);
 192
 193 /*
 194  * Set ordinate values in a Coordinate Sequence.
 195  * Return 0 on exception.
 196  */
 197 extern int GEOS_DLL GEOSCoordSeq_setX(GEOSCoordSequence* s,
 198         unsigned int idx, double val);
 199 extern int GEOS_DLL GEOSCoordSeq_setY(GEOSCoordSequence* s,
 200         unsigned int idx, double val);
 201 extern int GEOS_DLL GEOSCoordSeq_setZ(GEOSCoordSequence* s,
 202         unsigned int idx, double val);
 203 extern int GEOS_DLL GEOSCoordSeq_setOrdinate(GEOSCoordSequence* s,
 204         unsigned int idx, unsigned int dim, double val);
 205
 206 /*
 207  * Get ordinate values from a Coordinate Sequence.
 208  * Return 0 on exception.
 209  */
 210 extern int GEOS_DLL GEOSCoordSeq_getX(const GEOSCoordSequence* s,
 211         unsigned int idx, double *val);
 212 extern int GEOS_DLL GEOSCoordSeq_getY(const GEOSCoordSequence* s,
 213         unsigned int idx, double *val);
 214 extern int GEOS_DLL GEOSCoordSeq_getZ(const GEOSCoordSequence* s,
 215         unsigned int idx, double *val);
 216 extern int GEOS_DLL GEOSCoordSeq_getOrdinate(const GEOSCoordSequence* s,
 217         unsigned int idx, unsigned int dim, double *val);
 218
 219 /*
 220  * Get size and dimensions info from a Coordinate Sequence.
 221  * Return 0 on exception.
 222  */
 223 extern int GEOS_DLL GEOSCoordSeq_getSize(const GEOSCoordSequence* s,
 224         unsigned int *size);
 225 extern int GEOS_DLL GEOSCoordSeq_getDimensions(const GEOSCoordSequence* s,
 226         unsigned int *dims);
 227
 228
 229 /************************************************************************
 230  *
 231  * Geometry Constructors.
 232  * GEOSCoordSequence* arguments will become ownership of the returned object.
 233  * All functions return NULL on exception.
 234  *
 235  ***********************************************************************/
 236
 237 extern GEOSGeometry GEOS_DLL *GEOSGeom_createPoint(GEOSCoordSequence* s);
 238 extern GEOSGeometry GEOS_DLL *GEOSGeom_createLinearRing(GEOSCoordSequence* s);
 239 extern GEOSGeometry GEOS_DLL *GEOSGeom_createLineString(GEOSCoordSequence* s);
 240
 241 /*
 242  * Second argument is an array of GEOSGeometry* objects.
 243  * The caller remains owner of the array, but pointed-to
 244  * objects become ownership of the returned GEOSGeometry.
 245  */
 246 extern GEOSGeometry GEOS_DLL *GEOSGeom_createPolygon(GEOSGeometry* shell,
 247         GEOSGeometry** holes, unsigned int nholes);
 248 extern GEOSGeometry GEOS_DLL *GEOSGeom_createCollection(int type,
 249         GEOSGeometry* *geoms, unsigned int ngeoms);
 250
 251 extern GEOSGeometry GEOS_DLL *GEOSGeom_clone(const GEOSGeometry* g);
 252
 253 /************************************************************************
 254  *
 255  * Memory management
 256  *
 257  ***********************************************************************/
 258
 259 extern void GEOS_DLL GEOSGeom_destroy(GEOSGeometry* g);
 260
 261
 262 /************************************************************************
 263  *
 264  * Topology operations - return NULL on exception.
 265  *
 266  ***********************************************************************/
 267
 268 extern GEOSGeometry GEOS_DLL *GEOSEnvelope(const GEOSGeometry* g1);
 269 extern GEOSGeometry GEOS_DLL *GEOSIntersection(const GEOSGeometry* g1, const GEOSGeometry* g2);
 270 extern GEOSGeometry GEOS_DLL *GEOSBuffer(const GEOSGeometry* g1,
 271         double width, int quadsegs);
 272 extern GEOSGeometry GEOS_DLL *GEOSConvexHull(const GEOSGeometry* g1);
 273 extern GEOSGeometry GEOS_DLL *GEOSDifference(const GEOSGeometry* g1, const GEOSGeometry* g2);
 274 extern GEOSGeometry GEOS_DLL *GEOSSymDifference(const GEOSGeometry* g1,
 275         const GEOSGeometry* g2);
 276 extern GEOSGeometry GEOS_DLL *GEOSBoundary(const GEOSGeometry* g1);
 277 extern GEOSGeometry GEOS_DLL *GEOSUnion(const GEOSGeometry* g1, const GEOSGeometry* g2);
 278 extern GEOSGeometry GEOS_DLL *GEOSPointOnSurface(const GEOSGeometry* g1);
 279 extern GEOSGeometry GEOS_DLL *GEOSGetCentroid(const GEOSGeometry* g);
 280 extern char GEOS_DLL *GEOSRelate(const GEOSGeometry* g1, const GEOSGeometry* g2);
 281
 282 /*
 283  * all arguments remain ownership of the caller
 284  * (both Geometries and pointers)
 285  */
 286 extern GEOSGeometry GEOS_DLL *GEOSPolygonize(const GEOSGeometry * const geoms[],
 287         unsigned int ngeoms);
 288
 289 extern GEOSGeometry GEOS_DLL *GEOSLineMerge(const GEOSGeometry* g);
 290 extern GEOSGeometry GEOS_DLL *GEOSSimplify(const GEOSGeometry* g1, double tolerance);
 291 extern GEOSGeometry GEOS_DLL *GEOSTopologyPreserveSimplify(const GEOSGeometry* g1,
 292         double tolerance);
 293
 294 /************************************************************************
 295  *
 296  *  Binary predicates - return 2 on exception, 1 on true, 0 on false
 297  *
 298  ***********************************************************************/
 299
 300 extern char GEOS_DLL GEOSRelatePattern(const GEOSGeometry* g1, const GEOSGeometry* g2,
 301         const char *pat);
 302 extern char GEOS_DLL GEOSDisjoint(const GEOSGeometry* g1, const GEOSGeometry* g2);
 303 extern char GEOS_DLL GEOSTouches(const GEOSGeometry* g1, const GEOSGeometry* g2);
 304 extern char GEOS_DLL GEOSIntersects(const GEOSGeometry* g1, const GEOSGeometry* g2);
 305 extern char GEOS_DLL GEOSCrosses(const GEOSGeometry* g1, const GEOSGeometry* g2);
 306 extern char GEOS_DLL GEOSWithin(const GEOSGeometry* g1, const GEOSGeometry* g2);
 307 extern char GEOS_DLL GEOSContains(const GEOSGeometry* g1, const GEOSGeometry* g2);
 308 extern char GEOS_DLL GEOSOverlaps(const GEOSGeometry* g1, const GEOSGeometry* g2);
 309 extern char GEOS_DLL GEOSEquals(const GEOSGeometry* g1, const GEOSGeometry* g2);
 310 extern char GEOS_DLL GEOSEqualsExact(const GEOSGeometry* g1, const GEOSGeometry* g2, double tolerance);
 311
 312
 313 /************************************************************************
 314  *
 315  *  Unary predicate - return 2 on exception, 1 on true, 0 on false
 316  *
 317  ***********************************************************************/
 318
 319 extern char GEOS_DLL GEOSisEmpty(const GEOSGeometry* g1);
 320 extern char GEOS_DLL GEOSisValid(const GEOSGeometry* g1);
 321 extern char GEOS_DLL GEOSisSimple(const GEOSGeometry* g1);
 322 extern char GEOS_DLL GEOSisRing(const GEOSGeometry* g1);
 323 extern char GEOS_DLL GEOSHasZ(const GEOSGeometry* g1);
 324
 325
 326 /************************************************************************
 327  *
 328  *  Geometry info
 329  *
 330  ***********************************************************************/
 331
 332 /* Return NULL on exception, result must be freed by caller. */
 333 extern char GEOS_DLL *GEOSGeomType(const GEOSGeometry* g1);
 334
 335 /* Return -1 on exception */
 336 extern int GEOS_DLL GEOSGeomTypeId(const GEOSGeometry* g1);
 337
 338 /* Return 0 on exception */
 339 extern int GEOS_DLL GEOSGetSRID(const GEOSGeometry* g1);
 340
 341 extern void GEOS_DLL GEOSSetSRID(GEOSGeometry* g, int SRID);
 342
 343 /* May be called on all geometries in GEOS 3.x, returns -1 on error and 1
 344  * for non-multi geometries. Older GEOS versions only accept
 345  * GeometryCollections or Multi* geometries here, and are likely to crash
 346  * when feeded simple geometries, so beware if you need compatibility with
 347  * old GEOS versions.
 348  */
 349 extern int GEOS_DLL GEOSGetNumGeometries(const GEOSGeometry* g1);
 350
 351 /*
 352  * Return NULL on exception, Geometry must be a Collection.
 353  * Returned object is a pointer to internal storage:
 354  * it must NOT be destroyed directly.
 355  */
 356 extern const GEOSGeometry GEOS_DLL *GEOSGetGeometryN(const GEOSGeometry* g, int n);
 357
 358 /* Return -1 on exception */
 359 extern int GEOS_DLL GEOSNormalize(GEOSGeometry* g1);
 360
 361 /* Return -1 on exception */
 362 extern int GEOS_DLL GEOSGetNumInteriorRings(const GEOSGeometry* g1);
 363
 364 /*
 365  * Return NULL on exception, Geometry must be a Polygon.
 366  * Returned object is a pointer to internal storage:
 367  * it must NOT be destroyed directly.
 368  */
 369 extern const GEOSGeometry GEOS_DLL *GEOSGetInteriorRingN(const GEOSGeometry* g, int n);
 370
 371 /*
 372  * Return NULL on exception, Geometry must be a Polygon.
 373  * Returned object is a pointer to internal storage:
 374  * it must NOT be destroyed directly.
 375  */
 376 extern const GEOSGeometry GEOS_DLL *GEOSGetExteriorRing(const GEOSGeometry* g);
 377
 378 /* Return -1 on exception */
 379 extern int GEOS_DLL GEOSGetNumCoordinates(const GEOSGeometry* g1);
 380
 381 /*
 382  * Return NULL on exception.
 383  * Geometry must be a LineString, LinearRing or Point.
 384  */
 385 extern const GEOSCoordSequence GEOS_DLL *GEOSGeom_getCoordSeq(const GEOSGeometry* g);
 386
 387 /*
 388  * Return 0 on exception (or empty geometry)
 389  */
 390 extern int GEOS_DLL GEOSGeom_getDimensions(const GEOSGeometry* g);
 391
 392 /************************************************************************
 393  *
 394  *  Misc functions
 395  *
 396  ***********************************************************************/
 397
 398 /* Return 0 on exception, 1 otherwise */
 399 extern int GEOS_DLL GEOSArea(const GEOSGeometry* g1, double *area);
 400 extern int GEOS_DLL GEOSLength(const GEOSGeometry* g1, double *length);
 401 extern int GEOS_DLL GEOSDistance(const GEOSGeometry* g1, const GEOSGeometry* g2,
 402         double *dist);
 403
 404
 405
 406 /************************************************************************
 407  *
 408  * Reader and Writer APIs
 409  *
 410  ***********************************************************************/
 411
 412 typedef struct GEOSWKTReader_t GEOSWKTReader;
 413 typedef struct GEOSWKTWriter_t GEOSWKTWriter;
 414 typedef struct GEOSWKBReader_t GEOSWKBReader;
 415 typedef struct GEOSWKBWriter_t GEOSWKBWriter;
 416
 417
 418 /* WKT Reader */
 419 extern GEOSWKTReader GEOS_DLL *GEOSWKTReader_create();
 420 extern void GEOS_DLL GEOSWKTReader_destroy(GEOSWKTReader* reader);
 421 extern GEOSGeometry GEOS_DLL *GEOSWKTReader_read(GEOSWKTReader* reader, const char *wkt);
 422
 423 /* WKT Writer */
 424 extern GEOSWKTWriter GEOS_DLL *GEOSWKTWriter_create();
 425 extern void GEOS_DLL GEOSWKTWriter_destroy(GEOSWKTWriter* writer);
 426 extern char GEOS_DLL *GEOSWKTWriter_write(GEOSWKTWriter* reader, const GEOSGeometry* g);
 427
 428 /* WKB Reader */
 429 extern GEOSWKBReader GEOS_DLL *GEOSWKBReader_create();
 430 extern void GEOS_DLL GEOSWKBReader_destroy(GEOSWKBReader* reader);
 431 extern GEOSGeometry GEOS_DLL *GEOSWKBReader_read(GEOSWKBReader* reader, const unsigned char *wkb, size_t size);
 432 extern GEOSGeometry GEOS_DLL *GEOSWKBReader_readHEX(GEOSWKBReader* reader, const unsigned char *hex, size_t size);
 433
 434 /* WKB Writer */
 435 extern GEOSWKBWriter GEOS_DLL *GEOSWKBWriter_create();
 436 extern void GEOS_DLL GEOSWKBWriter_destroy(GEOSWKBWriter* writer);
 437
 438 /* The owner owns the results for these two methods! */
 439 extern unsigned char GEOS_DLL *GEOSWKBWriter_write(GEOSWKBWriter* writer, const GEOSGeometry* g, size_t *size);
 440 extern unsigned char GEOS_DLL *GEOSWKBWriter_writeHEX(GEOSWKBWriter* writer, const GEOSGeometry* g, size_t *size);
 441
 442 /*
 443  * Specify whether output WKB should be 2d or 3d.
 444  * Return previously set number of dimensions.
 445  */
 446 extern int GEOS_DLL GEOSWKBWriter_getOutputDimension(const GEOSWKBWriter* writer);
 447 extern void GEOS_DLL GEOSWKBWriter_setOutputDimension(GEOSWKBWriter* writer, int newDimension);
 448
 449 /*
 450  * Specify whether the WKB byte order is big or little endian.
 451  * The return value is the previous byte order.
 452  */
 453 extern int GEOS_DLL GEOSWKBWriter_getByteOrder(const GEOSWKBWriter* writer);
 454 extern void GEOS_DLL GEOSWKBWriter_setByteOrder(GEOSWKBWriter* writer, int byteOrder);
 455
 456 /*
 457  * Specify whether SRID values should be output.
 458  */
 459 extern char GEOS_DLL GEOSWKBWriter_getIncludeSRID(const GEOSWKBWriter* writer);
 460 extern void GEOS_DLL GEOSWKBWriter_setIncludeSRID(GEOSWKBWriter* writer, const char writeSRID);
 461
 462
 463
 464
 465 #ifdef __cplusplus
 466 } // extern "C"
 467 #endif
 468
 469 #endif /* #ifndef GEOS_C_H */