Scott Main | 604e4ed | 2011-12-13 18:24:34 -0800 | [diff] [blame] | 1 | page.title=Determining and Monitoring the Docking State and Type |
Scott Main | 580f014 | 2011-12-15 16:47:26 -0800 | [diff] [blame] | 2 | parent.title=Optimizing Battery Life |
Scott Main | 604e4ed | 2011-12-13 18:24:34 -0800 | [diff] [blame] | 3 | parent.link=index.html |
| 4 | |
| 5 | trainingnavtop=true |
| 6 | previous.title= Monitoring the Battery Level and Charging State |
| 7 | previous.link=battery-monitoring.html |
| 8 | next.title= Determining and Monitoring the Connectivity Status |
| 9 | next.link=connectivity-monitoring.html |
| 10 | |
| 11 | @jd:body |
| 12 | |
| 13 | <div id="tb-wrapper"> |
| 14 | <div id="tb"> |
| 15 | |
| 16 | <h2>This lesson teaches you to</h2> |
| 17 | <ol> |
| 18 | <li><a href="#CurrentDockState">Request the Audio Focus</a></li> |
| 19 | <li><a href="#DockType">Determine the Current Dock Type</a></li> |
| 20 | <li><a href="#MonitorDockState">Monitor for Changes in the Dock State or Type</a></li> |
| 21 | </ol> |
| 22 | |
| 23 | |
| 24 | <h2>You should also read</h2> |
| 25 | <ul> |
| 26 | <li><a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Filters</a> |
| 27 | </ul> |
| 28 | |
| 29 | </div> |
| 30 | </div> |
| 31 | |
| 32 | <p>Android devices can be docked into several different kinds of docks. These include car or home |
| 33 | docks and digital versus analog docks. The dock-state is typically closely linked to the charging |
| 34 | state as many docks provide power to docked devices.</p> |
| 35 | |
| 36 | <p>How the dock-state of the phone affects your update rate depends on your app. You may choose |
| 37 | to increase the update frequency of a sports center app when it's in the desktop dock, or disable |
| 38 | your updates completely if the device is car docked. Conversely, you may choose to maximize your |
| 39 | updates while car docked if your background service is updating traffic conditions.</p> |
| 40 | |
| 41 | <p>The dock state is also broadcast as a sticky {@link android.content.Intent}, allowing you to |
| 42 | query if the device is docked or not, and if so, in which kind of dock.</p> |
| 43 | |
| 44 | |
| 45 | <h2 id="CurrentDockState">Determine the Current Docking State</h2> |
| 46 | |
| 47 | <p>The dock-state details are included as an extra in a sticky broadcast of the {@link |
| 48 | android.content.Intent#ACTION_DOCK_EVENT} action. Because it's sticky, you don't need to register a |
| 49 | {@link android.content.BroadcastReceiver}. You can simply call {@link |
| 50 | android.content.Context#registerReceiver registerReceiver()} passing in {@code null} as the |
| 51 | broadcast receiver as shown in the next snippet.</p> |
| 52 | |
| 53 | <pre>IntentFilter ifilter = new IntentFilter(Intent.ACTION_DOCK_EVENT); |
| 54 | Intent dockStatus = context.registerReceiver(null, ifilter);</pre> |
| 55 | |
| 56 | <p>You can extract the current docking status from the {@code EXTRA_DOCK_STATE} extra:<p> |
| 57 | |
| 58 | <pre>int dockState = battery.getIntExtra(EXTRA_DOCK_STATE, -1); |
| 59 | boolean isDocked = dockState != Intent.EXTRA_DOCK_STATE_UNDOCKED;</pre> |
| 60 | |
| 61 | |
| 62 | <h2 id="DockType">Determine the Current Dock Type</h2> |
| 63 | |
| 64 | <p>If a device is docked, it can be docked in any one of four different type of dock: |
| 65 | <ul><li>Car</li> |
| 66 | <li>Desk</li> |
| 67 | <li>Low-End (Analog) Desk</li> |
| 68 | <li>High-End (Digital) Desk</li></ul></p> |
| 69 | |
| 70 | <p>Note that the latter two options were only introduced to Android in API level 11, so it's good |
| 71 | practice to check for all three where you are only interested in the type of dock rather than it |
| 72 | being digital or analog specifically:</p> |
| 73 | |
| 74 | <pre>boolean isCar = dockState == EXTRA_DOCK_STATE_CAR; |
| 75 | boolean isDesk = dockState == EXTRA_DOCK_STATE_DESK || |
| 76 | dockState == EXTRA_DOCK_STATE_LE_DESK || |
| 77 | dockState == EXTRA_DOCK_STATE_HE_DESK;</pre> |
| 78 | |
| 79 | |
| 80 | <h2 id="MonitorDockState">Monitor for Changes in the Dock State or Type</h2> |
| 81 | |
| 82 | <p>Whenever the the device is docked or undocked, the {@link |
| 83 | android.content.Intent#ACTION_DOCK_EVENT} action is broadcast. To monitor changes in the |
| 84 | device's dock-state, simply register a broadcast receiver in your application manifest as shown in |
| 85 | the snippet below:</p> |
| 86 | |
| 87 | <pre><action android:name="android.intent.action.ACTION_DOCK_EVENT"/></pre> |
| 88 | |
| 89 | <p>You can extract the dock type and state within the receiver implementation using the same |
| 90 | techniques described in the previous step.</p> |