1 page.title=Determining and Monitoring the Docking State and Type 2 parent.title=Optimizing Battery Life 3 parent.link=index.html 4 5 trainingnavtop=true 6 next.title=Optimizing for Power-Saving 7 next.link=battery-optimization.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">Determine the Current Docking State</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/components/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 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> 91
