Accessing Device Features

AccessingAccessingDevice Features

Ivano MalavoltaIvano Malavolta

[email protected]

http://www.di.univaq.it/malavolta

Roadmap

• Media Capture

• Camera• Camera

• Contacts

• Events

• Accelerometer

Media Capture

navigator.device.capture

Provides access for capturing

• AudioAudioAudioAudio• ImageImageImageImage• VideoVideoVideoVideo• VideoVideoVideoVideo

directly from the device

The Capture Object

navigator.device.capture

PropertiesProperties

supportedAudioModessupportedAudioModessupportedAudioModessupportedAudioModesThe audio recording formats supported by the device

supportedImageModessupportedImageModessupportedImageModessupportedImageModesThe recording image sizes and formats supported by the devicethe device

supportedVideoModessupportedVideoModessupportedVideoModessupportedVideoModesThe recording video resolutions and formats supported by the device

They all contain an array of ConfigurationDataConfigurationDataConfigurationDataConfigurationData objects

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. TypeTypeTypeType: String

The string in lower case representing the media typeThe string in lower case representing the media type

– video/3gpp

– video/quicktime

– image/jpeg

– audio/amr

– audio/wav

ConfigurationData

2.2.2.2. heightheightheightheight: integer

The height of the image or video in pixelsThe height of the image or video in pixels

3.3.3.3. widthwidthwidthwidth: 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

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);

}}

Capturing Audio

It is called on the capture object

Start the audio recorder application and return information about captured audio clip files

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 appappappapp

The operation allows the device user to capture multiple recordings multiple recordings multiple recordings multiple recordings in a single sessionmultiple recordings multiple recordings multiple recordings multiple recordings in a single session

Capturing Audio

When the capture operation is finished, it will invoke the CaptureCBCaptureCBCaptureCBCaptureCB callback with an array the CaptureCBCaptureCBCaptureCBCaptureCB callback with an array of MediaFile objects

If the operation is terminated by the user before an audio clip is captured, the CaptureErrorCBCaptureErrorCBCaptureErrorCBCaptureErrorCBcallback will be invoked callback will be invoked

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/wavaudio/amr

Audio Example

var options = { limit: 2, duration: 5 };

navigator.device.capture.captureAudio(win, fail, options);

function win(mediaFiles) {

var i;

for (i=0; i<mediaFiles.length; i++) {

console.log(mediaFiles[i]);

}

}}

function fail(error) {

console.log(‘Error with code: ' + error.code);

}

Capturing Images

It is called on the capture object

Start the camera application and return information about captured image file(s)

Capturing Images

It starts an asynchronous operation asynchronous operation asynchronous operation asynchronous operation to capture imagesimages

It uses the device camera applicationdevice camera applicationdevice camera applicationdevice camera application

The operation allows the device user to capture multiple multiple multiple multiple images images images images in a single sessionmultiple multiple multiple multiple images images images images in a single session

Capturing Images

Similarly to captureAudio...

When the capture operation is finished, it will invoke the CaptureCBCaptureCBCaptureCBCaptureCB 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 CaptureErrorCBCaptureErrorCBCaptureErrorCBCaptureErrorCB callback will be invoked

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

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<mediaFiles.length; i++) {

upload(mediaFiles[i]);}

}

It is verysimilar tothe audio example!

}

function fail(error) {console.log(‘Error with code: ' + error.code);

}

Recording Videos

It is called on the capture object

Start the video recorder application and return information about captured video clip file(s).

Recording Videos

It starts an asynchronous operation asynchronous operation asynchronous operation asynchronous operation to record videos

It uses the device video recording applicationdevice video recording applicationdevice video recording applicationdevice video recording application

The operation allows the device user to capture multiple multiple multiple multiple recordings recordings recordings recordings in a single session

Capturing Videos

Similarly to captureAudio...

When the capture operation is finished, it will invoke the CaptureCBCaptureCBCaptureCBCaptureCB 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 CaptureErrorCBCaptureErrorCBCaptureErrorCBCaptureErrorCB callback will be invoked

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

• mmmmode 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/quicktimevideo/3gpp

Video Example

navigator.device.capture.captureVideo(win, fail, {});navigator.device.capture.captureVideo(win, fail, {});

function win(mediaFiles) {

var i;

for (i=0; i<mediaFiles.length; i++) {

upload(mediaFiles[i]);

}

}

It is verysimilar to the image & audio examples!

}

