shp.h File Reference

Go to the source code of this file.

Data Structures
struct	shp_header_t
	File header. More...
struct	shp_record_t
	Record. More...
struct	shp_file_t
	File handle. More...

Typedefs
typedef int(*	shp_header_callback_t) (shp_file_t *fh, const shp_header_t *header)
	Handle the file header. More...
typedef int(*	shp_record_callback_t) (shp_file_t *fh, const shp_header_t *header, const shp_record_t *record, size_t file_offset)
	Handle a record. More...

Enumerations
enum	shp_type_t {   SHP_TYPE_NULL = 0 , SHP_TYPE_POINT = 1 , SHP_TYPE_POLYLINE = 3 , SHP_TYPE_POLYGON = 5 ,   SHP_TYPE_MULTIPOINT = 8 , SHP_TYPE_POINTZ = 11 , SHP_TYPE_POLYLINEZ = 13 , SHP_TYPE_POLYGONZ = 15 ,   SHP_TYPE_MULTIPOINTZ = 18 , SHP_TYPE_POINTM = 21 , SHP_TYPE_POLYLINEM = 23 , SHP_TYPE_POLYGONM = 25 ,   SHP_TYPE_MULTIPOINTM = 28 , SHP_TYPE_MULTIPATCH = 31 }
	Shape types. More...

Functions
shp_file_t *	shp_init_file (shp_file_t *fh, FILE *stream, void *user_data)
	Initialize a file handle. More...
void	shp_set_error (shp_file_t *fh, const char *format,...)
	Set an error message. More...
int	shp_read (shp_file_t *fh, shp_header_callback_t handle_header, shp_record_callback_t handle_record)
	Read a shape file. More...
int	shp_read_header (shp_file_t *fh, shp_header_t *header)
	Read the file header. More...
int	shp_read_record (shp_file_t *fh, shp_record_t **precord)
	Read a record. More...
int	shp_seek_record (shp_file_t *fh, size_t file_offset, shp_record_t **precord)
	Read a record at a particular file position. More...

Typedef Documentation

shp_header_callback_t

typedef int(* shp_header_callback_t) (shp_file_t *fh, const shp_header_t *header)

A callback function that is called for the file header.

Parameters

fh	a file handle.
header	a pointer to a shp_header_t structure.

Return values

1	on sucess.
0	to stop the processing.
-1	on error.

shp_record_callback_t

typedef int(* shp_record_callback_t) (shp_file_t *fh, const shp_header_t *header, const shp_record_t *record, size_t file_offset)

A callback function that is called for each record.

Parameters

fh	a file handle.
header	a pointer to a shp_header_t structure.
record	a pointer to a shp_record_t structure.
file_offset	the record's position in the file.

Return values

1	on sucess.
0	to stop the processing.
-1	on error.

Enumeration Type Documentation

shp_type_t

enum shp_type_t

Enumerator
SHP_TYPE_NULL	Null shape without geometric data.
SHP_TYPE_POINT	Point with X, Y coordinates.
SHP_TYPE_POLYLINE	PolyLine with X, Y coordinates.
SHP_TYPE_POLYGON	Polygon with X, Y coordinates.
SHP_TYPE_MULTIPOINT	Set of Points.
SHP_TYPE_POINTZ	PointZ with X, Y, Z, M coordinates.
SHP_TYPE_POLYLINEZ	PolyLineZ with X, Y, Z, M coordinates.
SHP_TYPE_POLYGONZ	PolygonZ with X, Y, Z, M coordinates.
SHP_TYPE_MULTIPOINTZ	Set of PointZs.
SHP_TYPE_POINTM	PointM with X, Y, M coordinates.
SHP_TYPE_POLYLINEM	PolyLineM with X, Y, M coordinates.
SHP_TYPE_POLYGONM	PolygonM with X, Y, M coordinates.
SHP_TYPE_MULTIPOINTM	Set of PointMs.
SHP_TYPE_MULTIPATCH	Complex surfaces.

Function Documentation

shp_init_file()

shp_file_t * shp_init_file	(	shp_file_t *	fh,
		FILE *	stream,
		void *	user_data
	)

Initializes a shp_file_t structure.

Parameters

fh	an uninitialized file handle.
stream	a FILE pointer.
user_data	callback data or NULL.

Returns

the initialized file handle.

shp_set_error()

void shp_set_error	(	shp_file_t *	fh,
		const char *	format,
			...
	)

Formats and sets an error message.

Parameters

fh	a file handle.
format	a printf format string followed by a variable number of arguments.

shp_read()

int shp_read	(	shp_file_t *	fh,
		shp_header_callback_t	handle_header,
		shp_record_callback_t	handle_record
	)

Reads a file that has the file extension ".shp" and calls functions for the file header and each record.

The data that is passed to the callback functions is only valid during the function call. Do not keep pointers to the data.

Example

int handle_header(shp_file_t *fh, const shp_header_t *header) {
  mydata_t *mydata = (mydata_t *) fh->user_data;
  // Do something
  return 1;
}
 
int handle_record(shp_file_t *fh, const shp_header_t *header,
                  const shp_record_t *record, size_t file_offset) {
  mydata_t *mydata = (mydata_t *) fh->user_data;
  // Do something
  return 1;
}
 
shp_init_file(fh, stream, mydata)
rc = shp_read(fh, handle_header, handle_record);

Parameters

fh	a file handle.
handle_header	a function that is called for the file header.
handle_record	a function that is called for each record.

Return values

1	on success.
0	on end of file.
-1	on error.

See also

the "ESRI Shapefile Technical Description" [2] for information on the file format.

shp_read_header()

int shp_read_header	(	shp_file_t *	fh,
		shp_header_t *	header
	)

Reads the header from a file that has the file extension ".shp".

Parameters

	fh	a file handle.
[out]	header	a shp_header_t structure.

Return values

1	on success.
0	on end of file.
-1	on error.

See also

shp_read_record

shp_read_record()

int shp_read_record	(	shp_file_t *	fh,
		shp_record_t **	precord
	)

Reads a record from a file that has the file extension ".shp".

Example

shp_header_t header;
shp_record_t *record;
 
if ((rc = shp_read_header(fh, &header)) > 0) {
  while ((rc = shp_read_record(fh, &record)) > 0) {
    // Do something
    free(record);
  }
}

Parameters

	fh	a file handle.
[out]	precord	on success, a pointer to a shp_record_t structure. Free the record with free() when you are done.

Return values

1	on success.
0	on end of file.
-1	on error.

See also

shp_read_header

shp_seek_record()

int shp_seek_record	(	shp_file_t *	fh,
		size_t	file_offset,
		shp_record_t **	precord
	)

Sets the file position to an offset from a ".shx" file and reads the requested record.

Example

shx_record_t index;
shp_record_t *record = NULL;
 
if (shx_seek_record(shx_fh, record_number, &index) > 0) {
  if (shp_seek_record(shp_fh, index.file_offset, &record) > 0) {
    // Do something
    free(record);
  }
}

Parameters

	fh	a file handle.
	file_offset	an offset from a ".shx" file.
[out]	precord	on success, a pointer to a shp_record_t structure. Free the record with free() when you are done.

Return values

1	on success.
0	on end of file.
-1	on error.

See also

shx_seek_record