/
localstorage.qdoc
138 lines (99 loc) · 4.95 KB
/
localstorage.qdoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qml-localstorage.html
\title QML Local Storage
\brief SQL storage for QML
The local storage API provides a JavaScript interface to an SQL relational
database. The QtQuick.LocalStorage module contains the API and it may be given
a namespace.
Import QtQuick.LocalStorage module from QML:
\code
//sql.qml
import QtQuick.LocalStorage 2.0 as Sql
\endcode
Import QtQuick.LocalStorage module from JavaScript:
\code
//sql.js
.import QtQuick.LocalStorage 2.0 as Sql
\endcode
Note, importing a module from JavaScript is different from importing from QML.
The \l{JavaScript Code} article contains detailed information on importing in JavaScript code.
\section2 Database API
The \c openDatabaseSync() and related functions
provide the ability to access local storage in an SQL database.
These databases are user-specific and QML-specific, but accessible to all QML applications.
They are stored in the \c Databases subdirectory
of QQmlEngine::offlineStoragePath(), currently as SQLite databases.
Database connections are automatically closed during Javascript garbage collection.
The API can be used from JavaScript functions in your QML:
\snippet declarative/sqllocalstorage/hello.qml 0
The API conforms to the Synchronous API of the HTML5 Web Database API,
\link http://www.w3.org/TR/2009/WD-webdatabase-20091029/ W3C Working Draft 29 October 2009\endlink.
The \l{declarative/sqllocalstorage}{SQL Local Storage example} demonstrates the basics of
using the Local Storage API.
\section3 db = openDatabaseSync(identifier, version, description, estimated_size, callback(db))
Returns the database identified by \i identifier. If the database does not already exist, it
is created, and the function \i callback is called with the database as a parameter. \i description
and \i estimated_size are written to the INI file (described below), but are otherwise currently
unused.
May throw exception with code property SQLException.DATABASE_ERR, or SQLException.VERSION_ERR.
When a database is first created, an INI file is also created specifying its characteristics:
\table
\header \o \bold {Key} \o \bold {Value}
\row \o Name \o The name of the database passed to \c openDatabase()
\row \o Version \o The version of the database passed to \c openDatabase()
\row \o Description \o The description of the database passed to \c openDatabase()
\row \o EstimatedSize \o The estimated size (in bytes) of the database passed to \c openDatabase()
\row \o Driver \o Currently "QSQLITE"
\endtable
This data can be used by application tools.
\section3 db.changeVersion(from, to, callback(tx))
This method allows you to perform a \i{Scheme Upgrade}.
If the current version of \i db is not \i from, then an exception is thrown.
Otherwise, a database transaction is created and passed to \i callback. In this function,
you can call \i executeSql on \i tx to upgrade the database.
May throw exception with code property SQLException.DATABASE_ERR or SQLException.UNKNOWN_ERR.
\section3 db.transaction(callback(tx))
This method creates a read/write transaction and passed to \i callback. In this function,
you can call \i executeSql on \i tx to read and modify the database.
If the callback throws exceptions, the transaction is rolled back.
\section3 db.readTransaction(callback(tx))
This method creates a read-only transaction and passed to \i callback. In this function,
you can call \i executeSql on \i tx to read the database (with SELECT statements).
\section3 results = tx.executeSql(statement, values)
This method executes a SQL \i statement, binding the list of \i values to SQL positional parameters ("?").
It returns a results object, with the following properties:
\table
\header \o \bold {Type} \o \bold {Property} \o \bold {Value} \o \bold {Applicability}
\row \o int \o rows.length \o The number of rows in the result \o SELECT
\row \o var \o rows.item(i) \o Function that returns row \i i of the result \o SELECT
\row \o int \o rowsAffected \o The number of rows affected by a modification \o UPDATE, DELETE
\row \o string \o insertId \o The id of the row inserted \o INSERT
\endtable
May throw exception with code property SQLException.DATABASE_ERR, SQLException.SYNTAX_ERR, or SQLException.UNKNOWN_ERR.
*/