• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Implementation Details for SdkControllerApp
2-------------------------------------------
3
4---- 2012-03-22
5App is in the namespace com.android.tools.sdkcontroller.
6
7This is an app that has a minSdkVersion of 7 (Eclair)
8and a targetSdkVersion of 15 (ICS). The target version
9means the app is forbidden under ICS from doing any network
10communication on its main thread.
11
12The overall design:
13- A background service is started by the app. It handles the connection
14  to the emulator and provides a number of "handlers". Handlers can be
15  though as being separate tasks that the user wants to achieve, for example
16  sending sensor data, sending multi-touch events, receiving screen updates,
17  sending a camera feed, etc.
18- All the handlers are started when the service starts and shutdown with it.
19  They basically stay there as long as the app is running, and its up to the
20  handler to deal with emulator connections starts/stopping. Some handlers
21  will run in the background (e.g. sending sensor data) whereas other might
22  need an activity to connect to them first.
23- The app has a number of activities which connect to existing handlers.
24
25Another way to see it is that the app handles a number of tasks which are
26composed of a background handler (that consumes data form the emulator and
27can send data to the emulator) and an optional activity for UI (that displays
28or controls the handler's state.)
29
30
31Here's a quick overview of the classes in the application:
32
33
34The main UI is in activities.MainActivity.
35There are 2 tasks activities: SensorActivity and MultiTouchActivity.
36
37These all derive from BaseBindingActivity which provides a few convenient common features
38- in onResume this will bind to the service, creating and starting it if necessary.
39- in onPause, this will unbind from the service, but does not stop it.
40
41Note however that due to the asynchronous nature of the bind operation, the activity
42must not attempt to use the service from onResume. Instead there are 2 callbacks to use:
43- onServiceConnected when the bind succeeded.
44- onServiceDisconnected as the reverse operation.
45
46When the activity is connected to the service, it can then use getServiceBinder()
47to get an interface to talk to the service.
48
49In the other direction, the activity provides a listener for the service to notify
50the application: ControllerListener createControllerListener().
51
52The activity can then access the handler:
53  handler = getServiceBinder().getHandler(HandlerType....)
54
55and then the activity wants to provide a listener to get notified by the handler:
56  handler.addUiHandler(new android.os.Handler(this));
57
58The emulator connection is separated in the "lib" subpackage:
59- EmulatorConnection abstracts a connection to the emulator.
60    - Object is first created by giving a non-null EmulatorListener.
61    - then connect(port) is called to initiate the connection.
62    - The EmulatorConnection is always created in SYNC mode.
63- EmulatorListener is a callback: the emulator connection uses it to indicate
64    when the connection is actually connected or disconnected.
65
66In the end we have the following workflow describing who controls what (-->):
67
68
69                                        Emulator
70                                         ^   ^
71                                         |   | EmuCnxHandler
72                      sendEventToEmulator|   | (EmulatorListener)
73                                         |   +-------------+
74                                         |                 |
75              handlers.BaseHandler       |                 v
76 Activity  ------------------------>  Handler  <---- ControllerService
77    UI     <------------------------                     |     ^
78              android.os.Handler                         |     |
79   |  ^                                                  |     |
80   |  |               ControllerListener                 |     |
81   |  +--------------------------------------------------+     |
82   +-----------------------------------------------------------+
83                       ControllerBinder
84
85----
86