Slide 1

Slide 1 text

Accessing Accessing Device Features Ivano Malavolta Ivano Malavolta [email protected] http://www.di.univaq.it/malavolta

Slide 2

Slide 2 text

Roadmap • Media Capture • Camera • Camera • Contacts • Events • Accelerometer

Slide 3

Slide 3 text

Media Capture navigator.device.capture Provides access for capturing • Audio Audio Audio Audio • Image Image Image Image • Video Video Video Video • Video Video Video Video directly from the device

Slide 4

Slide 4 text

The Capture Object navigator.device.capture Properties Properties supportedAudioModes supportedAudioModes supportedAudioModes supportedAudioModes The audio recording formats supported by the device supportedImageModes supportedImageModes supportedImageModes supportedImageModes The recording image sizes and formats supported by the device the device supportedVideoModes supportedVideoModes supportedVideoModes supportedVideoModes The recording video resolutions and formats supported by the device They all contain an array of ConfigurationData ConfigurationData ConfigurationData ConfigurationData objects

Slide 5

Slide 5 text

ConfigurationData It is used to describe media capture modes media capture modes media capture modes media capture modes supported by the device Properties: 1. 1. 1. 1. Type Type Type Type: String The string in lower case representing the media type The string in lower case representing the media type – video/3gpp – video/quicktime – image/jpeg – audio/amr – audio/wav

Slide 6

Slide 6 text

ConfigurationData 2. 2. 2. 2. height height height height: integer The height of the image or video in pixels The height of the image or video in pixels 3. 3. 3. 3. width width width width: integer The width of the image or video in pixels In the case of a sound clip, the value of these attributes In the case of a sound clip, the value of these attributes is 0

Slide 7

Slide 7 text

Example var imageModes = navigator.device.capture.supportedImageModes; navigator.device.capture.supportedImageModes; for each (var mode in imageModes) { console.log(mode.type); console.log(mode.height); console.log(mode.width); } }

Slide 8

Slide 8 text

Capturing Audio It is called on the capture object Start the audio recorder application and return information about captured audio clip files

Slide 9

Slide 9 text

Capturing Audio It starts an asynchronous operation asynchronous operation asynchronous operation asynchronous operation to capture audio recordings recordings It uses the device's default audio recording default audio recording default audio recording default audio recording app app app app The operation allows the device user to capture multiple recordings multiple recordings multiple recordings multiple recordings in a single session multiple recordings multiple recordings multiple recordings multiple recordings in a single session

Slide 10

Slide 10 text

Capturing Audio When the capture operation is finished, it will invoke the CaptureCB CaptureCB CaptureCB CaptureCB callback with an array the CaptureCB CaptureCB CaptureCB CaptureCB callback with an array of MediaFile objects If the operation is terminated by the user before an audio clip is captured, the CaptureErrorCB CaptureErrorCB CaptureErrorCB CaptureErrorCB callback will be invoked callback will be invoked

Slide 11

Slide 11 text

Capture Audio Options Encapsulates audio capture configuration options Properties: • limit limit limit limit (not supported in iOS only 1 recording at a time) The maximum number of audio clips the device user can record in a single capture operation • Duration Duration Duration Duration (not supported in Android unlimited) • Duration Duration Duration Duration (not supported in Android unlimited) The maximum duration of an audio sound clip, in seconds • Mode Mode Mode Mode (not supported in Android and iOS) The selected audio mode, it must match one of the elements in capture.supportedAudioModes audio/wav audio/amr

Slide 12

Slide 12 text

