shx.h File Reference

Go to the source code of this file.

Data Structures
struct	shx_record_t
	Index record. More...

Typedefs
typedef shp_header_t	shx_header_t
	Header.
typedef shp_file_t	shx_file_t
	File handle.
typedef int(*	shx_header_callback_t) (shx_file_t *fh, const shx_header_t *header)
	Handle the file header. More...
typedef int(*	shx_record_callback_t) (shx_file_t *fh, const shx_header_t *header, const shx_record_t *record)
	Handle a record. More...

Functions
shx_file_t *	shx_init_file (shx_file_t *fh, FILE *fp, void *user_data)
	Initialize a file handle. More...
void	shx_set_error (shx_file_t *fh, const char *format,...)
	Set an error message. More...
int	shx_read (shx_file_t *fh, shx_header_callback_t handle_header, shx_record_callback_t handle_record)
	Read an index file. More...
int	shx_read_header (shx_file_t *fh, shx_header_t *header)
	Read the file header. More...
int	shx_read_record (shx_file_t *fh, shx_record_t *record)
	Read an index record. More...
int	shx_seek_record (shx_file_t *fh, size_t record_number, shx_record_t *record)
	Read an index record by record number. More...

Typedef Documentation

shx_header_callback_t

typedef int(* shx_header_callback_t) (shx_file_t *fh, const shx_header_t *header)

A callback function that is called for the file header.

Parameters

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

Return values

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

shx_record_callback_t

typedef int(* shx_record_callback_t) (shx_file_t *fh, const shx_header_t *header, const shx_record_t *record)

A callback function that is called for each record.

Parameters

fh	a file handle.
header	a pointer to a shx_header_t structure.
record	a pointer to a shx_record_t structure.

Return values

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

Function Documentation

shx_init_file()

shx_file_t * shx_init_file	(	shx_file_t *	fh,
		FILE *	fp,
		void *	user_data
	)

Initializes a shx_file_t structure.

Parameters

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

Returns

the initialized file handle.

shx_set_error()

void shx_set_error	(	shx_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.

shx_read()

int shx_read	(	shx_file_t *	fh,
		shx_header_callback_t	handle_header,
		shx_record_callback_t	handle_record
	)

Reads a file that has the file extension ".shx" 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(shx_file_t *fh, const shx_header_t *header) {
  mydata_t *mydata = (mydata_t *) fh->user_data;
  // Do something
  return 1;
}
 
int handle_record(shx_file_t *fh, const shx_header_t *header,
                  const shx_record_t *record) {
  mydata_t *mydata = (mydata_t *) fh->user_data;
  // Do something
  return 1;
}
 
shx_init_file(fh, fp, mydata)
rc = shx_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.

shx_read_header()

int shx_read_header	(	shx_file_t *	fh,
		shx_header_t *	header
	)

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

Parameters

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

Return values

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

See also

shx_read_record

shx_read_record()

int shx_read_record	(	shx_file_t *	fh,
		shx_record_t *	record
	)

Reads an index record from a file that has the file extension ".shx".

Example

shx_header_t header;
shx_record_t record;
 
if ((rc = shx_read_header(fh, &header)) > 0) {
  while ((rc = shx_read_record(fh, &record)) > 0) {
    // Do something
  }
}

Parameters

	fh	a file handle.
[out]	record	a shx_record_t structure.

Return values

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

See also

shx_read_header

shx_seek_record()

int shx_seek_record	(	shx_file_t *	fh,
		size_t	record_number,
		shx_record_t *	record
	)

Sets the file position to the specified record number and reads the requested index record.

Please note that this function uses zero-based record numbers, whereas the record numbers in shapefiles begin at 1.

Parameters

	fh	a file handle.
	record_number	a zero-based record number.
[out]	record	a shx_record_t structure.

Return values

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

See also

shp_seek_record