GRASS Programmer's Manual  6.4.2(2012)
shapefil.h
Go to the documentation of this file.
00001 #ifndef _SHAPEFILE_H_INCLUDED
00002 #define _SHAPEFILE_H_INCLUDED
00003 
00004 /******************************************************************************
00005  * $Id: shapefil.h 32581 2008-08-06 19:30:45Z neteler $
00006  *
00007  * Project:  Shapelib
00008  * Purpose:  Primary include file for Shapelib.
00009  * Author:   Frank Warmerdam, warmerdam@pobox.com
00010  *
00011  ******************************************************************************
00012  * Copyright (c) 1999, Frank Warmerdam
00013  *
00014  * This software is available under the following "MIT Style" license,
00015  * or at the option of the licensee under the LGPL (see LICENSE.LGPL).  This
00016  * option is discussed in more detail in shapelib.html.
00017  *
00018  * --
00019  * 
00020  * Permission is hereby granted, free of charge, to any person obtaining a
00021  * copy of this software and associated documentation files (the "Software"),
00022  * to deal in the Software without restriction, including without limitation
00023  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
00024  * and/or sell copies of the Software, and to permit persons to whom the
00025  * Software is furnished to do so, subject to the following conditions:
00026  *
00027  * The above copyright notice and this permission notice shall be included
00028  * in all copies or substantial portions of the Software.
00029  *
00030  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
00031  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00032  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
00033  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00034  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
00035  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
00036  * DEALINGS IN THE SOFTWARE.
00037  ******************************************************************************
00038  *
00039  * $Log: shapefil.h,v $
00040  * Revision 1.40  2007/12/06 07:00:25  fwarmerdam
00041  * dbfopen now using SAHooks for fileio
00042  *
00043  * Revision 1.39  2007/12/04 20:37:56  fwarmerdam
00044  * preliminary implementation of hooks api for io and errors
00045  *
00046  * Revision 1.38  2007/11/21 22:39:56  fwarmerdam
00047  * close shx file in readonly mode (GDAL #1956)
00048  *
00049  * Revision 1.37  2007/10/27 03:31:14  fwarmerdam
00050  * limit default depth of tree to 12 levels (gdal ticket #1594)
00051  *
00052  * Revision 1.36  2007/09/10 23:33:15  fwarmerdam
00053  * Upstreamed support for visibility flag in SHPAPI_CALL for the needs
00054  * of GDAL (gdal ticket #1810).
00055  *
00056  * Revision 1.35  2007/09/03 19:48:10  fwarmerdam
00057  * move DBFReadAttribute() static dDoubleField into dbfinfo
00058  *
00059  * Revision 1.34  2006/06/17 15:33:32  fwarmerdam
00060  * added pszWorkField - bug 1202 (rso)
00061  *
00062  * Revision 1.33  2006/02/15 01:14:30  fwarmerdam
00063  * added DBFAddNativeFieldType
00064  *
00065  * Revision 1.32  2006/01/26 15:07:32  fwarmerdam
00066  * add bMeasureIsUsed flag from Craig Bruce: Bug 1249
00067  *
00068  * Revision 1.31  2006/01/05 01:27:27  fwarmerdam
00069  * added dbf deletion mark/fetch
00070  *
00071  * Revision 1.30  2005/01/03 22:30:13  fwarmerdam
00072  * added support for saved quadtrees
00073  *
00074  * Revision 1.29  2004/09/26 20:09:35  fwarmerdam
00075  * avoid rcsid warnings
00076  *
00077  * Revision 1.28  2003/12/29 06:02:18  fwarmerdam
00078  * added cpl_error.h option
00079  *
00080  * Revision 1.27  2003/04/21 18:30:37  warmerda
00081  * added header write/update public methods
00082  *
00083  * Revision 1.26  2002/09/29 00:00:08  warmerda
00084  * added FTLogical and logical attribute read/write calls
00085  *
00086  * Revision 1.25  2002/05/07 13:46:30  warmerda
00087  * added DBFWriteAttributeDirectly().
00088  *
00089  * Revision 1.24  2002/04/10 16:59:54  warmerda
00090  * added SHPRewindObject
00091  *
00092  * Revision 1.23  2002/01/15 14:36:07  warmerda
00093  * updated email address
00094  *
00095  * Revision 1.22  2002/01/15 14:32:00  warmerda
00096  * try to improve SHPAPI_CALL docs
00097  */
00098 
00099 #include <stdio.h>
00100 
00101 #ifdef USE_DBMALLOC
00102 #include <dbmalloc.h>
00103 #endif
00104 
00105 #ifdef USE_CPL
00106 #include "cpl_error.h"
00107 #include "cpl_vsi.h"
00108 #endif
00109 
00110 #ifdef __cplusplus
00111 extern "C" {
00112 #endif
00113 
00114 /************************************************************************/
00115 /*                        Configuration options.                        */
00116 /************************************************************************/
00117 
00118 /* -------------------------------------------------------------------- */
00119 /*      Should the DBFReadStringAttribute() strip leading and           */
00120 /*      trailing white space?                                           */
00121 /* -------------------------------------------------------------------- */
00122 #define TRIM_DBF_WHITESPACE
00123 
00124 /* -------------------------------------------------------------------- */
00125 /*      Should we write measure values to the Multipatch object?        */
00126 /*      Reportedly ArcView crashes if we do write it, so for now it     */
00127 /*      is disabled.                                                    */
00128 /* -------------------------------------------------------------------- */
00129 #define DISABLE_MULTIPATCH_MEASURE
00130     
00131 /* -------------------------------------------------------------------- */
00132 /*      SHPAPI_CALL                                                     */
00133 /*                                                                      */
00134 /*      The following two macros are present to allow forcing           */
00135 /*      various calling conventions on the Shapelib API.                */
00136 /*                                                                      */
00137 /*      To force __stdcall conventions (needed to call Shapelib         */
00138 /*      from Visual Basic and/or Dephi I believe) the makefile could    */
00139 /*      be modified to define:                                          */
00140 /*                                                                      */
00141 /*        /DSHPAPI_CALL=__stdcall                                       */
00142 /*                                                                      */
00143 /*      If it is desired to force export of the Shapelib API without    */
00144 /*      using the shapelib.def file, use the following definition.      */
00145 /*                                                                      */
00146 /*        /DSHAPELIB_DLLEXPORT                                          */
00147 /*                                                                      */
00148 /*      To get both at once it will be necessary to hack this           */
00149 /*      include file to define:                                         */
00150 /*                                                                      */
00151 /*        #define SHPAPI_CALL __declspec(dllexport) __stdcall           */
00152 /*        #define SHPAPI_CALL1 __declspec(dllexport) * __stdcall        */
00153 /*                                                                      */
00154 /*      The complexity of the situtation is partly caused by the        */
00155 /*      peculiar requirement of Visual C++ that __stdcall appear        */
00156 /*      after any "*"'s in the return value of a function while the     */
00157 /*      __declspec(dllexport) must appear before them.                  */
00158 /* -------------------------------------------------------------------- */
00159 
00160 #ifdef SHAPELIB_DLLEXPORT
00161 #  define SHPAPI_CALL __declspec(dllexport)
00162 #  define SHPAPI_CALL1(x)  __declspec(dllexport) x
00163 #endif
00164 
00165 #ifndef SHPAPI_CALL
00166 #  if defined(USE_GCC_VISIBILITY_FLAG)
00167 #    define SHPAPI_CALL     __attribute__ ((visibility("default")))
00168 #    define SHPAPI_CALL1(x) __attribute__ ((visibility("default")))     x
00169 #  else
00170 #    define SHPAPI_CALL
00171 #  endif
00172 #endif
00173 
00174 #ifndef SHPAPI_CALL1
00175 #  define SHPAPI_CALL1(x)      x SHPAPI_CALL
00176 #endif
00177     
00178 /* -------------------------------------------------------------------- */
00179 /*      Macros for controlling CVSID and ensuring they don't appear     */
00180 /*      as unreferenced variables resulting in lots of warnings.        */
00181 /* -------------------------------------------------------------------- */
00182 #ifndef DISABLE_CVSID
00183 #  define SHP_CVSID(string)     static char cpl_cvsid[] = string; \
00184 static char *cvsid_aw() { return( cvsid_aw() ? ((char *) NULL) : cpl_cvsid ); }
00185 #else
00186 #  define SHP_CVSID(string)
00187 #endif
00188     
00189 /* -------------------------------------------------------------------- */
00190 /*      IO/Error hook functions.                                        */
00191 /* -------------------------------------------------------------------- */
00192 typedef int *SAFile;
00193 
00194 #ifndef SAOffset
00195 typedef unsigned long SAOffset;
00196 #endif
00197 
00198 typedef struct {
00199     SAFile     (*FOpen) ( const char *filename, const char *path);
00200     SAOffset   (*FRead) ( void *p, SAOffset size, SAOffset nmemb, SAFile file);
00201     SAOffset   (*FWrite)( void *p, SAOffset size, SAOffset nmemb, SAFile file);
00202     SAOffset   (*FSeek) ( SAFile file, SAOffset offset, int whence );
00203     SAOffset   (*FTell) ( SAFile file );
00204     int        (*FFlush)( SAFile file );
00205     int        (*FClose)( SAFile file );
00206 
00207     void       (*Error) ( const char *message );
00208 } SAHooks;
00209 
00210 void SHPAPI_CALL SASetupDefaultHooks( SAHooks *psHooks );
00211 
00212 /************************************************************************/
00213 /*                             SHP Support.                             */
00214 /************************************************************************/
00215 typedef struct
00216 {
00217     SAHooks sHooks;
00218 
00219     SAFile      fpSHP;
00220     SAFile      fpSHX;
00221 
00222     int         nShapeType;                             /* SHPT_* */
00223     
00224     int         nFileSize;                              /* SHP file */
00225 
00226     int         nRecords;
00227     int         nMaxRecords;
00228     int         *panRecOffset;
00229     int         *panRecSize;
00230 
00231     double      adBoundsMin[4];
00232     double      adBoundsMax[4];
00233 
00234     int         bUpdated;
00235 
00236     unsigned char *pabyRec;
00237     int         nBufSize;
00238 } SHPInfo;
00239 
00240 typedef SHPInfo * SHPHandle;
00241 
00242 /* -------------------------------------------------------------------- */
00243 /*      Shape types (nSHPType)                                          */
00244 /* -------------------------------------------------------------------- */
00245 #define SHPT_NULL       0
00246 #define SHPT_POINT      1
00247 #define SHPT_ARC        3
00248 #define SHPT_POLYGON    5
00249 #define SHPT_MULTIPOINT 8
00250 #define SHPT_POINTZ     11
00251 #define SHPT_ARCZ       13
00252 #define SHPT_POLYGONZ   15
00253 #define SHPT_MULTIPOINTZ 18
00254 #define SHPT_POINTM     21
00255 #define SHPT_ARCM       23
00256 #define SHPT_POLYGONM   25
00257 #define SHPT_MULTIPOINTM 28
00258 #define SHPT_MULTIPATCH 31
00259 
00260 
00261 /* -------------------------------------------------------------------- */
00262 /*      Part types - everything but SHPT_MULTIPATCH just uses           */
00263 /*      SHPP_RING.                                                      */
00264 /* -------------------------------------------------------------------- */
00265 
00266 #define SHPP_TRISTRIP   0
00267 #define SHPP_TRIFAN     1
00268 #define SHPP_OUTERRING  2
00269 #define SHPP_INNERRING  3
00270 #define SHPP_FIRSTRING  4
00271 #define SHPP_RING       5
00272 
00273 /* -------------------------------------------------------------------- */
00274 /*      SHPObject - represents on shape (without attributes) read       */
00275 /*      from the .shp file.                                             */
00276 /* -------------------------------------------------------------------- */
00277 typedef struct
00278 {
00279     int         nSHPType;
00280 
00281     int         nShapeId; /* -1 is unknown/unassigned */
00282 
00283     int         nParts;
00284     int         *panPartStart;
00285     int         *panPartType;
00286     
00287     int         nVertices;
00288     double      *padfX;
00289     double      *padfY;
00290     double      *padfZ;
00291     double      *padfM;
00292 
00293     double      dfXMin;
00294     double      dfYMin;
00295     double      dfZMin;
00296     double      dfMMin;
00297 
00298     double      dfXMax;
00299     double      dfYMax;
00300     double      dfZMax;
00301     double      dfMMax;
00302 
00303     int         bMeasureIsUsed;
00304 } SHPObject;
00305 
00306 /* -------------------------------------------------------------------- */
00307 /*      SHP API Prototypes                                              */
00308 /* -------------------------------------------------------------------- */
00309 
00310 /* If pszAccess is read-only, the fpSHX field of the returned structure */
00311 /* will be NULL as it is not necessary to keep the SHX file open */
00312 SHPHandle SHPAPI_CALL
00313       SHPOpen( const char * pszShapeFile, const char * pszAccess );
00314 SHPHandle SHPAPI_CALL
00315       SHPOpenLL( const char *pszShapeFile, const char *pszAccess, 
00316                  SAHooks *psHooks );
00317 SHPHandle SHPAPI_CALL
00318       SHPCreate( const char * pszShapeFile, int nShapeType );
00319 SHPHandle SHPAPI_CALL
00320       SHPCreateLL( const char * pszShapeFile, int nShapeType,
00321                    SAHooks *psHooks );
00322 void SHPAPI_CALL
00323       SHPGetInfo( SHPHandle hSHP, int * pnEntities, int * pnShapeType,
00324                   double * padfMinBound, double * padfMaxBound );
00325 
00326 SHPObject SHPAPI_CALL1(*)
00327       SHPReadObject( SHPHandle hSHP, int iShape );
00328 int SHPAPI_CALL
00329       SHPWriteObject( SHPHandle hSHP, int iShape, SHPObject * psObject );
00330 
00331 void SHPAPI_CALL
00332       SHPDestroyObject( SHPObject * psObject );
00333 void SHPAPI_CALL
00334       SHPComputeExtents( SHPObject * psObject );
00335 SHPObject SHPAPI_CALL1(*)
00336       SHPCreateObject( int nSHPType, int nShapeId, int nParts, 
00337                        const int * panPartStart, const int * panPartType,
00338                        int nVertices, 
00339                        const double * padfX, const double * padfY,
00340                        const double * padfZ, const double * padfM );
00341 SHPObject SHPAPI_CALL1(*)
00342       SHPCreateSimpleObject( int nSHPType, int nVertices,
00343                              const double * padfX, 
00344                              const double * padfY, 
00345                              const double * padfZ );
00346 
00347 int SHPAPI_CALL
00348       SHPRewindObject( SHPHandle hSHP, SHPObject * psObject );
00349 
00350 void SHPAPI_CALL SHPClose( SHPHandle hSHP );
00351 void SHPAPI_CALL SHPWriteHeader( SHPHandle hSHP );
00352 
00353 const char SHPAPI_CALL1(*)
00354       SHPTypeName( int nSHPType );
00355 const char SHPAPI_CALL1(*)
00356       SHPPartTypeName( int nPartType );
00357 
00358 /* -------------------------------------------------------------------- */
00359 /*      Shape quadtree indexing API.                                    */
00360 /* -------------------------------------------------------------------- */
00361 
00362 /* this can be two or four for binary or quad tree */
00363 #define MAX_SUBNODE     4
00364 
00365 /* upper limit of tree levels for automatic estimation */
00366 #define MAX_DEFAULT_TREE_DEPTH 12
00367 
00368 typedef struct shape_tree_node
00369 {
00370     /* region covered by this node */
00371     double      adfBoundsMin[4];
00372     double      adfBoundsMax[4];
00373 
00374     /* list of shapes stored at this node.  The papsShapeObj pointers
00375        or the whole list can be NULL */
00376     int         nShapeCount;
00377     int         *panShapeIds;
00378     SHPObject   **papsShapeObj;
00379 
00380     int         nSubNodes;
00381     struct shape_tree_node *apsSubNode[MAX_SUBNODE];
00382     
00383 } SHPTreeNode;
00384 
00385 typedef struct
00386 {
00387     SHPHandle   hSHP;
00388     
00389     int         nMaxDepth;
00390     int         nDimension;
00391     int         nTotalCount;
00392     
00393     SHPTreeNode *psRoot;
00394 } SHPTree;
00395 
00396 SHPTree SHPAPI_CALL1(*)
00397       SHPCreateTree( SHPHandle hSHP, int nDimension, int nMaxDepth,
00398                      double *padfBoundsMin, double *padfBoundsMax );
00399 void    SHPAPI_CALL
00400       SHPDestroyTree( SHPTree * hTree );
00401 
00402 int     SHPAPI_CALL
00403       SHPWriteTree( SHPTree *hTree, const char * pszFilename );
00404 SHPTree SHPAPI_CALL
00405       SHPReadTree( const char * pszFilename );
00406 
00407 int     SHPAPI_CALL
00408       SHPTreeAddObject( SHPTree * hTree, SHPObject * psObject );
00409 int     SHPAPI_CALL
00410       SHPTreeAddShapeId( SHPTree * hTree, SHPObject * psObject );
00411 int     SHPAPI_CALL
00412       SHPTreeRemoveShapeId( SHPTree * hTree, int nShapeId );
00413 
00414 void    SHPAPI_CALL
00415       SHPTreeTrimExtraNodes( SHPTree * hTree );
00416 
00417 int    SHPAPI_CALL1(*)
00418       SHPTreeFindLikelyShapes( SHPTree * hTree,
00419                                double * padfBoundsMin,
00420                                double * padfBoundsMax,
00421                                int * );
00422 int     SHPAPI_CALL
00423       SHPCheckBoundsOverlap( double *, double *, double *, double *, int );
00424 
00425 int SHPAPI_CALL1(*) 
00426 SHPSearchDiskTree( FILE *fp, 
00427                    double *padfBoundsMin, double *padfBoundsMax,
00428                    int *pnShapeCount );
00429 
00430 /************************************************************************/
00431 /*                             DBF Support.                             */
00432 /************************************************************************/
00433 typedef struct
00434 {
00435     SAHooks sHooks;
00436 
00437     SAFile      fp;
00438 
00439     int         nRecords;
00440 
00441     int         nRecordLength;
00442     int         nHeaderLength;
00443     int         nFields;
00444     int         *panFieldOffset;
00445     int         *panFieldSize;
00446     int         *panFieldDecimals;
00447     char        *pachFieldType;
00448 
00449     char        *pszHeader;
00450 
00451     int         nCurrentRecord;
00452     int         bCurrentRecordModified;
00453     char        *pszCurrentRecord;
00454 
00455     int         nWorkFieldLength;
00456     char        *pszWorkField;
00457     
00458     int         bNoHeader;
00459     int         bUpdated;
00460 
00461     double      dfDoubleField;
00462 } DBFInfo;
00463 
00464 typedef DBFInfo * DBFHandle;
00465 
00466 typedef enum {
00467   FTString,
00468   FTInteger,
00469   FTDouble,
00470   FTLogical,
00471   FTInvalid
00472 } DBFFieldType;
00473 
00474 #define XBASE_FLDHDR_SZ       32
00475 
00476 
00477 DBFHandle SHPAPI_CALL
00478       DBFOpen( const char * pszDBFFile, const char * pszAccess );
00479 DBFHandle SHPAPI_CALL
00480       DBFOpenLL( const char * pszDBFFile, const char * pszAccess,
00481                  SAHooks *psHooks );
00482 DBFHandle SHPAPI_CALL
00483       DBFCreate( const char * pszDBFFile );
00484 DBFHandle SHPAPI_CALL
00485       DBFCreateLL( const char * pszDBFFile, SAHooks *psHooks );
00486 
00487 int     SHPAPI_CALL
00488       DBFGetFieldCount( DBFHandle psDBF );
00489 int     SHPAPI_CALL
00490       DBFGetRecordCount( DBFHandle psDBF );
00491 int     SHPAPI_CALL
00492       DBFAddField( DBFHandle hDBF, const char * pszFieldName,
00493                    DBFFieldType eType, int nWidth, int nDecimals );
00494 
00495 int     SHPAPI_CALL
00496       DBFAddNativeFieldType( DBFHandle hDBF, const char * pszFieldName,
00497                              char chType, int nWidth, int nDecimals );
00498 
00499 DBFFieldType SHPAPI_CALL
00500       DBFGetFieldInfo( DBFHandle psDBF, int iField, 
00501                        char * pszFieldName, int * pnWidth, int * pnDecimals );
00502 
00503 int SHPAPI_CALL
00504       DBFGetFieldIndex(DBFHandle psDBF, const char *pszFieldName);
00505 
00506 int     SHPAPI_CALL
00507       DBFReadIntegerAttribute( DBFHandle hDBF, int iShape, int iField );
00508 double  SHPAPI_CALL
00509       DBFReadDoubleAttribute( DBFHandle hDBF, int iShape, int iField );
00510 const char SHPAPI_CALL1(*)
00511       DBFReadStringAttribute( DBFHandle hDBF, int iShape, int iField );
00512 const char SHPAPI_CALL1(*)
00513       DBFReadLogicalAttribute( DBFHandle hDBF, int iShape, int iField );
00514 int     SHPAPI_CALL
00515       DBFIsAttributeNULL( DBFHandle hDBF, int iShape, int iField );
00516 
00517 int SHPAPI_CALL
00518       DBFWriteIntegerAttribute( DBFHandle hDBF, int iShape, int iField, 
00519                                 int nFieldValue );
00520 int SHPAPI_CALL
00521       DBFWriteDoubleAttribute( DBFHandle hDBF, int iShape, int iField,
00522                                double dFieldValue );
00523 int SHPAPI_CALL
00524       DBFWriteStringAttribute( DBFHandle hDBF, int iShape, int iField,
00525                                const char * pszFieldValue );
00526 int SHPAPI_CALL
00527      DBFWriteNULLAttribute( DBFHandle hDBF, int iShape, int iField );
00528 
00529 int SHPAPI_CALL
00530      DBFWriteLogicalAttribute( DBFHandle hDBF, int iShape, int iField,
00531                                const char lFieldValue);
00532 int SHPAPI_CALL
00533      DBFWriteAttributeDirectly(DBFHandle psDBF, int hEntity, int iField,
00534                                void * pValue );
00535 const char SHPAPI_CALL1(*)
00536       DBFReadTuple(DBFHandle psDBF, int hEntity );
00537 int SHPAPI_CALL
00538       DBFWriteTuple(DBFHandle psDBF, int hEntity, void * pRawTuple );
00539 
00540 int SHPAPI_CALL DBFIsRecordDeleted( DBFHandle psDBF, int iShape );
00541 int SHPAPI_CALL DBFMarkRecordDeleted( DBFHandle psDBF, int iShape, 
00542                                       int bIsDeleted );
00543 
00544 DBFHandle SHPAPI_CALL
00545       DBFCloneEmpty(DBFHandle psDBF, const char * pszFilename );
00546  
00547 void    SHPAPI_CALL
00548       DBFClose( DBFHandle hDBF );
00549 void    SHPAPI_CALL
00550       DBFUpdateHeader( DBFHandle hDBF );
00551 char    SHPAPI_CALL
00552       DBFGetNativeFieldType( DBFHandle hDBF, int iField );
00553 
00554 #ifdef __cplusplus
00555 }
00556 #endif
00557 
00558 #endif /* ndef _SHAPEFILE_H_INCLUDED */
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines