MITAB: mitab_capi.cpp File Reference


Defines
#define	INFO_NUMPARTS 0
#define	INFO_NUMPOINTS 1
#define	INFO_XVERTEX 2
#define	INFO_YVERTEX 3
Functions
int MITAB_STDCALL	mitab_c_getlibversion ()
	Returns the version of the library.
int MITAB_STDCALL	mitab_c_getlasterrorno ()
	Fetch the last error number.
const char *MITAB_STDCALL	mitab_c_getlasterrormsg ()
	Get the last error message.
int MITAB_STDCALL	mitab_c_getlasterrormsg_vb (char *errormsg, int l)
	Get the last error message (VB Version).
mitab_handle MITAB_STDCALL	mitab_c_open (const char *pszFilename)
	Open an existing .TAB or .MIF dataset for read access.
void MITAB_STDCALL	mitab_c_close (mitab_handle handle)
	Close a dataset previously opened using mitab_c_open() or created using mitab_c_create().
mitab_handle MITAB_STDCALL	mitab_c_create (const char filename, const char mif_or_tab, const char *mif_projection, double north, double south, double east, double west)
	Create a new .TAB or .MIF dataset.
int MITAB_STDCALL	mitab_c_set_quick_spatial_index_mode (mitab_handle dataset)
	Select "quick spatial index mode".
int MITAB_STDCALL	mitab_c_add_field (mitab_handle dataset, const char *field_name, int field_type, int width, int precision, int indexed, int unique)
	Add a new field to the dataset's schema.
void MITAB_STDCALL	mitab_c_destroy_feature (mitab_feature feature)
	Destroy a mitab_feature object and release all memory associated with it.
int MITAB_STDCALL	mitab_c_next_feature_id (mitab_handle handle, int last_feature_id)
	Iterator to get the next valid feature id when reading a dataset opened with mitab_c_open().
mitab_feature MITAB_STDCALL	mitab_c_read_feature (mitab_handle handle, int feature_id)
	Read a mitab_feature object from the file.
int MITAB_STDCALL	mitab_c_write_feature (mitab_handle handle, mitab_feature feature)
	Write a new feature to a dataset.
mitab_feature MITAB_STDCALL	mitab_c_create_feature (mitab_handle handle, int feature_type)
	Create a new mitab_feature object to be written to a dataset created using mitab_c_create().
void MITAB_STDCALL	mitab_c_set_field (mitab_feature feature, int field_index, const char *field_value)
	Set the value of specified field in a feature object.
void MITAB_STDCALL	mitab_c_set_points (mitab_feature feature, int part, int vertex_count, double x, double y)
	Set the feature's coordinates.
void MITAB_STDCALL	mitab_c_set_arc (mitab_feature feature, double center_x, double center_y, double x_radius, double y_radius, double start_angle, double end_angle)
	Set an arc or ellipse feature parameters.
void MITAB_STDCALL	mitab_c_set_text (mitab_feature feature, const char *text)
	Set the text string on a TABFC_Text object.
const char *MITAB_STDCALL	mitab_c_get_text (mitab_feature feature)
	Get the text string on a TABFC_Text object.
int MITAB_STDCALL	mitab_c_get_text_vb (mitab_feature feature, char *text, int l)
	Get the text string on a TABFC_Text object (VB Version).
void MITAB_STDCALL	mitab_c_set_text_display (mitab_feature feature, double angle, double height, double width, int fg_color, int bg_color, int justification, int spacing, int linetype)
	Set a TABFC_Text object's display properties.
double MITAB_STDCALL	mitab_c_get_text_angle (mitab_feature feature)
	Fetch a TABFC_Text object's angle property.
double MITAB_STDCALL	mitab_c_get_text_height (mitab_feature feature)
	Fetch a TABFC_Text object's MBR height property.
double MITAB_STDCALL	mitab_c_get_text_width (mitab_feature feature)
	Fetch a TABFC_Text object's MBR width property.
int MITAB_STDCALL	mitab_c_get_text_fgcolor (mitab_feature feature)
	Fetch a TABFC_Text object's foreground color property.
int MITAB_STDCALL	mitab_c_get_text_bgcolor (mitab_feature feature)
	Fetch a TABFC_Text object's background color property.
int MITAB_STDCALL	mitab_c_get_text_justification (mitab_feature feature)
	Fetch a TABFC_Text object's justification property.
int MITAB_STDCALL	mitab_c_get_text_spacing (mitab_feature feature)
	Fetch a TABFC_Text object's spacing property.
int MITAB_STDCALL	mitab_c_get_text_linetype (mitab_feature feature)
	Fetch a TABFC_Text object's linetype property.
void MITAB_STDCALL	mitab_c_set_font (mitab_feature feature, const char *fontname)
	Set the font name in a a TABFC_Text or TABFC_FontPoint object, or set the symbol name in a TABFC_CustomPoint.
const char *MITAB_STDCALL	mitab_c_get_font (mitab_feature feature)
	Get the font name from a TABFC_Text or TABFC_FontPoint object, or the symbol name from a TABFC_CustomPoint.
int MITAB_STDCALL	mitab_c_get_font_vb (mitab_feature feature, char *font, int l)
	Get the font name from a TABFC_Text or TABFC_FontPoint object, or the symbol name from a TABFC_CustomPoint.
void MITAB_STDCALL	mitab_c_set_brush (mitab_feature feature, int fg_color, int bg_color, int pattern, int transparent)
	Set an object's brush properties.
int MITAB_STDCALL	mitab_c_get_brush_fgcolor (mitab_feature feature)
	Get an object's brush foreground color property.
int MITAB_STDCALL	mitab_c_get_brush_bgcolor (mitab_feature feature)
	Get an object's brush background color property.
int MITAB_STDCALL	mitab_c_get_brush_pattern (mitab_feature feature)
	Get an object's brush pattern property.
int MITAB_STDCALL	mitab_c_get_brush_transparent (mitab_feature feature)
	Get an object's brush transparency property.
void MITAB_STDCALL	mitab_c_set_pen (mitab_feature feature, int width, int pattern, int color)
	Set an object's pen properties.
