Merge branch 'new-common-rc' into full-master-rc

- Include Windows (8.1) version together with the other versions (#129)
- Abort initially pending transactions for db handle (due to incorrect password key, for example) [from @brodysoft/Cordova-sqlcipher-adaptor]
- Existing QUnit-based test suite completely ported into Jasmine (2.2.0)-based test suite, working for all platforms (including Windows)
- README.md, AUTHORS.md, and LICENSE.md updated for new Windows (8.1) version (ref: #129)

bin/test.ps1 & spec/www/spec/legacy.js copied verbatim from new-common-rc

Minor fixes to README.md & LICENSE.md

AUTHORS.md

@@ -21,6 +21,12 @@
 - Cordova 2.7+ port with background processing by @j3k0 (Jean-Christophe Hoelt <hoelt@fovea.cc>)
 - Maintained by @brodybits (Chris Brody)
 
+## Windows (8.1) version
+
+- SQLiteProxy.js by @vldmrrr (Vladimir Avdonin) and @brodybits (Chris Brody)
+- Includes SQLite3-WinRT C++ classes and SQLite3JS (Javascript part) by @doo (doo GmbH)
+- SQLite3-Windows8.1.vcxproj to build SQLite3.winmd by @EionRobb
+
 ## WP(7/8) version
 
 - Original author: @marcucio (Mike Arcucio <mike@marcucio.com>)

LICENSE.md

@@ -12,6 +12,14 @@ MIT or Apache 2.0
 
 MIT only
 
+## Windows (8.1) version
+
+MIT or Apache 2.0
+
+### SQLite3-WinRT [used by  Windows (8.1) version]
+
+by @doo (doo GmbH)
+
 ## WP(7/8) version
 
 MIT or Apache 2.0
@@ -20,18 +28,17 @@ MIT or Apache 2.0
 
 ### C#-SQLite
 
-  MIT License
-
-  C#-SQLite is an independent reimplementation of the SQLite software library.
-  SQLite® is a registered trademark of Hipp, Wyrick & Company, Inc.
+MIT License
 
-  The overall C#-SQLite package is distributed under the terms of the MIT License, given below.  Some parts are distributed under more permissive licenses, see individual source files for details.
+C#-SQLite is an independent reimplementation of the SQLite software library.
+SQLite® is a registered trademark of Hipp, Wyrick & Company, Inc.
 
-  Copyright (c) 2009-2012 Noah Hart and others, see individual source files for details.
+The overall C#-SQLite package is distributed under the terms of the MIT License, given below.  Some parts are distributed under more permissive licenses, see individual source files for details.
 
-  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+Copyright (c) 2009-2012 Noah Hart and others, see individual source files for details.
 
-  The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 
-  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,25 +1,32 @@
 # Cordova/PhoneGap SQLitePlugin
 
-Native interface to sqlite in a Cordova/PhoneGap plugin for Android/iOS/WP(7/8), with API similar to HTML5/[Web SQL API](http://www.w3.org/TR/webdatabase/).
+Native interface to sqlite in a Cordova/PhoneGap plugin for Android, iOS, Windows (8.1), and WP(7/8) with API similar to HTML5/[Web SQL API](http://www.w3.org/TR/webdatabase/).
 
-License for Android & WP(7/8) versions: MIT or Apache 2.0
+License for Android, Windows (8.1), and WP(7/8) versions: MIT or Apache 2.0
 
 License for iOS version: MIT only
 
 ## Status
 
-- [Available at PhoneGap build](https://build.phonegap.com/plugins/2368)
+- [Stable version available at PhoneGap build](https://build.phonegap.com/plugins/2368)
+- Windows (8.1) version is in experimental state:
+  - No background processing
+  - Database close and delete operations not yet implemented
+  - insertId and rowsAffected are missing in the results for INSERT/UPDATE/DELETE statements
+  - Visual C++ build file is provided for Windows 8.1 only. Visual C++ build support for Windows Phone 8.1 will be added later.
+  - Not all Windows CPU targets are supported by automatic installation
 
 ## Announcements
 
+- Windows (8.1) version is added, using the C++ SQLite-WinRT library
 - [SQLCipher](https://www.zetetic.net/sqlcipher/) for Android & iOS is now supported by [brodysoft / Cordova-sqlcipher-adaptor](https://github.com/brodysoft/Cordova-sqlcipher-adaptor)
 - New `openDatabase` and `deleteDatabase` `location` option to select database location (iOS *only*) and disable iCloud backup
 - Pre-populated databases support for Android & iOS is now integrated, usage described below
 - Fixes to work with PouchDB by [@nolanlawson](https://github.com/nolanlawson)
 
 ## Highlights
 
-- Works with Cordova 3.x tooling and [available at PhoneGap build](https://build.phonegap.com/plugins/2368)
+- Works with Cordova 3.x tooling and [stable version available at PhoneGap build](https://build.phonegap.com/plugins/2368)
 - Drop-in replacement for HTML5 SQL API, the only change should be `window.openDatabase()` --> `sqlitePlugin.openDatabase()`
 - Failure-safe nested transactions with batch processing optimizations
 - As described in [this posting](http://brodyspark.blogspot.com/2012/12/cordovaphonegap-sqlite-plugins-offer.html):
@@ -38,6 +45,7 @@ License for iOS version: MIT only
 ## Known issues
 
 - Issue reported with PhoneGap Build Hydration.
+- Multi-page apps are not supported and known to be broken on Android.
 - Using web workers is currently not supported and known to be broken on Android.
 - Triggers are only supported for iOS, known to be broken on Android.
 - INSERT statement that affects multiple rows (due to SELECT cause or using triggers, for example) does not report proper rowsAffected on Android.
@@ -48,19 +56,27 @@ License for iOS version: MIT only
 - The sqlite plugin will not work before the callback for the "deviceready" event has been fired, as described in **Usage**.
 - The Android version cannot work with more than 100 open db files due to its threading model.
 - UNICODE line separator (`\u2028`) is currently not supported and known to be broken in iOS version.
-- UNICODE characters not working with WP(7/8) version
+- UNICODE characters not working in WP(7/8) version
 
 ## Limited support (testing needed)
 
-- Multi-page apps on WP(7/8)
 - DB Triggers (as described above - known to be broken for Android)
+- UNICODE characters not fully tested with Windows (8.1) version
 
-## Other versions and related projects
+## Other versions
 
-- [brodysoft / Cordova-sqlcipher-adaptor](https://github.com/brodysoft/Cordova-sqlcipher-adaptor) - supports [SQLCipher](https://www.zetetic.net/sqlcipher/) for Android & iOS.
-- [MetaMemoryT / websql-client](https://github.com/MetaMemoryT/websql-client) - provides the same API and connects to [websql-server](https://github.com/MetaMemoryT/websql-server) through WebSockets.
+- [pull request #157](https://github.com/brodysoft/Cordova-SQLitePlugin/pull/157) - contribution of a Windows version in C# with proper transaction support (manual installation required)
+- [brodysoft / Cordova-sqlcipher-adaptor](https://github.com/brodysoft/Cordova-sqlcipher-adaptor) - supports [SQLCipher](https://www.zetetic.net/sqlcipher/) for Android & iOS
 - Original version for iOS (with a different API): [davibe / Phonegap-SQLitePlugin](https://github.com/davibe/Phonegap-SQLitePlugin)
 
+## Other SQLite adapter projects
+
+- [EionRobb / phonegap-win8-sqlite](https://github.com/EionRobb/phonegap-win8-sqlite) - WebSQL add-on for Win8/Metro apps (perhaps with a different API), using an old version of the C++ library from [SQLite3-WinRT Component](https://github.com/doo/SQLite3-WinRT) (as referenced by [01org / cordova-win8](https://github.com/01org/cordova-win8))
+- [SQLite3-WinRT Component](https://github.com/doo/SQLite3-WinRT) - C++ component that provides a nice SQLite API with promises for WinJS
+- [01org / cordova-win8](https://github.com/01org/cordova-win8) - old, unofficial version of Cordova API support for Windows 8 Metro that includes an old version of the C++ [SQLite3-WinRT Component](https://github.com/doo/SQLite3-WinRT)
+- [MSOpenTech / cordova-plugin-websql](https://github.com/MSOpenTech/cordova-plugin-websql) - Windows 8(+) and Windows Phone 8(+) WebSQL plugin versions in C#
+- [MetaMemoryT / websql-client](https://github.com/MetaMemoryT/websql-client) - provides the same API and connects to [websql-server](https://github.com/MetaMemoryT/websql-server) through WebSockets.
+
 # Usage
 
 The idea is to emulate the HTML5/[Web SQL API](http://www.w3.org/TR/webdatabase/) as closely as possible. The only major change is to use `window.sqlitePlugin.openDatabase()` (or `sqlitePlugin.openDatabase()`) instead of `window.openDatabase()`. If you see any other major change please report it, it is probably a bug.
@@ -132,8 +148,9 @@ db = sqlitePlugin.openDatabase({name: "my.db", location: 2, createFromLocation:
 ## Background processing
 
 The threading model depends on which version is used:
-- For Android & WP(7/8), one background thread per db;
-- for iOS, background processing using a thread pool.
+- For Android and WP(7/8), one background thread per db;
+- for iOS, background processing using a thread pool;
+- for Windows, no background processing (will be added).
 
 # Sample with PRAGMA feature
 
@@ -216,8 +233,39 @@ window.sqlitePlugin.deleteDatabase({name: "my.db", location: 1}, successcb, erro
 
 `location` as described above for `openDatabase` (iOS *only*)
 
+**NOTE:** not yet implemented for Windows (8.1) version.
+
 # Installing
 
+## Windows target platform
+
+**WARNING:** This is still in experimental state. Please read and follow these items very carefully.
+- Please make sure your Cordova tooling is updated: `npm update -g cordova cordova-windows`
+- To create a new project: `cordova create MyProjectFolder com.my.project MyProject` (and then `cd` into your project directory)
+- To add the plugin: `cordova plugin add https://github.com/brodysoft/Cordova-SQLitePlugin`
+- To add the Windows target platform (if it does not exist): `cordova platform add windows`
+- If you are using Visual Studio Express (2013), you may have to remove the Windows 8.0 build from the Visual Studio solution.
+- If you use Cordova CLI for fully-automatic installation (as described here), you cannot run the project for "Any CPU". Please specify a CPU type (such as x86 or x64).
+
+To target all CPUs: make a clone of this project and in your clone, remove (or comment out) the item that includes the `SQLite3-Windows8.1.vcxproj` framework project:
+```xml
+--- a/plugin.xml
++++ b/plugin.xml
+@@ -79,8 +79,6 @@
+         <js-module src="src/windows/SQLite3-WinRT/SQLite3JS/js/SQLite3.js" name="SQLite3">
+             <merges target="" />
+         </js-module>
+-        <!-- Thanks to AllJoyn-Cordova / cordova-plugin-alljoyn: -->
+-        <framework src="src/windows/SQLite3-WinRT/SQLite3/SQLite3-Windows8.1.vcxproj" custom="true" type="projectReference" target="windows" />
+
+     </platform>
+```
+
+Then:
+- install the plugin from the location of your clone (can be in your filesystem);
+- add the Cordova `windows` target;
+- open the Windows target solution, and add the `SQLite3-Windows8.1.vcxproj` project (located in `path.to.plugin/src/windows/SQLite3-WinRT/SQLite3`) to your app solution project.
+
 ## Easy install with plugman tool
 
 ```shell
@@ -226,7 +274,9 @@ plugman install --platform MYPLATFORM --project path.to.my.project.folder --plug
 
 where MYPLATFORM is `android`, `ios`, or `wp8`.
 
-Here is a posting how to get started on Windows without the Cordova CLI tool: http://brodybits.blogspot.com/2015/03/trying-cordova-for-android-on-windows-without-cordova-cli.html
+A posting how to get started developing on Windows host without the Cordova CLI tool (for Android target only) is available [here](http://brodybits.blogspot.com/2015/03/trying-cordova-for-android-on-windows-without-cordova-cli.html).
+
+**NOTE:** Automatic installation for the Windows target platform is *not* properly supported by the `plugman` tool.
 
 ## Easy install with Cordova CLI tool
 
@@ -236,6 +286,8 @@ Here is a posting how to get started on Windows without the Cordova CLI tool: ht
 
 You can find more details at [this writeup](http://iphonedevlog.wordpress.com/2014/04/07/installing-chris-brodys-sqlite-database-with-cordova-cli-android/).
 
+**WARNING:** for Windows target platform please read the section above.
+
 **IMPORTANT:** sometimes you have to update the version for a platform before you can build, like: `cordova prepare ios`
 
 **NOTE:** If you cannot build for a platform after `cordova prepare`, you may have to remove the platform and add it again, such as:
@@ -246,9 +298,9 @@ You can find more details at [this writeup](http://iphonedevlog.wordpress.com/20
 ## Source tree
 
 - `SQLitePlugin.coffee.md`: platform-independent (Literate coffee-script, can be read by recent coffee-script compiler)
-- `www`: `SQLitePlugin.js` now platform-independent
-- `src`: Java plugin code for Android; Objective-C plugin code for iOS; C-sharp code & DLLs for WP(7/8)
-- `test-www`: simple testing in `index.html` using qunit 1.5.0
+- `www`: `SQLitePlugin.js` platform-independent Javascript as generated from `SQLitePlugin.coffee.md` (and checked in!)
+- `src`: Java plugin code for Android; Objective-C plugin code for iOS; Javascript proxy code for Windows (8.1); C-sharp code for WP(7/8)
+- `spec`: test suite using Jasmine (2.2.0), ported from QUnit `test-www` test suite, working on all platforms
 - `Lawnchair-adapter`: Lawnchair adaptor, based on the version from the Lawnchair repository, with the basic Lawnchair test suite in `test-www` subdirectory
 
 ## Manual installation - Android version
@@ -330,6 +382,10 @@ Enable the SQLitePlugin in `config.xml` (Cordova/PhoneGap 2.x):
          <plugin name="Compass" value="CDVLocation" />
 ```
 
+## Manual installation - Windows (8.1) version
+
+TODO
+
 ## Manual installation - WP(7/8) version
 
 TODO
@@ -427,7 +483,11 @@ To run then from a windows powershell do either
 
     .\bin\test.ps1 android
 
-or for Windows Phone 8:
+or for Windows (8.1):
+
+    .\bin\test.ps1 windows
+
+or for Windows Phone (7/8):
 
     .\bin\test.ps1 wp8
 
@@ -490,6 +550,9 @@ The adapter is now part of [PouchDB](http://pouchdb.com/) thanks to [@nolanlawso
 ## Major branches
 
 - `common-src` - source for Android & iOS versions
-- `wp-src` - source for Android, iOS, & WP(7/8) versions
-- `master-rc` - pre-release version, including source for CSharp-SQLite library classes
-- `master` - version for release, will be included in PhoneGap build.
+- `new-src` - source for Android, iOS, and Windows (8.1) versions
+- `new-common-rc` - pre-release version for Android/iOS/Windows (8.1), including source for SQLite-WinRT (C++ and Javascript) library
+- `wp-src` - source for Android, iOS, and WP(7/8) versions
+- `wp-master-rc` - pre-release version for Android/iOS/WP(7/8), including source for CSharp-SQLite (C#) library classes
+- `full-master-rc` - pre-release version for all platforms, including source for SQLite-WinRT and CSharp-SQLite libraries
+- [FUTURE TBD] ~~`master` - version for release, will be included in PhoneGap build.~~