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.camera.session;
18 
19 import android.graphics.Bitmap;
20 import android.location.Location;
21 import android.net.Uri;
22 
23 import java.io.File;
24 import java.io.IOException;
25 
26 /**
27  * Modules use this manager to store capture results.
28  */
29 public interface CaptureSessionManager {
30     /**
31      * Callback interface for session events.
32      */
33     public interface SessionListener {
34         /**
35          * Called when the session with the given Uri was queued and will be
36          * processed.
37          */
onSessionQueued(Uri mediaUri)38         public void onSessionQueued(Uri mediaUri);
39 
40         /**
41          * Called when the media underlying the session with the given Uri has
42          * been updated.
43          */
onSessionUpdated(Uri mediaUri)44         public void onSessionUpdated(Uri mediaUri);
45 
46         /**
47          * Called when the capture indicator for the given session has changed
48          * and should be updated.
49          *
50          * @param bitmap the capture indicator bitmap
51          * @param rotationDegrees the rotation of the updated preview
52          */
onSessionCaptureIndicatorUpdate(Bitmap bitmap, int rotationDegrees)53         public void onSessionCaptureIndicatorUpdate(Bitmap bitmap, int rotationDegrees);
54 
55         /** Called when the session with the given Uri finished. */
onSessionDone(Uri mediaUri)56         public void onSessionDone(Uri mediaUri);
57 
58         /** Called when the session with the given Uri failed processing. */
onSessionFailed(Uri mediaUri, int failureMessageId, boolean removeFromFilmstrip)59         public void onSessionFailed(Uri mediaUri, int failureMessageId, boolean removeFromFilmstrip);
60 
61         /** Called when the session with the given Uri was canceled. */
onSessionCanceled(Uri mediaUri)62         public void onSessionCanceled(Uri mediaUri);
63 
64         /** Called when the session with the given Uri has progressed. */
onSessionProgress(Uri mediaUri, int progress)65         public void onSessionProgress(Uri mediaUri, int progress);
66 
67         /** Called when the session with the given Uri has changed its progress text. */
onSessionProgressText(Uri mediaUri, int messageId)68         public void onSessionProgressText(Uri mediaUri, int messageId);
69 
70         /**
71          * Called when the thumbnail for the given session has changed and
72          * should be updated. This is only used by @{link CaptureIntentModule}.
73          * Filmstrip uses onSessionUpdated to refresh the thumbnail.
74          *
75          * @param bitmap the thumbnail bitmap
76          */
onSessionThumbnailUpdate(Bitmap bitmap)77         public void onSessionThumbnailUpdate(Bitmap bitmap);
78 
79         /**
80          * Called when the compressed picture data for the given session has
81          * changed and should be updated.
82          *
83          * @param pictureData the picture JPEG byte array.
84          * @param orientation the picture orientation.
85          */
onSessionPictureDataUpdate(byte[] pictureData, int orientation)86         public void onSessionPictureDataUpdate(byte[] pictureData, int orientation);
87     }
88 
89     /**
90      * Creates a new capture session.
91      *
92      * @param title the title of the new session.
93      * @param sessionStartMillis the start time of the new session (millis since epoch).
94      * @param location the location of the new session.
95      */
createNewSession(String title, long sessionStartMillis, Location location)96     public CaptureSession createNewSession(String title, long sessionStartMillis, Location location);
97 
98     /**
99      * Returns a session by session Uri or null if it is not found.
100      *
101      * @param sessionUri the Uri to look up.
102      *
103      * @return The corresponding CaptureSession.
104      */
getSession(Uri sessionUri)105     public CaptureSession getSession(Uri sessionUri);
106 
107     /**
108      * Add a listener to be informed about capture session updates.
109      * <p>
110      * Note: It is guaranteed that the callbacks will happen on the main thread,
111      * so callers have to make sure to not block execution.
112      */
addSessionListener(SessionListener listener)113     public void addSessionListener(SessionListener listener);
114 
115     /**
116      * Adds the session with the given uri.
117      */
putSession(Uri sessionUri, CaptureSession session)118     public void putSession(Uri sessionUri, CaptureSession session);
119 
120     /**
121      * Removes the session with the given uri from the manager. This may not
122      * remove temporary in memory resources from the session itself, see
123      * {@link CaptureSession#finalizeSession()} to complete session removal.
124      */
removeSession(Uri sessionUri)125     public CaptureSession removeSession(Uri sessionUri);
126 
127     /**
128      * Removes a previously added listener from receiving further capture
129      * session updates.
130      */
removeSessionListener(SessionListener listener)131     public void removeSessionListener(SessionListener listener);
132 
133     /**
134      * Calls the given listener for all the sessions that are currently
135      * in-flight.
136      */
fillTemporarySession(SessionListener listener)137     public void fillTemporarySession(SessionListener listener);
138 
139     /**
140      * Gets the directory to be used for temporary data. See
141      * {@link SessionStorageManager#getSessionDirectory(String)}
142      */
getSessionDirectory(String subDirectory)143     public File getSessionDirectory(String subDirectory) throws IOException;
144 
145     /**
146      * @return Whether the session with the given URI exists and has an error
147      *         message.
148      */
hasErrorMessage(Uri uri)149     public boolean hasErrorMessage(Uri uri);
150 
151     /**
152      * @return If existant, returns the error message ID for the session with the
153      *         given URI, -1 otherwise.
154      */
getErrorMessageId(Uri uri)155     public int getErrorMessageId(Uri uri);
156 
157     /**
158      * Removes any existing error messages for the session with the given URI.
159      */
removeErrorMessage(Uri uri)160     public void removeErrorMessage(Uri uri);
161 
162     /** Sets the error message for the session with the given URI. */
putErrorMessage(Uri uri, int failureMessageId)163     public void putErrorMessage(Uri uri, int failureMessageId);
164 }
165