12
12
* (at your option) any later version. *
14
14
***************************************************************************/
15
/* $Id: qgsvectordataprovider.h 5595 2006-07-14 03:11:25Z morb_au $ */
16
16
#ifndef QGSVECTORDATAPROVIDER_H
17
17
#define QGSVECTORDATAPROVIDER_H
25
// XXX no signals or slots so not needed #include <qobject.h>
29
#include <qgsdataprovider.h>
30
#include <qgsspatialrefsys.h>
31
#include <qgssearchstring.h>
27
#include "qgsdataprovider.h"
28
#include "qgsvectorlayer.h"
33
/** Base class for vector data providers
32
* This is the base class for vector data providers.
34
* Data providers abstract the retrieval and writing (where supported)
35
* of feature and attribute information from a spatial datasource.
36
class QgsVectorDataProvider : public QgsDataProvider
39
class CORE_EXPORT QgsVectorDataProvider : public QgsDataProvider
39
// XXX no signals or slots, so not needed Q_OBJECT
43
// If you add to this, please also add to capabilitiesString()
48
DeleteFeatures = 1 << 1,
49
ChangeAttributeValues = 1 << 2,
50
AddAttributes = 1 << 3, // TODO: what is this exactly?
51
DeleteAttributes = 1 << 4,
52
SaveAsShapefile = 1 << 5,
53
CreateSpatialIndex = 1 << 6,
55
ChangeGeometries = 1 << 8,
56
SelectGeometryAtId = 1 << 9,
57
RandomSelectGeometryAtId = 1 << 10,
58
SequentialSelectGeometryAtId = 1 << 11
61
QgsVectorDataProvider();
63
QgsVectorDataProvider( QString const & uri );
65
virtual ~QgsVectorDataProvider() {};
68
* Returns the permanent storage type for this layer as a friendly name.
70
virtual QString storageType() { return "Generic vector file"; };
73
* Select features based on a bounding rectangle. Features can be retrieved
74
* with calls to getFirstFeature and getNextFeature. Request for features
75
* for use in drawing the map canvas should set useIntersect to false.
76
* @param mbr QgsRect containing the extent to use in selecting features
77
* @param useIntersect If true, use the intersects function to select features
78
* rather than the PostGIS && operator that selects based on bounding box
82
virtual void select(QgsRect *mbr, bool useIntersect=false)=0;
84
* Update the feature count based on current spatial filter. If not
85
* overridden in the data provider this function returns -1
87
virtual long updateFeatureCount()
93
* Gets the feature at the given feature ID.
96
virtual QgsFeature * getFeatureAtId(int featureId)
102
* Get the first feature resulting from a select operation
105
virtual QgsFeature * getFirstFeature(bool fetchAttributes = false) = 0;
108
* Get the next feature resutling from a select operation
111
virtual QgsFeature * getNextFeature(bool fetchAttributes = false) = 0;
113
/**Get the next feature resulting from a select operation.
114
*@param attlist a list containing the indexes of the attribute fields to copy
115
* @param featureQueueSize a hint to the provider as to how many features are likely to be retrieved in a batch
117
// virtual QgsFeature* getNextFeature(std::list<int> const & attlist) = 0;
119
virtual QgsFeature* getNextFeature(std::list<int> const & attlist, int featureQueueSize = 1) { return 0; }
122
* Get the next feature using new method
123
* TODO - make this pure virtual once it works and change existing providers
124
* to use this method of fetching features
127
virtual bool getNextFeature(QgsFeature &feature, bool fetchAttributes = false) = 0;
129
/** Get feature type.
130
* Gets the feature type as defined in WKBTYPE (qgis.h).
131
* @return int representing the feature type
133
virtual int geometryType() const = 0;
137
* Number of features in the layer
138
* @return long containing number of features
140
virtual long featureCount() const = 0;
143
* Get the attributes associated with a feature
144
* TODO: Get rid of "row" and set up provider-internal caching instead
146
virtual void getFeatureAttributes(int key, int& row, QgsFeature *f) {};
149
* Fetch geometry for a particular feature with id "key",
150
* modifies "f" in-place.
152
* This function is enabled if capabilities() returns "SelectGeometryAtId".
154
virtual void getFeatureGeometry(int key, QgsFeature *f) {};
157
* Number of attribute fields for a feature in the layer
159
virtual int fieldCount() const = 0;
162
* Return a list of field names for this layer
163
* @return vector of field names
165
virtual std::vector<QgsField> const & fields() const = 0;
168
* Reset the layer to clear any spatial filtering or other contstraints that
169
* would prevent the entire record set from being traversed by call to
170
* getNextFeature(). Some data stores may not require any special action to
171
* reset the layer. In this case, the provider should simply implement an empty
174
virtual void reset() = 0;
176
/**Returns the minimum value of an attributs
177
@param position the number of the attribute*/
178
virtual QString minValue(int position) = 0;
180
/**Returns the maximum value of an attributs
181
@param position the number of the attribute*/
182
virtual QString maxValue(int position) = 0;
184
/**Adds a list of features
185
@return true in case of success and false in case of failure*/
186
virtual bool addFeatures(std::list<QgsFeature*> const flist);
189
@param id list containing feature ids to delete
190
@return true in case of success and false in case of failure*/
191
virtual bool deleteFeatures(std::list<int> const & id);
193
/**Adds new attributes
194
@param name map with attribute name as key and type as value
195
@return true in case of success and false in case of failure*/
196
virtual bool addAttributes(std::map<QString,QString> const & name);
198
/**Deletes existing attributes
199
@param names of the attributes to delete
200
@return true in case of success and false in case of failure*/
201
virtual bool deleteAttributes(std::set<QString> const & name);
203
/**Changes attribute values of existing features
204
@param attr_map a map containing the new attributes. The integer is the feature id,
205
the first QString is the attribute name and the second one is the new attribute value
206
@return true in case of success and false in case of failure*/
207
virtual bool changeAttributeValues(std::map<int,std::map<QString,QString> > const & attr_map);
209
/**Returns the default value for attribute @c attr for feature @c f. */
210
virtual QString getDefaultValue(const QString & attr, QgsFeature* f);
213
Changes geometries of existing features
214
@param geometry_map A std::map containing the feature IDs to change the geometries of.
215
the second map parameter being the new geometries themselves
216
@return true in case of success and false in case of failure
218
virtual bool changeGeometryValues(std::map<int, QgsGeometry> & geometry_map);
221
* Identify features within the search radius specified by rect
222
* @param rect Bounding rectangle of search radius
223
* @return std::vector containing QgsFeature objects that intersect rect
225
virtual std::vector<QgsFeature>& identify(QgsRect *rect) = 0;
227
/** saves current data as Shape file, if it can */
228
virtual bool saveAsShapefile()
234
/**Creates a spatial index on the datasource (if supported by the provider type). Returns true in case of success*/
235
virtual bool createSpatialIndex();
237
/** Sets filter based on attribute values. Returns false when input string contains errors */
238
virtual bool setAttributeFilter(const QgsSearchString& attributeFilter);
240
/** Returns current attribute filter */
241
virtual QgsSearchString getAttributeFilter() { return mAttributeFilter; }
243
/** Returns a bitmask containing the supported capabilities
244
Note, some capabilities may change depending on whether
245
a spatial filter is active on this provider, so it may
246
be prudent to check this value per intended operation.
248
virtual int capabilities() const {return QgsVectorDataProvider::NoCapabilities;}
251
* Returns the above in friendly format.
253
QString capabilitiesString() const;
255
const std::list<QString>& nonNumericalTypes(){return mNonNumericalTypes;}
256
const std::list<QString>& numericalTypes(){return mNumericalTypes;}
258
virtual void setEncoding(const QString& e);
259
QString encoding() const;
261
/*! Indicates if the provider does its own coordinate transforms
262
* @return true if the provider transforms its coordinates, otherwise false
264
virtual bool supportsNativeTransform(){return false;};
265
/*! Used to determine if the provider supports transformation using the
266
* SRID of the target SRS.
268
* @note XXXXX WARNING THIS METHOD WILL BE DEPRECATED
269
* XXXXX in favour of SpatialRefSys accessors
270
* XXXXX and mutators!
272
* @return true if SRID is used, otherwise false
274
virtual bool usesSrid(){return false;};
275
/*! Used to determine if the provider supports transformation using the
276
* WKT of the target SRS.
278
* @note XXXXX WARNING THIS METHOD WILL BE DEPRECATED
279
* XXXXX in favour of SpatialRefSys accessors
280
* XXXXX and mutators!
282
* @return true if WKT is used, otherwise false
284
virtual bool usesWKT(){return false;};
285
/*! Set the SRID of the target SRS.
286
* This is only implemented if the provider supports native
287
* transformation of its coordinates
289
* @note XXXXX WARNING THIS METHOD WILL BE DEPRECATED
290
* XXXXX in favour of SpatialRefSys accessors
291
* XXXXX and mutators!
293
* @param srid Spatial reference id of the target (map canvas)
295
virtual void setSrid(int srid){};
296
/*! Get the SRID of the target SRS
297
* If the provider isn't capable of reporting the SRID of
298
* the projection, ti will return 0
300
* @note XXXXX WARNING THIS METHOD WILL BE DEPRECATED
301
* XXXXX in favour of SpatialRefSys accessors
302
* XXXXX and mutators!
305
virtual int getSrid(){return 0;};
306
/*! Set the WKT of the target SRS.
307
* This is only implemented if the provider supports native
308
* transformation of its coordinates
310
* @note XXXXX WARNING THIS METHOD WILL BE DEPRECATED
311
* XXXXX in favour of SpatialRefSys accessors
312
* XXXXX and mutators!
314
* @param wkt Well known text of the target (map canvas) SRS
316
virtual void setWKT(QString wkt){};
318
/**Returns the index of a field name or -1 if the field does not exist*/
319
int indexFromFieldName(const QString& fieldName) const;
323
QTextCodec* mEncoding;
324
/**List of type names for non-numerical types*/
325
std::list<QString> mNonNumericalTypes;
326
/**List of type names for numerical types*/
327
std::list<QString> mNumericalTypes;
328
/** attribute filter (in 'simple search string' format) */
329
QgsSearchString mAttributeFilter;
331
/** The spatial reference id of the map canvas. This is the
332
* SRID the provider should transform its coordinates to if
333
* supportsNativeTransform is true. Otherwise this member is unused.
335
* @note XXXXX WARNING THIS MEMBER WILL BE DEPRECATED
336
* XXXXX in favour of SpatialRefSys accessors
337
* XXXXX and mutators!
341
/** The WKT of the SRS of the map canvas. This is the
342
* SRS the provider should transform its coordinates to if
343
* supportsNativeTransform is true. Otherwise this member is unused.
344
* The provider may choose to support transformation using SRID or WKT.
346
* @note XXXXX WARNING THIS MEMBER WILL BE DEPRECATED
347
* XXXXX in favour of SpatialRefSys accessors
348
* XXXXX and mutators!
43
// If you add to this, please also add to capabilitiesString()
45
* enumeration with capabilities that providers might implement
49
/** provider has no capabilities */
51
/** allows adding features */
53
/** allows deletion of features */
54
DeleteFeatures = 1 << 1,
55
/** allows modification of attribute values */
56
ChangeAttributeValues = 1 << 2,
57
/** allows addition of new attributes (fields) */
58
AddAttributes = 1 << 3,
59
/** allows deletion of attributes (fields) */
60
DeleteAttributes = 1 << 4,
61
/** DEPRECATED - do not use */
62
SaveAsShapefile = 1 << 5,
63
/** allows creation of spatial index */
64
CreateSpatialIndex = 1 << 6,
65
/** fast access to features using their ID */
67
/** allows modifications of geometries */
68
ChangeGeometries = 1 << 8,
69
/** DEPRECATED - do not use */
70
SelectGeometryAtId = 1 << 9,
71
/** DEPRECATED - do not use */
72
RandomSelectGeometryAtId = 1 << 10,
73
/** DEPRECATED - do not use */
74
SequentialSelectGeometryAtId = 1 << 11,
77
/** bitmask of all provider's editing capabilities */
78
const static int EditingCapabilities = AddFeatures | DeleteFeatures |
79
ChangeAttributeValues | ChangeGeometries | AddAttributes | DeleteAttributes;
82
* Constructor of the vector provider
83
* @param uri uniform resource locator (URI) for a dataset
85
QgsVectorDataProvider( QString uri = QString() );
90
virtual ~QgsVectorDataProvider();
93
* Returns the permanent storage type for this layer as a friendly name.
95
virtual QString storageType() const;
97
/** Select features based on a bounding rectangle. Features can be retrieved with calls to nextFeature.
98
* @param fetchAttributes list of attributes which should be fetched
99
* @param rect spatial filter
100
* @param fetchGeometry true if the feature geometry should be fetched
101
* @param useIntersect true if an accurate intersection test should be used,
102
* false if a test based on bounding box is sufficient
104
virtual void select( QgsAttributeList fetchAttributes = QgsAttributeList(),
105
QgsRectangle rect = QgsRectangle(),
106
bool fetchGeometry = true,
107
bool useIntersect = false ) = 0;
110
* Update the feature count based on current spatial filter. If not
111
* overridden in the data provider this function returns -1
113
virtual long updateFeatureCount();
116
* Gets the feature at the given feature ID.
117
* @param featureId of the feature to be returned
118
* @param feature which will receive the data
119
* @param fetchGeometry flag which if true, will cause the geometry to be fetched from the provider
120
* @param fetchAttributes a list containing the indexes of the attribute fields to copy
121
* @return True when feature was found, otherwise false
123
* Default implementation traverses all features until it finds the one with correct ID.
124
* In case the provider supports reading the feature directly, override this function.
126
virtual bool featureAtId( int featureId,
128
bool fetchGeometry = true,
129
QgsAttributeList fetchAttributes = QgsAttributeList() );
132
* Get the next feature resulting from a select operation.
133
* @param feature feature which will receive data from the provider
134
* @return true when there was a feature to fetch, false when end was hit
136
virtual bool nextFeature( QgsFeature& feature ) = 0;
140
* @return int representing the feature type
142
virtual QGis::WkbType geometryType() const = 0;
146
* Number of features in the layer
147
* @return long containing number of features
149
virtual long featureCount() const = 0;
153
* Number of attribute fields for a feature in the layer
155
virtual uint fieldCount() const = 0;
158
* Return a map of indexes with field names for this layer
159
* @return map of fields
162
virtual const QgsFieldMap &fields() const = 0;
165
* Return a short comment for the data that this provider is
166
* providing access to (e.g. the comment for postgres table).
168
virtual QString dataComment() const;
170
/** Restart reading features from previous select operation */
171
virtual void rewind() = 0;
174
* Returns the minimum value of an attribute
175
* @param index the index of the attribute
177
* Default implementation walks all numeric attributes and caches minimal
178
* and maximal values. If provider has facilities to retrieve minimal
179
* value directly, override this function.
181
virtual QVariant minimumValue( int index );
184
* Returns the maximum value of an attribute
185
* @param index the index of the attribute
187
* Default implementation walks all numeric attributes and caches minimal
188
* and maximal values. If provider has facilities to retrieve maximal
189
* value directly, override this function.
191
virtual QVariant maximumValue( int index );
194
* Return unique values of an attribute
195
* @param index the index of the attribute
196
* @param values reference to the list to fill
197
* @param limit maxmum number of the values to return (added in 1.4)
199
* Default implementation simply iterates the features
201
virtual void uniqueValues( int index, QList<QVariant> &uniqueValues, int limit = -1 );
203
/**Returns the possible enum values of an attribute. Returns an empty stringlist if a provider does not support enum types
204
or if the given attribute is not an enum type.
205
* @param index the index of the attribute
206
* @param enumList reference to the list to fill
207
@note: added in version 1.2*/
208
virtual void enumValues( int index, QStringList& enumList ) { Q_UNUSED( index ); enumList.clear(); }
211
* Adds a list of features
212
* @return true in case of success and false in case of failure
214
virtual bool addFeatures( QgsFeatureList &flist );
217
* Deletes one or more features
218
* @param id list containing feature ids to delete
219
* @return true in case of success and false in case of failure
221
virtual bool deleteFeatures( const QgsFeatureIds &id );
224
* Adds new attributes
225
* @param attributes list of new attributes
226
* @return true in case of success and false in case of failure
229
virtual bool addAttributes( const QList<QgsField> &attributes );
233
* @param attributes map of attributes name as key and type as value
234
* @return true in case of success and false in case of failure
237
virtual bool addAttributes( const QMap<QString, QString> &attributes );
240
* Deletes existing attributes
241
* @param attributes a set containing names of attributes
242
* @return true in case of success and false in case of failure
244
virtual bool deleteAttributes( const QgsAttributeIds &attributes );
247
* Changes attribute values of existing features.
248
* @param attr_map a map containing changed attributes
249
* @return true in case of success and false in case of failure
251
virtual bool changeAttributeValues( const QgsChangedAttributesMap &attr_map );
254
* Returns the default value for field specified by @c fieldId
256
virtual QVariant defaultValue( int fieldId );
259
* Changes geometries of existing features
260
* @param geometry_map A QgsGeometryMap whose index contains the feature IDs
261
* that will have their geometries changed.
262
* The second map parameter being the new geometries themselves
263
* @return True in case of success and false in case of failure
265
virtual bool changeGeometryValues( QgsGeometryMap & geometry_map );
268
* Creates a spatial index on the datasource (if supported by the provider type).
269
* @return true in case of success
271
virtual bool createSpatialIndex();
273
/** Returns a bitmask containing the supported capabilities
274
Note, some capabilities may change depending on whether
275
a spatial filter is active on this provider, so it may
276
be prudent to check this value per intended operation.
278
virtual int capabilities() const;
281
* Returns the above in friendly format.
283
QString capabilitiesString() const;
286
* Set encoding used for accessing data from layer
288
virtual void setEncoding( const QString& e );
291
* Get encoding which is used for accessing data
293
QString encoding() const;
296
* Returns the index of a field name or -1 if the field does not exist
298
int fieldNameIndex( const QString& fieldName ) const;
300
/**Return a map where the key is the name of the field and the value is its index*/
301
QMap<QString, int> fieldNameMap() const;
304
* Return list of indexes to fetch all attributes in nextFeature()
306
virtual QgsAttributeList attributeIndexes();
309
* Set whether provider should also return features that don't have
310
* associated geometry. FALSE by default
312
void enableGeometrylessFeatures( bool fetch );
315
* check if provider supports type of field
318
bool supportedType( const QgsField &field ) const;
322
NativeType( QString typeDesc, QString typeName, QVariant::Type type, int minLen = 0, int maxLen = 0, int minPrec = 0, int maxPrec = 0 ) :
323
mTypeDesc( typeDesc ), mTypeName( typeName ), mType( type ), mMinLen( minLen ), mMaxLen( maxLen ), mMinPrec( minPrec ), mMaxPrec( maxPrec ) {};
327
QVariant::Type mType;
328
int mMinLen, mMaxLen;
329
int mMinPrec, mMaxPrec;
334
* Returns the names of the supported types
337
const QList< NativeType > &nativeTypes() const;
341
* Returns the names of the supported types
344
const QMap<QString, QVariant::Type> &supportedNativeTypes() const;
346
/** Returns true if the provider is strict about the type of inserted features
347
(e.g. no multipolygon in a polygon layer)
348
@note: added in version 1.4*/
349
virtual bool doesStrictFeatureTypeCheck() const { return true;}
352
QVariant convertValue( QVariant::Type type, QString value );
354
void fillMinMaxCache();
356
bool mCacheMinMaxDirty;
357
QMap<int, QVariant> mCacheMinValues, mCacheMaxValues;
360
QTextCodec* mEncoding;
362
/** should provider fetch also features that don't have geometry? */
363
bool mFetchFeaturesWithoutGeom;
365
/**True if geometry should be added to the features in nextFeature calls*/
368
/**List of attribute indices to fetch with nextFeature calls*/
369
QgsAttributeList mAttributesToFetch;
371
/**The names of the providers native types*/
372
QList< NativeType > mNativeTypes;
376
QMap<QString, QVariant::Type> mOldTypeList;