int MITAB_STDCALL	mitab_c_get_pen_color (mitab_feature feature)
	Get an object's pen color property.
int MITAB_STDCALL	mitab_c_get_pen_width (mitab_feature feature)
	Get an object's pen width property.
int MITAB_STDCALL	mitab_c_get_pen_pattern (mitab_feature feature)
	Get an object's pen pattern property.
void MITAB_STDCALL	mitab_c_set_symbol (mitab_feature feature, int symbol_no, int symbol_size, int symbol_color)
	Set an object's symbol properties.
void MITAB_STDCALL	mitab_c_set_symbol_angle (mitab_feature feature, double symbol_angle)
	Set the point symbol's angle.
int MITAB_STDCALL	mitab_c_get_symbol_color (mitab_feature feature)
	Get an object's symbol color property.
int MITAB_STDCALL	mitab_c_get_symbol_no (mitab_feature feature)
	Get an object's symbol number property.
int MITAB_STDCALL	mitab_c_get_symbol_size (mitab_feature feature)
	Get an object's symbol size property.
double MITAB_STDCALL	mitab_c_get_symbol_angle (mitab_feature feature)
	Get an font point object's angle property.
int MITAB_STDCALL	mitab_c_get_type (mitab_feature feature)
	Return a mitab_feature's object type.
int MITAB_STDCALL	mitab_c_get_parts (mitab_feature feature)
	Return the number of parts (rings or polyline segments) in an object.
int MITAB_DLL MITAB_STDCALL	mitab_c_is_interior_ring (mitab_feature feature, int requestedringindex)
	Return a false if te ring is the first of a polygon.
int MITAB_STDCALL	mitab_c_get_vertex_count (mitab_feature feature, int part)
	Return the number of points in a part of a mitab_feature object.
double MITAB_STDCALL	mitab_c_get_vertex_x (mitab_feature feature, int part, int vertex)
	Return the X coordinate of a point in a part of a mitab_feature object.
double MITAB_STDCALL	mitab_c_get_vertex_y (mitab_feature feature, int part, int vertex)
	Return the Y coordinate of a point in a part of a mitab_feature object.
int MITAB_STDCALL	mitab_c_get_field_count (mitab_handle handle)
	Return the number of attribute fields in a dataset's schema.
int MITAB_STDCALL	mitab_c_get_feature_count (mitab_handle handle)
	Return the number of features in a dataset.
int MITAB_STDCALL	mitab_c_get_field_type (mitab_handle handle, int field)
	Return the type of an attribute field in a dataset's schema.
const char *MITAB_STDCALL	mitab_c_get_field_name (mitab_handle handle, int field)
	Return the name of an attribute field in a dataset's schema.
int MITAB_STDCALL	mitab_c_get_field_name_vb (mitab_handle handle, int field, char *name, int l)
	Return the name of an attribute field in a dataset's schema (VB version).
int MITAB_STDCALL	mitab_c_get_field_width (mitab_handle handle, int field)
	Return the width of an attribute field in a dataset's schema.
int MITAB_STDCALL	mitab_c_get_field_precision (mitab_handle handle, int field)
	Return the precision of an attribute field in a dataset's schema.
int MITAB_STDCALL	mitab_c_is_field_indexed (mitab_handle handle, int field)
	Test whether specified field in a dataset's schema is indexed or not.
int MITAB_STDCALL	mitab_c_is_field_unique (mitab_handle handle, int field)
	For indexed fields only, test whether the specified indexed field in a dataset's schema has the unique flag set.
const char *MITAB_STDCALL	mitab_c_get_field_as_string (mitab_feature feature, int field)
	Fetch an attribute field value in a mitab_feature as a string.
int MITAB_STDCALL	mitab_c_get_field_as_string_vb (mitab_feature feature, int field, char *value, int l)
	Fetch an attribute field value in a mitab_feature as a string (VB Version).
double MITAB_STDCALL	mitab_c_get_field_as_double (mitab_feature feature, int field)
	Fetch an attribute field value in a mitab_feature as a double.
mitab_projinfo MITAB_STDCALL	mitab_c_get_projinfo (mitab_handle dataset)
	Get the projinfo handle from an opened dataset.
int MITAB_STDCALL	mitab_c_set_projinfo (mitab_handle dataset, mitab_projinfo projinfo)
	Set the projinfo on a newly created dataset.
const char *MITAB_STDCALL	mitab_c_get_mif_coordsys (mitab_handle dataset)
	Get the MIF CoordSys string from an opened dataset.
const char *MITAB_STDCALL	mitab_c_get_extended_mif_coordsys (mitab_handle dataset)
	Get the MIF CoordSys string from an opened dataset including the affine transformation parameters if available.
void MITAB_STDCALL	mitab_c_get_projection_info (mitab_projinfo projInfo, int nProjId, int nEllipsoidId, int nUnitsId, double adProjParams)
void MITAB_STDCALL	mitab_c_set_projection_info (mitab_projinfo projInfo, int nProjId, int nEllipsoidId, int nUnitsId, double *adProjParams)
void MITAB_STDCALL	mitab_c_get_datum_info (mitab_projinfo projInfo, double dDatumShiftX, double dDatumShiftY, double dDatumShiftZ, double adDatumParams)
void MITAB_STDCALL	mitab_c_set_datum_info (mitab_projinfo projInfo, double dDatumShiftX, double dDatumShiftY, double dDatumShiftZ, double *adDatumParams)
int MITAB_STDCALL	mitab_c_get_affine_params (mitab_projinfo projInfo, int nAffineUnits, double adAffineParams)
void MITAB_STDCALL	mitab_c_set_affine_params (mitab_projinfo projInfo, int nAffineUnits, double *adAffineParams)
int MITAB_STDCALL	mitab_c_get_extended_mif_coordsys_vb (mitab_handle dataset, char *coordsys, int l)
	Get the MIF CoordSys string from an opened dataset including the affine transformation parameters if available.
int MITAB_STDCALL	mitab_c_get_mif_coordsys_vb (mitab_handle dataset, char *coordsys, int l)
	Get the MIF CoordSys string from an opened dataset (VB Version).
