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 
17 package android.telephony.mbms;
18 
19 import android.annotation.IntDef;
20 import android.annotation.Nullable;
21 
22 import java.lang.annotation.Retention;
23 import java.lang.annotation.RetentionPolicy;
24 
25 /**
26  * A callback class for use when the application is actively streaming content. The middleware
27  * will provide updates on the status of the stream via this callback.
28  */
29 public class StreamingServiceCallback {
30     /** @hide */
31     @Retention(RetentionPolicy.SOURCE)
32     @IntDef(value = {
33             MbmsErrors.ERROR_NO_UNIQUE_MIDDLEWARE,
34             MbmsErrors.ERROR_MIDDLEWARE_LOST,
35             MbmsErrors.ERROR_MIDDLEWARE_NOT_BOUND,
36             MbmsErrors.GeneralErrors.ERROR_MIDDLEWARE_NOT_YET_READY,
37             MbmsErrors.GeneralErrors.ERROR_OUT_OF_MEMORY,
38             MbmsErrors.GeneralErrors.ERROR_MIDDLEWARE_TEMPORARILY_UNAVAILABLE,
39             MbmsErrors.GeneralErrors.ERROR_IN_E911,
40             MbmsErrors.GeneralErrors.ERROR_NOT_CONNECTED_TO_HOME_CARRIER_LTE,
41             MbmsErrors.GeneralErrors.ERROR_UNABLE_TO_READ_SIM,
42             MbmsErrors.GeneralErrors.ERROR_CARRIER_CHANGE_NOT_ALLOWED,
43             MbmsErrors.StreamingErrors.ERROR_CONCURRENT_SERVICE_LIMIT_REACHED,
44             MbmsErrors.StreamingErrors.ERROR_UNABLE_TO_START_SERVICE,
45             MbmsErrors.StreamingErrors.ERROR_DUPLICATE_START_STREAM}, prefix = { "ERROR_" })
46     private @interface StreamingServiceError{}
47 
48     /**
49      * Indicates broadcast signal strength is not available for this service.
50      *
51      * This may be due to the service no longer being available due to geography
52      * or timing (end of service) or because lack of demand has caused the service
53      * to be delivered via unicast.
54      */
55     public static final int SIGNAL_STRENGTH_UNAVAILABLE = -1;
56 
57     /**
58      * Called by the middleware when it has detected an error condition in this stream. The
59      * possible error codes are listed in {@link MbmsErrors}.
60      * @param errorCode The error code.
61      * @param message A human-readable message generated by the middleware for debugging purposes.
62      */
onError(@treamingServiceError int errorCode, @Nullable String message)63     public void onError(@StreamingServiceError int errorCode, @Nullable String message) {
64         // default implementation empty
65     }
66 
67     /**
68      * Called to indicate this stream has changed state.
69      *
70      * See {@link StreamingService#STATE_STOPPED}, {@link StreamingService#STATE_STARTED}
71      * and {@link StreamingService#STATE_STALLED}.
72      */
onStreamStateUpdated(@treamingService.StreamingState int state, @StreamingService.StreamingStateChangeReason int reason)73     public void onStreamStateUpdated(@StreamingService.StreamingState int state,
74             @StreamingService.StreamingStateChangeReason int reason) {
75         // default implementation empty
76     }
77 
78     /**
79      * Called to indicate the mpd of a the stream has changed.
80      *
81      * Depending on the Dash Client it may need to be either reset
82      * (less drastic, but original spec didn't allow mpd to change so not
83      * always supported) or restarted.
84      *
85      * This may be called when a looping stream hits the end or
86      * when parameters have changed to account for time drift.
87      */
onMediaDescriptionUpdated()88     public void onMediaDescriptionUpdated() {
89         // default implementation empty
90     }
91 
92     /**
93      * Broadcast Signal Strength updated.
94      *
95      * This signal strength is the BROADCAST signal strength which,
96      * depending on technology in play and it's deployment, may be
97      * stronger or weaker than the traditional UNICAST signal
98      * strength.  It a simple int from 0-4 for valid levels or
99      * {@link #SIGNAL_STRENGTH_UNAVAILABLE} if broadcast is not available
100      * for this service due to timing, geography or popularity.
101      */
onBroadcastSignalStrengthUpdated(int signalStrength)102     public void onBroadcastSignalStrengthUpdated(int signalStrength) {
103         // default implementation empty
104     }
105 
106     /**
107      * Notify of bcast/unicast method being used.
108      *
109      * This is intended to be informational.  Indicates
110      * whether we're able to use cell broadcast or have
111      * had to fallback to unicast for this stream.
112      *
113      * This must be called once at the beginning of the stream
114      * around the same time as we change to STATE_STARTED, but
115      * strict ordering is not specified.  It must be called
116      * again if we change modes, but if that doesn't happen
117      * the callback won't be used again.
118      *
119      * See {@link StreamingService#BROADCAST_METHOD} and
120      * {@link StreamingService#UNICAST_METHOD}
121      */
onStreamMethodUpdated(int methodType)122     public void onStreamMethodUpdated(int methodType) {
123         // default implementation empty
124     }
125 }
126