function fail(error) {

console.log(‘Error with code: ' + error.code);

}

Media Files

A MediaFile encapsulates properties of a media capture file

Name Name Name Name (String)The name of the file, without path information

fullPathfullPathfullPathfullPath (String)The full path of the file, including the name

TypeTypeTypeType (String)TypeTypeTypeType (String)The mime type

lastModifiedDatelastModifiedDatelastModifiedDatelastModifiedDate (Date)The date and time that the file was last modified

SizeSizeSizeSize (Integer)The size of the file, in bytes

Capture Errors

Encapsulates the error code resulting from a failed media capture operationmedia capture operation

It contains a prepreprepre----defined defined defined defined error error error error codecodecodecode

CaptureError.CAPTURE_INTERNAL_ERR

CaptureError.CAPTURE_APPLICATION_BUSYCaptureError.CAPTURE_APPLICATION_BUSY

CaptureError.CAPTURE_INVALID_ARGUMENT

CaptureError.CAPTURE_NO_MEDIA_FILES

CaptureError.CAPTURE_NOT__SUPPORTED

Roadmap

• Media Capture

• Camera• Camera

• Contacts

• Events

• Accelerometer

Camera

A dedicated API for capturing images from the device’s default camera applicationdefault camera application

Takes a photo using the camera or retrieves a photo from the device's album

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

Camera Options

getPicture() can be called with the following options

Camera Options

qqqquality uality uality uality (integer)

Quality of saved imageQuality of saved image

Range [0, 100]

ddddestinationTypeestinationTypeestinationTypeestinationType (Integer)

Camera Options

ssssourceTypeourceTypeourceTypeourceType (integer)

allowEditallowEditallowEditallowEdit (Boolean)

Allow simple editing of image before selection

Camera Options

encodingTypeencodingTypeencodingTypeencodingType (integer)

targetWidthtargetWidthtargetWidthtargetWidth, , , , targetHeighttargetHeighttargetHeighttargetHeight (Integer)

Width/height in pixels to scale image

Camera Options

mediaTypemediaTypemediaTypemediaType (integer)

correctOrientationcorrectOrientationcorrectOrientationcorrectOrientation (Boolean)

Rotate the image to correct for the orientation of the device during capture

Camera Options

saveToPhotoAlbumsaveToPhotoAlbumsaveToPhotoAlbumsaveToPhotoAlbum (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 checkEvery platform has its own quirks, you better checkthem on the Cordova documentation

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

Roadmap

• Media Capture

• Camera• Camera

• Contacts

• Events

• Accelerometer

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.createcontacts.createcontacts.createcontacts.create

• contacts.findcontacts.findcontacts.findcontacts.find

Creating contacts

navigator.contacts.create(properties)

It is a synchronoussynchronoussynchronoussynchronous 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 methodto invoke the Contact.save method

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“

});

The Contact Object

It represents a user contactIt represents a user contactIt represents a user contactIt 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 oneor more Contacts from the device contacts databaseor more Contacts from the device contacts database

Contact Properties

It contains all the properties that a contact can have

Every platform has its own quirks, you better checkthem on the Cordova documentation

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 databaseRemoves 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 ididididalready exists

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);

};

Finding contacts

navigator.contacts.find(

contactFields, contactFields,

contactSuccess,

contactError,

contactFindOptions

);

It is an asyncronousasyncronousasyncronousasyncronous function that queries the device It is an asyncronousasyncronousasyncronousasyncronous function that queries the device contacts database and returns an array of Contact Contact Contact Contact objects

Find Parameters

contactFieldscontactFieldscontactFieldscontactFields, StringContact 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

contactSuccesscontactSuccesscontactSuccesscontactSuccessSuccess callback function that is invoked with the array of contacts returned from the contacts database

contactErrorcontactErrorcontactErrorcontactError [optional]Error callback function

contactFindOptionscontactFindOptionscontactFindOptionscontactFindOptions [Optional]Search options to filter contacts

Contact Fields

Specifies which fields should be included in the Contact objects resulting from a find operationobjects 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);

};