int MITAB_STDCALL	mitab_c_load_coordsys_table (const char *filename)
	Load a Coordsys bounds lookup table from an external file.
mitab_feature MITAB_STDCALL	mitab_c_get_collection_region_ref (mitab_feature feature)
	Returns a reference to the region component of a collection.
mitab_feature MITAB_STDCALL	mitab_c_get_collection_polyline_ref (mitab_feature feature)
	Returns a reference to the polyline component of a collection.
mitab_feature MITAB_STDCALL	mitab_c_get_collection_multipoint_ref (mitab_feature feature)
	Returns a reference to the multipoint component of a collection.
int MITAB_STDCALL	mitab_c_set_collection_region (mitab_feature feature, mitab_feature region, int make_copy)
	Set or update the region component of a collection.
int MITAB_STDCALL	mitab_c_set_collection_polyline (mitab_feature feature, mitab_feature polyline, int make_copy)
	Set or update the polyline component of a collection.
int MITAB_STDCALL	mitab_c_set_collection_multipoint (mitab_feature feature, mitab_feature multipoint, int make_copy)
	Set or update the multipoint component of a collection.

Detailed Description

The C wrapper functions contained in mitab_capi.cpp provide a much simpler interface than the OGR-based C++ classes to the MITAB library to read and write .TAB and .MIF files.

To use the C API, simply include "mitab_capi.h" and use the functions defined in mitab_capi.cpp.

See contrib/README_VB.TXT in the MITAB source code distribution for informations on using the MITAB C API from VB, Pascal, or MapBasic.

Function Documentation

int MITAB_STDCALL mitab_c_add_field	(	mitab_handle	dataset,
		const char *	field_name,
		int	field_type,
		int	width,
		int	precision,
		int	indexed,
		int	unique
	)

Add a new field to the dataset's schema.

Adding fields MUST be done immediately after creating a new dataset and BEFORE creating the first feature.

Parameters:

	dataset	the mitab_handle of the newly created dataset.
	field_name	the name of the new field to create.
	field_type	the new field type, one of TABFT_Char (1), TABFT_Integer (2), TABFT_SmallInt (3), TABFT_Decimal (4), TABFT_Float (5), TABFT_Date (6), or TABFT_Logical (7)
	width	the width of the new field, applies only to char and decimal types.
	precision	the number of digits after the decimal point, applies only to the decimal field type.
	indexed	TRUE (1) to create an indexed field (or FALSE (0) for no index)
	unique	for indexed fields, set this to TRUE (1) if the field values are guaranteed to be unique, or FALSE (0) otherwise.

Returns:: the 0-based index of the new field, or -1 if the field could not be created.

void MITAB_STDCALL mitab_c_close ( mitab_handle handle )

Close a dataset previously opened using mitab_c_open() or created using mitab_c_create().

Parameters:

handle

the mitab_handle of the dataset to close.

mitab_handle MITAB_STDCALL mitab_c_create	(	const char *	filename,
		const char *	mif_or_tab,
		const char *	mif_projection,
		double	north,
		double	south,
		double	east,
		double	west
	)

Create a new .TAB or .MIF dataset.

Note that it is not possible to open a file for update (i.e. read+write) with the current version of the library.

Parameters:

	filename	the complete filename (including extension .TAB or .MIF) of the file to create.
	mif_or_tab	one of "mif" to create a .MIF dataset or "tab" to create a .TAB dataset. The default is to create a TAB dataset if this parameter's value is NULL or an empty string.
	mif_projection	the projection to use for the dataset, in the same format that is used in the "CoordSys" line of a MIF file header. If this parameter's value is NULL or empty then a LAT/LON coordsys is assumed. See also mitab_c_get_mif_coordsys().
	north	the upper dataset bound. Note that valid bounds are required for a .TAB dataset otherwise data may not be stored properly in the file. MITAB knows the default bounds only for the most common MapInfo coordinate systems, passing north,south,east,west as 0,0,0,0 will instruct MITAB to attempt to use the default bounds for that projection. If no default bounds are found for this projection then your data may not be stored properly in the file unless you provide valid bounds via the north,south,east,west parameters.
	south	the lower dataset bound.
	east	the right dataset bound.
	west	the left dataset bound.

Returns:: a valid mitab_handle, or NULL if the file could not be created.

mitab_feature MITAB_STDCALL mitab_c_create_feature	(	mitab_handle	handle,
		int	feature_type
	)

Create a new mitab_feature object to be written to a dataset created using mitab_c_create().

Parameters:

	handle	the handle of the dataset opened for write access.
	feature_type	the type of feature object to create. At this point, only the following types can be created by this C API function: TABFC_NoGeom (0), TABFC_Point (1), TABFC_FontPoint (2), TABFC_CustomPoint (3), TABFC_Text (4), TABFC_Polyline (5), TABFC_Arc (6), TABFC_Region (7), TABFC_Rectangle (8), TABFC_Ellipse (9), TABFC_MultiPoint (10) and TABFC_Collection (11)

Returns:: the new mitab_feature object, or NULL if creation failed. Note that the new object will have to be released using mitab_c_destroy_feature().

void MITAB_STDCALL mitab_c_destroy_feature ( mitab_feature feature )

Destroy a mitab_feature object and release all memory associated with it.

Parameters:

feature

the mitab_feature to destroy.

int MITAB_STDCALL mitab_c_get_brush_bgcolor ( mitab_feature feature )

Get an object's brush background color property.

Applies to region, ellipse and rectangle objects.

Parameters:

feature

the mitab_feature object.

Returns:: the brush background color (24 bits RGB value).

int MITAB_STDCALL mitab_c_get_brush_fgcolor ( mitab_feature feature )

Get an object's brush foreground color property.

Applies to region, ellipse and rectangle objects.

Parameters:

feature

the mitab_feature object.

Returns:: the brush foreground color (24 bits RGB value).

int MITAB_STDCALL mitab_c_get_brush_pattern ( mitab_feature feature )

Get an object's brush pattern property.

Applies to region, ellipse and rectangle objects.

Parameters:

feature

the mitab_feature object.

Returns:: the brush pattern number (1 is none, 2 is solid fill, etc.).