Audio Example var options = { limit: 2, duration: 5 }; navigator.device.capture.captureAudio(win, fail, options); function win(mediaFiles) { var i; for (i=0; i

Slide 13

Slide 13 text

Capturing Images It is called on the capture object Start the camera application and return information about captured image file(s)

Slide 14

Slide 14 text

Capturing Images It starts an asynchronous operation asynchronous operation asynchronous operation asynchronous operation to capture images images It uses the device camera application device camera application device camera application device camera application The operation allows the device user to capture multiple multiple multiple multiple images images images images in a single session multiple multiple multiple multiple images images images images in a single session

Slide 15

Slide 15 text

Capturing Images Similarly to captureAudio... When the capture operation is finished, it will invoke the CaptureCB CaptureCB CaptureCB CaptureCB callback with an array of MediaFile objects If the operation is terminated by the user before any If the operation is terminated by the user before any image is captured, the CaptureErrorCB CaptureErrorCB CaptureErrorCB CaptureErrorCB callback will be invoked

Slide 16

Slide 16 text

Capture Image Options Encapsulates image capture configuration options Properties: • limit limit limit limit (not supported in iOS only 1 image at a time) The maximum number of images the device user can capture in a single capture operation • Mode Mode Mode Mode (not supported in Android and iOS image/jpeg only) The selected image mode, it must match one of the elements in capture.supportedImageModes

Slide 17

Slide 17 text

Image Example var options = { limit: 3}; navigator.device.capture.captureImage(win, fail, navigator.device.capture.captureImage(win, fail, options); function win(mediaFiles) { var i; for (i=0; i

Slide 18

Slide 18 text

Recording Videos It is called on the capture object Start the video recorder application and return information about captured video clip file(s).

Slide 19

Slide 19 text

Recording Videos It starts an asynchronous operation asynchronous operation asynchronous operation asynchronous operation to record videos It uses the device video recording application device video recording application device video recording application device video recording application The operation allows the device user to capture multiple multiple multiple multiple recordings recordings recordings recordings in a single session

Slide 20

Slide 20 text

Capturing Videos Similarly to captureAudio... When the capture operation is finished, it will invoke the CaptureCB CaptureCB CaptureCB CaptureCB callback with an array of MediaFile objects If the operation is terminated by the user before any If the operation is terminated by the user before any video is recorded, the CaptureErrorCB CaptureErrorCB CaptureErrorCB CaptureErrorCB callback will be invoked

Slide 21

Slide 21 text

Capture Video Options Encapsulates video recording configuration options Properties: • limit limit limit limit (not supported in iOS only 1 video at a time) The maximum number of video clips the device user can record in a single capture operation • duration duration duration duration (not supported in Android and iOS unlimited) • duration duration duration duration (not supported in Android and iOS unlimited) The maximum duration of a video clip, in seconds • m m m mode ode ode ode (not supported in Android and iOS) The selected video recording mode, it must match one of the elements in capture.supportedVideoModes video/quicktime video/3gpp

Slide 22

Slide 22 text

Video Example navigator.device.capture.captureVideo(win, fail, {}); navigator.device.capture.captureVideo(win, fail, {}); function win(mediaFiles) { var i; for (i=0; i

Slide 23

Slide 23 text

Media Files A MediaFile encapsulates properties of a media capture file Name Name Name Name (String) The name of the file, without path information fullPath fullPath fullPath fullPath (String) The full path of the file, including the name Type Type Type Type (String) Type Type Type Type (String) The mime type lastModifiedDate lastModifiedDate lastModifiedDate lastModifiedDate (Date) The date and time that the file was last modified Size Size Size Size (Integer) The size of the file, in bytes

Slide 24

Slide 24 text

Capture Errors Encapsulates the error code resulting from a failed media capture operation media capture operation It contains a pre pre pre pre- - - -defined defined defined defined error error error error code code code code CaptureError.CAPTURE_INTERNAL_ERR CaptureError.CAPTURE_APPLICATION_BUSY CaptureError.CAPTURE_APPLICATION_BUSY CaptureError.CAPTURE_INVALID_ARGUMENT CaptureError.CAPTURE_NO_MEDIA_FILES CaptureError.CAPTURE_NOT__SUPPORTED

Slide 25

Slide 25 text

Roadmap • Media Capture • Camera • Camera • Contacts • Events • Accelerometer

Slide 26

Slide 26 text

Camera A dedicated API for capturing images from the device’s default camera application default camera application Takes a photo using the camera or retrieves a photo from the device's album

Slide 27

Slide 27 text

Camera The result of a call to getPicture() can be: • a base64 encoded string, or • the URI of an image file Encoding the image using Base64 has caused memory Encoding the image using Base64 has caused memory issues on some of these devices it is recommended to use the URI of the image file

Slide 28

Slide 28 text

Camera Options getPicture() can be called with the following options

Slide 29

Slide 29 text

Camera Options q q q quality uality uality uality (integer) Quality of saved image Quality of saved image Range [0, 100] d d d destinationType estinationType estinationType estinationType (Integer)

Slide 30

Slide 30 text

Camera Options s s s sourceType ourceType ourceType ourceType (integer) allowEdit allowEdit allowEdit allowEdit (Boolean) Allow simple editing of image before selection

Slide 31

Slide 31 text

Camera Options encodingType encodingType encodingType encodingType (integer) targetWidth targetWidth targetWidth targetWidth, , , , targetHeight targetHeight targetHeight targetHeight (Integer) Width/height in pixels to scale image

Slide 32

Slide 32 text

Camera Options mediaType mediaType mediaType mediaType (integer) correctOrientation correctOrientation correctOrientation correctOrientation (Boolean) Rotate the image to correct for the orientation of the device during capture

Slide 33

Slide 33 text

Camera Options saveToPhotoAlbum saveToPhotoAlbum saveToPhotoAlbum saveToPhotoAlbum (Boolean) Save the image to the photo album on the device after Save the image to the photo album on the device after capture Every platform has its own quirks, you better check Every platform has its own quirks, you better check them on the Cordova documentation

Slide 34

Slide 34 text

Camera Example navigator.camera.getPicture(win, fail, { quality: 50, { quality: 50, destinationType: destinationType.FILE_URI, pictureSource.PHOTOLIBRARY }); function win(imageURI) { var element = $(“#block”); element.src(imageURI); element.src(imageURI); } // fail function omitted here

Slide 35

Slide 35 text

Roadmap • Media Capture • Camera • Camera • Contacts • Events • Accelerometer

Slide 36

Slide 36 text

Contacts navigator.contacts It is a global object that provides access to the device contacts DB You can call 2 methods on You can call 2 methods on navigator.contacts • contacts.create contacts.create contacts.create contacts.create • contacts.find contacts.find contacts.find contacts.find

Slide 37

Slide 37 text

Creating contacts navigator.contacts.create(properties) It is a synchronous synchronous synchronous synchronous function that returns a new Contact Contact Contact Contact object To persist the Contact object to the device, you have to invoke the Contact.save method to invoke the Contact.save method

Slide 38

Slide 38 text

Creating contacts navigator.contacts.create(properties) the properties parameter is a map of properties of the new Contact object ex. ex. var contact = navigator.contacts.create({ "displayName": “Ivano“ });

Slide 39

Slide 39 text

The Contact Object It represents a user contact It represents a user contact It represents a user contact It represents a user contact A contact can be created, saved or removed from the device contacts database The contacts.find method is used for retrieving one or more Contacts from the device contacts database or more Contacts from the device contacts database

Slide 40

Slide 40 text

Contact Properties It contains all the properties that a contact can have Every platform has its own quirks, you better check them on the Cordova documentation

Slide 41

Slide 41 text

Contact Methods A contact object provides the following methods • clone() clone() clone() clone() • clone() clone() clone() clone() Returns a new Contact object that is a deep copy of the calling object, its id property is null • remove(win, fail) remove(win, fail) remove(win, fail) remove(win, fail) Removes the contact from the device contacts database Removes the contact from the device contacts database • save(win, fail) save(win, fail) save(win, fail) save(win, fail) Saves a new contact to the device contacts database, or updates an existing contact if a contact with the same id id id id already exists

Slide 42

Slide 42 text

Create Contact Example var contact = navigator.contacts.create({ "displayName": “Ivano“ }); }); var name = new ContactName(); name.givenName = “Ivano“; name.familyName = “Malavolta“; contact.name = name; contact.birthday = new Date(“19 July 1983"); contact.save(win, fail); function win(contact) { alert("Save Success"); }; function fail(contactError) { alert("Error = " + contactError.code); };

Slide 43

Slide 43 text

Finding contacts navigator.contacts.find( contactFields, contactFields, contactSuccess, contactError, contactFindOptions ); It is an asyncronous asyncronous asyncronous asyncronous function that queries the device It is an asyncronous asyncronous asyncronous asyncronous function that queries the device contacts database and returns an array of Contact Contact Contact Contact objects

Slide 44

Slide 44 text

Find Parameters contactFields contactFields contactFields contactFields, String Contact fields to be used as search qualifier. Only these Contact fields to be used as search qualifier. Only these fields will have values in the resulting Contact objects contactSuccess contactSuccess contactSuccess contactSuccess Success callback function that is invoked with the array of contacts returned from the contacts database contactError contactError contactError contactError [optional] Error callback function contactFindOptions contactFindOptions contactFindOptions contactFindOptions [Optional] Search options to filter contacts

Slide 45

Slide 45 text

Contact Fields Specifies which fields should be included in the Contact objects resulting from a find operation objects resulting from a find operation var fields = ["displayName", "name"]; // or [“*”] navigator.contacts.find(fields, win, fail); function win(contacts) { function win(contacts) { console.log(‘ok'); }; function fail(err) { console.log(err.code); };

Slide 46

Slide 46 text

Contact Find Options Contains properties that can be used to filter the results Properties Properties Properties Properties filter filter filter filter (String) (Default: "") The search string used to find contacts A case-insensitive, partial value match is applied to each A case-insensitive, partial value match is applied to each field specified in the contactFields contactFields contactFields contactFields parameter multiple multiple multiple multiple (Boolean) (default: false) Determines if the find operation should return multiple contacts

Slide 47

Slide 47 text

Find Contact Example var options = new ContactFindOptions(); options.filter = “Ivano"; options.multiple = true; filter = ["displayName",“birthday"]; navigator.contacts.find(filter, win, fail, options); function win(contacts) { for (var i=0; i

Slide 48

Slide 48 text

ContactError It is always returned to the fail callback when an error occurs error occurs ContactError.UNKNOWN_ERROR ContactError.INVALID_ARGUMENT_ERROR ContactError.TIMEOUT_ERROR ContactError.PENDING_OPERATION_ERROR ContactError.IO_ERROR ContactError.IO_ERROR ContactError.NOT_SUPPORTED_ERROR ContactError.PERMISSION_DENIED_ERROR

Slide 49

Slide 49 text

Roadmap • Media Capture • Camera • Camera • Contacts • Events • Accelerometer

Slide 50

Slide 50 text

Events An event is an action that can be detected by your Javascript code Javascript code In traditional JS programs, any element of the page can have certain events – ontouchstart, onclick, ... – ontouchstart, onclick, ...

Slide 51

Slide 51 text

Listening to Events To use any event, you’ll want to use an event listener document.addEventListener(EVENTNAME, onEvent, false); function onEvent() { // handle the event } EVENTNAME is the name of the event you want to listen to onEvent() is the callback function triggered every time the event is fired

Slide 52

Slide 52 text

Main Cordova Events other events are specific to Cordova applications • deviceready • pause, resume • online, offline • batterycritical, batterylow, batterystatus • backbutton, menubutton, searchbutton • backbutton, menubutton, searchbutton

Slide 53

Slide 53 text

deviceready It is the most important in event in a Cordova app Cordova consists of two code bases: Cordova consists of two code bases: • native • JavaScript Once deviceready is fired, you know two things: 1. The DOM has loaded 1. The DOM has loaded 2. the Cordova native API are loaded too Only at this point you can try to call Cordova APIs

Slide 54

Slide 54 text

App lifecycle Events Based on two main events: pause fires when an application is put into the background resume fires when a paused application is put back into the foreground

Slide 55

Slide 55 text

Connection Events Based on two main events: When running in the WP emulator, the connection.status of the device is always unknown online fires when the application's network connection changes to being online (that is, it is connected to the Internet) device is always unknown the online event will NOT fire offline fires when the application's network connection changes to being offline (that is, no Internet connection available)

Slide 56

Slide 56 text

Connection If you need to know the type of connection, you have to use the navigator.network.connection object use the navigator.network.connection object It has a type property with one of the following values: Connection.UNKNOWN Connection.ETHERNET Connection.ETHERNET Connection.WIFI Connection.CELL_2G Connection.CELL_3G Connection.CELL_4G Connection.NONE

Slide 57

Slide 57 text

Battery Events Based on three main events: this value is batterycritical fires when the battery has reached the critical level threshold batterylow similar to , but with a higher threeshold this value is device-specific similar to batterycritical, but with a higher threeshold batterystatus fires a change in the battery status is detected the battery status must change of at least 1%

Slide 58

Slide 58 text

Battery Events The handler of a battery event is always called with an object that contains two properties: level level level level (Integer) The percentage of battery (0-100) isPlugged isPlugged isPlugged isPlugged (Boolean) Represents whether or not the device is plugged in or not

Slide 59

Slide 59 text

Android buttons Events Based on three main events: backbutton fires when the user presses the “back” button menubutton fires when the user presses the “menu” button fires when the user presses the “menu” button searchbutton fires when the user presses the “search” button

Slide 60

Slide 60 text

Roadmap • Media Capture • Camera • Camera • Contacts • Events • Accelerometer

Slide 61

Slide 61 text

Accelerometer navigator.accelerometer It is a global object that captures device motion in the x, y, and z direction You can call 3 methods on it: You can call 3 methods on it: • accelerometer.getCurrentAcceleration accelerometer.getCurrentAcceleration accelerometer.getCurrentAcceleration accelerometer.getCurrentAcceleration • accelerometer.watchAcceleration accelerometer.watchAcceleration accelerometer.watchAcceleration accelerometer.watchAcceleration • accelerometer.clearWatch accelerometer.clearWatch accelerometer.clearWatch accelerometer.clearWatch

Slide 62

Slide 62 text

getCurrentAcceleration It gets the current acceleration along the x, y, and z axis axis getCurrentAcceleration(win, fail); win win win win callback function with an Acceleration Acceleration Acceleration Acceleration parameter fail fail fail fail error callback

Slide 63

Slide 63 text

watchAcceleration It gets the device's current acceleration at a regular interval var watchID = navigator.accelerometer.watchAcceleration(win, fail, [options]); win win win win callback function with an Acceleration Acceleration Acceleration Acceleration parameter, it is called at regular intervals fail fail fail fail fail fail fail fail error callback options options options options the interval is specified in the frequency parameter

Slide 64

Slide 64 text

clearWatch Stop watching the Acceleration referenced by the watch ID parameter watch ID parameter clearWatch(watchID); watchID watchID watchID watchID ID returned by accelerometer.watchAcceleration ID returned by accelerometer.watchAcceleration

Slide 65

Slide 65 text

Acceleration It contains Accelerometer data captured at a specific point in time point in time Properties Properties Properties Properties x x x x (Number) Amount of acceleration on the x-axis. (in m/s^2) y y y y (Number) these values include the effect of gravity (9.81 m/s^2) Amount of acceleration on the y-axis. (in m/s^2) z z z z (Number) Amount of acceleration on the z-axis. (in m/s^2) timestamp timestamp timestamp timestamp (Timestamp) Creation timestamp in milliseconds

Slide 66

Slide 66 text

Example var options = { frequency: 3000 }; var watchID = navigator.accelerometer.watchAcceleration(win, fail, options); options); function win(acc) { if((acc.x == 0) && (acc.y == 0) && (acc.z == 9,81)) { console.log(“I am on a table”); stop(); } } function fail() { console.log(“error”); console.log(“error”); } function stop() { if(watchID) { navigator.accelerometer.clearWatch(watchID); watchID = null; } }

Slide 67

Slide 67 text

Shake Detection var previousReading = {x: null, y: null, z: null}; navigator.accelerometer.watchAcceleration(function (reading) { var changes = {}, var changes = {}, bound = 3; if (previousReading.x !== null) { changes.x = Math.abs(previousReading.x, reading.x); changes.y = Math.abs(previousReading.y, reading.y); changes.z = Math.abs(previousReading.z, reading.z); } if (changes.x>bound && changes.y>bound && changes.z>bound) { console.log(‹shake detected'); console.log(‹shake detected'); } previousReading = { x: reading.x, y: reading.y, z: reading.z } }, null, { frequency: 300 });

Slide 68

Slide 68 text

References