Represents GDAL/OGR vector datasource which may be represented by spatial database or file-based vector format. More...
Public Member Functions | |
void | Close () |
Closes datasource and underlying connection. More... | |
bool | CreateLayer (string layerName, ShpfileType ShpType, GeoProjection Projection=null, string creationOptions="") |
Creates a new empty layer in the datasource. More... | |
bool | DeleteLayer (int layerIndex) |
Deletes a layer with specified index from datasource. More... | |
bool | ExecuteSQL (string sql, out string errorMessage) |
Executes SQL statement against datasource. More... | |
string | get_DriverMetadata (tkGdalDriverMetadata metadata) |
Returns certain type of metadata associated with current driver. More... | |
string | get_DriverMetadataItem (int metadataIndex) |
Gets metadata item with specified index associated with current driver. More... | |
string | get_ErrorMsg (int ErrorCode) |
Gets the description of the specific error code. More... | |
OgrLayer | GetLayer (int Index, bool forUpdate=false) |
Gets a layer with specified index from datasource. More... | |
OgrLayer | GetLayer2 (int Index, bool forUpdate, bool newConnection) |
OgrLayer | GetLayerByName (string layerName, bool forUpdate=false) |
Gets a layer with specified name from the datasource. More... | |
string | GetLayerName (int layerIndex) |
Gets a name of the layer with particular index. More... | |
object | GetSchemas () |
Gets the array with schema names in the datasources. More... | |
bool | ImportShapefile (Shapefile shapefile, string layerName, string creationOptions="", tkShapeValidationMode validationMode=tkShapeValidationMode.TryFixSkipOnFailure) |
Creates a new layer in the datasource and populates it with data from specified shapefile. More... | |
int | LayerIndexByName (string layerName) |
Returns index of layer with the specified name. More... | |
bool | Open (string connectionString) |
Opens particular type of datasource supported by GDAL/OGR. More... | |
bool | Open2 (string connectionString, bool forUpdate) |
Opens particular type of datasource supported by GDAL/OGR. More... | |
OgrLayer | RunQuery (string sql) |
Runs a query against datasource and returns the result as a temporary layer. More... | |
bool | TestCapability (tkOgrDSCapability capability) |
Test whether driver of the currently opened datasource supports particular capability. More... | |
Properties | |
int | DriverMetadataCount [get] |
Gets the number of metadata items associated with current driver. More... | |
string | DriverName [get] |
Gets name driver (name of format) for this datasource. More... | |
string | GdalLastErrorMsg [get] |
Extracts the last error message reported by GDAL library. More... | |
ICallback | GlobalCallback [get, set] |
Gets or sets a Callback object which handles progress and error messages. More... | |
string | Key [get, set] |
Gets or sets a text string associated with object. Any value can be stored by developer in this property. More... | |
int | LastErrorCode [get] |
Gets code of the last error which took place inside this object. More... | |
int | LayerCount [get] |
Gets number of layers in the datasource. More... | |
Represents GDAL/OGR vector datasource which may be represented by spatial database or file-based vector format.
The class can be used to access various vector datasources supported by GDAL/OGR. Depending on driver, datasources may be represented by particular file formats ( ESRI Shapefile, MapInfo TAB, KML, etc) or spatial databases (PostGIS, Microsoft SQL Server, SpatiaLite, etc). See the full list of formats in GDAL documentation.
OgrDatasource can be used for such tasks as:
An instance of OgrDatasource can't be added to the map directly, but instances of OgrLayer class opened by its methods can.
OgrDatasource encapsulates an instance of GDALDataset C++ class. Check its documentation to better understand what's going on under the hood.
Here is code sample which lists all layers available in PostGIS database.
See more samples in description of particular methods.
String encoding.
OgrDatasource and OgrLayer classes by default use UTF-8 string encoding to interact with underlying drivers. This applies to connection strings, layer names, SQL queries and error messages. This behavior can be changed by setting GlobalSettings.OgrStringEncoding property. The new setting will be used immediately by all existing and new objects. See details about string encoding in the documentation of particular OGR driver.
Here is a diagram for the OgrDatasource class.
void OgrDatasource.Close | ( | ) |
Closes datasource and underlying connection.
This method should be called as soon as datasource is no longer needed.
bool OgrDatasource.CreateLayer | ( | string | layerName, |
ShpfileType | ShpType, | ||
GeoProjection | Projection = null , |
||
string | creationOptions = "" |
||
) |
Creates a new empty layer in the datasource.
SRID will be set to 0 if null or empty GeoProjection object is passed. See OgrDatasource.ImportShapefile for the details on creation options.
Known issues: creation of layer in nonexistent schema in PostGIS databases completes successfully, yet the neither schema nor objects in it are visible afterwards.
layerName | Name of the new layer. |
ShpType | ShpType of the new layer. Will be converted to appropriate OGRwkbGeometryType. |
Projection | GeoProjection object which sets SRID of the new layer. |
creationOptions | Format specific creation options separated with semicolon, e.g. "OVERWRITE=YES;MW_MULTI_PART=no". |
bool OgrDatasource.DeleteLayer | ( | int | layerIndex | ) |
Deletes a layer with specified index from datasource.
Use OgrDatasource.TestCapability(tkOgrDSCapability.odcDeleteLayer) to check whether functionality is supported by particular driver.
layerIndex | Layer index within datasource. |
bool OgrDatasource.ExecuteSQL | ( | string | sql, |
out string | errorMessage | ||
) |
Executes SQL statement against datasource.
Should be used for non-SELECT instructions which don't return resulting set of rows. To select data use OgrDatasource.RunQuery instead.
sql | SQL instruction. |
errorMessage | Error message provided in case of failure. |
The following code deletes records from underlying database table with gid > 100.
string OgrDatasource.get_DriverMetadata | ( | tkGdalDriverMetadata | metadata | ) |
Returns certain type of metadata associated with current driver.
metadata | Type of metadata to be returned. |
string OgrDatasource.get_DriverMetadataItem | ( | int | metadataIndex | ) |
Gets metadata item with specified index associated with current driver.
metadataIndex | Index of metadata item to be returned. |
string OgrDatasource.get_ErrorMsg | ( | int | ErrorCode | ) |
Gets the description of the specific error code.
ErrorCode | The error code returned by LastErrorCode property. |
OgrLayer OgrDatasource.GetLayer | ( | int | Index, |
bool | forUpdate = false |
||
) |
Gets a layer with specified index from datasource.
Resulting OgrLayer has no reference to OgrDatasource object, which can safely closed if it is no longer needed.
Index | Index of layer to be returned. |
forUpdate | Indicates whether the returned layer will support saving of changes back to source (the functionality should be supported by particular driver). |
The following code adds all layers found in the datasource to the map:
See more details on projection & coordinates strategies in Map projection and coordinates section.
OgrLayer OgrDatasource.GetLayer2 | ( | int | Index, |
bool | forUpdate, | ||
bool | newConnection | ||
) |
OgrLayer OgrDatasource.GetLayerByName | ( | string | layerName, |
bool | forUpdate = false |
||
) |
Gets a layer with specified name from the datasource.
In case of spatial databases layerName corresponds to name of the underlying table. However there can be some format specifics. For example name may include schema prefix and name of geometry column (in case there is more than one geometry column in the table). For example, "public.buildings(geom2)" may correspond to "geom2" column of table named "buildings" in "public" schema.
Resulting layer has no reference to OgrDatasource object, which can safely closed if it is no longer needed.
layerName | Layer name (case insensitive). |
forUpdate | Indicates whether the returned layer will support saving of changes back to source (the functionality should be supported by particular driver). |
string OgrDatasource.GetLayerName | ( | int | layerIndex | ) |
Gets a name of the layer with particular index.
layerIndex | Index of layer. |
object OgrDatasource.GetSchemas | ( | ) |
Gets the array with schema names in the datasources.
bool OgrDatasource.ImportShapefile | ( | Shapefile | shapefile, |
string | layerName, | ||
string | creationOptions = "" , |
||
tkShapeValidationMode | validationMode = tkShapeValidationMode.TryFixSkipOnFailure |
||
) |
Creates a new layer in the datasource and populates it with data from specified shapefile.
The list of available creation options can be found in GDAL on-line documentation or retrieved by calling OgrDatasource.get_DriverMetadata(tkGdalDriverMetadata.dmdLAYER_CREATIONOPTIONLIST).
In addition MapWinGIS defines its own options:
shapefile | Shapefile to import. |
layerName | Name for the imported layer. |
creationOptions | Format specific creation options separated with semicolon, e.g. "OVERWRITE=YES;MW_MULTI_PART=no". |
validationMode | Sets validation mode for input shapes, ranging from no validation to abort the whole operation on the first invalid shape. |
The following code imports all shapefiles from the specified folder as layers into the datasource.
int OgrDatasource.LayerIndexByName | ( | string | layerName | ) |
Returns index of layer with the specified name.
layerName | Layer name (case insensitive). |
bool OgrDatasource.Open | ( | string | connectionString | ) |
Opens particular type of datasource supported by GDAL/OGR.
See details about connection strings here: http://www.gdal.org/ogr_formats.html
connectionString | Connection string for RDMSs or filename for file-based formats. |
bool OgrDatasource.Open2 | ( | string | connectionString, |
bool | forUpdate | ||
) |
Opens particular type of datasource supported by GDAL/OGR.
See details about connection strings here: http://www.gdal.org/ogr_formats.html
connectionString | Connection string for RDMSs or filename for file-based formats. |
forUpdate | Indicates whether datasource will be opened with update flag. |
OgrLayer OgrDatasource.RunQuery | ( | string | sql | ) |
Runs a query against datasource and returns the result as a temporary layer.
Usually some sort of SELECT query returning a set of rows with one or several geometry columns is expected here. Other types of SQL instructions will also be processed, however OgrDatasource.ExecuteSQL is recommended way to do it.
Resulting layer has no reference to OgrDatasource object, which can safely closed if it is no longer needed.
sql | SQL query. |
The following code builds 0.01 degree buffer zones around waterways layer extracted from database and displays both waterways and buffer layers on the map. st_buffer function is supported by PostGIS. See documentation of particular spatial database for list of supported functions and their arguments.
bool OgrDatasource.TestCapability | ( | tkOgrDSCapability | capability | ) |
Test whether driver of the currently opened datasource supports particular capability.
capability | A capability to test. |
|
get |
Gets the number of metadata items associated with current driver.
|
get |
Gets name driver (name of format) for this datasource.
|
get |
Extracts the last error message reported by GDAL library.
|
getset |
Gets or sets a Callback object which handles progress and error messages.
|
getset |
Gets or sets a text string associated with object. Any value can be stored by developer in this property.
|
get |
Gets code of the last error which took place inside this object.
|
get |
Gets number of layers in the datasource.