int MITAB_STDCALL mitab_c_get_brush_transparent ( mitab_feature feature )

Get an object's brush transparency property.

Applies to region, ellipse and rectangle objects.

Parameters:

feature

the mitab_feature object.

Returns:: the brush transparency value, either 0 for an opaque brush (using bg color) or 1 for transparent (ignore bg color).

mitab_feature MITAB_STDCALL mitab_c_get_collection_multipoint_ref ( mitab_feature feature )

Returns a reference to the multipoint component of a collection.

The returned object is only a reference and remains owned by the collection and will remain valid only during the lifespan of the collection or until the multipoint component is overwritten. The returned feature can be modified but CANNOT be destroyed by the caller.

If the object's geometry is ever modified then a call to mitab_c_set_collection_multipoint() will be required to force updating the internal geometry of the collection.

Parameters:

feature

the TABFC_Collection feature to read from.

Returns:: the mitab_feature object that was read or NULL if there is no multipoint component in the collection.

mitab_feature MITAB_STDCALL mitab_c_get_collection_polyline_ref ( mitab_feature feature )

Returns a reference to the polyline component of a collection.

The returned object is only a reference and remains owned by the collection and will remain valid only during the lifespan of the collection or until the polyline component is overwritten. The returned feature can be modified but CANNOT be destroyed by the caller.

If the object's geometry is ever modified then a call to mitab_c_set_collection_polyline() will be required to force updating the internal geometry of the collection.

Parameters:

feature

the TABFC_Collection feature to read from.

Returns:: the mitab_feature object that was read or NULL if there is no polyline component in the collection.

mitab_feature MITAB_STDCALL mitab_c_get_collection_region_ref ( mitab_feature feature )

Returns a reference to the region component of a collection.

The returned object is only a reference and remains owned by the collection and will remain valid only during the lifespan of the collection or until the region component is overwritten. The returned feature can be modified but CANNOT be destroyed by the caller.

If the object's geometry is ever modified then a call to mitab_c_set_collection_region() will be required to force updating the internal geometry of the collection.

Parameters:

feature

the TABFC_Collection feature to read from.

Returns:: the mitab_feature object that was read or NULL if there is no region component in the collection.

const char* MITAB_STDCALL mitab_c_get_extended_mif_coordsys ( mitab_handle dataset )

Get the MIF CoordSys string from an opened dataset including the affine transformation parameters if available.

Parameters:

dataset

the mitab_handle of the source dataset.

Returns:: a string with the dataset coordinate system definition in MIF CoordSys format. Returns NULL if the information could not be read. The returned string is valid only until the next call to mitab_c_get_mif_coordsys().

MITAB_AFFINE_PARAMS

int MITAB_STDCALL mitab_c_get_extended_mif_coordsys_vb	(	mitab_handle	dataset,
		char *	coordsys,
		int	l
	)

Get the MIF CoordSys string from an opened dataset including the affine transformation parameters if available.

Parameters:

	dataset	the mitab_handle of the source dataset.
	coordsys	a string buffer to return the dataset coordinate system definition in MIF CoordSys format. This value can then be passed to mitab_c_create() to create new datasets with the same coordinate system. Returns empty string if the information could not be read.
	l	the maximum length of the coordsys string including terminating null.

Returns:: the length of the string in coordsys or zero if the information could not be read

int MITAB_STDCALL mitab_c_get_feature_count ( mitab_handle handle )

Return the number of features in a dataset.

Parameters:

handle

the dataset's handle.

Returns:: the number of features in the dataset.

double MITAB_STDCALL mitab_c_get_field_as_double	(	mitab_feature	feature,
		int	field
	)

Fetch an attribute field value in a mitab_feature as a double.

Parameters:

	feature	the mitab_feature object.
	field	the index of the field to look at, with 0 being the first field.

Returns:: the value of the field converted to double.

const char* MITAB_STDCALL mitab_c_get_field_as_string	(	mitab_feature	feature,
		int	field
	)

Fetch an attribute field value in a mitab_feature as a string.

The function returns a reference to an internal string buffer that contains the string representation of the attribute field's value (integer and floating point values are converted to string using sprintf()).

Parameters:

	feature	the mitab_feature object.
	field	the index of the field to look at, with 0 being the first field.

Returns:: a string containing the value of the field. The returned string pointer is a reference to an internal buffer and should not be modified or freed by the caller. Its value will be valid only until the next call to mitab_c_get_field().

int MITAB_STDCALL mitab_c_get_field_as_string_vb	(	mitab_feature	feature,
		int	field,
		char *	value,
		int	l
	)

Fetch an attribute field value in a mitab_feature as a string (VB Version).

The function returns a reference to the string representation of the attribute field's value (integer and floating point values are converted to string using sprintf()).

Parameters:

	feature	the mitab_feature object.
	field	the index of the field to look at, with 0 being the first field.
	value	string buffer to return the value of the field.
	l	the maximum lenght of the value string including terminating null.

Returns:: the length of the string containing the value of the field.

int MITAB_STDCALL mitab_c_get_field_count ( mitab_handle handle )

Return the number of attribute fields in a dataset's schema.

Parameters:

handle

the dataset's handle.

Returns:: the number of attribute fields defined in the dataset.

const char* MITAB_STDCALL mitab_c_get_field_name	(	mitab_handle	handle,
		int	field
	)

Return the name of an attribute field in a dataset's schema.

Parameters:

	handle	the dataset's handle.
	field	the index of the field to look at, with 0 being the first field.

Returns:: the field name. The returned string pointer is a reference to an internal buffer and should not be modified or freed by the caller.

int MITAB_STDCALL mitab_c_get_field_name_vb	(	mitab_handle	handle,
		int	field,
		char *	name,
		int	l
	)

Return the name of an attribute field in a dataset's schema (VB version).

Parameters:

	handle	the dataset's handle.
	field	the index of the field to look at, with 0 being the first field.
	name	string buffer to return the field name.
	l	the maximum lenght of the name string including terminating null.

Returns:: the length of the field name.

int MITAB_STDCALL mitab_c_get_field_precision	(	mitab_handle	handle,
		int	field
	)