Contact Find Options

Contains properties that can be used to filter the results

PropertiesPropertiesPropertiesProperties

filter filter filter filter (String) (Default: "")The search string used to find contactsA case-insensitive, partial value match is applied to each A case-insensitive, partial value match is applied to each

field specified in the contactFieldscontactFieldscontactFieldscontactFields parameter

multiplemultiplemultiplemultiple (Boolean) (default: false)Determines if the find operation should return multiple

contacts

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<contacts.length; i++) {

console.log(contacts[i].displayName);console.log(contacts[i].displayName);

}

};

function fail(contactError) {

alert("Error = " + contactError.code);

};

ContactError

It is always returned to the fail callback when an error occurserror occurs

ContactError.UNKNOWN_ERROR

ContactError.INVALID_ARGUMENT_ERROR

ContactError.TIMEOUT_ERROR

ContactError.PENDING_OPERATION_ERROR

ContactError.IO_ERRORContactError.IO_ERROR

ContactError.NOT_SUPPORTED_ERROR

ContactError.PERMISSION_DENIED_ERROR

Roadmap

• Media Capture

• Camera• Camera

• Contacts

• Events

• Accelerometer

Events

An event is an action that can be detected by yourJavascript codeJavascript code

In traditional JS programs, any element of the pagecan have certain events

– ontouchstart, onclick, ...– ontouchstart, onclick, ...

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 timethe event is fired

Main Cordova Events

other events are specific to Cordova applications

• deviceready

• pause, resume

• online, offline

• batterycritical, batterylow, batterystatus

• backbutton, menubutton, searchbutton• backbutton, menubutton, searchbutton

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 loaded1. The DOM has loaded2. the Cordova native API are loaded too

Only at this point you can try to call Cordova APIs

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

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)

Connection

If you need to know the type of connection, you have touse the navigator.network.connection objectuse the navigator.network.connection object

It has a type property with one of the following values:

Connection.UNKNOWN

Connection.ETHERNETConnection.ETHERNET

Connection.WIFI

Connection.CELL_2G

Connection.CELL_3G

Connection.CELL_4G

Connection.NONE

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 isdevice-specific

similar to batterycritical, but with a higher threeshold

batterystatus

fires a change in the battery status is detected

the battery status mustchange of at least 1%

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)

isPluggedisPluggedisPluggedisPlugged (Boolean)

Represents whether or not the device is plugged in or not

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” buttonfires when the user presses the “menu” button

searchbutton

fires when the user presses the “search” button

Roadmap

• Media Capture

• Camera• Camera

• Contacts

• Events

• Accelerometer

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.getCurrentAccelerationaccelerometer.getCurrentAccelerationaccelerometer.getCurrentAccelerationaccelerometer.getCurrentAcceleration• accelerometer.watchAccelerationaccelerometer.watchAccelerationaccelerometer.watchAccelerationaccelerometer.watchAcceleration• accelerometer.clearWatchaccelerometer.clearWatchaccelerometer.clearWatchaccelerometer.clearWatch

getCurrentAcceleration

It gets the current acceleration along the x, y, and z axisaxis

getCurrentAcceleration(win, fail);

winwinwinwincallback function with an AccelerationAccelerationAccelerationAcceleration parameter

failfailfailfailerror callback

watchAcceleration

It gets the device's current acceleration at a regular interval

var watchID = navigator.accelerometer.watchAcceleration(win, fail, [options]);

winwinwinwincallback function with an AccelerationAccelerationAccelerationAcceleration parameter, it is called at regular intervals

failfailfailfailfailfailfailfailerror callback

optionsoptionsoptionsoptionsthe interval is specified in the frequency parameter

clearWatch

Stop watching the Acceleration referenced by the watch ID parameterwatch ID parameter

clearWatch(watchID);

watchIDwatchIDwatchIDwatchID

ID returned by accelerometer.watchAccelerationID returned by accelerometer.watchAcceleration

Acceleration

It contains Accelerometer data captured at a specific point in timepoint in time

PropertiesPropertiesPropertiesPropertiesxxxx (Number)

Amount of acceleration on the x-axis. (in m/s^2)y y y y (Number)

these values include the effect ofgravity (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

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;

}

}

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 });

References