1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Touchgui/plugins/org.apache.cordova.device/doc/index.md Thu Jun 04 14:50:33 2015 +0200
1.3 @@ -0,0 +1,218 @@
1.4 +<!---
1.5 + Licensed to the Apache Software Foundation (ASF) under one
1.6 + or more contributor license agreements. See the NOTICE file
1.7 + distributed with this work for additional information
1.8 + regarding copyright ownership. The ASF licenses this file
1.9 + to you under the Apache License, Version 2.0 (the
1.10 + "License"); you may not use this file except in compliance
1.11 + with the License. You may obtain a copy of the License at
1.12 +
1.13 + http://www.apache.org/licenses/LICENSE-2.0
1.14 +
1.15 + Unless required by applicable law or agreed to in writing,
1.16 + software distributed under the License is distributed on an
1.17 + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
1.18 + KIND, either express or implied. See the License for the
1.19 + specific language governing permissions and limitations
1.20 + under the License.
1.21 +-->
1.22 +
1.23 +# org.apache.cordova.device
1.24 +
1.25 +This plugin defines a global `device` object, which describes the device's hardware and software.
1.26 +Although the object is in the global scope, it is not available until after the `deviceready` event.
1.27 +
1.28 + document.addEventListener("deviceready", onDeviceReady, false);
1.29 + function onDeviceReady() {
1.30 + console.log(device.cordova);
1.31 + }
1.32 +
1.33 +## Installation
1.34 +
1.35 + cordova plugin add org.apache.cordova.device
1.36 +
1.37 +## Properties
1.38 +
1.39 +- device.cordova
1.40 +- device.model
1.41 +- device.platform
1.42 +- device.uuid
1.43 +- device.version
1.44 +
1.45 +## device.cordova
1.46 +
1.47 +Get the version of Cordova running on the device.
1.48 +
1.49 +### Supported Platforms
1.50 +
1.51 +- Amazon Fire OS
1.52 +- Android
1.53 +- BlackBerry 10
1.54 +- Browser
1.55 +- Firefox OS
1.56 +- iOS
1.57 +- Tizen
1.58 +- Windows Phone 7 and 8
1.59 +- Windows 8
1.60 +
1.61 +## device.model
1.62 +
1.63 +The `device.model` returns the name of the device's model or
1.64 +product. The value is set by the device manufacturer and may be
1.65 +different across versions of the same product.
1.66 +
1.67 +### Supported Platforms
1.68 +
1.69 +- Android
1.70 +- BlackBerry 10
1.71 +- Browser
1.72 +- iOS
1.73 +- Tizen
1.74 +- Windows Phone 7 and 8
1.75 +- Windows 8
1.76 +
1.77 +### Quick Example
1.78 +
1.79 + // Android: Nexus One returns "Passion" (Nexus One code name)
1.80 + // Motorola Droid returns "voles"
1.81 + // BlackBerry: Torch 9800 returns "9800"
1.82 + // Browser: Google Chrome returns "Chrome"
1.83 + // Safari returns "Safari"
1.84 + // iOS: for the iPad Mini, returns iPad2,5; iPhone 5 is iPhone 5,1. See http://theiphonewiki.com/wiki/index.php?title=Models
1.85 + //
1.86 + var model = device.model;
1.87 +
1.88 +### Android Quirks
1.89 +
1.90 +- 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`.
1.91 +
1.92 +### Tizen Quirks
1.93 +
1.94 +- Returns the device model assigned by the vendor, for example, `TIZEN`
1.95 +
1.96 +### Windows Phone 7 and 8 Quirks
1.97 +
1.98 +- Returns the device model specified by the manufacturer. For example, the Samsung Focus returns `SGH-i917`.
1.99 +
1.100 +## device.platform
1.101 +
1.102 +Get the device's operating system name.
1.103 +
1.104 + var string = device.platform;
1.105 +
1.106 +### Supported Platforms
1.107 +
1.108 +- Android
1.109 +- BlackBerry 10
1.110 +- Browser4
1.111 +- Firefox OS
1.112 +- iOS
1.113 +- Tizen
1.114 +- Windows Phone 7 and 8
1.115 +- Windows 8
1.116 +
1.117 +### Quick Example
1.118 +
1.119 + // Depending on the device, a few examples are:
1.120 + // - "Android"
1.121 + // - "BlackBerry 10"
1.122 + // - Browser: returns "MacIntel" on Mac
1.123 + // returns "Win32" on Windows
1.124 + // - "iOS"
1.125 + // - "WinCE"
1.126 + // - "Tizen"
1.127 + var devicePlatform = device.platform;
1.128 +
1.129 +### Windows Phone 7 Quirks
1.130 +
1.131 +Windows Phone 7 devices report the platform as `WinCE`.
1.132 +
1.133 +### Windows Phone 8 Quirks
1.134 +
1.135 +Windows Phone 8 devices report the platform as `Win32NT`.
1.136 +
1.137 +## device.uuid
1.138 +
1.139 +Get the device's Universally Unique Identifier ([UUID](http://en.wikipedia.org/wiki/Universally_Unique_Identifier)).
1.140 +
1.141 + var string = device.uuid;
1.142 +
1.143 +### Description
1.144 +
1.145 +The details of how a UUID is generated are determined by the device manufacturer and are specific to the device's platform or model.
1.146 +
1.147 +### Supported Platforms
1.148 +
1.149 +- Android
1.150 +- BlackBerry 10
1.151 +- iOS
1.152 +- Tizen
1.153 +- Windows Phone 7 and 8
1.154 +- Windows 8
1.155 +
1.156 +### Quick Example
1.157 +
1.158 + // Android: Returns a random 64-bit integer (as a string, again!)
1.159 + // The integer is generated on the device's first boot
1.160 + //
1.161 + // BlackBerry: Returns the PIN number of the device
1.162 + // This is a nine-digit unique integer (as a string, though!)
1.163 + //
1.164 + // iPhone: (Paraphrased from the UIDevice Class documentation)
1.165 + // Returns a string of hash values created from multiple hardware identifies.
1.166 + // It is guaranteed to be unique for every device and can't be tied
1.167 + // to the user account.
1.168 + // Windows Phone 7 : Returns a hash of device+current user,
1.169 + // if the user is not defined, a guid is generated and will persist until the app is uninstalled
1.170 + // Tizen: returns the device IMEI (International Mobile Equipment Identity or IMEI is a number
1.171 + // unique to every GSM and UMTS mobile phone.
1.172 + var deviceID = device.uuid;
1.173 +
1.174 +### iOS Quirk
1.175 +
1.176 +The `uuid` on iOS is not unique to a device, but varies for each
1.177 +application, for each installation. It changes if you delete and
1.178 +re-install the app, and possibly also when you upgrade iOS, or even
1.179 +upgrade the app per version (apparent in iOS 5.1). The `uuid` is not
1.180 +a reliable value.
1.181 +
1.182 +### Windows Phone 7 and 8 Quirks
1.183 +
1.184 +The `uuid` for Windows Phone 7 requires the permission
1.185 +`ID_CAP_IDENTITY_DEVICE`. Microsoft will likely deprecate this
1.186 +property soon. If the capability is not available, the application
1.187 +generates a persistent guid that is maintained for the duration of the
1.188 +application's installation on the device.
1.189 +
1.190 +## device.version
1.191 +
1.192 +Get the operating system version.
1.193 +
1.194 + var string = device.version;
1.195 +
1.196 +### Supported Platforms
1.197 +
1.198 +- Android 2.1+
1.199 +- BlackBerry 10
1.200 +- Browser
1.201 +- iOS
1.202 +- Tizen
1.203 +- Windows Phone 7 and 8
1.204 +- Windows 8
1.205 +
1.206 +### Quick Example
1.207 +
1.208 + // Android: Froyo OS would return "2.2"
1.209 + // Eclair OS would return "2.1", "2.0.1", or "2.0"
1.210 + // Version can also return update level "2.1-update1"
1.211 + //
1.212 + // BlackBerry: Torch 9800 using OS 6.0 would return "6.0.0.600"
1.213 + //
1.214 + // Browser: Returns version number for the browser
1.215 + //
1.216 + // iPhone: iOS 3.2 returns "3.2"
1.217 + //
1.218 + // Windows Phone 7: returns current OS version number, ex. on Mango returns 7.10.7720
1.219 + // Tizen: returns "TIZEN_20120425_2"
1.220 + var deviceVersion = device.version;
1.221 +
