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 android.support.v7.media;
18 
19 import android.content.Intent;
20 import android.os.Messenger;
21 
22 /**
23  * Defines the communication protocol for media route provider services.
24  */
25 abstract class MediaRouteProviderProtocol {
26     /**
27      * The {@link Intent} that must be declared as handled by the service.
28      * Put this in your manifest.
29      */
30     public static final String SERVICE_INTERFACE =
31             "android.media.MediaRouteProviderService";
32 
33     /*
34      * Messages sent from the client to the service.
35      * DO NOT RENUMBER THESE!
36      */
37 
38     /** (client v1)
39      * Register client.
40      * - replyTo : client messenger
41      * - arg1    : request id
42      * - arg2    : client version
43      */
44     public static final int CLIENT_MSG_REGISTER = 1;
45 
46     /** (client v1)
47      * Unregister client.
48      * - replyTo : client messenger
49      * - arg1    : request id
50      */
51     public static final int CLIENT_MSG_UNREGISTER = 2;
52 
53     /** (client v1)
54      * Create route controller.
55      * - replyTo : client messenger
56      * - arg1    : request id
57      * - arg2    : route controller id
58      * - CLIENT_DATA_ROUTE_ID : route id string
59      */
60     public static final int CLIENT_MSG_CREATE_ROUTE_CONTROLLER = 3;
61 
62     /** (client v1)
63      * Release route controller.
64      * - replyTo : client messenger
65      * - arg1    : request id
66      * - arg2    : route controller id
67      */
68     public static final int CLIENT_MSG_RELEASE_ROUTE_CONTROLLER = 4;
69 
70     /** (client v1)
71      * Select route.
72      * - replyTo : client messenger
73      * - arg1    : request id
74      * - arg2    : route controller id
75      */
76     public static final int CLIENT_MSG_SELECT_ROUTE = 5;
77 
78     /** (client v1)
79      * Unselect route.
80      * - replyTo : client messenger
81      * - arg1    : request id
82      * - arg2    : route controller id
83      */
84     public static final int CLIENT_MSG_UNSELECT_ROUTE = 6;
85 
86     /** (client v1)
87      * Set route volume.
88      * - replyTo : client messenger
89      * - arg1    : request id
90      * - arg2    : route controller id
91      * - CLIENT_DATA_VOLUME : volume integer
92      */
93     public static final int CLIENT_MSG_SET_ROUTE_VOLUME = 7;
94 
95     /** (client v1)
96      * Update route volume.
97      * - replyTo : client messenger
98      * - arg1    : request id
99      * - arg2    : route controller id
100      * - CLIENT_DATA_VOLUME : volume delta integer
101      */
102     public static final int CLIENT_MSG_UPDATE_ROUTE_VOLUME = 8;
103 
104     /** (client v1)
105      * Route control request.
106      * - replyTo : client messenger
107      * - arg1    : request id
108      * - arg2    : route controller id
109      * - obj     : media control intent
110      */
111     public static final int CLIENT_MSG_ROUTE_CONTROL_REQUEST = 9;
112 
113     /** (client v1)
114      * Sets the discovery request.
115      * - replyTo : client messenger
116      * - arg1    : request id
117      * - obj     : discovery request bundle, or null if none
118      */
119     public static final int CLIENT_MSG_SET_DISCOVERY_REQUEST = 10;
120 
121     public static final String CLIENT_DATA_ROUTE_ID = "routeId";
122     public static final String CLIENT_DATA_ROUTE_LIBRARY_GROUP = "routeGroupId";
123     public static final String CLIENT_DATA_VOLUME = "volume";
124     public static final String CLIENT_DATA_UNSELECT_REASON = "unselectReason";
125 
126     /*
127      * Messages sent from the service to the client.
128      * DO NOT RENUMBER THESE!
129      */
130 
131     /** (service v1)
132      * Generic failure sent in response to any unrecognized or malformed request.
133      * - arg1    : request id
134      */
135     public static final int SERVICE_MSG_GENERIC_FAILURE = 0;
136 
137     /** (service v1)
138      * Generic failure sent in response to a successful message.
139      * - arg1    : request id
140      */
141     public static final int SERVICE_MSG_GENERIC_SUCCESS = 1;
142 
143     /** (service v1)
144      * Registration succeeded.
145      * - arg1    : request id
146      * - arg2    : server version
147      * - obj     : route provider descriptor bundle, or null
148      */
149     public static final int SERVICE_MSG_REGISTERED = 2;
150 
151     /** (service v1)
152      * Route control request success result.
153      * - arg1    : request id
154      * - obj     : result data bundle, or null
155      */
156     public static final int SERVICE_MSG_CONTROL_REQUEST_SUCCEEDED = 3;
157 
158     /** (service v1)
159      * Route control request failure result.
160      * - arg1    : request id
161      * - obj     : result data bundle, or null
162      * - SERVICE_DATA_ERROR: error message
163      */
164     public static final int SERVICE_MSG_CONTROL_REQUEST_FAILED = 4;
165 
166     /** (service v1)
167      * Route provider descriptor changed.  (unsolicited event)
168      * - arg1    : reserved (0)
169      * - obj     : route provider descriptor bundle, or null
170      */
171     public static final int SERVICE_MSG_DESCRIPTOR_CHANGED = 5;
172 
173     public static final String SERVICE_DATA_ERROR = "error";
174 
175     /*
176      * Recognized client version numbers.  (Reserved for future use.)
177      * DO NOT RENUMBER THESE!
178      */
179 
180     /**
181      * The client version used from the beginning.
182      */
183     public static final int CLIENT_VERSION_1 = 1;
184 
185     /**
186      * The client version used from support library v24.1.0.
187      */
188     public static final int CLIENT_VERSION_2 = 2;
189 
190     /**
191      * The current client version.
192      */
193     public static final int CLIENT_VERSION_CURRENT = CLIENT_VERSION_2;
194 
195     /*
196      * Recognized server version numbers.  (Reserved for future use.)
197      * DO NOT RENUMBER THESE!
198      */
199 
200     /**
201      * The service version used from the beginning.
202      */
203     public static final int SERVICE_VERSION_1 = 1;
204 
205     /**
206      * The current service version.
207      */
208     public static final int SERVICE_VERSION_CURRENT = SERVICE_VERSION_1;
209 
210     static final int CLIENT_VERSION_START = CLIENT_VERSION_1;
211 
212     /**
213      * Returns true if the messenger object is valid.
214      * <p>
215      * The messenger constructor and unparceling code does not check whether the
216      * provided IBinder is a valid IMessenger object.  As a result, it's possible
217      * for a peer to send an invalid IBinder that will result in crashes downstream.
218      * This method checks that the messenger is in a valid state.
219      * </p>
220      */
isValidRemoteMessenger(Messenger messenger)221     public static boolean isValidRemoteMessenger(Messenger messenger) {
222         try {
223             return messenger != null && messenger.getBinder() != null;
224         } catch (NullPointerException ex) {
225             // If the messenger was constructed with a binder interface other than
226             // IMessenger then the call to getBinder() will crash with an NPE.
227             return false;
228         }
229     }
230 }
231