Return the precision of an attribute field in a dataset's schema.

Parameters:

	handle	the dataset's handle.
	field	the index of the field to look at, with 0 being the first field.

Returns:: the field precision.

int MITAB_STDCALL mitab_c_get_field_type	(	mitab_handle	handle,
		int	field
	)

Return the type of an attribute field in a dataset's schema.

Parameters:

	handle	the dataset's handle.
	field	the index of the field to look at, with 0 being the first field.

Returns:: the field type, one of TABFT_Char (1), TABFT_Integer (2), TABFT_SmallInt (3), TABFT_Decimal (4), TABFT_Float (5), TABFT_Date (6), or TABFT_Logical (7)

int MITAB_STDCALL mitab_c_get_field_width	(	mitab_handle	handle,
		int	field
	)

Return the width of an attribute field in a dataset's schema.

Parameters:

	handle	the dataset's handle.
	field	the index of the field to look at, with 0 being the first field.

Returns:: the field width.

const char* MITAB_STDCALL mitab_c_get_font ( mitab_feature feature )

Get the font name from a TABFC_Text or TABFC_FontPoint object, or the symbol name from a TABFC_CustomPoint.

Parameters:

feature

the mitab_feature object.

Returns:: the text font name.

int MITAB_STDCALL mitab_c_get_font_vb	(	mitab_feature	feature,
		char *	font,
		int	l
	)

Get the font name from a TABFC_Text or TABFC_FontPoint object, or the symbol name from a TABFC_CustomPoint.

(VB Version)

Parameters:

	feature	the mitab_feature object.
	font	string buffer to return the text font name.
	l	the maximum lentgh of the text string including terminating null.

Returns:: the length of the text font name.

const char* MITAB_STDCALL mitab_c_get_mif_coordsys ( mitab_handle dataset )

Get the MIF CoordSys string from an opened dataset.

Parameters:

dataset

the mitab_handle of the source dataset.

Returns:: a string with the dataset coordinate system definition in MIF CoordSys format. This value can be passed to mitab_c_create() to create new datasets with the same coordinate system. Returns NULL if the information could not be read. The returned string is valid only until the next call to mitab_c_get_mif_coordsys().

int MITAB_STDCALL mitab_c_get_mif_coordsys_vb	(	mitab_handle	dataset,
		char *	coordsys,
		int	l
	)

Get the MIF CoordSys string from an opened dataset (VB Version).

Parameters:

	dataset	the mitab_handle of the source dataset.
	coordsys	a string buffer to return the dataset coordinate system definition in MIF CoordSys format. This value can then be passed to mitab_c_create() to create new datasets with the same coordinate system. Returns empty string if the information could not be read.
	l	the maximum length of the coordsys string including terminating null.

Returns:: the length of the string in coordsys or zero if the information could not be read

int MITAB_STDCALL mitab_c_get_parts ( mitab_feature feature )

Return the number of parts (rings or polyline segments) in an object.

Parameters:

feature

the mitab_feature object.

Returns:: the number of parts (in a region or polyline) or 0 if the object's geometry was not set. For all object types other than polyline region, returns 1 if object geometry is set.

int MITAB_STDCALL mitab_c_get_pen_color ( mitab_feature feature )

Get an object's pen color property.

Applies only to polyline, region, rectangle, arc and ellipse objects.

Parameters:

feature

the mitab_feature object.

Returns:: the pen color (24 bits RGB value).

int MITAB_STDCALL mitab_c_get_pen_pattern ( mitab_feature feature )

Get an object's pen pattern property.

Applies only to polyline, region, rectangle, arc and ellipse objects.

Parameters:

feature

the mitab_feature object.

Returns:: the pen pattern number (2 is default solid pen).

int MITAB_STDCALL mitab_c_get_pen_width ( mitab_feature feature )

Get an object's pen width property.

Applies only to polyline, region, rectangle, arc and ellipse objects.

Parameters:

feature

the mitab_feature object.

Returns:: the pen as defined in the MIF specs: 1-7 for pixel width, or 11-2047 for width in points (10 + (point_width*10)).

mitab_projinfo MITAB_STDCALL mitab_c_get_projinfo ( mitab_handle dataset )

Get the projinfo handle from an opened dataset.

Parameters:

dataset

the mitab_handle of the source dataset.

Returns:: a mitab_projinfo handle usable with mitab_c_set_projinfo() or NULL if the information is not available. The handle is valid only until the next call to mitab_c_get_projinfo().

double MITAB_STDCALL mitab_c_get_symbol_angle ( mitab_feature feature )

Get an font point object's angle property.

Applies only to point objects of type TABFC_FontPoint

Parameters:

feature

the mitab_feature object.

Returns:: the symbol angle in degrees

int MITAB_STDCALL mitab_c_get_symbol_color ( mitab_feature feature )

Get an object's symbol color property.

Applies only to point and multipoint objects.

Parameters:

feature

the mitab_feature object.

Returns:: the symbol color (24 bits RGB value).

int MITAB_STDCALL mitab_c_get_symbol_no ( mitab_feature feature )

Get an object's symbol number property.

Applies only to point and multipoint objects.

Parameters:

feature

the mitab_feature object.

Returns:: the symbol number (valid range: 32 to 67)

int MITAB_STDCALL mitab_c_get_symbol_size ( mitab_feature feature )

Get an object's symbol size property.

Applies only to point and multipoint objects.

Parameters:

feature

the mitab_feature object.

Returns:: the symbol size in pixels (valid range 1 to 48)

const char* MITAB_STDCALL mitab_c_get_text ( mitab_feature feature )

Get the text string on a TABFC_Text object.

Parameters:

feature

the mitab_feature object.

Returns:: the text string in the object.

double MITAB_STDCALL mitab_c_get_text_angle ( mitab_feature feature )

Fetch a TABFC_Text object's angle property.

Parameters:

feature

the mitab_feature object.

Returns:: the text angle in degrees.

int MITAB_STDCALL mitab_c_get_text_bgcolor ( mitab_feature feature )

Fetch a TABFC_Text object's background color property.

Parameters:

feature

the mitab_feature object.

