Exif API
Remark: In order to access files, a proper privilege has to be defined additionally:
- for accessing only internal storage using this API, a privilege http://tizen.org/privilege/mediastorage must be provided,
- for accessing only external storage using this API, a privilege http://tizen.org/privilege/externalstorage must be provided,
- for accessing internal and external storage using this API, privileges (http://tizen.org/privilege/mediastorage and http://tizen.org/privilege/externalstorage) must be provided.
- Storage privileges are privacy-related privileges and there is a need of asking user directly with proper pop-up. Please refer to Privacy Privilege API for more details.
For more information about how to use Exif API, see Exif Guide.
Since: 2.3.1
Table of Contents
- 1. Type Definitions
- 1.1. WhiteBalanceMode
- 1.2. ExposureProgram
- 2. Interfaces
- 2.1. ExifManagerObject
- 2.2. ExifManager
- 2.3. ExifInit
- 2.4. ExifInformation
- 2.5. ExifInformationSuccessCallback
- 2.6. ExifThumbnailSuccessCallback
- 3. Full WebIDL
Summary of Interfaces and Methods
Interface | Method |
---|---|
ExifManagerObject | |
ExifManager |
void getExifInfo (DOMString uri, ExifInformationSuccessCallback successCallback, optional ErrorCallback? errorCallback)
void saveExifInfo (ExifInformation exifInfo, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void getThumbnail (DOMString uri, ExifThumbnailSuccessCallback successCallback, optional ErrorCallback? errorCallback)
|
ExifInit | |
ExifInformation | |
ExifInformationSuccessCallback | void onsuccess (ExifInformation exifInfo) |
ExifThumbnailSuccessCallback | void onsuccess (DOMString? uri) |
1. Type Definitions
1.1. WhiteBalanceMode
enum WhiteBalanceMode { "AUTO", "MANUAL" };
Since: 2.3.1
- AUTO - Automatic White Balance mode
- MANUAL - Manual White Balance mode
1.2. ExposureProgram
enum ExposureProgram { "NOT_DEFINED", "MANUAL", "NORMAL", "APERTURE_PRIORITY", "SHUTTER_PRIORITY", "CREATIVE_PROGRAM", "ACTION_PROGRAM", "PORTRAIT_MODE", "LANDSCAPE_MODE" };
Since: 2.3.1
Some additional information can be found in the List of digital camera modes article.
- NOT_DEFINED - Exposure program info is not present or is unknown
- MANUAL - In the manual mode both shutter speed and aperture are independently set manually (with ISO sensitivity also set manually)
- NORMAL - Corresponds to normal exposure program info.
- APERTURE_PRIORITY - aka A, Av(Aperture value) mode enables manual control of the aperture, and shutter speed is calculated by the camera for proper exposure (given an ISO sensitivity)
- SHUTTER_PRIORITY - aka S, Tv(Time value) mode enables manual control of the shutter speed, and aperture is calculated by the camera for proper exposure (given an ISO sensitivity)
- CREATIVE_PROGRAM - Program mode makes the camera calculate both shutter speed and aperture (given a manually or automatically selected ISO)
- ACTION_PROGRAM - Action or sports modes increase ISO and use a faster shutter speed to capture an action
- PORTRAIT_MODE - Portrait mode widens the aperture to throw the background out of focus. The camera may recognize and focus on a human face
- LANDSCAPE_MODE - Landscape modes use a small aperture to gain depth of a field
2. Interfaces
2.1. ExifManagerObject
[NoInterfaceObject] interface ExifManagerObject { readonly attribute ExifManager exif; };
Tizen implements ExifManagerObject;
Since: 2.3.1
Attributes
-
readonly
ExifManager exifObject representing a exif manager.
Since: 2.3.1
2.2. ExifManager
[NoInterfaceObject] interface ExifManager { void getExifInfo(DOMString uri, ExifInformationSuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void saveExifInfo(ExifInformation exifInfo, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void getThumbnail(DOMString uri, ExifThumbnailSuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); };
Since: 2.3.1
It provides access to the API functionalities through the tizen.exif interface.
Methods
-
getExifInfo
-
Gets the ExifInformation object to manipulate the Exif data in a JPEG file.
void getExifInfo(DOMString uri, ExifInformationSuccessCallback successCallback, optional ErrorCallback? errorCallback);
Since: 2.3.1
This function returns (via callback) the ExifInformation object that contains the Exif data in the JPEG file.
The errorCallback is launched with these error types:
- NotFoundError: If the file of the input parameters is not found or the file does not contain Exif data
- IOError: If access to the image file is denied due to insufficient permissions
- InvalidValuesError: If any input parameter contains invalid values
- UnknownError: In any other error case
Parameters:
- uri: URI of the JPEG file, as available in ImageContent::contentURI or returned by File::toURI().
- successCallback: Callback method to be invoked when Exif information has been retrieved successfully.
- errorCallback [optional] [nullable]: Callback method to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have privilege to access the storage. For more information, see Storage privileges.
Code example:
/* Preconditions: please provide images/tizen.jpg file with present Exif data. */ /* Defines success callback. */ function onSuccess(exifInfo) { console.log("Success to get Exif information object"); } /* Defines error callback. */ function onError(error) { console.log("Error occurred: " + error.name); } function resolveSuccess(file) { tizen.exif.getExifInfo(file.toURI(), onSuccess, onError); } function resolveFail(error) { console.log("Error occurred: " + error.name); } tizen.filesystem.resolve("images/tizen.jpg", resolveSuccess, resolveFail);
-
saveExifInfo
-
Saves the Exif data of the ExifInformation object into the JPEG file.
void saveExifInfo(ExifInformation exifInfo, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 2.3.1
The errorCallback is launched with these error types:
- NotFoundError: If the file of the input parameters is not found
- InvalidValuesError: If any input parameter contains invalid values
- UnknownError: In any other error case
Parameters:
- exifInfo: Exif information object that contains the Exif data in the JPEG file.
- successCallback [optional] [nullable]: Callback method to be invoked when Exif data has been saved successfully.
- errorCallback [optional] [nullable]: Callback method to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have privilege to access the storage. For more information, see Storage privileges.
Code example:
/* Preconditions: please provide images/tizen.jpg file with present Exif data. */ /* Defines success callback. */ function onSaveSuccess() { console.log("success to save Exif information"); } /* Defines error callback. */ function onSaveError(error) { console.log("Error occurred: " + error.name); } /* Defines success callback. */ function onSuccess(exifInfo) { console.log("success to get Exif information object"); exifInfo.orientation = "ROTATE_90"; tizen.exif.saveExifInfo(exifInfo, onSaveSuccess, onSaveError); } /* Defines error callback. */ function onError(error) { console.log("Error occurred: " + error.name); } function resolveSuccess(file) { tizen.exif.getExifInfo(file.toURI(), onSuccess, onError); } function resolveFail(error) { console.log("Error occurred: " + error.name); } tizen.filesystem.resolve("images/tizen.jpg", resolveSuccess, resolveFail);
-
getThumbnail
-
Gets the thumbnail of the specified JPEG file. If there is no thumbnail in the JPEG file, null is returned.
void getThumbnail(DOMString uri, ExifThumbnailSuccessCallback successCallback, optional ErrorCallback? errorCallback);
Since: 2.3.1
successCallback is invoked with a URI as the first argument. This URI is a data URI. It can be used as an src attribute value of the img element.
The errorCallback is launched with these error types:
- NotFoundError: If the file of the input parameters is not found
- IOError: If access to the thumbnail file is denied due to insufficient permissions
- InvalidValuesError: If any of the input parameters contains an invalid value
- UnknownError: In any other error case
Parameters:
- uri: URI of the JPEG file.
- successCallback: Callback method to be invoked when thumbnail data has been retrieved successfully.
- errorCallback [optional] [nullable]: Callback method to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have privilege to access the storage. For more information, see Storage privileges.
Code example:
/* Preconditions: please provide images/tizen.jpg file with present Exif data. */ /* Defines success callback. */ function onSuccess(thumbData) { console.log("got thumbnail data of JPEG file"); if (thumbData) { var img = new Image(); img.src = thumbData; document.body.appendChild(img); } } /* Defines error callback. */ function onError(error) { console.log("Error occurred: " + error.name); } function resolveSuccess(file) { tizen.exif.getThumbnail(file.toURI(), onSuccess, onError); } function resolveFail(error) { console.log("Error occurred: " + error.name); } tizen.filesystem.resolve("images/tizen.jpg", resolveSuccess, resolveFail);
2.3. ExifInit
dictionary ExifInit { DOMString uri; unsigned long width; unsigned long height; DOMString deviceMaker; DOMString deviceModel; Date originalTime; ImageContentOrientation orientation; double fNumber; unsigned short[] isoSpeedRatings; DOMString exposureTime; ExposureProgram exposureProgram; boolean flash; double focalLength; WhiteBalanceMode whiteBalance; SimpleCoordinates gpsLocation; double gpsAltitude; DOMString gpsProcessingMethod; Date gpsTime; DOMString userComment; };
Since: 2.3.1
This dictionary is used to input parameters when ExifInformation is created. For description of attributes please see the corresponding attributes in the ExifInformation interface.
2.4. ExifInformation
[Constructor(optional ExifInit? ExifInitDict)] interface ExifInformation { attribute DOMString uri; attribute unsigned long? width; attribute unsigned long? height; attribute DOMString? deviceMaker; attribute DOMString? deviceModel; attribute Date? originalTime; attribute ImageContentOrientation? orientation; attribute double? fNumber; attribute unsigned short[]? isoSpeedRatings; attribute DOMString? exposureTime; attribute ExposureProgram? exposureProgram; attribute boolean? flash; attribute double? focalLength; attribute WhiteBalanceMode? whiteBalance; attribute SimpleCoordinates? gpsLocation; attribute double? gpsAltitude; attribute DOMString? gpsProcessingMethod; attribute TZDate? gpsTime; attribute DOMString? userComment; };
Since: 2.3.1
When the format of a value is given in the attribute description then this format should be followed when updating values.
Every Exif related attribute is nullable - null means that this information is missing in the file. By setting an attribute to null and saving ExifInformation one can remove that Exif tag from the file.
Attributes
-
DOMString uriURI of the image.
The path to the file from which ExifInformation data is collected.
Since: 2.3.1
-
unsigned long width [nullable]Width of the image i.e. the number of points (pixels) per image line.
Note if the value of this attribute is changed, the new value is not verified against the actual size of the image.
Since: 2.3.1
-
unsigned long height [nullable]Height of the image i.e. the number of lines in the image.
Note if the value of this attribute is changed, the new value is not verified against the actual size of the image.
Since: 2.3.1
-
DOMString deviceMaker [nullable]Name of the camera manufacturer.
Since: 2.3.1
-
DOMString deviceModel [nullable]Model name or model number of the camera or input device.
Since: 2.3.1
-
Date originalTime [nullable]Date and time when the picture was taken.
Since: 2.3.1
-
ImageContentOrientation orientation [nullable]Orientation of the image when displayed.
This attribute shows the relation between the stored image data and the visual content orientation. In other words - how a stored image should be oriented when presented to the user.
Since: 2.3.1
-
double fNumber [nullable]The f-number when the image was taken.
Exif specification: "Conversion is not made to the focal length of a 35 mm film".
The f-number is the ratio of the lens' focal length to the diameter of the entrance pupil. F-number is also called focal ratio, f-ratio, f-stop, or relative aperture. Example values: 1.4, 2, 2.8, 4, 5.6, 8, 11 ...
Since: 2.3.1
-
unsigned short[]
isoSpeedRatings [nullable]Photo sensitivity (also called ISO speed and ISO latitude) of the camera or input device.
Example values: 80, 100, 200, 400, 800, 1600, 3200 ..
Since: 2.3.1
-
DOMString exposureTime [nullable]Exposure time, given in seconds.
If exposure time is below one second it is expressed as 1/x. For example: 1 second exposure is "1", 0.25s is "1/4".
Since: 2.3.1
-
ExposureProgram exposureProgram [nullable]Exposure balance program used by the camera to set exposure when the picture was taken.
Since: 2.3.1
-
boolean flash [nullable]Boolean value that indicates whether flash was fired when the picture was taken (true: flash fired).
Since: 2.3.1
-
double focalLength [nullable]Focal length of the lens, given in mm.
Since: 2.3.1
-
WhiteBalanceMode whiteBalance [nullable]White balance mode set when the picture was taken.
Since: 2.3.1
-
SimpleCoordinates gpsLocation [nullable]Latitude and longitude of the camera (from GPS) when the picture was taken.
Since: 2.3.1
-
double gpsAltitude [nullable]Altitude (from GPS) of the camera when the picture was taken.
This value is expressed in meters above sea level (can be negative).
Since: 2.3.1
-
DOMString gpsProcessingMethod [nullable]Name of the method used for finding the location.
Since: 2.3.1
-
TZDate gpsTime [nullable]Date and time information relative to UTC (Universal Time Coordinated) provided by GPS when the photo was taken.
Since: 2.3.1
-
DOMString userComment [nullable]User comment.
Since: 2.3.1
2.5. ExifInformationSuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface ExifInformationSuccessCallback { void onsuccess(ExifInformation exifInfo); };
Since: 2.3.1
Methods
-
onsuccess
-
Called when the Exif information object has been successfully retrieved.
void onsuccess(ExifInformation exifInfo);
Since: 2.3.1
Parameters:
- exifInfo: ExifInformation to be retrieved.
2.6. ExifThumbnailSuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface ExifThumbnailSuccessCallback { void onsuccess(DOMString? uri); };
Since: 2.3.1
3. Full WebIDL
module Exif { enum WhiteBalanceMode { "AUTO", "MANUAL" }; enum ExposureProgram { "NOT_DEFINED", "MANUAL", "NORMAL", "APERTURE_PRIORITY", "SHUTTER_PRIORITY", "CREATIVE_PROGRAM", "ACTION_PROGRAM", "PORTRAIT_MODE", "LANDSCAPE_MODE" }; dictionary ExifInit { DOMString uri; unsigned long width; unsigned long height; DOMString deviceMaker; DOMString deviceModel; Date originalTime; ImageContentOrientation orientation; double fNumber; unsigned short[] isoSpeedRatings; DOMString exposureTime; ExposureProgram exposureProgram; boolean flash; double focalLength; WhiteBalanceMode whiteBalance; SimpleCoordinates gpsLocation; double gpsAltitude; DOMString gpsProcessingMethod; Date gpsTime; DOMString userComment; }; Tizen implements ExifManagerObject; [NoInterfaceObject] interface ExifManagerObject { readonly attribute ExifManager exif; }; [NoInterfaceObject] interface ExifManager { void getExifInfo(DOMString uri, ExifInformationSuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void saveExifInfo(ExifInformation exifInfo, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void getThumbnail(DOMString uri, ExifThumbnailSuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); }; [Constructor(optional ExifInit? ExifInitDict)] interface ExifInformation { attribute DOMString uri; attribute unsigned long? width; attribute unsigned long? height; attribute DOMString? deviceMaker; attribute DOMString? deviceModel; attribute Date? originalTime; attribute ImageContentOrientation? orientation; attribute double? fNumber; attribute unsigned short[]? isoSpeedRatings; attribute DOMString? exposureTime; attribute ExposureProgram? exposureProgram; attribute boolean? flash; attribute double? focalLength; attribute WhiteBalanceMode? whiteBalance; attribute SimpleCoordinates? gpsLocation; attribute double? gpsAltitude; attribute DOMString? gpsProcessingMethod; attribute TZDate? gpsTime; attribute DOMString? userComment; }; [Callback=FunctionOnly, NoInterfaceObject] interface ExifInformationSuccessCallback { void onsuccess(ExifInformation exifInfo); }; [Callback=FunctionOnly, NoInterfaceObject] interface ExifThumbnailSuccessCallback { void onsuccess(DOMString? uri); }; };