Get the text string on a TABFC_Text object (VB Version).More...
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.More...
Get the MIF CoordSys string from an opened dataset (VB Version).More...
Detailed Description
MITAB C API.
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 also mitabc_test.cpp which for examples of use of the C API.
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)
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.
Returns:
the 0-based index of the new field, or -1 if the field could not
be created.
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.
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_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) and
TABFC_MultiPoint (10)
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).
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.
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)).
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().
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) or TABFC_MultiPoint (10).
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.
point
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.
point
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.
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_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_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.
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).
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.
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_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.