Returns:: the text background color (24 bits RGB value).

int MITAB_STDCALL mitab_c_get_text_fgcolor ( mitab_feature feature )

Fetch a TABFC_Text object's foreground color property.

Parameters:

feature

the mitab_feature object.

Returns:: the text foreground color (24 bits RGB value).

double MITAB_STDCALL mitab_c_get_text_height ( mitab_feature feature )

Fetch a TABFC_Text object's MBR height property.

Parameters:

feature

the mitab_feature object.

Returns:: the height of the text's MBR in ground units.

int MITAB_STDCALL mitab_c_get_text_justification ( mitab_feature feature )

Fetch a TABFC_Text object's justification property.

Parameters:

feature

the mitab_feature object.

Returns:: the text justification, one of TABTJ_Left (0), TABTJ_Center (1), or TABTJ_Right (2).

int MITAB_STDCALL mitab_c_get_text_linetype ( mitab_feature feature )

Fetch a TABFC_Text object's linetype property.

Parameters:

feature

the mitab_feature object.

Returns:: the text linetype, one of TABTL_NoLine (0), TABTL_Simple (1), or TABTL_Arrow (2).

int MITAB_STDCALL mitab_c_get_text_spacing ( mitab_feature feature )

Fetch a TABFC_Text object's spacing property.

Parameters:

feature

the mitab_feature object.

Returns:: the text spacing, one of TABTS_1 (0), TABTS_1_5 (1), or TABTS_2 (2).

int MITAB_STDCALL mitab_c_get_text_vb	(	mitab_feature	feature,
		char *	text,
		int	l
	)

Get the text string on a TABFC_Text object (VB Version).

Parameters:

	feature	the mitab_feature object.
	text	string buffer to return the text string in the object.
	l	the maximum length of the text string including terminating null.

Returns:: the length of the text string in the object.

double MITAB_STDCALL mitab_c_get_text_width ( mitab_feature feature )

Fetch a TABFC_Text object's MBR width property.

Parameters:

feature

the mitab_feature object.

Returns:: the width of the text's MBR in ground units.

int MITAB_STDCALL mitab_c_get_type ( mitab_feature feature )

Return a mitab_feature's object type.

Parameters:

feature

the mitab_feature object.

Returns:: the feature type, one of TABFC_NoGeom (0), TABFC_Point (1), TABFC_FontPoint (2), TABFC_CustomPoint (3), TABFC_Text (4), TABFC_Polyline (5), TABFC_Arc (6), TABFC_Region (7), TABFC_Rectangle (8), TABFC_Ellipse (9), TABFC_MultiPoint (10) or TABFC_Collection (11)

int MITAB_STDCALL mitab_c_get_vertex_count	(	mitab_feature	feature,
		int	part
	)

Return the number of points in a part of a mitab_feature object.

Parameters:

	feature	the mitab_feature object.
	part	the part number we are interested in. Use 0 for objects which cannot have multiple parts.

Returns:: the number of points in that feature's part or 0 if the object has no geometry or the part number is invalid.

double MITAB_STDCALL mitab_c_get_vertex_x	(	mitab_feature	feature,
		int	part,
		int	vertex
	)

Return the X coordinate of a point in a part of a mitab_feature object.

Parameters:

	feature	the mitab_feature object.
	part	the part number we are interested in. Use 0 for objects which cannot have multiple parts.
	vertex	the point number, with 0 being the first point.

Returns:: the X coordinate of the specified point or if the object has no geometry or the part or the point number is invalid.

double MITAB_STDCALL mitab_c_get_vertex_y	(	mitab_feature	feature,
		int	part,
		int	vertex
	)

Return the Y coordinate of a point in a part of a mitab_feature object.

Parameters:

	feature	the mitab_feature object.
	part	the part number we are interested in. Use 0 for objects which cannot have multiple parts.
	vertex	the point number, with 0 being the first point.

Returns:: the Y coordinate of the specified point or if the object has no geometry or the part or the point number is invalid.

const char* MITAB_STDCALL mitab_c_getlasterrormsg ( )

Get the last error message.

Fetches the last error message posted with CPLError(), that hasn't been cleared by CPLErrorReset(). The returned pointer is to an internal string that should not be altered or freed.

Returns:: the last error message, or an empty string if there is no posted error message.

int MITAB_STDCALL mitab_c_getlasterrormsg_vb	(	char *	errormsg,
		int	l
	)

Get the last error message (VB Version).

Fetches the last error message posted with CPLError(), that hasn't been cleared by CPLErrorReset(). The returned pointer is to an internal string that should not be altered or freed.

Parameters:

	errormsg	string buffer to return the last error message (will return an empty string if there is no posted error message).
	l	the maximum length of the errormessage string including terminating null.

Returns:: the length of the last error message, or zero if there is no posted error message.

int MITAB_STDCALL mitab_c_getlasterrorno ( )

Fetch the last error number.

This is the error number, not the error class.

Returns:: the error number of the last error to occur, or CPLE_None (0) if there are no posted errors.

int MITAB_STDCALL mitab_c_getlibversion ( )

Returns the version of the library.

Returns:: an integer representing the current version of the MITAB library in the format xxxyyyzzz, e.g. returns 1002004 for v1.2.4.

int MITAB_STDCALL mitab_c_is_field_indexed	(	mitab_handle	handle,
		int	field
	)

Test whether specified field in a dataset's schema is indexed or not.

Parameters:

	handle	the dataset's handle.
	field	the index of the field to look at, with 0 being the first field.

Returns:: TRUE (1) if field is indexed, FALSE (0) otherwise.

int MITAB_STDCALL mitab_c_is_field_unique	(	mitab_handle	handle,
		int	field
	)

For indexed fields only, test whether the specified indexed field in a dataset's schema has the unique flag set.

Parameters:

	handle	the dataset's handle.
	field	the index of the field to look at, with 0 being the first field.

Returns:: TRUE (1) if indexed field has unique flag set, FALSE (0) otherwise.

int MITAB_DLL MITAB_STDCALL mitab_c_is_interior_ring	(	mitab_feature	feature,
		int	requestedringindex
	)

Return a false if te ring is the first of a polygon.

