ServiceCompat.java revision 9fd802d8c8217948bf70eb7a8baf632a0a301753
1/* 2 * Copyright (C) 2011 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 17package android.support.v4.app; 18 19import android.app.Notification; 20import android.app.Service; 21import android.support.annotation.IntDef; 22import android.support.v4.os.BuildCompat; 23 24import java.lang.annotation.Retention; 25import java.lang.annotation.RetentionPolicy; 26 27/** 28 * Helper for accessing features in {@link android.app.Service} 29 * introduced after API level 9 in a backwards compatible fashion. 30 */ 31public final class ServiceCompat { 32 33 private ServiceCompat() { 34 /* Hide constructor */ 35 } 36 37 /** 38 * Constant to return from {@link android.app.Service#onStartCommand}: if this 39 * service's process is killed while it is started (after returning from 40 * {@link android.app.Service#onStartCommand}), then leave it in the started 41 * state but don't retain this delivered intent. Later the system will try to 42 * re-create the service. Because it is in the started state, it will 43 * guarantee to call {@link android.app.Service#onStartCommand} after creating 44 * the new service instance; if there are not any pending start commands to be 45 * delivered to the service, it will be called with a null intent 46 * object, so you must take care to check for this. 47 * 48 * <p>This mode makes sense for things that will be explicitly started 49 * and stopped to run for arbitrary periods of time, such as a service 50 * performing background music playback. 51 */ 52 public static final int START_STICKY = 1; 53 54 /** 55 * Flag for {@link #stopForeground(Service, int)}: if set, the notification previously provided 56 * to {@link Service#startForeground(int, Notification)} will be removed. Otherwise it 57 * will remain until a later call (to {@link Service#startForeground(int, Notification)} or 58 * {@link #stopForeground(Service, int)} removes it, or the service is destroyed. 59 */ 60 public static final int STOP_FOREGROUND_REMOVE = 1<<0; 61 62 /** 63 * Flag for {@link #stopForeground(Service, int)}: if set, the notification previously provided 64 * to {@link Service#startForeground(int, Notification)} will be detached from the service. 65 * Only makes sense when {@link #STOP_FOREGROUND_REMOVE} is <b>not</b> set -- in this case, the 66 * notification will remain shown, but be completely detached from the service and so no longer 67 * changed except through direct calls to the 68 * notification manager. 69 * <p> 70 * This flag will only work on 71 * {@link android.os.Build.VERSION_CODES#N} and later. It doesn't have any effect on earlier 72 * platform versions. 73 */ 74 public static final int STOP_FOREGROUND_DETACH = 1<<1; 75 76 /** @hide */ 77 @IntDef(flag = true, 78 value = { 79 STOP_FOREGROUND_REMOVE, 80 STOP_FOREGROUND_DETACH 81 }) 82 @Retention(RetentionPolicy.SOURCE) 83 public @interface StopForegroundFlags {} 84 85 interface ServiceCompatImpl { 86 void stopForeground(Service service, @ServiceCompat.StopForegroundFlags int flags); 87 } 88 89 static class BaseServiceCompatImpl implements ServiceCompat.ServiceCompatImpl { 90 public void stopForeground(Service service, @ServiceCompat.StopForegroundFlags int flags) { 91 service.stopForeground((flags & Service.STOP_FOREGROUND_REMOVE) != 0); 92 } 93 } 94 95 static class Api24ServiceCompatImpl implements ServiceCompat.ServiceCompatImpl { 96 public void stopForeground(Service service, @ServiceCompat.StopForegroundFlags int flags) { 97 ServiceCompatApi24.stopForeground(service, flags); 98 } 99 } 100 101 static final ServiceCompatImpl IMPL; 102 static { 103 if (BuildCompat.isAtLeastN()) { 104 IMPL = new Api24ServiceCompatImpl(); 105 } else { 106 IMPL = new BaseServiceCompatImpl(); 107 } 108 } 109 110 /** 111 * Remove the passed service from foreground state, allowing it to be killed if 112 * more memory is needed. 113 * @param flags Additional behavior options: {@link #STOP_FOREGROUND_REMOVE}, 114 * {@link #STOP_FOREGROUND_DETACH}. 115 * @see Service#startForeground(int, Notification) 116 */ 117 public static void stopForeground(Service service, 118 @ServiceCompat.StopForegroundFlags int flags) { 119 IMPL.stopForeground(service, flags); 120 } 121} 122