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 */

Generated on Wed Jul 1 13:08:11 2009 for GEOS by  doxygen 1.5.4