Parameters:

	feature	the mitab_feature object.
	requestedringindex	the requested ring index

Returns:: true or false depends on the part number of the ring in the polygon, true if it's not the first part of a polygon. If the feature is not a region the return value will be false.

int MITAB_STDCALL mitab_c_load_coordsys_table ( const char * filename )

Load a Coordsys bounds lookup table from an external file.

The entries from that table will be looked up in priority BEFORE the default bounds predefined for each coordsys inside the MITAB library. This allows users to override the default bounds for existing projections, and to define bounds for new projections not already supported by MITAB.

The format of the file is a simple text file with one CoordSys string per line. The CoordSys lines should follow the MIF specs, and MUST include the optional Bounds definition at the end of the line.

e.g. CoordSys Earth Projection 8, 24, "m", -63, 0, 0.9996, 500000, 0 Bounds \ (-7746230.6469039, -9998287.383889269) (8746230.6469039, 9998287.383889269)

Parameters:

filename

the filename of the table to load. Path is relative to the current working directory or can be absolute.

Returns:: 0 on success, -1 on error.

int MITAB_STDCALL mitab_c_next_feature_id	(	mitab_handle	handle,
		int	last_feature_id
	)

Iterator to get the next valid feature id when reading a dataset opened with mitab_c_open().

Parameters:

	handle	the mitab_handle of the file opened for read access.
	last_feature_id	the id of the last feature that was read. Use -1 to get first feature id in the dataset.

Returns:: the next valid feature id in the dataset, or -1 when there are no more feature ids.

mitab_handle MITAB_STDCALL mitab_c_open ( const char * pszFilename )

Open an existing .TAB or .MIF dataset for read access.

The function automatically detects the format (.MIF or .TAB) of the specified file.

Note that it is not possible to open a file for update (i.e. read+write) with the current version of the library.

Parameters:

pszFilename

the complete filename (including extension .TAB or .MIF) of the file to open.

Returns:: a valid mitab_handle, or NULL if the file could not be opened.

mitab_feature MITAB_STDCALL mitab_c_read_feature	(	mitab_handle	handle,
		int	feature_id
	)

Read a mitab_feature object from the file.

Works only with datasets opened with mitab_c_open().

Parameters:

	handle	the mitab_handle of the file opened for read access.
	feature_id	the id of the feature to read, obtained by calling mitab_c_next_feature_id().

Returns:: the mitab_feature object that was read. The object will have to be destroyed using mitab_c_destroy_feature() once you are done with it.

void MITAB_STDCALL mitab_c_set_arc	(	mitab_feature	feature,
		double	center_x,
		double	center_y,
		double	x_radius,
		double	y_radius,
		double	start_angle,
		double	end_angle
	)

Set an arc or ellipse feature parameters.

Parameters:

	feature	the mitab_feature object.
	center_x	the arc/ellipse center X coordinate.
	center_y	the arc/ellipse center Y coordinate.
	x_radius	the arc/ellipse X radius.
	y_radius	the arc/ellipse Y radius.
	start_angle	for an arc: the start angle in degrees, counterclockwise. for an ellipse, this parameter is ignored.
	end_angle	for an arc: the end angle in degrees, counterclockwise. for an ellipse, this parameter is ignored.

void MITAB_STDCALL mitab_c_set_brush	(	mitab_feature	feature,
		int	fg_color,
		int	bg_color,
		int	pattern,
		int	transparent
	)

Set an object's brush properties.

Applies to region, ellipse and rectangle objects.

See the MIF specs for more details on the meaning and valid values of each parameter.

Parameters:

	feature	the mitab_feature object.
	fg_color	the foreground color (24 bits RGB value).
	bg_color	the background color.
	pattern	the brush number (1 is none, 2 is solid fill, etc.).
	transparent	either 0 for an opaque brush (using bg color) or 1 for transparent (ignore bg color).

int MITAB_STDCALL mitab_c_set_collection_multipoint	(	mitab_feature	feature,
		mitab_feature	multipoint,
		int	make_copy
	)

Set or update the multipoint component of a collection.

This method can be used in three possible ways:

1- with a new multipoint feature to set a new multipoint component in the collection.

2- pass the multipoint handle obtained from mitab_c_get_collection_multipoint_ref() after making modifications to it to force an internal update of the multipoint geometry into the collection

3- pass NULL to remove the multipoint component of the collection.

Parameters:

	feature	the target TABFC_Collection feature.
	multipoint	the TABFC_Multipoint feature to set in the collection.
	make_copy	if set to true then a copy of the multipoint is made, otherwise the multipoint becomes owned by the collection.

Returns:: 0 on success, -1 on error.

int MITAB_STDCALL mitab_c_set_collection_polyline	(	mitab_feature	feature,
		mitab_feature	polyline,
		int	make_copy
	)

Set or update the polyline component of a collection.

This method can be used in three possible ways:

1- with a new polyline feature to set a new polyline component in the collection.

2- pass the polyline handle obtained from mitab_c_get_collection_polyline_ref() after making modifications to it to force an internal update of the polyline geometry into the collection

3- pass NULL to remove the polyline component of the collection.

Parameters:

	feature	the target TABFC_Collection feature.
	polyline	the TABFC_Polyline feature to set in the collection.
	make_copy	if set to true then a copy of the polyline is made, otherwise the polyline becomes owned by the collection.

Returns:: 0 on success, -1 on error.

int MITAB_STDCALL mitab_c_set_collection_region	(	mitab_feature	feature,
		mitab_feature	region,
		int	make_copy
	)

Set or update the region component of a collection.

This method can be used in three possible ways:

1- with a new region feature to set a new region component in the collection.

2- pass the region handle obtained from mitab_c_get_collection_region_ref() after making modifications to it to force an internal update of the region geometry into the collection

3- pass NULL to remove the region component of the collection.

Parameters:

	feature	the target TABFC_Collection feature.
	region	the TABFC_Region feature to set in the collection.
	make_copy	if set to true then a copy of the region is made, otherwise the region becomes owned by the collection.

Returns:: 0 on success, -1 on error.

