Home | History | Annotate | Download | only in data 
      1 /*
      2  * Copyright (C) 2013 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package com.android.photos.data;
     18 
     19 import android.net.Uri;
     20 
     21 import java.io.File;
     22 
     23 public interface MediaRetriever {
     24     public enum MediaSize {
     25         TemporaryThumbnail(5), Thumbnail(10), TemporaryPreview(15), Preview(20), Original(30);
     26 
     27         private final int mValue;
     28 
     29         private MediaSize(int value) {
     30             mValue = value;
     31         }
     32 
     33         public int getValue() {
     34             return mValue;
     35         }
     36 
     37         static MediaSize fromInteger(int value) {
     38             switch (value) {
     39                 case 10:
     40                     return MediaSize.Thumbnail;
     41                 case 20:
     42                     return MediaSize.Preview;
     43                 case 30:
     44                     return MediaSize.Original;
     45                 default:
     46                     throw new IllegalArgumentException();
     47             }
     48         }
     49 
     50         public boolean isBetterThan(MediaSize that) {
     51             return mValue > that.mValue;
     52         }
     53 
     54         public boolean isTemporary() {
     55             return this == TemporaryThumbnail || this == TemporaryPreview;
     56         }
     57     }
     58 
     59     /**
     60      * Returns the local File for the given Uri. If the image is not stored
     61      * locally, null should be returned. The image should not be retrieved if it
     62      * isn't already available.
     63      *
     64      * @param contentUri The media URI to search for.
     65      * @return The local File of the image if it is available or null if it
     66      *         isn't.
     67      */
     68     File getLocalFile(Uri contentUri);
     69 
     70     /**
     71      * Returns the fast access image type for a given image size, if supported.
     72      * This image should be smaller than size and should be quick to retrieve.
     73      * It does not have to obey the expected aspect ratio.
     74      *
     75      * @param contentUri The original media Uri.
     76      * @param size The target size to search for a fast-access image.
     77      * @return The fast image type supported for the given image size or null of
     78      *         no fast image is supported.
     79      */
     80     MediaSize getFastImageSize(Uri contentUri, MediaSize size);
     81 
     82     /**
     83      * Returns a byte array containing the contents of the fast temporary image
     84      * for a given image size. For example, a thumbnail may be smaller or of a
     85      * different aspect ratio than the generated thumbnail.
     86      *
     87      * @param contentUri The original media Uri.
     88      * @param temporarySize The target media size. Guaranteed to be a MediaSize
     89      *            for which isTemporary() returns true.
     90      * @return A byte array of contents for for the given contentUri and
     91      *         fastImageType. null can be retrieved if the quick retrieval
     92      *         fails.
     93      */
     94     byte[] getTemporaryImage(Uri contentUri, MediaSize temporarySize);
     95 
     96     /**
     97      * Retrieves an image and saves it to a file.
     98      *
     99      * @param contentUri The original media Uri.
    100      * @param size The target media size.
    101      * @param tempFile The file to write the bitmap to.
    102      * @return <code>true</code> on success.
    103      */
    104     boolean getMedia(Uri contentUri, MediaSize imageSize, File tempFile);
    105 
    106     /**
    107      * Normalizes a URI that may have additional parameters. It is fine to
    108      * return contentUri. This is executed on the calling thread, so it must be
    109      * a fast access operation and cannot depend, for example, on I/O.
    110      *
    111      * @param contentUri The URI to normalize
    112      * @param size The size of the image being requested
    113      * @return The normalized URI representation of contentUri.
    114      */
    115     Uri normalizeUri(Uri contentUri, MediaSize size);
    116 
    117     /**
    118      * Normalize the MediaSize for a given URI. Typically the size returned
    119      * would be the passed-in size. Some URIs may only have one size used and
    120      * should be treaded as Thumbnails, for example. This is executed on the
    121      * calling thread, so it must be a fast access operation and cannot depend,
    122      * for example, on I/O.
    123      *
    124      * @param contentUri The URI for the size being normalized.
    125      * @param size The size to be normalized.
    126      * @return The normalized size of the given URI.
    127      */
    128     MediaSize normalizeMediaSize(Uri contentUri, MediaSize size);
    129 }
    130