1 /* 2 * Copyright (C) 2016 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 package com.android.settings.overlay; 17 18 import android.app.Activity; 19 import android.content.BroadcastReceiver; 20 import android.content.Context; 21 import android.content.IntentFilter; 22 import android.support.annotation.Nullable; 23 import android.support.v4.content.LocalBroadcastManager; 24 25 /** 26 * An interface for classes wishing to provide the ability to serve surveys to implement. 27 */ 28 public interface SurveyFeatureProvider { 29 30 /** 31 * Downloads a survey asynchronously to shared preferences to be served at a later date. 32 * 33 * @param activity A valid context. 34 * @param surveyId A unique Id representing a survey to download. 35 * @param data a text blob to be attached to the survey results. 36 */ 37 void downloadSurvey(Activity activity, String surveyId, @Nullable String data); 38 39 /** 40 * Shows a previously downloaded survey/prompt if possible in the activity provided. 41 * 42 * @param activity The host activity to show the survey in. 43 * @param surveyId A unique Id representing a survey to download. 44 * @return A boolean indicating if a survey was shown or not. 45 */ 46 boolean showSurveyIfAvailable(Activity activity, String surveyId); 47 48 /** 49 * A helper method to get the surveyId. Implementers should create a mapping of 50 * keys to surveyIds and provide them via this function. 51 * 52 * @param context A valid context. 53 * @param simpleKey The simple name of the key to get the surveyId for. 54 * @return The unique Id as a string or null on error. 55 */ 56 String getSurveyId(Context context, String simpleKey); 57 58 /** 59 * Removes the survey for {@code siteId} if it expired, then returns the expiration date (as a 60 * unix timestamp) for the remaining survey should it exist and be ready to show. Returns -1 if 61 * no valid survey exists after removing the potentially expired one. 62 * 63 * @param context the calling context. 64 * @param surveyId the site ID. 65 * @return the unix timestamp for the available survey for the given {@coe siteId} or -1 if 66 * there is none available. 67 */ 68 long getSurveyExpirationDate(Context context, String surveyId); 69 70 /** 71 * Registers an activity to show surveys/prompts as soon as they are downloaded. The receiver 72 * should be unregistered prior to destroying the activity to avoid undefined behavior by 73 * calling {@link #unregisterReceiver(Activity, BroadcastReceiver)}. 74 * @param activity The activity that should show surveys once they are downloaded. 75 * @return the broadcast receiver listening for survey downloads. Must be unregistered before 76 * leaving the activity. 77 */ 78 BroadcastReceiver createAndRegisterReceiver(Activity activity); 79 80 /** 81 * Unregisters the broadcast receiver for this activity. Should only be called once per activity 82 * after a call to {@link #createAndRegisterReceiver(Activity)}. 83 * @param activity The activity that was used to register the BroadcastReceiver. 84 */ 85 static void unregisterReceiver(Activity activity, BroadcastReceiver receiver) { 86 if (activity == null) { 87 throw new IllegalStateException("Cannot unregister receiver if activity is null"); 88 } 89 90 LocalBroadcastManager.getInstance(activity).unregisterReceiver(receiver); 91 } 92 } 93