void MITAB_STDCALL mitab_c_set_field	(	mitab_feature	feature,
		int	field_index,
		const char *	field_value
	)

Set the value of specified field in a feature object.

Parameters:

	feature	the mitab_feature object.
	field_index	the 0-based index of the field to set.
	field_value	a string containing the value to set the field to. For any field type, the value should always be passed using its character string representation.

void MITAB_STDCALL mitab_c_set_font	(	mitab_feature	feature,
		const char *	fontname
	)

Set the font name in a a TABFC_Text or TABFC_FontPoint object, or set the symbol name in a TABFC_CustomPoint.

Parameters:

	feature	the mitab_feature object.
	fontname	the new font name.

void MITAB_STDCALL mitab_c_set_pen	(	mitab_feature	feature,
		int	width,
		int	pattern,
		int	color
	)

Set an object's pen properties.

Applies only to polyline, region, rectangle, arc and ellipse objects.

See the MIF specs for more details on the meaning and valid values of each parameter.

Parameters:

	feature	the mitab_feature object.
	width	the pen width as defined in the MIF specs: 1-7 for pixel width, or 11-2047 for width in points (10 + (point_width*10))
	pattern	the pen number (2 is default solid pen).
	color	the pen color (24 bits RGB value).

void MITAB_STDCALL mitab_c_set_points	(	mitab_feature	feature,
		int	part,
		int	vertex_count,
		double *	x,
		double *	y
	)

Set the feature's coordinates.

Parameters:

	feature	the mitab_feature object.
	part	the part number. Applies only to a region or a polyline, it is ignored for other object types. For regions and polyline, with multiple parts, call mitab_c_set_points() once for each part of the object (ring or polyline segment), starting with 0 for the first part. Note that it is only possible to add parts in a sequential order, and it is not possible to overwrite or modify existing parts using this function. For regions with multiple islands and holes, passing a negative part number will result in adding a new island (i.e. polygon). By default, parts > 1 are treated as holes in the last island (polygon) that was created.
	vertex_count	the number of points (pairs of x,y values).
	x	the array of 'vertex_count' X values. Note: for rectangle objects, the MBR of the array of points defines rectangle corners.
	y	the array of 'vertex_count' Y values.

int MITAB_STDCALL mitab_c_set_projinfo	(	mitab_handle	dataset,
		mitab_projinfo	projinfo
	)

Set the projinfo on a newly created dataset.

Should be called immediately after creating the dataset and before adding features to it.

Parameters:

	dataset	the mitab_handle of the target dataset.
	projinfo	the mitab_projinfo to set on the target dataset, obtained from mitab_c_get_projinfo().

Returns:: 0 on success, -1 on failure.

int MITAB_STDCALL mitab_c_set_quick_spatial_index_mode ( mitab_handle dataset )

Select "quick spatial index mode".

The default behavior of MITAB is to generate an optimized spatial index, but this results in slower write speed.

Applications that want faster write speed and do not care about the performance of spatial queries on the resulting file can use this function to require the creation of a non-optimal spatial index (actually emulating the type of spatial index produced by MITAB before version 1.6.0). In this mode writing files can be about 5 times faster, but spatial queries can be up to 30 times slower.

mitab_c_set_quick_spatial_index_mode() must be called immediately after mitab_c_create() and before starting to write any data to the file. This function applies only to newly created TAB files and does not do anything useful for MIF files.

Parameters:

dataset

the mitab_handle of the newly created dataset.

Returns:: 0 on success, -1 on error.

void MITAB_STDCALL mitab_c_set_symbol	(	mitab_feature	feature,
		int	symbol_no,
		int	symbol_size,
		int	symbol_color
	)

Set an object's symbol properties.

Applies only to point objects and multipoint.

See the MIF specs for more details on the meaning and valid values of each parameter.

Parameters:

	feature	the mitab_feature object.
	symbol_no	the symbol number (valid range: 32 to 67)
	symbol_size	the symbol size in pixels (valid range 1 to 48)
	symbol_color	the symbol color (24 bits RGB value)

void MITAB_STDCALL mitab_c_set_symbol_angle	(	mitab_feature	feature,
		double	symbol_angle
	)

Set the point symbol's angle.

Applies only to point objects of type TABFC_FontPoint.

Parameters:

	feature	the mitab_feature object.
	symbol_angle	the symbol angle in degrees

void MITAB_STDCALL mitab_c_set_text	(	mitab_feature	feature,
		const char *	text
	)

Set the text string on a TABFC_Text object.

Parameters:

	feature	the mitab_feature object.
	text	the text string to set in the object.

void MITAB_STDCALL mitab_c_set_text_display	(	mitab_feature	feature,
		double	angle,
		double	height,
		double	width,
		int	fg_color,
		int	bg_color,
		int	justification,
		int	spacing,
		int	linetype
	)

Set a TABFC_Text object's display properties.

See the MIF specs for more details on the meaning and valid values of each parameter.

Parameters:

	feature	the mitab_feature object.
	angle	the text angle in degrees.
	height	the height of the text's MBR in ground units.
	width	the width of the text's MBR in ground units.
	fg_color	foreground color (24 bits RGB value).
	bg_color	background color.
	justification	one of TABTJ_Left (0), TABTJ_Center (1), or TABTJ_Right (2).
	spacing	one of TABTS_1 (0), TABTS_1_5 (1), or TABTS_2 (2)
	linetype	one of TABTL_NoLine (0), TABTL_Simple (1), or TABTL_Arrow (2).

int MITAB_STDCALL mitab_c_write_feature	(	mitab_handle	handle,
		mitab_feature	feature
	)

Write a new feature to a dataset.

Works only with datasets created using mitab_c_create().

The feature to write should have been created using mitab_c_create_feature() and its attributes and coordinate information set prior to calling this function.

Also note that the mitab_feature object will NOT be owned by the dataset after this call and it is still the responsibility of the caller to destroy it.

Parameters:

	handle	the mitab_handle of the dataset opened for write access.
	feature	the mitab_feature to write to the dataset.

Returns:: TRUE (1) on success, FALSE (0) on error.

mitab_capi.cpp File Reference

Defines

Functions

Detailed Description

Function Documentation