michael@0: <!---
michael@0:     Licensed to the Apache Software Foundation (ASF) under one
michael@0:     or more contributor license agreements.  See the NOTICE file
michael@0:     distributed with this work for additional information
michael@0:     regarding copyright ownership.  The ASF licenses this file
michael@0:     to you under the Apache License, Version 2.0 (the
michael@0:     "License"); you may not use this file except in compliance
michael@0:     with the License.  You may obtain a copy of the License at
michael@0: 
michael@0:       http://www.apache.org/licenses/LICENSE-2.0
michael@0: 
michael@0:     Unless required by applicable law or agreed to in writing,
michael@0:     software distributed under the License is distributed on an
michael@0:     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
michael@0:     KIND, either express or implied.  See the License for the
michael@0:     specific language governing permissions and limitations
michael@0:     under the License.
michael@0: -->
michael@0: 
michael@0: # org.apache.cordova.device
michael@0: 
michael@0: This plugin defines a global `device` object, which describes the device's hardware and software.
michael@0: Although the object is in the global scope, it is not available until after the `deviceready` event.
michael@0: 
michael@0:     document.addEventListener("deviceready", onDeviceReady, false);
michael@0:     function onDeviceReady() {
michael@0:         console.log(device.cordova);
michael@0:     }
michael@0: 
michael@0: ## Installation
michael@0: 
michael@0:     cordova plugin add org.apache.cordova.device
michael@0: 
michael@0: ## Properties
michael@0: 
michael@0: - device.cordova
michael@0: - device.model
michael@0: - device.platform
michael@0: - device.uuid
michael@0: - device.version
michael@0: 
michael@0: ## device.cordova
michael@0: 
michael@0: Get the version of Cordova running on the device.
michael@0: 
michael@0: ### Supported Platforms
michael@0: 
michael@0: - Amazon Fire OS
michael@0: - Android
michael@0: - BlackBerry 10
michael@0: - Browser
michael@0: - Firefox OS
michael@0: - iOS
michael@0: - Tizen
michael@0: - Windows Phone 7 and 8
michael@0: - Windows 8
michael@0: 
michael@0: ## device.model
michael@0: 
michael@0: The `device.model` returns the name of the device's model or
michael@0: product. The value is set by the device manufacturer and may be
michael@0: different across versions of the same product.
michael@0: 
michael@0: ### Supported Platforms
michael@0: 
michael@0: - Android
michael@0: - BlackBerry 10
michael@0: - Browser
michael@0: - iOS
michael@0: - Tizen
michael@0: - Windows Phone 7 and 8
michael@0: - Windows 8
michael@0: 
michael@0: ### Quick Example
michael@0: 
michael@0:     // Android:    Nexus One       returns "Passion" (Nexus One code name)
michael@0:     //             Motorola Droid  returns "voles"
michael@0:     // BlackBerry: Torch 9800      returns "9800"
michael@0:     // Browser:    Google Chrome   returns "Chrome"
michael@0:     //             Safari          returns "Safari"
michael@0:     // iOS:     for the iPad Mini, returns iPad2,5; iPhone 5 is iPhone 5,1. See http://theiphonewiki.com/wiki/index.php?title=Models
michael@0:     //
michael@0:     var model = device.model;
michael@0: 
michael@0: ### Android Quirks
michael@0: 
michael@0: - Gets the [product name](http://developer.android.com/reference/android/os/Build.html#PRODUCT) instead of the [model name](http://developer.android.com/reference/android/os/Build.html#MODEL), which is often the production code name. For example, the Nexus One returns `Passion`, and Motorola Droid returns `voles`.
michael@0: 
michael@0: ### Tizen Quirks
michael@0: 
michael@0: - Returns the device model assigned by the vendor, for example, `TIZEN`
michael@0: 
michael@0: ### Windows Phone 7 and 8 Quirks
michael@0: 
michael@0: - Returns the device model specified by the manufacturer. For example, the Samsung Focus returns `SGH-i917`.
michael@0: 
michael@0: ## device.platform
michael@0: 
michael@0: Get the device's operating system name.
michael@0: 
michael@0:     var string = device.platform;
michael@0: 
michael@0: ### Supported Platforms
michael@0: 
michael@0: - Android
michael@0: - BlackBerry 10
michael@0: - Browser4
michael@0: - Firefox OS
michael@0: - iOS
michael@0: - Tizen
michael@0: - Windows Phone 7 and 8
michael@0: - Windows 8
michael@0: 
michael@0: ### Quick Example
michael@0: 
michael@0:     // Depending on the device, a few examples are:
michael@0:     //   - "Android"
michael@0:     //   - "BlackBerry 10"
michael@0:     //   - Browser:         returns "MacIntel" on Mac
michael@0:     //                      returns "Win32" on Windows
michael@0:     //   - "iOS"
michael@0:     //   - "WinCE"
michael@0:     //   - "Tizen"
michael@0:     var devicePlatform = device.platform;
michael@0: 
michael@0: ### Windows Phone 7 Quirks
michael@0: 
michael@0: Windows Phone 7 devices report the platform as `WinCE`.
michael@0: 
michael@0: ### Windows Phone 8 Quirks
michael@0: 
michael@0: Windows Phone 8 devices report the platform as `Win32NT`.
michael@0: 
michael@0: ## device.uuid
michael@0: 
michael@0: Get the device's Universally Unique Identifier ([UUID](http://en.wikipedia.org/wiki/Universally_Unique_Identifier)).
michael@0: 
michael@0:     var string = device.uuid;
michael@0: 
michael@0: ### Description
michael@0: 
michael@0: The details of how a UUID is generated are determined by the device manufacturer and are specific to the device's platform or model.
michael@0: 
michael@0: ### Supported Platforms
michael@0: 
michael@0: - Android
michael@0: - BlackBerry 10
michael@0: - iOS
michael@0: - Tizen
michael@0: - Windows Phone 7 and 8
michael@0: - Windows 8
michael@0: 
michael@0: ### Quick Example
michael@0: 
michael@0:     // Android: Returns a random 64-bit integer (as a string, again!)
michael@0:     //          The integer is generated on the device's first boot
michael@0:     //
michael@0:     // BlackBerry: Returns the PIN number of the device
michael@0:     //             This is a nine-digit unique integer (as a string, though!)
michael@0:     //
michael@0:     // iPhone: (Paraphrased from the UIDevice Class documentation)
michael@0:     //         Returns a string of hash values created from multiple hardware identifies.
michael@0:     //         It is guaranteed to be unique for every device and can't be tied
michael@0:     //         to the user account.
michael@0:     // Windows Phone 7 : Returns a hash of device+current user,
michael@0:     // if the user is not defined, a guid is generated and will persist until the app is uninstalled
michael@0:     // Tizen: returns the device IMEI (International Mobile Equipment Identity or IMEI is a number
michael@0:     // unique to every GSM and UMTS mobile phone.
michael@0:     var deviceID = device.uuid;
michael@0: 
michael@0: ### iOS Quirk
michael@0: 
michael@0: The `uuid` on iOS is not unique to a device, but varies for each
michael@0: application, for each installation.  It changes if you delete and
michael@0: re-install the app, and possibly also when you upgrade iOS, or even
michael@0: upgrade the app per version (apparent in iOS 5.1). The `uuid` is not
michael@0: a reliable value.
michael@0: 
michael@0: ### Windows Phone 7 and 8 Quirks
michael@0: 
michael@0: The `uuid` for Windows Phone 7 requires the permission
michael@0: `ID_CAP_IDENTITY_DEVICE`.  Microsoft will likely deprecate this
michael@0: property soon.  If the capability is not available, the application
michael@0: generates a persistent guid that is maintained for the duration of the
michael@0: application's installation on the device.
michael@0: 
michael@0: ## device.version
michael@0: 
michael@0: Get the operating system version.
michael@0: 
michael@0:     var string = device.version;
michael@0: 
michael@0: ### Supported Platforms
michael@0: 
michael@0: - Android 2.1+
michael@0: - BlackBerry 10
michael@0: - Browser
michael@0: - iOS
michael@0: - Tizen
michael@0: - Windows Phone 7 and 8
michael@0: - Windows 8
michael@0: 
michael@0: ### Quick Example
michael@0: 
michael@0:     // Android:    Froyo OS would return "2.2"
michael@0:     //             Eclair OS would return "2.1", "2.0.1", or "2.0"
michael@0:     //             Version can also return update level "2.1-update1"
michael@0:     //
michael@0:     // BlackBerry: Torch 9800 using OS 6.0 would return "6.0.0.600"
michael@0:     //
michael@0:     // Browser:    Returns version number for the browser
michael@0:     //
michael@0:     // iPhone:     iOS 3.2 returns "3.2"
michael@0:     //
michael@0:     // Windows Phone 7: returns current OS version number, ex. on Mango returns 7.10.7720
michael@0:     // Tizen: returns "TIZEN_20120425_2"
michael@0:     var deviceVersion = device.version;
michael@0: