# geos_c.h

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