# geos_c.h

    00001 /************************************************************************
    00002  *
    00003  * $Id: geos_c.h.in 2027 2007-09-21 17:40:15Z csavage $
    00004  *
    00005  * C-Wrapper for GEOS library
    00006  *
    00007  * Copyright (C) 2005 Refractions Research Inc.
    00008  *
    00009  * This is free software; you can redistribute and/or modify it under
    00010  * the terms of the GNU Lesser General Public Licence as published
    00011  * by the Free Software Foundation.
    00012  * See the COPYING file for more information.
    00013  *
    00014  * Author: Sandro Santilli <strk@refractions.net>
    00015  *
    00016  ***********************************************************************
    00017  *
    00018  * GENERAL NOTES:
    00019  *
    00020  *      - Remember to call initGEOS() before any use of this library's
    00021  *        functions, and call finishGEOS() when done.
    00022  *
    00023  *      - Currently you have to explicitly GEOSGeom_destroy() all
    00024  *        GEOSGeom objects to avoid memory leaks, and to free()
    00025  *        all returned char * (unless const). This might change
    00026  *        before first release to ensure greater API stability.
    00027  *
    00028  ***********************************************************************/
    00029
    00030 #ifndef GEOS_C_H
    00031 #define GEOS_C_H
    00032
    00033 #ifndef __cplusplus
    00034 # include <stddef.h> /* for size_t definition */
    00035 #endif
    00036
    00037 #ifdef __cplusplus
    00038 extern "C" {
    00039 #endif
    00040
    00041 /************************************************************************
    00042  *
    00043  * Version
    00044  *
    00045  ***********************************************************************/
    00046
    00047 /*
    00048  * Following 'ifdef' hack fixes problem with generating geos_c.h on Windows,
    00049  * when building with Visual C++ compiler.
    00050  */
    00051 #if defined(_MSC_VER)
    00052 #include <geos/version.h>
    00053 #define GEOS_CAPI_VERSION_MAJOR 1
    00054 #define GEOS_CAPI_VERSION_MINOR 3
    00055 #define GEOS_CAPI_VERSION_PATCH 3
    00056 #define GEOS_CAPI_VERSION "3.0.0rc4-CAPI-1.3.3"
    00057 #else
    00058 #define GEOS_VERSION_MAJOR 3
    00059 #define GEOS_VERSION_MINOR 0
    00060 #define GEOS_VERSION_PATCH 0
    00061 #define GEOS_VERSION "3.0.0"
    00062 #define GEOS_JTS_PORT "1.7.1"
    00063
    00064 #define GEOS_CAPI_VERSION_MAJOR 1
    00065 #define GEOS_CAPI_VERSION_MINOR 4
    00066 #define GEOS_CAPI_VERSION_PATCH 1
    00067 #define GEOS_CAPI_VERSION "3.0.0-CAPI-1.4.1"
    00068 #endif
    00069
    00070 #define GEOS_CAPI_FIRST_INTERFACE GEOS_CAPI_VERSION_MAJOR
    00071 #define GEOS_CAPI_LAST_INTERFACE (GEOS_CAPI_VERSION_MAJOR+GEOS_CAPI_VERSION_MINOR)
    00072
    00073 /************************************************************************
    00074  *
    00075  * (Abstract) type definitions
    00076  *
    00077  ***********************************************************************/
    00078
    00079 typedef void (*GEOSMessageHandler)(const char *fmt, ...);
    00080
    00081 /* When we're included by geos_c.cpp, those are #defined to the original
    00082  * JTS definitions via preprocessor. We don't touch them to allow the
    00083  * compiler to cross-check the declarations. However, for all "normal"
    00084  * C-API users, we need to define them as "opaque" struct pointers, as
    00085  * those clients don't have access to the original C++ headers, by design.
    00086  */
    00087 #ifndef GEOSGeometry
    00088 typedef struct GEOSGeom_t GEOSGeometry;
    00089 typedef struct GEOSCoordSeq_t GEOSCoordSequence;
    00090 #endif
    00091
    00092 /* Those are compatibility definitions for source compatibility
    00093  * with GEOS 2.X clients relying on that type.
    00094  */
    00095 typedef GEOSGeometry* GEOSGeom;
    00096 typedef GEOSCoordSequence* GEOSCoordSeq;
    00097
    00098 /* Supported geometry types
    00099  * This was renamed from GEOSGeomTypeId in GEOS 2.2.X, which might
    00100  * break compatibility, this issue is still under investigation.
    00101  */
    00102
    00103 enum GEOSGeomTypes {
    00104         GEOS_POINT,
    00105         GEOS_LINESTRING,
    00106         GEOS_LINEARRING,
    00107         GEOS_POLYGON,
    00108         GEOS_MULTIPOINT,
    00109         GEOS_MULTILINESTRING,
    00110         GEOS_MULTIPOLYGON,
    00111         GEOS_GEOMETRYCOLLECTION
    00112 };
    00113
    00114 /* Byte oders exposed via the c api */
    00115 enum GEOSByteOrders {
    00116         GEOS_WKB_XDR = 0, /* Big Endian */
    00117         GEOS_WKB_NDR = 1 /* Little Endian */
    00118 };
    00119
    00120
    00121 /************************************************************************
    00122  *
    00123  * Initialization, cleanup, version
    00124  *
    00125  ***********************************************************************/
    00126
    00127 #if defined(_MSC_VER)
    00128 #  define GEOS_DLL     __declspec(dllexport)
    00129 #else
    00130 #  define GEOS_DLL
    00131 #endif
    00132
    00133 extern void GEOS_DLL initGEOS(GEOSMessageHandler notice_function,
    00134         GEOSMessageHandler error_function);
    00135 extern void GEOS_DLL finishGEOS(void);
    00136 extern const char GEOS_DLL *GEOSversion();
    00137
    00138
    00139 /************************************************************************
    00140  *
    00141  * NOTE - These functions are DEPRECATED.  Please use the new Reader and
    00142  * writer APIS!
    00143  *
    00144  ***********************************************************************/
    00145
    00146 extern GEOSGeometry GEOS_DLL *GEOSGeomFromWKT(const char *wkt);
    00147 extern char GEOS_DLL *GEOSGeomToWKT(const GEOSGeometry* g);
    00148
    00149 /*
    00150  * Specify whether output WKB should be 2d or 3d.
    00151  * Return previously set number of dimensions.
    00152  */
    00153 extern int GEOS_DLL GEOS_getWKBOutputDims();
    00154 extern int GEOS_DLL GEOS_setWKBOutputDims(int newDims);
    00155
    00156 /*
    00157  * Specify whether the WKB byte order is big or little endian.
    00158  * The return value is the previous byte order.
    00159  */
    00160 extern int GEOS_DLL GEOS_getWKBByteOrder();
    00161 extern int GEOS_DLL GEOS_setWKBByteOrder(int byteOrder);
    00162
    00163 extern GEOSGeometry GEOS_DLL *GEOSGeomFromWKB_buf(const unsigned char *wkb, size_t size);
    00164 extern unsigned char GEOS_DLL *GEOSGeomToWKB_buf(const GEOSGeometry* g, size_t *size);
    00165
    00166 extern GEOSGeometry GEOS_DLL *GEOSGeomFromHEX_buf(const unsigned char *hex, size_t size);
    00167 extern unsigned char GEOS_DLL *GEOSGeomToHEX_buf(const GEOSGeometry* g, size_t *size);
    00168
    00169 /************************************************************************
    00170  *
    00171  * Coordinate Sequence functions
    00172  *
    00173  ***********************************************************************/
    00174
    00175 /*
    00176  * Create a Coordinate sequence with ``size'' coordinates
    00177  * of ``dims'' dimensions.
    00178  * Return NULL on exception.
    00179  */
    00180 extern GEOSCoordSequence GEOS_DLL *GEOSCoordSeq_create(unsigned int size, unsigned int dims);
    00181
    00182 /*
    00183  * Clone a Coordinate Sequence.
    00184  * Return NULL on exception.
    00185  */
    00186 extern GEOSCoordSequence GEOS_DLL *GEOSCoordSeq_clone(const GEOSCoordSequence* s);
    00187
    00188 /*
    00189  * Destroy a Coordinate Sequence.
    00190  */
    00191 extern void GEOS_DLL GEOSCoordSeq_destroy(GEOSCoordSequence* s);
    00192
    00193 /*
    00194  * Set ordinate values in a Coordinate Sequence.
    00195  * Return 0 on exception.
    00196  */
    00197 extern int GEOS_DLL GEOSCoordSeq_setX(GEOSCoordSequence* s,
    00198         unsigned int idx, double val);
    00199 extern int GEOS_DLL GEOSCoordSeq_setY(GEOSCoordSequence* s,
    00200         unsigned int idx, double val);
    00201 extern int GEOS_DLL GEOSCoordSeq_setZ(GEOSCoordSequence* s,
    00202         unsigned int idx, double val);
    00203 extern int GEOS_DLL GEOSCoordSeq_setOrdinate(GEOSCoordSequence* s,
    00204         unsigned int idx, unsigned int dim, double val);
    00205
    00206 /*
    00207  * Get ordinate values from a Coordinate Sequence.
    00208  * Return 0 on exception.
    00209  */
    00210 extern int GEOS_DLL GEOSCoordSeq_getX(const GEOSCoordSequence* s,
    00211         unsigned int idx, double *val);
    00212 extern int GEOS_DLL GEOSCoordSeq_getY(const GEOSCoordSequence* s,
    00213         unsigned int idx, double *val);
    00214 extern int GEOS_DLL GEOSCoordSeq_getZ(const GEOSCoordSequence* s,
    00215         unsigned int idx, double *val);
    00216 extern int GEOS_DLL GEOSCoordSeq_getOrdinate(const GEOSCoordSequence* s,
    00217         unsigned int idx, unsigned int dim, double *val);
    00218
    00219 /*
    00220  * Get size and dimensions info from a Coordinate Sequence.
    00221  * Return 0 on exception.
    00222  */
    00223 extern int GEOS_DLL GEOSCoordSeq_getSize(const GEOSCoordSequence* s,
    00224         unsigned int *size);
    00225 extern int GEOS_DLL GEOSCoordSeq_getDimensions(const GEOSCoordSequence* s,
    00226         unsigned int *dims);
    00227
    00228
    00229 /************************************************************************
    00230  *
    00231  * Geometry Constructors.
    00232  * GEOSCoordSequence* arguments will become ownership of the returned object.
    00233  * All functions return NULL on exception.
    00234  *
    00235  ***********************************************************************/
    00236
    00237 extern GEOSGeometry GEOS_DLL *GEOSGeom_createPoint(GEOSCoordSequence* s);
    00238 extern GEOSGeometry GEOS_DLL *GEOSGeom_createLinearRing(GEOSCoordSequence* s);
    00239 extern GEOSGeometry GEOS_DLL *GEOSGeom_createLineString(GEOSCoordSequence* s);
    00240
    00241 /*
    00242  * Second argument is an array of GEOSGeometry* objects.
    00243  * The caller remains owner of the array, but pointed-to
    00244  * objects become ownership of the returned GEOSGeometry.
    00245  */
    00246 extern GEOSGeometry GEOS_DLL *GEOSGeom_createPolygon(GEOSGeometry* shell,
    00247         GEOSGeometry** holes, unsigned int nholes);
    00248 extern GEOSGeometry GEOS_DLL *GEOSGeom_createCollection(int type,
    00249         GEOSGeometry* *geoms, unsigned int ngeoms);
    00250
    00251 extern GEOSGeometry GEOS_DLL *GEOSGeom_clone(const GEOSGeometry* g);
    00252
    00253 /************************************************************************
    00254  *
    00255  * Memory management
    00256  *
    00257  ***********************************************************************/
    00258
    00259 extern void GEOS_DLL GEOSGeom_destroy(GEOSGeometry* g);
    00260
    00261
    00262 /************************************************************************
    00263  *
    00264  * Topology operations - return NULL on exception.
    00265  *
    00266  ***********************************************************************/
    00267
    00268 extern GEOSGeometry GEOS_DLL *GEOSEnvelope(const GEOSGeometry* g1);
    00269 extern GEOSGeometry GEOS_DLL *GEOSIntersection(const GEOSGeometry* g1, const GEOSGeometry* g2);
    00270 extern GEOSGeometry GEOS_DLL *GEOSBuffer(const GEOSGeometry* g1,
    00271         double width, int quadsegs);
    00272 extern GEOSGeometry GEOS_DLL *GEOSConvexHull(const GEOSGeometry* g1);
    00273 extern GEOSGeometry GEOS_DLL *GEOSDifference(const GEOSGeometry* g1, const GEOSGeometry* g2);
    00274 extern GEOSGeometry GEOS_DLL *GEOSSymDifference(const GEOSGeometry* g1,
    00275         const GEOSGeometry* g2);
    00276 extern GEOSGeometry GEOS_DLL *GEOSBoundary(const GEOSGeometry* g1);
    00277 extern GEOSGeometry GEOS_DLL *GEOSUnion(const GEOSGeometry* g1, const GEOSGeometry* g2);
    00278 extern GEOSGeometry GEOS_DLL *GEOSPointOnSurface(const GEOSGeometry* g1);
    00279 extern GEOSGeometry GEOS_DLL *GEOSGetCentroid(const GEOSGeometry* g);
    00280 extern char GEOS_DLL *GEOSRelate(const GEOSGeometry* g1, const GEOSGeometry* g2);
    00281
    00282 /*
    00283  * all arguments remain ownership of the caller
    00284  * (both Geometries and pointers)
    00285  */
    00286 extern GEOSGeometry GEOS_DLL *GEOSPolygonize(const GEOSGeometry * const geoms[],
    00287         unsigned int ngeoms);
    00288
    00289 extern GEOSGeometry GEOS_DLL *GEOSLineMerge(const GEOSGeometry* g);
    00290 extern GEOSGeometry GEOS_DLL *GEOSSimplify(const GEOSGeometry* g1, double tolerance);
    00291 extern GEOSGeometry GEOS_DLL *GEOSTopologyPreserveSimplify(const GEOSGeometry* g1,
    00292         double tolerance);
    00293
    00294 /************************************************************************
    00295  *
    00296  *  Binary predicates - return 2 on exception, 1 on true, 0 on false
    00297  *
    00298  ***********************************************************************/
    00299
    00300 extern char GEOS_DLL GEOSRelatePattern(const GEOSGeometry* g1, const GEOSGeometry* g2,
    00301         const char *pat);
    00302 extern char GEOS_DLL GEOSDisjoint(const GEOSGeometry* g1, const GEOSGeometry* g2);
    00303 extern char GEOS_DLL GEOSTouches(const GEOSGeometry* g1, const GEOSGeometry* g2);
    00304 extern char GEOS_DLL GEOSIntersects(const GEOSGeometry* g1, const GEOSGeometry* g2);
    00305 extern char GEOS_DLL GEOSCrosses(const GEOSGeometry* g1, const GEOSGeometry* g2);
    00306 extern char GEOS_DLL GEOSWithin(const GEOSGeometry* g1, const GEOSGeometry* g2);
    00307 extern char GEOS_DLL GEOSContains(const GEOSGeometry* g1, const GEOSGeometry* g2);
    00308 extern char GEOS_DLL GEOSOverlaps(const GEOSGeometry* g1, const GEOSGeometry* g2);
    00309 extern char GEOS_DLL GEOSEquals(const GEOSGeometry* g1, const GEOSGeometry* g2);
    00310 extern char GEOS_DLL GEOSEqualsExact(const GEOSGeometry* g1, const GEOSGeometry* g2, double tolerance);
    00311
    00312
    00313 /************************************************************************
    00314  *
    00315  *  Unary predicate - return 2 on exception, 1 on true, 0 on false
    00316  *
    00317  ***********************************************************************/
    00318
    00319 extern char GEOS_DLL GEOSisEmpty(const GEOSGeometry* g1);
    00320 extern char GEOS_DLL GEOSisValid(const GEOSGeometry* g1);
    00321 extern char GEOS_DLL GEOSisSimple(const GEOSGeometry* g1);
    00322 extern char GEOS_DLL GEOSisRing(const GEOSGeometry* g1);
    00323 extern char GEOS_DLL GEOSHasZ(const GEOSGeometry* g1);
    00324
    00325
    00326 /************************************************************************
    00327  *
    00328  *  Geometry info
    00329  *
    00330  ***********************************************************************/
    00331
    00332 /* Return NULL on exception, result must be freed by caller. */
    00333 extern char GEOS_DLL *GEOSGeomType(const GEOSGeometry* g1);
    00334
    00335 /* Return -1 on exception */
    00336 extern int GEOS_DLL GEOSGeomTypeId(const GEOSGeometry* g1);
    00337
    00338 /* Return 0 on exception */
    00339 extern int GEOS_DLL GEOSGetSRID(const GEOSGeometry* g1);
    00340
    00341 extern void GEOS_DLL GEOSSetSRID(GEOSGeometry* g, int SRID);
    00342
    00343 /* May be called on all geometries in GEOS 3.x, returns -1 on error and 1
    00344  * for non-multi geometries. Older GEOS versions only accept
    00345  * GeometryCollections or Multi* geometries here, and are likely to crash
    00346  * when feeded simple geometries, so beware if you need compatibility with
    00347  * old GEOS versions.
    00348  */
    00349 extern int GEOS_DLL GEOSGetNumGeometries(const GEOSGeometry* g1);
    00350
    00351 /*
    00352  * Return NULL on exception, Geometry must be a Collection.
    00353  * Returned object is a pointer to internal storage:
    00354  * it must NOT be destroyed directly.
    00355  */
    00356 extern const GEOSGeometry GEOS_DLL *GEOSGetGeometryN(const GEOSGeometry* g, int n);
    00357
    00358 /* Return -1 on exception */
    00359 extern int GEOS_DLL GEOSNormalize(GEOSGeometry* g1);
    00360
    00361 /* Return -1 on exception */
    00362 extern int GEOS_DLL GEOSGetNumInteriorRings(const GEOSGeometry* g1);
    00363
    00364 /*
    00365  * Return NULL on exception, Geometry must be a Polygon.
    00366  * Returned object is a pointer to internal storage:
    00367  * it must NOT be destroyed directly.
    00368  */
    00369 extern const GEOSGeometry GEOS_DLL *GEOSGetInteriorRingN(const GEOSGeometry* g, int n);
    00370
    00371 /*
    00372  * Return NULL on exception, Geometry must be a Polygon.
    00373  * Returned object is a pointer to internal storage:
    00374  * it must NOT be destroyed directly.
    00375  */
    00376 extern const GEOSGeometry GEOS_DLL *GEOSGetExteriorRing(const GEOSGeometry* g);
    00377
    00378 /* Return -1 on exception */
    00379 extern int GEOS_DLL GEOSGetNumCoordinates(const GEOSGeometry* g1);
    00380
    00381 /*
    00382  * Return NULL on exception.
    00383  * Geometry must be a LineString, LinearRing or Point.
    00384  */
    00385 extern const GEOSCoordSequence GEOS_DLL *GEOSGeom_getCoordSeq(const GEOSGeometry* g);
    00386
    00387 /*
    00388  * Return 0 on exception (or empty geometry)
    00389  */
    00390 extern int GEOS_DLL GEOSGeom_getDimensions(const GEOSGeometry* g);
    00391
    00392 /************************************************************************
    00393  *
    00394  *  Misc functions
    00395  *
    00396  ***********************************************************************/
    00397
    00398 /* Return 0 on exception, 1 otherwise */
    00399 extern int GEOS_DLL GEOSArea(const GEOSGeometry* g1, double *area);
    00400 extern int GEOS_DLL GEOSLength(const GEOSGeometry* g1, double *length);
    00401 extern int GEOS_DLL GEOSDistance(const GEOSGeometry* g1, const GEOSGeometry* g2,
    00402         double *dist);
    00403
    00404
    00405
    00406 /************************************************************************
    00407  *
    00408  * Reader and Writer APIs
    00409  *
    00410  ***********************************************************************/
    00411
    00412 typedef struct GEOSWKTReader_t GEOSWKTReader;
    00413 typedef struct GEOSWKTWriter_t GEOSWKTWriter;
    00414 typedef struct GEOSWKBReader_t GEOSWKBReader;
    00415 typedef struct GEOSWKBWriter_t GEOSWKBWriter;
    00416
    00417
    00418 /* WKT Reader */
    00419 extern GEOSWKTReader GEOS_DLL *GEOSWKTReader_create();
    00420 extern void GEOS_DLL GEOSWKTReader_destroy(GEOSWKTReader* reader);
    00421 extern GEOSGeometry GEOS_DLL *GEOSWKTReader_read(GEOSWKTReader* reader, const char *wkt);
    00422
    00423 /* WKT Writer */
    00424 extern GEOSWKTWriter GEOS_DLL *GEOSWKTWriter_create();
    00425 extern void GEOS_DLL GEOSWKTWriter_destroy(GEOSWKTWriter* writer);
    00426 extern char GEOS_DLL *GEOSWKTWriter_write(GEOSWKTWriter* reader, const GEOSGeometry* g);
    00427
    00428 /* WKB Reader */
    00429 extern GEOSWKBReader GEOS_DLL *GEOSWKBReader_create();
    00430 extern void GEOS_DLL GEOSWKBReader_destroy(GEOSWKBReader* reader);
    00431 extern GEOSGeometry GEOS_DLL *GEOSWKBReader_read(GEOSWKBReader* reader, const unsigned char *wkb, size_t size);
    00432 extern GEOSGeometry GEOS_DLL *GEOSWKBReader_readHEX(GEOSWKBReader* reader, const unsigned char *hex, size_t size);
    00433
    00434 /* WKB Writer */
    00435 extern GEOSWKBWriter GEOS_DLL *GEOSWKBWriter_create();
    00436 extern void GEOS_DLL GEOSWKBWriter_destroy(GEOSWKBWriter* writer);
    00437
    00438 /* The owner owns the results for these two methods! */
    00439 extern unsigned char GEOS_DLL *GEOSWKBWriter_write(GEOSWKBWriter* writer, const GEOSGeometry* g, size_t *size);
    00440 extern unsigned char GEOS_DLL *GEOSWKBWriter_writeHEX(GEOSWKBWriter* writer, const GEOSGeometry* g, size_t *size);
    00441
    00442 /*
    00443  * Specify whether output WKB should be 2d or 3d.
    00444  * Return previously set number of dimensions.
    00445  */
    00446 extern int GEOS_DLL GEOSWKBWriter_getOutputDimension(const GEOSWKBWriter* writer);
    00447 extern void GEOS_DLL GEOSWKBWriter_setOutputDimension(GEOSWKBWriter* writer, int newDimension);
    00448
    00449 /*
    00450  * Specify whether the WKB byte order is big or little endian.
    00451  * The return value is the previous byte order.
    00452  */
    00453 extern int GEOS_DLL GEOSWKBWriter_getByteOrder(const GEOSWKBWriter* writer);
    00454 extern void GEOS_DLL GEOSWKBWriter_setByteOrder(GEOSWKBWriter* writer, int byteOrder);
    00455
    00456 /*
    00457  * Specify whether SRID values should be output.
    00458  */
    00459 extern char GEOS_DLL GEOSWKBWriter_getIncludeSRID(const GEOSWKBWriter* writer);
    00460 extern void GEOS_DLL GEOSWKBWriter_setIncludeSRID(GEOSWKBWriter* writer, const char writeSRID);
    00461
    00462
    00463
    00464
    00465 #ifdef __cplusplus
    00466 } // extern "C"
    00467 #endif
    00468
    00469 #endif /* #ifndef GEOS_C_H */