Exif API

The Exif API provides interfaces and methods for manipulating Exif data from a JPEG file. The ExifManager object provides methods to retrieve the ExifInformation object from a JPEG file and save the Exif data from the ExifInformation object in the JPEG file. The ExifInformation object provides functionality to get and set the Exif attributes corresponding to the Exif tag. Changing the value of the attribute in the ExifInformation object stores the Exif data in the ExifInformation object. It does not change data in the JPEG file. For applying the modified Exif data to the JPEG file, the saveExifInfo() method of the ExifManager object should be called with the ExifInformation object that has the modified Exif data.

For more information about how to use Exif API, see Exif Guide.

Since 2.3

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

Specifies a white balance mode for an image.

    enum WhiteBalanceMode { "AUTO", "MANUAL" };

Since 2.3

  • AUTO - Automatic White Balance mode
  • MANUAL - Manual White Balance mode

1.2. ExposureProgram

Specifies an exposure balance program for an image.

    enum ExposureProgram { "NOT_DEFINED", "MANUAL", "NORMAL", "APERTURE_PRIORITY", "SHUTTER_PRIORITY", "CREATIVE_PROGRAM", "ACTION_PROGRAM", "PORTRAIT_MODE", "LANDSCAPE_MODE" };

Since 2.3

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

The ExifManagerObject interface defines what is instantiated by the Tizen object from the Tizen Platform. The tizen.exif object allows access to the Exif data of a JPEG file.

    [NoInterfaceObject] interface ExifManagerObject {
        readonly attribute ExifManager exif;
    };

    Tizen implements ExifManagerObject;

Since 2.3

2.2. ExifManager

The ExifManager interface provides methods to retrieve the ExifInformation object and save the Exif data of the ExifInformation object in a JPEG file.

    [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

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

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.

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

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.

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 occur" + 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 occur" + 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

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.

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 occur" + 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 for specifying ExifInformation attributes upon ExifInformation creation.

    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

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

The ExifInformation interface implements the ExifInformation object.

    [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

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.

Constructors

ExifInformation(optional ExifInit? ExifInitDict);

Attributes

  • DOMString uri

    URI of the image.

    The path to the file from which ExifInformation data is collected.

    Since 2.3

  • 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

  • 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

  • DOMString deviceMaker [nullable]

    Name of the camera manufacturer.

    Since 2.3

  • DOMString deviceModel [nullable]

    Model name or model number of the camera or input device.

    Since 2.3

  • Date originalTime [nullable]

    Date and time when the picture was taken.

    Since 2.3

  • 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

  • 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

  • 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

  • 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

  • ExposureProgram exposureProgram [nullable]

    Exposure balance program used by the camera to set exposure when the picture was taken.

    Since 2.3

  • boolean flash [nullable]

    Boolean value that indicates whether flash was fired when the picture was taken (true: flash fired).

    Since 2.3

  • double focalLength [nullable]

    Focal length of the lens, given in mm.

    Since 2.3

  • WhiteBalanceMode whiteBalance [nullable]

    White balance mode set when the picture was taken.

    Since 2.3

  • SimpleCoordinates gpsLocation [nullable]

    Latitude and longitude of the camera (from GPS) when the picture was taken.

    Since 2.3

  • 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

  • DOMString gpsProcessingMethod [nullable]

    Name of the method used for finding the location.

    Since 2.3

  • TZDate gpsTime [nullable]

    Date and time information relative to UTC (Universal Time Coordinated) provided by GPS when the photo was taken.

    Since 2.3

  • DOMString userComment [nullable]

    User comment.

    Since 2.3

2.5. ExifInformationSuccessCallback

The ExifInformationSuccessCallback interface provides a success callback that is invoked when the Exif information object has been retrieved. This callback interface specifies a success method with an ExifInformation object as an input parameter. It is used in exif.getExifInfo().

    [Callback=FunctionOnly, NoInterfaceObject] interface ExifInformationSuccessCallback {
        void onsuccess(ExifInformation exifInfo);
    };

Since 2.3

Methods

onsuccess

Called when the Exif information object has been successfully retrieved.

void onsuccess(ExifInformation exifInfo);

Since 2.3

Parameters:

  • exifInfo: ExifInformation to be retrieved

2.6. ExifThumbnailSuccessCallback

The ExifThumbnailSuccessCallback interface provides a success callback that is invoked when the Exif thumbnail has been retrieved. This callback interface specifies a success method with the URI for the thumbnail as an input parameter. It is used in exif.getThumbnail().

    [Callback=FunctionOnly, NoInterfaceObject] interface ExifThumbnailSuccessCallback {
        void onsuccess(DOMString? uri);
    };

Since 2.3

Methods

onsuccess

Called when the thumbnail of the JPEG file has been successfully retrieved.

void onsuccess(DOMString? uri);

Since 2.3

Parameters:

  • uri [nullable]: URI for the thumbnail to be retrieved
    If there is no thumbnail in the JPEG file, null is returned.

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

    [NoInterfaceObject] interface ExifManagerObject {
        readonly attribute ExifManager exif;
    };
    Tizen implements ExifManagerObject;

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

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

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

};