JsonDataAccess
Since: BlackBerry 10.0.0
#include <bb/data/JsonDataAccess>
To link against this class, add the following line to your .pro file: LIBS += -lbbdata
Provides load and save operations for JSON data.
The JsonDataAccess class converts data from JSON format to Qt C++ value objects or from Qt C++ value objects to JSON format. You can use this class to provide JSON data to a ListView to display the data in your application.
Load operations read and parse JSON (JavaScript Object Notation) data coming from a file or memory buffer into a tree of Qt value objects. Save operations convert Qt value objects into JSON format, which are written to a file or returned in a memory buffer.
The topmost (root) JSON element must be either an array or an object. See http://www.json.org/ for the JSON format description.
The Qt value data must always be a QVariant that contains either a QVariantList or QVariantMap.
Both formats support unlimited nesting of hierarchical data.
JSON Type Qt Type --------- ----------------- null empty QVariant int QVariant(Int64) uint QVariant(UInt64) real QVariant(double) string QVariant(const char*) boolean QVariant(bool) array QVariant(QVariantList) object QVariant(QVariantMap)
Loading data
Here's an example of how to load JSON data from a file (called contacts.json) and insert the data into a data model. The data model is then used to provide data for a ListView.
[ { "id":1, "firstname": "Mike", "lastname": "Chepesky", "title": "Sr. Editor", "image": "images/data/mike_chepesky.png", "active": true, "gender": "m" }, { "id":2, "firstname": "Westlee", "lastname": "Barichak", "title": "Talent Scout", "image": "images/data/westlee_barichak.png", "active": true, "gender": "m" }, ... ]
// Create a data model with sorting keys for firstname and lastname GroupDataModel *model = new GroupDataModel(QStringList() << "firstname" << "lastname"); // Load the JSON data JsonDataAccess jda; QVariant list = jda.load("contacts.json"); // Add the data to the model model->insertList(list.value<QVariantList>()); // Create a ListView control and add the model to the list ListView *listView = new ListView(); listView->setDataModel(model);QML:
import bb.cascades 1.0 import bb.data 1.0 Page { content: ListView { id: listView dataModel: dataModel //... } attachedObjects: [ GroupDataModel { id: dataModel }, DataSource { id: dataSource source: "contacts.json" onDataLoaded: { dataModel.insertList(data) } } ] onCreationCompleted: { dataSource.load(); } }
Unicode
JSON data, in general, is encoded in Unicode. The default encoding is UTF-8 but external data in UTF-16 formats can also be loaded and parsed. The various load and save methods in this class will indicate what assumptions and restrictions they have regarding decoding and encoding.
Overview
Public Functions Index
JsonDataAccess (QObject *parent=0) | |
virtual | ~JsonDataAccess () |
DataAccessError | error () const |
bool | hasError () const |
QVariant | load (const QString &filePath) |
QVariant | load (QIODevice *ioDevice) |
QVariant | loadFromBuffer (const QByteArray &buffer) |
QVariant | loadFromBuffer (const QString &buffer) |
void | save (const QVariant &data, const QString &filePath) |
void | save (const QVariant &data, QIODevice *ioDevice) |
void | saveToBuffer (const QVariant &data, QByteArray *buffer) |
void | saveToBuffer (const QVariant &data, QString *buffer) |
Public Functions
Constructs a JsonDataAccess object with the specified parent.
Parameters | |
---|---|
parent |
The parent owner or 0. Optional and will default to 0 if not specified. |
BlackBerry 10.0.0
virtual
Destructor.
BlackBerry 10.0.0
DataAccessError
Returns an error object for the most recent operation.
DataAccessError with error type and error message.
BlackBerry 10.0.0
bool
Returns indication of whether or not most recent operation ended with an error.
true if current error or false if none.
BlackBerry 10.0.0
QVariant
Loads JSON data from specified file and returns it as a hierarchy of Qt value objects.
The data returned is a QVariant with a type that matches the type of the root JSON object (see table of types in the class description of JsonDataAccess). Unless the data is a single primitive JSON value, the returned data will be either a QVariantList (if root JSON node is array) or a QVariantMap (if root JSON node is an object), cast as a QVariant.
You can use DataAccess::hasError() to determine if the most recent operation resulted in an error, and you can use DataAccess::error() to retrieve information about the error that occurred.
The file data can be encoded as UTF-8 (with or without byte-order-mark) or as UTF-16 (must have a byte-order-mark to indicate little endian or big endian).
Parameters | |
---|---|
filePath |
The path to the JSON file. |
A QVariant containing a hierarchy of Qt value objects.
BlackBerry 10.0.0
QVariant
Loads JSON data from the specified I/O device and returns it as a hierarchy of Qt value objects.
An I/O device is used to read or write data from various sources. A QIODevice can represent several useful types, including QBuffer and QFile.
The data returned is a QVariant with a type that matches the type of the root JSON object (see the table of types in the class description of JsonDataAccess). Unless the data is a single primitive JSON value, the returned data will be either a QVariantList (if the root JSON node is an array) or a QVariantMap (if root JSON node is an object), cast as a QVariant.
You can use DataAccess::hasError() to determine if the most recent operation resulted in an error, and you can use DataAccess::error() to retrieve information about the error that occurred.
The input data can be encoded as UTF-8 (with or without byte-order-mark) or as UTF-16 (must have a byte-order-mark to indicate little endian or big endian).
Parameters | |
---|---|
ioDevice |
The I/O device that is used to read and write data. |
A QVariant containing a hierarchy of Qt value objects.
BlackBerry 10.0.0
QVariant
Parses the specified JSON byte array buffer and returns it as a hierarchy of Qt value objects.
The data returned is a QVariant with a type that matches the type of the root JSON object (see the table of types in the class description of JsonDataAccess). Unless the data is a single primitive JSON value, the returned data will be either a QVariantList (if the root JSON node is an array) or a QVariantMap (if root JSON node is an object), cast as a QVariant.
You can use DataAccess::hasError() to determine if the most recent operation resulted in an error, and you can use DataAccess::error() to retrieve information about the error that occurred.
Parameters | |
---|---|
buffer |
An in-memory byte array containing JSON data encoded as UTF-8. |
A QVariant containing a hierarchy of Qt value objects.
BlackBerry 10.0.0
QVariant
Parses the specified JSON string buffer and returns it as a hierarchy of Qt value objects.
The data returned is a QVariant with a type that matches the type of the root JSON object (see the table of types in the class description of JsonDataAccess). Unless the data is a single primitive JSON value, the returned data will be either a QVariantList (if the root JSON node is an array) or a QVariantMap (if root JSON node is an object), cast as a QVariant.
You can use DataAccess::hasError() to determine if the most recent operation resulted in an error, and you can use DataAccess::error() to retrieve information about the error that occurred.
Parameters | |
---|---|
buffer |
An in-memory string containing JSON unicode data. |
A QVariant containing a hierarchy of Qt value objects.
BlackBerry 10.0.0
void
Saves JSON data to the specified file.
The data parameter is a QVariant (see the table of types in the class description of JsonDataAccess). Unless the data is a single primitive JSON value, the data should be either a QVariantList (if the root JSON node is an array) or a QVariantMap (if root JSON node is an object), cast as a QVariant.
You can use DataAccess::hasError() to determine if the most recent operation resulted in an error, and you can use DataAccess::error() to retrieve information about the error that occurred.
Parameters | |
---|---|
data |
The data to be converted to JSON format. |
filePath |
The path to the JSON file to be written as UTF-8 (with no byte-order-mark). |
BlackBerry 10.0.0
void
Saves JSON data to the specified I/O device.
The data parameter is a QVariant (see the table of types in the class description of JsonDataAccess). Unless the data is a single primitive JSON value, the data should be either a QVariantList (if the root JSON node is an array) or a QVariantMap (if root JSON node is an object), cast as a QVariant.
You can use DataAccess::hasError() to determine if the most recent operation resulted in an error, and you can use DataAccess::error() to retrieve information about the error that occurred.
An I/O device is used to read or write data from various sources. A QIODevice can represent several useful types, including QBuffer and QFile.
Parameters | |
---|---|
data |
The data to be converted to JSON format. |
ioDevice |
The I/O device that is used to write JSON data as UTF-8 (no byte order mark). |
BlackBerry 10.0.0
void
Saves JSON data to the specified QByteArray buffer.
The data parameter is a QVariant (see the table of types in the class description of JsonDataAccess). Unless the data is a single primitive JSON value, the data should be either a QVariantList (if the root JSON node is an array) or a QVariantMap (if root JSON node is an object), cast as a QVariant.
You can use DataAccess::hasError() to determine if the most recent operation resulted in an error, and you can use DataAccess::error() to retrieve information about the error that occurred.
Parameters | |
---|---|
data |
The data to be converted to JSON format. |
buffer |
An output parameter that is updated with JSON-formatted data in UTF-8 format. |
BlackBerry 10.0.0
void
Saves JSON data to the specified QString buffer.
The data parameter is a QVariant (see the table of types in the class description of JsonDataAccess). Unless the data is a single primitive JSON value, the data should be either a QVariantList (if the root JSON node is an array) or a QVariantMap (if root JSON node is an object), cast as a QVariant.
You can use DataAccess::hasError() to determine if the most recent operation resulted in an error, and you can use DataAccess::error() to retrieve information about the error that occurred.
Parameters | |
---|---|
data |
The data to be converted to JSON format. |
buffer |
An output parameter that is updated with JSON-formatted Unicode data. |
BlackBerry 10.0.0