diff options
Diffstat (limited to 'docs/html/guide')
| -rw-r--r-- | docs/html/guide/developing/building/building-cmdline.jd | 2 | ||||
| -rw-r--r-- | docs/html/guide/guide_toc.cs | 16 | ||||
| -rwxr-xr-x | docs/html/guide/market/billing/billing_integrate.jd | 10 | ||||
| -rw-r--r-- | docs/html/guide/practices/security.jd | 772 | ||||
| -rw-r--r-- | docs/html/guide/topics/admin/device-admin.jd | 247 | ||||
| -rw-r--r-- | docs/html/guide/topics/providers/calendar-provider.jd | 1185 | ||||
| -rw-r--r-- | docs/html/guide/topics/providers/content-providers.jd | 9 | ||||
| -rw-r--r-- | docs/html/guide/topics/resources/drawable-resource.jd | 22 |
8 files changed, 2120 insertions, 143 deletions
diff --git a/docs/html/guide/developing/building/building-cmdline.jd b/docs/html/guide/developing/building/building-cmdline.jd index d78a4f5..c43962a 100644 --- a/docs/html/guide/developing/building/building-cmdline.jd +++ b/docs/html/guide/developing/building/building-cmdline.jd @@ -365,7 +365,7 @@ test project, the tested project is also cleaned.</dd> <dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and runs the tests.</dd> - <dt><code>ant emma debug installt test</code></dt> + <dt><code>ant emma debug install test</code></dt> <dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and runs the tests with code coverage enabled.</dd> diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index a3bb6d4..af379de 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -82,9 +82,17 @@ </a></li> </ul> </li> - <li><a href="<?cs var:toroot ?>guide/topics/providers/content-providers.html"> + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>guide/topics/providers/content-providers.html"> <span class="en">Content Providers</span> - </a></li> + </a><span class="new">updated</span></div> + <ul> + <li><a href="<?cs var:toroot ?>guide/topics/providers/calendar-provider.html"> + <span class="en">Calendar Provider</span></a> + <span class="new">new!</span> + </li> + </ul> + </li> <li><a href="<?cs var:toroot ?>guide/topics/intents/intents-filters.html"> <span class="en">Intents and Intent Filters</span> </a></li> @@ -789,6 +797,10 @@ applications</span> <li><a href="<?cs var:toroot ?>guide/practices/design/seamlessness.html"> <span class="en">Designing for Seamlessness</span> </a></li> + <li><a href="<?cs var:toroot ?>guide/practices/security.html"> + <span class="en">Designing for Security</span></a> + <span class="new">new!</span><!-- 11/7/10 --> + </li> </ul> </li> diff --git a/docs/html/guide/market/billing/billing_integrate.jd b/docs/html/guide/market/billing/billing_integrate.jd index 3eebd59..6017583 100755 --- a/docs/html/guide/market/billing/billing_integrate.jd +++ b/docs/html/guide/market/billing/billing_integrate.jd @@ -476,7 +476,7 @@ key can have the following five values:</p> <ul> <li><code>CHECK_BILLING_SUPPORTED</code>—verifies that the Android Market application supports in-app billing.</li> - <li><code>REQUEST_PURCHASE</code>—sends a purchase request for an in-app item.</li> + <li><code>REQUEST_PURCHASE</code>—sends a purchase request for an in-app item.</li> <li><code>GET_PURCHASE_INFORMATION</code>—retrieves transaction information for a purchase or refund.</li> <li><code>CONFIRM_NOTIFICATIONS</code>—acknowledges that you received the transaction @@ -584,9 +584,9 @@ interface.</p> // Note that the developer payload is optional. if (mDeveloperPayload != null) { request.putString(DEVELOPER_PAYLOAD, mDeveloperPayload); + } Bundle response = mService.sendBillingRequest(request); // Do something with this response. - } </pre> <p>The <code>makeRequestBundle()</code> method constructs an initial Bundle, which contains the three keys that are required for all requests: <code>BILLING_REQUEST</code>, @@ -930,9 +930,9 @@ sent in response to billing requests.</p> <pre> public class BillingReceiver extends BroadcastReceiver { - + private static final String TAG = "BillingReceiver"; - + // Intent actions that we receive in the BillingReceiver from Android Market. // These are defined by Android Market and cannot be changed. // The sample application defines these in the Consts.java file. @@ -940,7 +940,7 @@ public class BillingReceiver extends BroadcastReceiver { public static final String ACTION_RESPONSE_CODE = "com.android.vending.billing.RESPONSE_CODE"; public static final String ACTION_PURCHASE_STATE_CHANGED = "com.android.vending.billing.PURCHASE_STATE_CHANGED"; - + // The intent extras that are passed in an intent from Android Market. // These are defined by Android Market and cannot be changed. // The sample application defines these in the Consts.java file. diff --git a/docs/html/guide/practices/security.jd b/docs/html/guide/practices/security.jd new file mode 100644 index 0000000..5da7e98 --- /dev/null +++ b/docs/html/guide/practices/security.jd @@ -0,0 +1,772 @@ +page.title=Designing for Security +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> +<ol> +<li><a href="#Dalvik">Using Davlik Code</a></li> +<li><a href="#Native">Using Native Code</a></li> +<li><a href="#Data">Storing Data</a></li> +<li><a href="#IPC">Using IPC</a></li> +<li><a href="#Permissions">Using Permissions</a></li> +<li><a href="#Networking">Using Networking</a></li> +<li><a href="#DynamicCode">Dynamically Loading Code</a></li> +<li><a href="#Input">Performing Input Validation</a></li> +<li><a href="#UserData">Handling User Data</a></li> +<li><a href="#Crypto">Using Cryptography</a></li> +</ol> +<h2>See also</h2> +<ol> +<li><a href="http://source.android.com/tech/security/index.html">Android +Security Overview</a></li> +<li><a href="{@docRoot}guide/topics/security/security.html">Android Security +And Permissions</a></li> +</ol> +</div></div> +<p>Android was designed so that most developers will be able to build +applications using the default settings and not be confronted with difficult +decisions about security. Android also has a number of security features built +into the operating system that significantly reduce the frequency and impact of +application security issues.</p> + +<p>Some of the security features that help developers build secure applications +include: +<ul> +<li>The Android Application Sandbox that isolates data and code execution on a +per-application basis.</li> +<li>Android application framework with robust implementations of common +security functionality such as cryptography, permissions, and secure IPC.</li> +<li>Technologies like ASLR, NX, ProPolice, safe_iop, OpenBSD dlmalloc, OpenBSD +calloc, and Linux mmap_min_addr to mitigate risks associated with common memory +management errors</li> +<li>An encrypted filesystem that can be enabled to protect data on lost or +stolen devices.</li> +</ul></p> + +<p>Nevertheless, it is important for developers to be familiar with Android +security best practices to make sure they take advantage of these capabilities +and to reduce the likelihood of inadvertently introducing security issues that +can affect their applications.</p> + +<p>This document is organized around common APIs and development techniques +that can have security implications for your application and its users. As +these best practices are constantly evolving, we recommend you check back +occasionally throughout your application development process.</p> + +<a name="Dalvik"></a> +<h2>Using Dalvik Code</h2> +<p>Writing secure code that runs in virtual machines is a well-studied topic +and many of the issues are not specific to Android. Rather than attempting to +rehash these topics, we’d recommend that you familiarize yourself with the +existing literature. Two of the more popular resources are: +<ul> +<li><a href="http://www.securingjava.com/toc.html"> +http://www.securingjava.com/toc.html</a></li> +<li><a +href="https://www.owasp.org/index.php/Java_Security_Resources"> +https://www.owasp.org/index.php/Java_Security_Resources</a></li> +</ul></p> + +<p>This document is focused on the areas which are Android specific and/or +different from other environments. For developers experienced with VM +programming in other environments, there are two broad issues that may be +different about writing apps for Android: +<ul> +<li>Some virtual machines, such as the JVM or .net runtime, act as a security +boundary, isolating code from the underlying operating system capabilities. On +Android, the Dalvik VM is not a security boundary -- the application sandbox is +implemented at the OS level, so Dalvik can interoperate with native code in the +same application without any security constraints.</li> +<li>Given the limited storage on mobile devices, it’s common for developers +to want to build modular applications and use dynamic class loading. When +doing this consider both the source where you retrieve your application logic +and where you store it locally. Do not use dynamic class loading from sources +that are not verified, such as unsecured network sources or external storage, +since that code can be modified to include malicious behavior.</li> +</ul></p> + +<a name="Native"></a> +<h2>Using Native Code</h2> + +<p>In general, we encourage developers to use the Android SDK for most +application development, rather than using native code. Applications built +with native code are more complex, less portable, and more like to include +common memory corruption errors such as buffer overflows.</p> + +<p>Android is built using the Linux kernel and being familiar with Linux +development security best practices is especially useful if you are going to +use native code. This document is too short to discuss all of those best +practices, but one of the most popular resources is “Secure Programming for +Linux and Unix HOWTO”, available at <a +href="http://www.dwheeler.com/secure-programs"> +http://www.dwheeler.com/secure-programs</a>.</p> + +<p>An important difference between Android and most Linux environments is the +Application Sandbox. On Android, all applications run in the Application +Sandbox, including those written with native code. At the most basic level, a +good way to think about it for developers familiar with Linux is to know that +every application is given a unique UID with very limited permissions. This is +discussed in more detail in the <a +href="http://source.android.com/tech/security/index.html">Android Security +Overview</a> and you should be familiar with application permissions even if +you are using native code.</p> + +<a name="Data"></a> +<h2>Storing Data</h2> + +<h3>Using internal files</h3> + +<p>By default, files created on <a +href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal +storage</a> are only accessible to the application that created the file. This +protection is implemented by Android and is sufficient for most +applications.</p> + +<p>Use of <a +href="{@docRoot}reference/android/content/Context.html#MODE_WORLD_WRITEABLE"> +world writable</a> or <a +href="{@docRoot}reference/android/content/Context.html#MODE_WORLD_READABLE +">world readable</a> files for IPC is discouraged because it does not provide +the ability to limit data access to particular applications, nor does it +provide any control on data format. As an alternative, you might consider using +a ContentProvider which provides read and write permissions, and can make +dynamic permission grants on a case-by-case basis.</p> + +<p>To provide additional protection for sensitive data, some applications +choose to encrypt local files using a key that is not accessible to the +application. (For example, a key can be placed in a <code><a +href={@docRoot}reference/java/security/KeyStore.html">KeyStore</a></code> and +protected with a user password that is not stored on the device). While this +does not protect data from a root compromise that can monitor the user +inputting the password, it can provide protection for a lost device without <a +href="http://source.android.com/tech/encryption/index.html">file system +encryption</a>.</p> + +<h3>Using external storage</h3> + +<p>Files created on <a +href="{@docRoot}guide/topics/data/data-storage.html#filesExternal">external +storage</a>, such as SD Cards, are globally readable and writable. Since +external storage can be removed by the user and also modified by any +application, applications should not store sensitive information using +external storage.</p> + +<p>As with data from any untrusted source, applications should perform input +validation when handling data from external storage (see Input Validation +section). We strongly recommend that applications not store executables or +class files on external storage prior to dynamic loading. If an application +does retrieve executable files from external storage they should be signed and +cryptographically verified prior to dynamic loading.</p> + +<h3>Using content providers</h3> + +<p>ContentProviders provide a structured storage mechanism that can be limited +to your own application, or exported to allow access by other applications. By +default, a <code> +<a href="{@docRoot}reference/android/content/ContentProvider.html"> +ContentProvider</a></code> is +<a href="{@docRoot}guide/topics/manifest/provider-element.html#exported">exported +</a> for use by other applications. If you do not intend to provide other +applications with access to your<code> +<a href="{@docRoot}reference/android/content/ContentProvider.html"> +ContentProvider</a></code>, mark them as <code><a +href="{@docRoot}guide/topics/manifest/provider-element.html#exported"> +android:exported=false</a></code> in the application manifest.</p> + +<p>When creating a <code> +<a href="{@docRoot}reference/android/content/ContentProvider.html">ContentProvider +</a></code> that will be exported for use by other applications, you can specify +a single +<a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">permission +</a> for reading and writing, or distinct permissions for reading and writing +within the manifest. We recommend that you limit your permissions to those +required to accomplish the task at hand. Keep in mind that it’s usually +easier to add permissions later to expose new functionality than it is to take +them away and break existing users.</p> + +<p>If you are using a <code> +<a href="{@docRoot}reference/android/content/ContentProvider.html"> +ContentProvider</a></code> for sharing data between applications built by the +same developer, it is preferable to use +<a href="{@docRoot}guide/topics/manifest/permission-element.html#plevel">signature +level permissions</a>. Signature permissions do not require user confirmation, +so they provide a better user experience and more controlled access to the +<code> +<a href="{@docRoot}reference/android/content/ContentProvider.html"> +ContentProvider</a></code>.</p> + +<p>ContentProviders can also provide more granular access by declaring the <a +href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn"> +grantUriPermissions</a> element and using the <code><a +href="{@docRoot}reference/android/content/Intent.html#FLAG_GRANT_READ_URI_PERMIS +SION">FLAG_GRANT_READ_URI_PERMISSION</a></code> and <code><a +href="{@docRoot}reference/android/content/Intent.html#FLAG_GRANT_WRITE_URI_PERMI +SSION">FLAG_GRANT_WRITE_URI_PERMISSION</a></code> flags in the Intent object +that activates the component. The scope of these permissions can be further +limited by the <code><a +href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"> +grant-uri-permission element</a></code>.</p> + +<p>When accessing a <code> +<a href="{@docRoot}reference/android/content/ContentProvider.html"> +ContentProvider</a></code>, use parameterized query methods such as <code> +<a href="{@docRoot}reference/android/content/ContentProvider.html#query(android.net +.Uri,%20java.lang.String[],%20java.lang.String,%20java.lang.String[],%20java.lan +g.String)">query()</a></code>, <code><a +href="{@docRoot}reference/android/content/ContentProvider.html#update(android.ne +t.Uri,%20android.content.ContentValues,%20java.lang.String,%20java.lang.String[] +)">update()</a></code>, and <code><a +href="{@docRoot}reference/android/content/ContentProvider.html#delete(android.ne +t.Uri,%20java.lang.String,%20java.lang.String[])">delete()</a></code> to avoid +potential <a href="http://en.wikipedia.org/wiki/SQL_injection">SQL +Injection</a> from untrusted data. Note that using parameterized methods is not +sufficient if the <code>selection</code> is built by concatenating user data +prior to submitting it to the method.</p> + +<p>Do not have a false sense of security about the write permission. Consider +that the write permission allows SQL statements which make it possible for some +data to be confirmed using creative <code>WHERE</code> clauses and parsing the +results. For example, an attacker might probe for presence of a specific phone +number in a call-log by modifying a row only if that phone number already +exists. If the content provider data has predictable structure, the write +permission may be equivalent to providing both reading and writing.</p> + +<a name="IPC"></a> +<h2>Using Interprocess Communication (IPC)</h2> + +<p>Some Android applications attempt to implement IPC using traditional Linux +techniques such as network sockets and shared files. We strongly encourage the +use of Android system functionality for IPC such as Intents, Binders, Services, +and Receivers. The Android IPC mechanisms allow you to verify the identity of +the application connecting to your IPC and set security policy for each IPC +mechanism.</p> + +<p>Many of the security elements are shared across IPC mechanisms. <a +href="{@docRoot}reference/android/content/BroadcastReceiver.html"> +Broadcast Receivers</a>, <a +href="{@docRoot}reference/android/R.styleable.html#AndroidManifestActivity"> +Activities</a>, and <a +href="{@docRoot}reference/android/R.styleable.html#AndroidManifestService"> +Services</a> are all declared in the application manifest. If your IPC mechanism is +not intended for use by other applications, set the android:exported property +to false. This is useful for applications that consist of multiple processes +within the same UID, or if you decide late in development that you do not +actually want to expose functionality as IPC but you don’t want to rewrite +the code.</p> + +<p>If your IPC is intended to be accessible to other applications, you can +apply a security policy by using the <a +href="{@docRoot}reference/android/R.styleable.html#AndroidManifestPermission"> +Permission</a> tag. If IPC is between applications built by the same developer, +it is preferable to use <a +href="{@docRoot}guide/topics/manifest/permission-element.html#plevel">signature +level permissions</a>. Signature permissions do not require user confirmation, +so they provide a better user experience and more controlled access to the IPC +mechanism.</p> + +<p>One area that can introduce confusion is the use of intent filters. Note +that Intent filters should not be considered a security feature -- components +can be invoked directly and may not have data that would conform to the intent +filter. You should perform input validation within your intent receiver to +confirm that it is properly formatted for the invoked receiver, service, or +activity.</p> + +<h3>Using intents</h3> + +<p>Intents are the preferred mechanism for asynchronous IPC in Android. +Depending on your application requirements, you might use <code><a +href="{@docRoot}reference/android/content/Context.html#sendBroadcast(android.con +tent.Intent)">sendBroadcast()</a></code>, <code><a +href="{@docRoot}reference/android/content/Context.html#sendOrderedBroadcast(andr +oid.content.Intent,%20java.lang.String)">sendOrderedBroadcast()</a></code>, or +direct an intent to a specific application component.</p> + +<p>Note that ordered broadcasts can be “consumed” by a recipient, so they +may not be delivered to all applications. If you are sending an Intent where +delivery to a specific receiver is required, the intent must be delivered +directly to the receiver.</p> + +<p>Senders of an intent can verify that the recipient has a permission +specifying a non-Null Permission upon sending. Only applications with that +Permission will receive the intent. If data within a broadcast intent may be +sensitive, you should consider applying a permission to make sure that +malicious applications cannot register to receive those messages without +appropriate permissions. In those circumstances, you may also consider +invoking the receiver directly, rather than raising a broadcast.</p> + +<h3>Using binder and AIDL interfaces</h3> + +<p><a href="{@docRoot}reference/android/os/Binder.html">Binders</a> are the +preferred mechanism for RPC-style IPC in Android. They provide a well-defined +interface that enables mutual authentication of the endpoints, if required.</p> + +<p>We strongly encourage designing interfaces in a manner that does not require +interface specific permission checks. Binders are not declared within the +application manifest, and therefore you cannot apply declarative permissions +directly to a Binder. Binders generally inherit permissions declared in the +application manifest for the Service or Activity within which they are +implemented. If you are creating an interface that requires authentication +and/or access controls on a specific binder interface, those controls must be +explicitly added as code in the interface.</p> + +<p>If providing an interface that does require access controls, use <code><a +href="{@docRoot}reference/android/content/Context.html#checkCallingPermission(ja +va.lang.String)">checkCallingPermission()</a></code> to verify whether the +caller of the Binder has a required permission. This is especially important +before accessing a Service on behalf of the caller, as the identify of your +application is passed to other interfaces. If invoking an interface provided +by a Service, the <code><a +href="{@docRoot}reference/android/content/Context.html#bindService(android.conte +nt.Intent,%20android.content.ServiceConnection,%20int)">bindService()</a></code> + invocation may fail if you do not have permission to access the given Service. + If calling an interface provided locally by your own application, it may be +useful to use the <code><a +href="{@docRoot}reference/android/os/Binder.html#clearCallingIdentity()"> +clearCallingIdentity()</a></code> to satisfy internal security checks.</p> + +<h3>Using broadcast receivers</h3> + +<p>Broadcast receivers are used to handle asynchronous requests initiated via +an intent.</p> + +<p>By default, receivers are exported and can be invoked by any other +application. If your <code><a +href={@docRoot}reference/android/content/BroadcastReceiver.html"> +BroadcastReceivers</a></code> is intended for use by other applications, you +may want to apply security permissions to receivers using the <code><a +href="{@docRoot}reference/android/R.styleable.html#AndroidManifestReceiver"> +<receiver></a></code> element within the application manifest. This will +prevent applications without appropriate permissions from sending an intent to +the <code><a +href={@docRoot}reference/android/content/BroadcastReceiver.html"> +BroadcastReceivers</a></code>.</p> + +<h3>Using Services</h3> + +<p>Services are often used to supply functionality for other applications to +use. Each service class must have a corresponding <service> declaration in its +package's AndroidManifest.xml.</p> + +<p>By default, Services are exported and can be invoked by any other +application. Services can be protected using the android:permission attribute +within the manifest’s <code><a +href="{@docRoot}reference/android/R.styleable.html#AndroidManifestService"> +<service></a></code> tag. By doing so, other applications will need to declare +a corresponding <code><a +href="{@docRoot}reference/android/R.styleable.html#AndroidManifestService_permis +sion"><uses-permission></a></code> element in their own manifest to be +able to start, stop, or bind to the service.</p> + +<p>A Service can protect individual IPC calls into it with permissions, by +calling <code><a +href="{@docRoot}reference/android/content/Context.html#checkCallingPermission(ja +va.lang.String)">checkCallingPermission()</a></code>before executing +the implementation of that call. We generally recommend using the +declarative permissions in the manifest, since those are less prone to +oversight.</p> + +<h3>Using Activities</h3> + +<p>Activities are most often used for providing the core user-facing +functionality of an application. By default, Activities are exported and +invokable by other applications only if they have an intent filter or binder +declared. In general, we recommend that you specifically declare a Receiver or +Service to handle IPC, since this modular approach reduces the risk of exposing +functionality that is not intended for use by other applications.</p> + +<p>If you do expose an Activity for purposes of IPC, the <code><a +href="{@docRoot}reference/android/R.styleable.html#AndroidManifestActivity_permi +ssion">android:permission</a></code> attribute in the <code><a +href="{@docRoot}reference/android/R.styleable.html#AndroidManifestActivity"> +<activity></a></code> declaration in the application manifest can be used to +restrict access to only those applications which have the stated +permissions.</p> + +<a name="Permissions"></a> +<h2>Using Permissions</h2> + +<h3>Requesting Permissions</h3> + +<p>We recommend minimizing the number of permissions requested by an +application. Not having access to sensitive permissions reduces the risk of +inadvertently misusing those permissions, can improve user adoption, and makes +applications less attractive targets for attackers.</p> + +<p>If it is possible to design your application in a way that does not require +a permission, that is preferable. For example, rather than requesting access +to device information to create an identifier, create a <a +href="{@docRoot}reference/java/util/UUID.html">GUID</a> for your application. +(This specific example is also discussed in Handling User Data) Or, rather than +using external storage, store data in your application directory.</p> + +<p>If a permission is not required, do not request it. This sounds simple, but +there has been quite a bit of research into the frequency of over-requesting +permissions. If you’re interested in the subject you might start with this +research paper published by U.C. Berkeley: <a +href="http://www.eecs.berkeley.edu/Pubs/TechRpts/2011/EECS-2011-48.pdf"> +http://www.eecs.berkeley.edu/Pubs/TechRpts/2011/EECS-2011-48.pdf</a></p> + +<p>In addition to requesting permissions, your application can use <a +href="{@docRoot}guide/topics/manifest/permission-element.html">permissions</a> +to protect IPC that is security sensitive and will be exposed to other +applications -- such as a <code><a +href="{@docRoot}reference/android/content/ContentProvider.html"> +ContentProvider</a></code>. In general, we recommend using access controls +other than user confirmed permissions where possible since permissions can +be confusing for users. For example, consider using the <a +href="{@docRoot}guide/topics/manifest/permission-element.html#plevel">signature +protection level</a> on permissions for IPC communication between applications +provided by a single developer.</p> + +<p>Do not cause permission re-delegation. This occurs when an app exposes data +over IPC that is only available because it has a specific permission, but does +not require that permission of any clients of it’s IPC interface. More +details on the potential impacts, and frequency of this type of problem is +provided in this research paper published at USENIX: <a +href="http://www.cs.berkeley.edu/~afelt/felt_usenixsec2011.pdf">http://www.cs.be +rkeley.edu/~afelt/felt_usenixsec2011.pdf</a></p> + +<h3>Creating Permissions</h3> + +<p>Generally, you should strive to create as few permissions as possible while +satisfying your security requirements. Creating a new permission is relatively +uncommon for most applications, since <a +href="{@docRoot}reference/android/Manifest.permission.html"> +system-defined permissions</a> cover many situations. Where appropriate, +perform access checks using existing permissions.</p> + +<p>If you must create a new permission, consider whether you can accomplish +your task with a Signature permission. Signature permissions are transparent +to the user and only allow access by applications signed by the same developer +as application performing the permission check. If you create a Dangerous +permission, then the user needs to decide whether to install the application. +This can be confusing for other developers, as well as for users.</p> + +<p>If you create a Dangerous permission, there are a number of complexities +that you need to consider. +<ul> +<li>The permission must have a string that concisely expresses to a user the +security decision they will be required to make.</li> +<li>The permission string must be localized to many different languages.</li> +<li>Uses may choose not to install an application because a permission is +confusing or perceived as risky.</li> +<li>Applications may request the permission when the creator of the permission +has not been installed.</li> +</ul></p> + +<p>Each of these poses a significant non-technical challenge for an application +developer, which is why we discourage the use of Dangerous permission.</p> + +<a name="Networking"></a> +<h2>Using Networking</h2> + +<h3>Using IP Networking</h3> + +<p>Networking on Android is not significantly different from Linux +environments. The key consideration is making sure that appropriate protocols +are used for sensitive data, such as <a +href="{@docRoot}reference/javax/net/ssl/HttpsURLConnection.html">HTTPS</a> for +web traffic. We prefer use of HTTPS over HTTP anywhere that HTTPS is +supported on the server, since mobile devices frequently connect on networks +that are not secured, such as public WiFi hotspots.</p> + +<p>Authenticated, encrypted socket-level communication can be easily +implemented using the <code><a +href="{@docRoot}reference/javax/net/ssl/SSLSocket.html">SSLSocket</a></code> +class. Given the frequency with which Android devices connect to unsecured +wireless networks using WiFi, the use of secure networking is strongly +encouraged for all applications.</p> + +<p>We have seen some applications use <a +href="http://en.wikipedia.org/wiki/Localhost">localhost</a> network ports for +handling sensitive IPC. We discourage this approach since these interfaces are +accessible by other applications on the device. Instead, use an Android IPC +mechanism where authentication is possible such as a Service and Binder. (Even +worse than using loopback is to bind to INADDR_ANY since then your application +may receive requests from anywhere. We’ve seen that, too.)</p> + +<p>Also, one common issue that warrants repeating is to make sure that you do +not trust data downloaded from HTTP or other insecure protocols. This includes +validation of input in <code><a +href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code> and +any responses to intents issued against HTTP.</p> + +<h3>Using Telephony Networking</h3> + +<p>SMS is the telephony protocol most frequently used by Android developers. +Developers should keep in mind that this protocol was primarily designed for +user-to-user communication and is not well-suited for some application +purposes. Due to the limitations of SMS, we strongly recommend the use of <a +href="http://code.google.com/android/c2dm/">C2DM</a> and IP networking for +sending data messages to devices.</p> + +<p>Many developers do not realize that SMS is not encrypted or strongly +authenticated on the network or on the device. In particular, any SMS receiver +should expect that a malicious user may have sent the SMS to your application +-- do not rely on unauthenticated SMS data to perform sensitive commands. +Also, you should be aware that SMS may be subject to spoofing and/or +interception on the network. On the Android-powered device itself, SMS +messages are transmitted as Broadcast intents, so they may be read or captured +by other applications that have the READ_SMS permission.</p> + +<a name="DynamicCode"></a> +<h2>Dynamically Loading Code</h2> + +<p>We strongly discourage loading code from outside of the application APK. +Doing so significantly increases the likelihood of application compromise due +to code injection or code tampering. It also adds complexity around version +management and application testing. Finally, it can make it impossible to +verify the behavior of an application, so it may be prohibited in some +environments.</p> + +<p>If your application does dynamically load code, the most important thing to +keep in mind about dynamically loaded code is that it runs with the same +security permissions as the application APK. The user made a decision to +install your application based on your identity, and they are expecting that +you provide any code run within the application, including code that is +dynamically loaded.</p> + +<p>The major security risk associated with dynamically loading code is that the +code needs to come from a verifiable source. If the modules are included +directly within your APK, then they cannot be modified by other applications. +This is true whether the code is a native library or a class being loaded using +<a href="{@docRoot}reference/dalvik/system/DexClassLoader.html"> +<code>DexClassLoader</code></a>. We have seen many instances of applications +attempting to load code from insecure locations, such as downloaded from the +network over unencrypted protocols or from world writable locations such as +external storage. These locations could allow someone on the network to modify +the content in transit, or another application on a users device to modify the +content, respectively.</p> + + +<h3>Using WebView</h3> + +<p>Since WebView consumes web content that can include HTML and JavaScript, +improper use can introduce common web security issues such as <a +href="http://en.wikipedia.org/wiki/Cross_site_scripting">cross-site-scripting</a +> (JavaScript injection). Android includes a number of mechanisms to reduce +the scope of these potential issues by limiting the capability of WebView to +the minimum functionality required by your application.</p> + +<p>If your application does not directly use JavaScript within a <code><a +href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code>, do +not call +<a href="{@docRoot}reference/android/webkit/WebSettings.html#setJavaScriptEnabled(boolean) +<code>setJavaScriptEnabled()</code></a>. We have seen this method invoked +in sample code that might be repurposed in production application -- so +remove it if necessary. By default, <code><a +href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code> does +not execute JavaScript so cross-site-scripting is not possible.</p> + +<p>Use <code><a +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(jav +a.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> with +particular care because it allows JavaScript to invoke operations that are +normally reserved for Android applications. Only expose <code><a +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(jav +a.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> to +sources from which all input is trustworthy. If untrusted input is allowed, +untrusted JavaScript may be able to invoke Android methods. In general, we +recommend only exposing <code><a +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(jav +a.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> to +JavaScript that is contained within your application APK.</p> + +<p>Do not trust information downloaded over HTTP, use HTTPS instead. Even if +you are connecting only to a single website that you trust or control, HTTP is +subject to <a +href="http://en.wikipedia.org/wiki/Man-in-the-middle_attack">MiTM</a> attacks +and interception of data. Sensitive capabilities using <code><a +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(jav +a.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> should +not ever be exposed to unverified script downloaded over HTTP. Note that even +with the use of HTTPS, +<code><a +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(jav +a.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> +increases the attack surface of your application to include the server +infrastructure and all CAs trusted by the Android-powered device.</p> + +<p>If your application accesses sensitive data with a <code><a +href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code>, you +may want to use the <code><a +href="{@docRoot}reference/android/webkit/WebView.html#clearCache(boolean)"> +clearCache()</a></code> method to delete any files stored locally. Server side +headers like no-cache can also be used to indicate that an application should +not cache particular content.</p> + +<a name="Input"></a> +<h2>Performing Input Validation</h2> + +<p>Insufficient input validation is one of the most common security problems +affecting applications, regardless of what platform they run on. Android does +have platform-level countermeasures that reduce the exposure of applications to +input validation issues, you should use those features where possible. Also +note that selection of type-safe languages tends to reduce the likelihood of +input validation issues. We strongly recommend building your applications with +the Android SDK.</p> + +<p>If you are using native code, then any data read from files, received over +the network, or received from an IPC has the potential to introduce a security +issue. The most common problems are <a +href="http://en.wikipedia.org/wiki/Buffer_overflow">buffer overflows</a>, <a +href="http://en.wikipedia.org/wiki/Double_free#Use_after_free">use after +free</a>, and <a +href="http://en.wikipedia.org/wiki/Off-by-one_error">off-by-one errors</a>. +Android provides a number of technologies like ASLR and DEP that reduce the +exploitability of these errors, but they do not solve the underlying problem. +These can be prevented by careful handling of pointers and managing of +buffers.</p> + +<p>Dynamic, string based languages such as JavaScript and SQL are also subject +to input validation problems due to escape characters and <a +href="http://en.wikipedia.org/wiki/Code_injection">script injection</a>.</p> + +<p>If you are using data within queries that are submitted to SQL Database or a +Content Provider, SQL Injection may be an issue. The best defense is to use +parameterized queries, as is discussed in the ContentProviders section. +Limiting permissions to read-only or write-only can also reduce the potential +for harm related to SQL Injection.</p> + +<p>If you are using <code><a +href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code>, then +you must consider the possibility of XSS. If your application does not +directly use JavaScript within a <code><a +href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code>, do +not call setJavaScriptEnabled() and XSS is no longer possible. If you must +enable JavaScript then the WebView section provides other security best +practices.</p> + +<p>If you cannot use the security features above, we strongly recommend the use +of well-structured data formats and verifying that the data conforms to the +expected format. While blacklisting of characters or character-replacement can +be an effective strategy, these techniques are error-prone in practice and +should be avoided when possible.</p> + +<a name="UserData"></a> +<h2>Handling User Data</h2> + +<p>In general, the best approach is to minimize use of APIs that access +sensitive or personal user data. If you have access to data and can avoid +storing or transmitting the information, do not store or transmit the data. +Finally, consider if there is a way that your application logic can be +implemented using a hash or non-reversible form of the data. For example, your +application might use the hash of an an email address as a primary key, to +avoid transmitting or storing the email address. This reduces the chances of +inadvertently exposing data, and it also reduces the chance of attackers +attempting to exploit your application.</p> + +<p>If your application accesses personal information such as passwords or +usernames, keep in mind that some jurisdictions may require you to provide a +privacy policy explaining your use and storage of that data. So following the +security best practice of minimizing access to user data may also simplify +compliance.</p> + +<p>You should also consider whether your application might be inadvertently +exposing personal information to other parties such as third-party components +for advertising or third-party services used by your application. If you don't +know why a component or service requires a personal information, don’t +provide it. In general, reducing the access to personal information by your +application will reduce the potential for problems in this area.</p> + +<p>If access to sensitive data is required, evaluate whether that information +must be transmitted to a server, or whether the operation can be performed on +the client. Consider running any code using sensitive data on the client to +avoid transmitting user data.</p> + +<p>Also, make sure that you do not inadvertently expose user data to other +application on the device through overly permissive IPC, world writable files, +or network sockets. This is a special case of permission redelegation, +discussed in the Requesting Permissions section.</p> + +<p>If a GUID is required, create a large, unique number and store it. Do not +use phone identifiers such as the phone number or IMEI which may be associated +with personal information. This topic is discussed in more detail in the <a +href="http://android-developers.blogspot.com/2011/03/identifying-app-installatio +ns.html">Android Developer Blog</a>.</p> + +<h3>Handling Credentials</h3> + +<p>In general, we recommend minimizing the frequency of asking for user +credentials -- to make phishing attacks more conspicuous, and less likely to be +successful. Instead use an authorization token and refresh it.</p> + +<p>Where possible, username and password should not be stored on the device. +Instead, perform initial authentication using the username and password +supplied by the user, and then use a short-lived, service-specific +authorization token.</p> + +<p>Services that will be accessible to multiple applications should be accessed +using <code> +<a href="{@docRoot}reference/android/accounts/AccountManager.html"> +AccountManager</a></code>. If possible, use the <code><a +href="{@docRoot}reference/android/accounts/AccountManager.html"> +AccountManager</a></code> class to invoke a cloud-based service and do not store +passwords on the device.</p> + +<p>After using <code><a +href="{@docRoot}reference/android/accounts/AccountManager.html"> +AccountManager</a></code> to retrieve an Account, check the <code><a +href="{@docRoot}reference/android/accounts/Account.html#CREATOR">CREATOR</a> +</code> before passing in any credentials, so that you do not inadvertently pass +credentials to the wrong application.</p> + +<p>If credentials are to be used only by applications that you create, then you +can verify the application which accesses the <code><a +href="{@docRoot}reference/android/accounts/AccountManager.html"> +AccountManager</a></code> using <code><a href="<code><a +href="{@docRoot}h/reference/android/content/pm/PackageManager.html#checkSignatur +es(java.lang.String,%20java.lang.String)">checkSignature()</a></code>. +Alternatively, if only one application will use the credential, you might use a +<code><a +href={@docRoot}reference/java/security/KeyStore.html">KeyStore</a></code> for +storage.</p> + +<a name="Crypto"></a> +<h2>Using Cryptography</h2> + +<p>In addition to providing data isolation, supporting full-filesystem +encryption, and providing secure communications channels Android provides a +wide array of algorithms for protecting data using cryptography.</p> + +<p>In general, try to use the highest level of pre-existing framework +implementation that can support your use case. If you need to securely +retrieve a file from a known location, a simple HTTPS URI may be adequate and +require no knowledge of cryptography on your part. If you need a secure +tunnel, consider using +<a href="{@docRoot}reference/javax/net/ssl/HttpsURLConnection.html"> +<code>HttpsURLConnection</code></a> or <code><a +href="{@docRoot}reference/javax/net/ssl/SSLSocket.html">SSLSocket</a></code>, +rather than writing your own protocol.</p> + +<p>If you do find yourself needing to implement your own protocol, we strongly +recommend that you not implement your own cryptographic algorithms. Use +existing cryptographic algorithms such as those in the implementation of AES or +RSA provided in the <code><a +href="{@docRoot}reference/javax/crypto/Cipher.html">Cipher</a></code> class.</p> + +<p>Use a secure random number generator ( +<a href="http://developer.android.com/reference/java/security/SecureRandom.html"> +<code>SecureRandom</code></a>) to initialize any cryptographic keys (<a +href="http://developer.android.com/reference/javax/crypto/KeyGenerator.html"> +<code>KeyGenerator</code></a>). Use of a key that is not generated with a secure random +number generator significantly weakens the strength of the algorithm, and may +allow offline attacks.</p> + +<p>If you need to store a key for repeated use, use a mechanism like <code><a +href={@docRoot}reference/java/security/KeyStore.html">KeyStore</a></code> that +provides a mechanism for long term storage and retrieval of cryptographic +keys.</p> + +<h2>Conclusion</h2> + +<p>Android provides developers with the ability to design applications with a +broad range of security requirements. These best practices will help you make +sure that your application takes advantage of the security benefits provided by +the platform.</p> + +<p>You can receive more information on these topics and discuss security best +practices with other developers in the <a +href="http://groups.google.com/group/android-security-discuss">Android Security +Discuss</a> Google Group</p> diff --git a/docs/html/guide/topics/admin/device-admin.jd b/docs/html/guide/topics/admin/device-admin.jd index 7bbf5e6..820c3c0 100644 --- a/docs/html/guide/topics/admin/device-admin.jd +++ b/docs/html/guide/topics/admin/device-admin.jd @@ -27,6 +27,12 @@ page.title=Device Administration <li>{@link android.app.admin.DevicePolicyManager}</li> <li>{@link android.app.admin.DeviceAdminInfo}</li> </ol> + <h2>Related samples</h2> + <ol> + <li><a +href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/DeviceAdminSample.html"> +DeviceAdminSample</a></li> +</ol> </div> </div> @@ -201,6 +207,16 @@ access data. The value can be between 1 and 60 minutes.</td> </tr> <td>Specifies that the storage area should be encrypted, if the device supports it. Introduced in Android 3.0.</td> </tr> +<tr> + <td>Disable camera</td> + + <td>Specifies that the camera should be disabled. Note that this doesn't have +to be a permanent disabling. The camera can be enabled/disabled dynamically +based on context, time, and so on. Introduced in Android 4.0.</td> + +</tr> + + </table> <h4>Other features</h4> @@ -247,6 +263,7 @@ one of the last <em>n</em> passwords they previously used.</li> locks.</li> <li>Make the device lock immediately.</li> <li>Wipe the device's data (that is, restore factory settings).</li> + <li>Disable the camera.</li> </ul> @@ -280,46 +297,38 @@ intent, expressed in the manifest as an intent filter.</li> <li>A declaration of security policies used in metadata.</li> </ul> <p>Here is an excerpt from the Device Administration sample manifest:</p> -<pre><activity android:name=".app.DeviceAdminSample$Controller" - android:label="@string/activity_sample_device_admin"> - <intent-filter> - <action android:name="android.intent.action.MAIN" /> - <category android:name="android.intent.category.SAMPLE_CODE" /> - </intent-filter> +<pre><activity android:name=".app.DeviceAdminSample" + android:label="@string/activity_sample_device_admin"> + <intent-filter> + <action android:name="android.intent.action.MAIN" /> + <category android:name="android.intent.category.SAMPLE_CODE" /> + </intent-filter> </activity> - -<receiver android:name=".app.DeviceAdminSample" - android:label="@string/sample_device_admin" - android:description="@string/sample_device_admin_description" - android:permission="android.permission.BIND_DEVICE_ADMIN"> - <meta-data android:name="android.app.device_admin" - android:resource="@xml/device_admin_sample" /> - <intent-filter> - <action android:name="android.app.action.DEVICE_ADMIN_ENABLED" /> - </intent-filter> +<receiver android:name=".app.DeviceAdminSample$DeviceAdminSampleReceiver" + android:label="@string/sample_device_admin" + android:description="@string/sample_device_admin_description" + android:permission="android.permission.BIND_DEVICE_ADMIN"> + <meta-data android:name="android.app.device_admin" + android:resource="@xml/device_admin_sample" /> + <intent-filter> + <action android:name="android.app.action.DEVICE_ADMIN_ENABLED" /> + </intent-filter> </receiver></pre> <p>Note that:</p> <ul> - <li>The activity in the sample application is an {@link android.app.Activity} -subclass called <code>Controller</code>. The syntax -<code>".app.DeviceAdminSample$Controller"</code> indicates that -<code>Controller</code> is an inner class that is nested inside the -<code>DeviceAdminSample</code> class. Note that an Activity does not need to be -an inner class; it just is in this example.</li> - <li>The following attributes refer to string resources that for the sample application reside in <code>ApiDemos/res/values/strings.xml</code>. For more information about resources, see <a href="{@docRoot}guide/topics/resources/index.html">Application Resources</a>. <ul> -<li><code>android:label="@string/activity_sample_device_admin"</code> refers to the +<li><code>android:label="@string/activity_sample_device_admin"</code> refers to the user-readable label for the activity.</li> -<li><code>android:label="@string/sample_device_admin"</code> refers to the +<li><code>android:label="@string/sample_device_admin"</code> refers to the user-readable label for the permission.</li> -<li><code>android:description="@string/sample_device_admin_description"</code> refers to +<li><code>android:description="@string/sample_device_admin_description"</code> refers to the user-readable description of the permission. A descripton is typically longer and more informative than a label.</li> @@ -357,6 +366,9 @@ android.app.admin.DeviceAdminInfo} class. Here are the contents of <reset-password /> <force-lock /> <wipe-data /> + <expire-password /> + <encrypted-storage /> + <disable-camera /> </uses-policies> </device-admin> </pre> @@ -401,33 +413,34 @@ simply displays a {@link android.widget.Toast} notification in response to parti events. For example:</p> <pre>public class DeviceAdminSample extends DeviceAdminReceiver { -... + void showToast(Context context, String msg) { + String status = context.getString(R.string.admin_receiver_status, msg); + Toast.makeText(context, status, Toast.LENGTH_SHORT).show(); + } + + @Override + public void onEnabled(Context context, Intent intent) { + showToast(context, context.getString(R.string.admin_receiver_status_enabled)); + } + @Override - public void onEnabled(Context context, Intent intent) { - showToast(context, "Sample Device Admin: enabled"); - } - - @Override - public CharSequence onDisableRequested(Context context, Intent intent) { - return "This is an optional message to warn the user about disabling."; - } - - @Override - public void onDisabled(Context context, Intent intent) { - showToast(context, "Sample Device Admin: disabled"); - } - - @Override - public void onPasswordChanged(Context context, Intent intent) { - showToast(context, "Sample Device Admin: pw changed"); - } - - void showToast(Context context, CharSequence msg) { - Toast.makeText(context, msg, Toast.LENGTH_SHORT).show(); + public CharSequence onDisableRequested(Context context, Intent intent) { + return context.getString(R.string.admin_receiver_status_disable_warning); + } + + @Override + public void onDisabled(Context context, Intent intent) { + showToast(context, context.getString(R.string.admin_receiver_status_disabled)); + } + + @Override + public void onPasswordChanged(Context context, Intent intent) { + showToast(context, context.getString(R.string.admin_receiver_status_pw_changed)); } ... }</pre> + <h4 id="enabling">Enabling the application</h4> <p>One of the major events a device admin application has to handle is the user enabling the application. The user must explicitly enable the application for @@ -438,43 +451,50 @@ get any of the application's benefits.</p> action that triggers the {@link android.app.admin.DevicePolicyManager#ACTION_ADD_DEVICE_ADMIN} intent. In the sample application, this happens when the user clicks the <strong>Enable -Admin</strong> button. </p> -<p>When the user clicks the <strong>Enable Admin</strong> button, the display -changes to prompt the user to enable the device admin application, as shown in figure +Admin</strong> checkbox. </p> +<p>When the user clicks the <strong>Enable Admin</strong> checkbox, the display +changes to prompt the user to activate the device admin application, as shown in figure 2.</p> <img src="{@docRoot}images/admin/device-admin-activate-prompt.png"/> <p class="img-caption"><strong>Figure 2.</strong> Sample Application: Activating the Application</p> -<p>Below is the code that gets executed when the user clicks the <strong>Enable -Admin</strong> button shown in figure 1. </p> - -<pre> private OnClickListener mEnableListener = new OnClickListener() { - public void onClick(View v) { - // Launch the activity to have the user enable our admin. - Intent intent = new Intent(DevicePolicyManager.ACTION_ADD_DEVICE_ADMIN); - intent.putExtra(DevicePolicyManager.EXTRA_DEVICE_ADMIN, - mDeviceAdminSample); - intent.putExtra(DevicePolicyManager.EXTRA_ADD_EXPLANATION, - "Additional text explaining why this needs to be added."); - startActivityForResult(intent, RESULT_ENABLE); - } -}; -... -// This code checks whether the device admin app was successfully enabled. -@Override -protected void onActivityResult(int requestCode, int resultCode, Intent data) { - switch (requestCode) { - case RESULT_ENABLE: - if (resultCode == Activity.RESULT_OK) { - Log.i("DeviceAdminSample", "Administration enabled!"); - } else { - Log.i("DeviceAdminSample", "Administration enable FAILED!"); - } - return; - } - super.onActivityResult(requestCode, resultCode, data); -}</pre> +<p>Below is the code that gets executed when the user clicks the <strong>Enable Admin</strong> checkbox. This has the effect of triggering the +{@link android.preference.Preference.OnPreferenceChangeListener#onPreferenceChange(android.preference.Preference, java.lang.Object) onPreferenceChange()} +callback. This callback is invoked when the value of this {@link android.preference.Preference} has been changed by the user and is about to be set and/or persisted. If the user is enabling the application, the display +changes to prompt the user to activate the device admin application, as shown in figure +2. Otherwise, the device admin application is disabled. </p> + +<pre>@Override + public boolean onPreferenceChange(Preference preference, Object newValue) { + if (super.onPreferenceChange(preference, newValue)) { + return true; + } + boolean value = (Boolean) newValue; + if (preference == mEnableCheckbox) { + if (value != mAdminActive) { + if (value) { + // Launch the activity to have the user enable our admin. + Intent intent = new Intent(DevicePolicyManager.ACTION_ADD_DEVICE_ADMIN); + intent.putExtra(DevicePolicyManager.EXTRA_DEVICE_ADMIN, mDeviceAdminSample); + intent.putExtra(DevicePolicyManager.EXTRA_ADD_EXPLANATION, + mActivity.getString(R.string.add_admin_extra_app_text)); + startActivityForResult(intent, REQUEST_CODE_ENABLE_ADMIN); + // return false - don't update checkbox until we're really active + return false; + } else { + mDPM.removeActiveAdmin(mDeviceAdminSample); + enableDeviceCapabilitiesArea(false); + mAdminActive = false; + } + } + } else if (preference == mDisableCameraCheckbox) { + mDPM.setCameraDisabled(mDeviceAdminSample, value); + ... + } + return true; + }</pre> + <p>The line <code>intent.putExtra(DevicePolicyManager.EXTRA_DEVICE_ADMIN, @@ -489,18 +509,17 @@ active. To do this it uses the {@link android.app.admin.DevicePolicyManager} met {@link android.app.admin.DevicePolicyManager#isAdminActive(android.content.ComponentName) isAdminActive()}. Notice that the {@link android.app.admin.DevicePolicyManager} method {@link android.app.admin.DevicePolicyManager#isAdminActive(android.content.ComponentName) isAdminActive()} takes a {@link android.app.admin.DeviceAdminReceiver} component as its argument:</p> + <pre> DevicePolicyManager mDPM; ... -boolean active = mDPM.isAdminActive(mDeviceAdminSample); -if (active) { - // Admin app is active, so do some admin stuff - ... -} else { - // do something else +private boolean isActiveAdmin() { + return mDPM.isAdminActive(mDeviceAdminSample); } </pre> + + <h3 id="admin_ops">Managing policies</h3> <p>{@link android.app.admin.DevicePolicyManager} is a public class for managing policies enforced on a device. {@link android.app.admin.DevicePolicyManager} manages policies for one @@ -618,49 +637,6 @@ long pwExpiration; ... mDPM.setPasswordExpirationTimeout(mDeviceAdminSample, pwExpiration); </pre> - -<p>From the <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/DeviceAdminSample.html" ->Device Administration API sample</a>, here is the code -that updates the password expiration status:</p> - -<pre> -DevicePolicyManager mDPM; -ComponentName mDeviceAdminSample; -private TextView mPasswordExpirationStatus; -... -void updatePasswordExpirationStatus() { - boolean active = mDPM.isAdminActive(mDeviceAdminSample); - String statusText; - if (active) { - long now = System.currentTimeMillis(); - // Query the DevicePolicyManager twice - first for the expiration values - // set by the sample app, and later, for the system values (which may be different - // if there is another administrator active.) - long expirationDate = mDPM.getPasswordExpiration(mDeviceAdminSample); - long mSecUntilExpiration = expirationDate - now; - if (mSecUntilExpiration >= 0) { - statusText = "Expiration in " + countdownString(mSecUntilExpiration); - } else { - statusText = "Expired " + countdownString(-mSecUntilExpiration) + " ago"; - } - - // expirationTimeout is the cycle time between required password refresh - long expirationTimeout = mDPM.getPasswordExpirationTimeout(mDeviceAdminSample); - statusText += " / timeout period " + countdownString(expirationTimeout); - - // Now report the aggregate (global) expiration time - statusText += " / Aggregate "; - expirationDate = mDPM.getPasswordExpiration(null); - mSecUntilExpiration = expirationDate - now; - if (mSecUntilExpiration >= 0) { - statusText += "expiration in " + countdownString(mSecUntilExpiration); - } else { - statusText += "expired " + countdownString(-mSecUntilExpiration) + " ago"; - } - } else { - statusText = "<inactive>"; - } - mPasswordExpirationStatus.setText(statusText);</pre> <h5 id="history">Restrict password based on history</h5> @@ -718,6 +694,19 @@ mDPM.wipeData(0);</pre> <p>The {@link android.app.admin.DevicePolicyManager#wipeData wipeData()} method takes as its parameter a bit mask of additional options. Currently the value must be 0. </p> +<h4>Disable camera</h4> +<p>Beginning with Android 4.0, you can disable the camera. Note that this doesn't have to be a permanent disabling. The camera can be enabled/disabled dynamically based on context, time, and so on. </p> +<p>You control whether the camera is disabled by using the +{@link android.app.admin.DevicePolicyManager#setCameraDisabled(android.content.ComponentName, boolean) setCameraDisabled()} method. For example, this snippet sets the camera to be enabled or disabled based on a checkbox setting:</p> + +<pre>private CheckBoxPreference mDisableCameraCheckbox; +DevicePolicyManager mDPM; +ComponentName mDeviceAdminSample; +... +mDPM.setCameraDisabled(mDeviceAdminSample, mDisableCameraCheckbox.isChecked());<br /> +</pre> + + <h4 id=storage">Storage encryption</h4> <p>Beginning with Android 3.0, you can use the {@link android.app.admin.DevicePolicyManager#setStorageEncryption(android.content.ComponentName,boolean) setStorageEncryption()} diff --git a/docs/html/guide/topics/providers/calendar-provider.jd b/docs/html/guide/topics/providers/calendar-provider.jd new file mode 100644 index 0000000..3ab5125 --- /dev/null +++ b/docs/html/guide/topics/providers/calendar-provider.jd @@ -0,0 +1,1185 @@ +page.title=Calendar Provider +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#overview">Basics</a></li> + <li><a href="#manifest">User Permissions</a></li> + <li><a href="#calendar">Calendars table</a> +<ol> + <li><a href="#query">Querying a calendar</a></li> + <li><a href="#modify-calendar">Modifying a calendar</a></li> + <li><a href="#insert-calendar">Inserting a calendar</a></li> + </ol> + </li> + <li><a href="#events">Events table</a> +<ol> + <li><a href="#add-event">Adding Events</a></li> + <li><a href="#update-event">Updating Events</a></li> + <li><a href="#delete-event">Deleting Events</a></li> + </ol> + </li> + <li><a href="#attendees">Attendees table</a> +<ol> + <li><a href="#add-attendees">Adding Attendees</a></li> + </ol> + </li> + <li><a href="#reminders">Reminders table</a> +<ol> + <li><a href="#add-reminders">Adding Reminders</a></li> + </ol> + </li> + <li><a href="#instances">Instances table</a> + <ol> + <li><a href="#query-instances">Querying the Instances table</a></li> + </ol></li> + <li><a href="#intents">Calendar Intents</a> + <ol> + <li><a href="#intent-insert">Using an intent to insert an event</a></li> + <li><a href="#intent-edit">Using an intent to edit an event</a></li> + <li><a href="#intent-view">Using intents to view calendar data</a></li> + </ol> + </li> + + <li><a href="#sync-adapter">Sync Adapters</a></li> +</ol> + + <h2>Key classes</h2> + <ol> + <li>{@link android.provider.CalendarContract.Calendars}</li> + <li>{@link android.provider.CalendarContract.Events}</li> + <li>{@link android.provider.CalendarContract.Attendees}</li> + <li>{@link android.provider.CalendarContract.Reminders}</li> + </ol> +</div> +</div> + +<p>The Calendar Provider is a repository for a user's calendar events. The +Calendar Provider API allows you to perform query, insert, update, and delete +operations on calendars, events, attendees, reminders, and so on.</p> + + +<p>The Calender Provider API can be used by applications and sync adapters. The +rules vary depending on what type of program is making the calls. This document +focuses primarily on using the Calendar Provider API as an application. For +a discussion of how sync adapters are different, see +<a href="#sync-adapter">Sync Adapters</a>.</p> + + +<p>Normally, to read or write calendar data, an application's manifest must +include the proper permissions, described in <a href="#manifest">User +Permissions</a>. To make performing common operations easier, the Calendar +Provider offers a set of intents, as described in <a href="#intents">Calendar +Intents</a>. These intents take users to the Calendar application to insert, view, +and edit events. The user interacts with the Calendar application and then +returns to the original application. Thus your application doesn't need to request permissions, +nor does it need to provide a user interface to view or create events.</p> + +<h2 id="overview">Basics</h2> + +<p><a href="{@docRoot}guide/topics/providers/content-providers.html">Content providers</a> store data and make it accessible to +applications. The content providers offered by the Android platform (including the Calendar Provider) typically expose data as a set of tables based on a +relational database model, where each row is a record and each column is data of +a particular type and meaning. Through the Calendar Provider API, applications +and sync adapters can get read/write access to the database tables that hold a +user's calendar data.</p> + +<p>Every content provider exposes a public URI (wrapped as a +{@link android.net.Uri} +object) that uniquely identifies its data set. A content provider that controls + multiple data sets (multiple tables) exposes a separate URI for each one. All +URIs for providers begin with the string "content://". This +identifies the data as being controlled by a content provider. The Calendar +Provider defines constants for the URIs for each of its classes (tables). These +URIs have the format <code><em><class></em>.CONTENT_URI</code>. For +example, {@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}.</p> + +<p>Figure 1 shows a graphical representation of the Calendar Provider data model. It shows the +main tables and the fields that link them to each other.</p> + +<img src="{@docRoot}images/providers/datamodel.png" alt="Calendar Provider Data Model"/> +<p class="img-caption"><strong>Figure 1.</strong> Calendar Provider data model.</p> + +<p>A user can have multiple calendars, and different calendars can be associated with different types of accounts (Google Calendar, Exchange, and so on).</p> + +<p>The {@link android.provider.CalendarContract} defines the data model of calendar and event related information. This data is stored in a number of tables, listed below.</p> + +<table> + <tr> + <th>Table (Class)</th> + <th>Description</th> + </tr> + <tr> + <td><p>{@link android.provider.CalendarContract.Calendars}</p></td> + + <td>This table holds +the calendar-specific information. Each row in this table contains the details for +a single calendar, such as the name, color, sync information, and so on.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Events}</td> + + <td>This table holds the +event-specific information. Each row in this table has the information for a single +event—for example, event title, location, start time, end +time, and so on. The event can occur one-time or can recur multiple times. Attendees, +reminders, and extended properties are stored in separate tables. +They each have an {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} +that references the {@link android.provider.BaseColumns#_ID} in the Events table.</td> + + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Instances}</td> + + <td>This table holds the +start and end time for each occurrence of an event. Each row in this table +represents a single event occurrence. For one-time events there is a 1:1 mapping +of instances to events. For recurring events, multiple rows are automatically + generated that correspond to multiple occurrences of that event.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Attendees}</td> + + <td>This table holds the +event attendee (guest) information. Each row represents a single guest of an +event. It specifies the type of guest and the guest's attendance response +for the event.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Reminders}</td> + + <td>This table holds the +alert/notification data. Each row represents a single alert for an event. An +event can have multiple reminders. The maximum number of reminders per event is +specified in +{@link android.provider.CalendarContract.CalendarColumns#MAX_REMINDERS}, +which is set by the sync adapter that +owns the given calendar. Reminders are specified in minutes before the event +and have a method that determines how the user will be alerted.</td> + </tr> + +</table> + +<p>The Calendar Provider API is designed to be flexible and powerful. At the +same time, it's important to provide a good end user experience and +protect the integrity of the calendar and its data. To this end, here are +some things to keep in mind when using the API:</p> + +<ul> + +<li><strong>Inserting, updating, and viewing calendar events.</strong> To directly insert, modify, and read events from the Calendar Provider, you need the appropriate <a href="#manifest">permissions</a>. However, if you're not building a full-fledged calendar application or sync adapter, requesting these permissions isn't necessary. You can instead use intents supported by Android's Calendar application to hand off read and write operations to that application. When you use the intents, your application sends users to the Calendar application to perform the desired operation +in a pre-filled form. After they're done, they're returned to your application. +By designing your application to perform common operations through the Calendar, +you provide users with a consistent, robust user interface. This is the +recommended approach. For more information, see <a href="#intents">Calendar +Intents</a>.</p> + + +<li><strong>Sync adapters.</strong> A sync adapter synchronizes the calendar data +on a user's device with another server or data source. In the +{@link android.provider.CalendarContract.Calendars} and +{@link android.provider.CalendarContract.Events} tables, +there are columns that are reserved for the sync adapters to use. +The provider and applications should not modify them. In fact, they are not +visible unless they are accessed as a sync adapter. For more information about +sync adapters, see <a href="#sync-adapter">Sync Adapters</a>.</li> + +</ul> + + +<h2 id="manifest">User Permissions</h2> + +<p>To read calendar data, an application must include the {@link +android.Manifest.permission#READ_CALENDAR} permission in its manifest file. It +must include the {@link android.Manifest.permission#WRITE_CALENDAR} permission +to delete, insert or update calendar data:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<manifest xmlns:android="http://schemas.android.com/apk/res/android"...> + <uses-sdk android:minSdkVersion="14" /> + <uses-permission android:name="android.permission.READ_CALENDAR" /> + <uses-permission android:name="android.permission.WRITE_CALENDAR" /> + ... +</manifest> +</pre> + + +<h2 id="calendar">Calendars Table</h2> + +<p>The {@link android.provider.CalendarContract.Calendars} table contains details +for individual calendars. The following +Calendars columns are writable by both an application and a <a href="#sync-adapter">sync adapter</a>. +For a full list of supported fields, see the +{@link android.provider.CalendarContract.Calendars} reference.</p> +<table> + <tr> + <th>Constant</th> + <th>Description</th> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Calendars#NAME}</td> + <td>The name of the calendar.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Calendars#CALENDAR_DISPLAY_NAME}</td> + <td>The name of this calendar that is displayed to the user.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Calendars#VISIBLE}</td> + + <td>A boolean indicating whether the calendar is selected to be displayed. A +value of 0 indicates that events associated with this calendar should not be +shown. A value of 1 indicates that events associated with this calendar should +be shown. This value affects the generation of rows in the {@link +android.provider.CalendarContract.Instances} table.</td> + + + </tr> + <tr> + <td>{@link android.provider.CalendarContract.CalendarColumns#SYNC_EVENTS}</td> + + <td>A boolean indicating whether the calendar should be synced and have its +events stored on the device. A value of 0 says do not sync this calendar or +store its events on the device. A value of 1 says sync events for this calendar +and store its events on the device.</td> + </tr> +</table> + +<h3 id="query">Querying a calendar</h3> + +<p>Here is an example that shows how to get all the calendars for a particular +user. For simplicity's sake, in this example the query operation is shown in the +user interface thread ("main thread"). In practice, this should be done in an asynchronous +thread instead of on the main thread. For more discussion, see +<a href="{@docRoot}guide/topics/fundamentals/loaders.html">Loaders</a>. If you are not just reading data but modifying it, see {@link android.content.AsyncQueryHandler}. +</p> + + +<pre> + // Projection array. Creating indices for this array instead of doing + // dynamic lookups improves performance. + public static final String[] EVENT_PROJECTION = new String[] { + Calendars._ID, // 0 + Calendars.ACCOUNT_NAME, // 1 + Calendars.CALENDAR_DISPLAY_NAME // 2 + }; + + // The indices for the projection array above. + private static final int PROJECTION_ID_INDEX = 0; + private static final int PROJECTION_ACCOUNT_NAME_INDEX = 1; + private static final int PROJECTION_DISPLAY_NAME_INDEX = 2;</pre> + + +<div class="sidebox-wrapper"> <div class="sidebox"> <h3>Why must you include +ACCOUNT_TYPE?</h3> <p>If you query on a {@link +android.provider.CalendarContract.Calendars#ACCOUNT_NAME +Calendars.ACCOUNT_NAME}, you must also include +{@link android.provider.CalendarContract.Calendars#ACCOUNT_TYPE Calendars.ACCOUNT_TYPE} +in the selection. That is because a given account is +only considered unique given both its <code>ACCOUNT_NAME</code> and its +<code>ACCOUNT_TYPE</code>. The <code>ACCOUNT_TYPE</code> refers to the way that +the account is being synced. It is often but not always the domain. For +example, an account could be synced through a corporate pop3 sync adapter, in which +case the <code>ACCOUNT_TYPE</code> would not be a domain. There is also a +special type of account called {@link +android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL} for calendars not +associated with a device account. {@link +android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL} accounts do not get +synced.</p> </div> </div> + + +<p> In the next part of the example, you construct your query. The selection +specifies the criteria for the query. In this example the query is looking for +all calendars that have the <code>ACCOUNT_NAME</code> +"sampleuser@google.com" and the <code>ACCOUNT_TYPE</code> +"com.google". The query returns a {@link android.database.Cursor} +object that you can use to traverse the result set returned by the database +query. For more discussion of using queries in content providers, see <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>.</p> + + +<pre>// Run query +Cursor cur = null; +ContentResolver cr = getContentResolver(); +Uri uri = Calendars.CONTENT_URI; +String selection = "((" + Calendars.ACCOUNT_NAME + " = ?) AND (" + + Calendars.ACCOUNT_TYPE + " = ?))"; +String[] selectionArgs = new String[] {"sampleuser@gmail.com", "com.google"}; +// Submit the query and get a Cursor object back. +cur = cr.query(uri, EVENT_PROJECTION, selection, selectionArgs, null);</pre> + +<p>This next section uses the cursor to step through the result set. It uses the +constants that were set up at the beginning of the example to return the values +for each field.</p> + +<pre>// Use the cursor to step through the returned records +while (cur.moveToNext()) { + long calID = 0; + String displayName = null; + String accountName = null; + + // Get the field values + calID = cur.getLong(PROJECTION_ID_INDEX); + displayName = cur.getString(PROJECTION_DISPLAY_NAME_INDEX); + accountName = cur.getString(PROJECTION_ACCOUNT_NAME_INDEX); + + // Do something with the values... + + ... +} +</pre> + +<h3 id="modify-calendar">Modifying a calendar</h3> + +<p>To perform an update of an calendar, you can provide the {@link +android.provider.BaseColumns#_ID} of the calendar either as an appended ID to +the Uri + +({@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()}) +or as the first selection item. The selection +should start with <code>"_id=?"</code>, and the first +<code>selectionArg</code> should be the {@link +android.provider.BaseColumns#_ID} of the calendar. +You can also do updates by encoding the ID in the URI. This example changes a +calendar's display name using the +({@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()}) +approach:</p> + +<pre>private static final String DEBUG_TAG = "MyActivity"; +... +long calID = 2; +ContentValues values = new ContentValues(); +// The new display name for the calendar +values.put(Calendars.CALENDAR_DISPLAY_NAME, "Trevor's Calendar"); +Uri updateUri = ContentUris.withAppendedId(Calendars.CONTENT_URI, calID); +int rows = getContentResolver().update(updateUri, values, null, null); +Log.i(DEBUG_TAG, "Rows updated: " + rows);</pre> + +<h3 id="insert-calendar">Inserting a calendar</h2> + +<p>Calendars are designed to be primarily managed by a sync adapter, so you +should only insert new calendars as a sync adapter. For the most part, +applications can only make superficial changes to calendars, such as changing the display name. If +an application needs to create a local calendar, it can do this by performing +the calendar insertion as a sync adapter, using an {@link +android.provider.CalendarContract.SyncColumns#ACCOUNT_TYPE} of {@link +android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL}. +{@link android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL} +is a special account type for calendars that are not +associated with a device account. Calendars of this type are not synced to a server. For a +discussion of sync adapters, see <a href="#sync-adapter">Sync Adapters</a>.</p> + +<h2 id="events">Events Table</h2> + +<p>The {@link android.provider.CalendarContract.Events} table contains details +for individual events. To add, update, or delete events, an application must +include the {@link android.Manifest.permission#WRITE_CALENDAR} permission in its +<a href="#manifest">manifest file</a>.</p> + +<p>The following Events columns are writable by both an application and a sync +adapter. For a full list of supported fields, see the {@link +android.provider.CalendarContract.Events} reference.</p> + +<table> + <tr> + <th>Constant</th> + <th>Description</th> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#CALENDAR_ID}</td> + <td>The {@link android.provider.BaseColumns#_ID} of the calendar the event belongs to.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#ORGANIZER}</td> + <td>Email of the organizer (owner) of the event.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#TITLE}</td> + <td>The title of the event.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#EVENT_LOCATION}</td> + <td>Where the event takes place. </td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#DESCRIPTION}</td> + <td>The description of the event.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#DTSTART}</td> + <td>The time the event starts in UTC milliseconds since the epoch. </td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#DTEND}</td> + <td>The time the event ends in UTC milliseconds since the epoch. </td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#EVENT_TIMEZONE}</td> + <td>The time zone for the event.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#EVENT_END_TIMEZONE}</td> + <td>The time zone for the end time of the event.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#DURATION}</td> + + <td>The duration of the event in <a +href="http://tools.ietf.org/html/rfc5545#section-3.8.2.5">RFC5545</a> format. +For example, a value of <code>"PT1H"</code> states that the event +should last one hour, and a value of <code>"P2W"</code> indicates a +duration of 2 weeks. </td> + + + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#ALL_DAY}</td> + + <td>A value of 1 indicates this event occupies the entire day, as defined by +the local time zone. A value of 0 indicates it is a regular event that may start +and end at any time during a day.</td> + + + </tr> + + + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#RRULE}</td> + + <td>The recurrence rule for the event format. For +example, <code>"FREQ=WEEKLY;COUNT=10;WKST=SU"</code>. You can find +more examples <a +href="http://tools.ietf.org/html/rfc5545#section-3.8.5.3">here</a>.</td> + + </tr> + + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#RDATE}</td> + <td>The recurrence dates for the event. + You typically use {@link android.provider.CalendarContract.EventsColumns#RDATE} + in conjunction with {@link android.provider.CalendarContract.EventsColumns#RRULE} + to define an aggregate set of +repeating occurrences. For more discussion, see the <a +href="http://tools.ietf.org/html/rfc5545#section-3.8.5.2">RFC5545 spec</a>.</td> +</tr> + + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#AVAILABILITY}</td> + + <td>If this event counts as busy time or is free time that can be +scheduled over. </td> + + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#GUESTS_CAN_MODIFY}</td> + <td>Whether guests can modify the event. </td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#GUESTS_CAN_INVITE_OTHERS}</td> + <td>Whether guests can invite other guests. </td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#GUESTS_CAN_SEE_GUESTS}</td> + <td>Whether guests can see the list of attendees.</td> + </tr> +</table> + +<h3 id="add-event">Adding Events</h3> + +<p>When your application inserts a new event, we recommend that you use an +{@link android.content.Intent#ACTION_INSERT INSERT} Intent, as described in <a +href="#intent-insert">Using an intent to insert an event</a>. However, if you +need to, you can insert events directly. This section describes how to do +this.</p> + + +<p>Here are the rules for inserting a new event: </p> +<ul> + + <li>You must include {@link +android.provider.CalendarContract.EventsColumns#CALENDAR_ID} and {@link +android.provider.CalendarContract.EventsColumns#DTSTART}.</li> + +<li>You must include an {@link +android.provider.CalendarContract.EventsColumns#EVENT_TIMEZONE}. To get a list +of the system's installed time zone IDs, use {@link +java.util.TimeZone#getAvailableIDs()}. Note that this rule does not apply if +you're inserting an event through the {@link +android.content.Intent#ACTION_INSERT INSERT} Intent, described in <a +href="#intent-insert">Using an intent to insert an event</a>—in that +scenario, a default time zone is supplied.</li> + + <li>For non-recurring events, you must include {@link +android.provider.CalendarContract.EventsColumns#DTEND}. </li> + + + <li>For recurring events, you must include a {@link +android.provider.CalendarContract.EventsColumns#DURATION} in addition to {@link +android.provider.CalendarContract.EventsColumns#RRULE} or {@link +android.provider.CalendarContract.EventsColumns#RDATE}. Note that this rule does not apply if +you're inserting an event through the {@link +android.content.Intent#ACTION_INSERT INSERT} Intent, described in <a +href="#intent-insert">Using an intent to insert an event</a>—in that +scenario, you can use an {@link +android.provider.CalendarContract.EventsColumns#RRULE} in conjunction with {@link android.provider.CalendarContract.EventsColumns#DTSTART} and {@link android.provider.CalendarContract.EventsColumns#DTEND}, and the Calendar application +converts it to a duration automatically.</li> + +</ul> + +<p>Here is an example of inserting an event. This is being performed in the UI +thread for simplicity. In practice, inserts and updates should be done in an +asynchronous thread to move the action into a background thread. For more +information, see {@link android.content.AsyncQueryHandler}.</p> + + +<pre> +long calID = 3; +long startMillis = 0; +long endMillis = 0; +Calendar beginTime = Calendar.getInstance(); +beginTime.set(2012, 9, 14, 7, 30); +startMillis = beginTime.getTimeInMillis(); +Calendar endTime = Calendar.getInstance(); +endTime.set(2012, 9, 14, 8, 45); +endMillis = endTime.getTimeInMillis(); +... + +ContentResolver cr = getContentResolver(); +ContentValues values = new ContentValues(); +values.put(Events.DTSTART, startMillis); +values.put(Events.DTEND, endMillis); +values.put(Events.TITLE, "Jazzercise"); +values.put(Events.DESCRIPTION, "Group workout"); +values.put(Events.CALENDAR_ID, calID); +values.put(Events.EVENT_TIMEZONE, "America/Los_Angeles"); +Uri uri = cr.insert(Events.CONTENT_URI, values); + +// get the event ID that is the last element in the Uri +long eventID = Long.parseLong(uri.getLastPathSegment()); +// +// ... do something with event ID +// +//</pre> + +<p class="note"><strong>Note:</strong> See how this example captures the event +ID after the event is created. This is the easiest way to get an event ID. You often +need the event ID to perform other calendar operations—for example, to add +attendees or reminders to an event.</p> + + +<h3 id="update-event">Updating Events</h3> + +<p>When your application wants to allow the user to edit an event, we recommend +that you use an {@link android.content.Intent#ACTION_EDIT EDIT} Intent, as +described in <a href="#intent-edit">Using an intent to edit an event</a>. +However, if you need to, you can edit events directly. To perform an update of +an Event, you can provide the <code>_ID</code> of the +event either as an appended ID to the Uri ({@link +android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()}) +or as the first selection item. +The selection should start with <code>"_id=?"</code>, and the first +<code>selectionArg</code> should be the <code>_ID</code> of the event. You can +also do updates using a selection with no ID. Here is an example of updating an +event. It changes the title of the event using the +{@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()} +approach:</p> + + +<pre>private static final String DEBUG_TAG = "MyActivity"; +... +long eventID = 188; +... +ContentResolver cr = getContentResolver(); +ContentValues values = new ContentValues(); +Uri updateUri = null; +// The new title for the event +values.put(Events.TITLE, "Kickboxing"); +myUri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); +int rows = getContentResolver().update(updateUri, values, null, null); +Log.i(DEBUG_TAG, "Rows updated: " + rows); </pre> + +<h3 id="delete-event">Deleting Events</h3> + +<p>You can delete an event either by its {@link +android.provider.BaseColumns#_ID} as an appended ID on the URI, or by using +standard selection. If you use an appended ID, you can't also do a selection. +There are two versions of delete: as an application and as a sync adapter. An +application delete sets the <em>deleted</em> column to 1. This flag that tells +the sync adapter that the row was deleted and that this deletion should be +propagated to the server. A sync adapter delete removes the event from the +database along with all its associated data. Here is an example of application +deleting an event through its {@link android.provider.BaseColumns#_ID}:</p> + + +<pre>private static final String DEBUG_TAG = "MyActivity"; +... +long eventID = 201; +... +ContentResolver cr = getContentResolver(); +ContentValues values = new ContentValues(); +Uri deleteUri = null; +deleteUri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); +int rows = getContentResolver().delete(deleteUri, null, null); +Log.i(DEBUG_TAG, "Rows deleted: " + rows); +</pre> + +<h2 id="attendees">Attendees Table</h2> + +<p>Each row of the {@link android.provider.CalendarContract.Attendees} table +represents a single attendee or guest of an event. Calling +{@link android.provider.CalendarContract.Reminders#query(android.content.ContentResolver, long, java.lang.String[]) query()} +returns a list of attendees for the +event with the given {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID}. +This {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} +must match the {@link +android.provider.BaseColumns#_ID} of a particular event.</p> + +<p>The following table lists the +writable fields. When inserting a new attendee, you must include all of them +except <code>ATTENDEE_NAME</code>. +</p> + + +<table> + <tr> + <th>Constant</th> + <th>Description</th> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID}</td> + <td>The ID of the event.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_NAME}</td> + <td>The name of the attendee.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_EMAIL}</td> + <td>The email address of the attendee.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_RELATIONSHIP}</td> + <td><p>The relationship of the attendee to the event. One of:</p> + <ul> + <li>{@link android.provider.CalendarContract.AttendeesColumns#RELATIONSHIP_ATTENDEE}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#RELATIONSHIP_NONE}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#RELATIONSHIP_ORGANIZER}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#RELATIONSHIP_PERFORMER}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#RELATIONSHIP_SPEAKER}</li> + </ul> + </td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_TYPE}</td> + <td><p>The type of attendee. One of: </p> + <ul> + <li>{@link android.provider.CalendarContract.AttendeesColumns#TYPE_REQUIRED}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#TYPE_OPTIONAL}</li> + </ul></td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS}</td> + <td><p>The attendance status of the attendee. One of:</p> + <ul> + <li>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS_ACCEPTED}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS_DECLINED}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS_INVITED}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS_NONE}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS_TENTATIVE}</li> + </ul></td> + </tr> +</table> + +<h3 id="add-attendees">Adding Attendees</h3> + +<p>Here is an example that adds a single attendee to an event. Note that the +{@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} +is required:</p> + +<pre> +long eventID = 202; +... +ContentResolver cr = getContentResolver(); +ContentValues values = new ContentValues(); +values.put(Attendees.ATTENDEE_NAME, "Trevor"); +values.put(Attendees.ATTENDEE_EMAIL, "trevor@example.com"); +values.put(Attendees.ATTENDEE_RELATIONSHIP, Attendees.RELATIONSHIP_ATTENDEE); +values.put(Attendees.ATTENDEE_TYPE, Attendees.TYPE_OPTIONAL); +values.put(Attendees.ATTENDEE_STATUS, Attendees.ATTENDEE_STATUS_INVITED); +values.put(Attendees.EVENT_ID, eventID); +Uri uri = cr.insert(Attendees.CONTENT_URI, values); +</pre> + +<h2 id="reminders">Reminders Table</h2> + +<p>Each row of the {@link android.provider.CalendarContract.Reminders} table +represents a single reminder for an event. Calling +{@link android.provider.CalendarContract.Reminders#query(android.content.ContentResolver, long, java.lang.String[]) query()} returns a list of reminders for the +event with the given +{@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID}.</p> + + +<p>The following table lists the writable fields for reminders. All of them must +be included when inserting a new reminder. Note that sync adapters specify the +types of reminders they support in the {@link +android.provider.CalendarContract.Calendars} table. See +{@link android.provider.CalendarContract.CalendarColumns#ALLOWED_REMINDERS} +for details.</p> + + +<table> + <tr> + <th>Constant</th> + <th>Description</th> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.RemindersColumns#EVENT_ID}</td> + <td>The ID of the event.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.RemindersColumns#MINUTES}</td> + <td>The minutes prior to the event that the reminder should fire.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.RemindersColumns#METHOD}</td> + <td><p>The alarm method, as set on the server. One of:</p> + <ul> + <li>{@link android.provider.CalendarContract.RemindersColumns#METHOD_ALERT}</li> + <li>{@link android.provider.CalendarContract.RemindersColumns#METHOD_DEFAULT}</li> + <li>{@link android.provider.CalendarContract.RemindersColumns#METHOD_EMAIL}</li> + <li>{@link android.provider.CalendarContract.RemindersColumns#METHOD_SMS}</li> + </ul></td> + </tr> +</table> + +<h3 id="add-reminders">Adding Reminders</h3> + +<p>This example adds a reminder to an event. The reminder fires 15 +minutes before the event.</p> +<pre> +long eventID = 221; +... +ContentResolver cr = getContentResolver(); +ContentValues values = new ContentValues(); +values.put(Reminders.MINUTES, 15); +values.put(Reminders.EVENT_ID, eventID); +values.put(Reminders.METHOD, Reminders.METHOD_ALERT); +Uri uri = cr.insert(Reminders.CONTENT_URI, values);</pre> + +<h2 id="instances">Instances Table</h2> + +<p>The +{@link android.provider.CalendarContract.Instances} table holds the +start and end time for occurrences of an event. Each row in this table +represents a single event occurrence. The instances table is not writable and only +provides a way to query event occurrences. </p> + +<p>The following table lists some of the fields you can query on for an instance. Note +that time zone is defined by +{@link android.provider.CalendarContract.CalendarCache#KEY_TIMEZONE_TYPE} +and +{@link android.provider.CalendarContract.CalendarCache#KEY_TIMEZONE_INSTANCES}.</p> + + +<table> + <tr> + <th>Constant</th> + <th>Description</th> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Instances#BEGIN}</td> + <td>The beginning time of the instance, in UTC milliseconds.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Instances#END}</td> + <td>The ending time of the instance, in UTC milliseconds.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Instances#END_DAY}</td> + + <td>The Julian end day of the instance, relative to the Calendar's time +zone. + +</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Instances#END_MINUTE}</td> + + <td>The end minute of the instance measured from midnight in the the +Calendar's time zone.</td> + + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Instances#EVENT_ID}</td> + <td>The <code>_ID</code> of the event for this instance.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Instances#START_DAY}</td> + <td>The Julian start day of the instance, relative to the Calendar's time zone. + </td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Instances#START_MINUTE}</td> + + <td>The start minute of the instance measured from midnight, relative to the +Calendar's time zone. +</td> + + </tr> + +</table> + +<h3 id="query-instances">Querying the Instances table</h3> + +<p>To query the Instances table, you need to specify a range time for the query +in the URI. In this example, {@link android.provider.CalendarContract.Instances} +gets access to the {@link +android.provider.CalendarContract.EventsColumns#TITLE} field through its +implementation of the {@link android.provider.CalendarContract.EventsColumns} interface. +In other words, {@link +android.provider.CalendarContract.EventsColumns#TITLE} is returned through a +database view, not through querying the raw {@link +android.provider.CalendarContract.Instances} table.</p> + +<pre> +private static final String DEBUG_TAG = "MyActivity"; +public static final String[] INSTANCE_PROJECTION = new String[] { + Instances.EVENT_ID, // 0 + Instances.BEGIN, // 1 + Instances.TITLE // 2 + }; + +// The indices for the projection array above. +private static final int PROJECTION_ID_INDEX = 0; +private static final int PROJECTION_BEGIN_INDEX = 1; +private static final int PROJECTION_TITLE_INDEX = 2; +... + +// Specify the date range you want to search for recurring +// event instances +Calendar beginTime = Calendar.getInstance(); +beginTime.set(2011, 9, 23, 8, 0); +long startMillis = beginTime.getTimeInMillis(); +Calendar endTime = Calendar.getInstance(); +endTime.set(2011, 10, 24, 8, 0); +long endMillis = endTime.getTimeInMillis(); + +Cursor cur = null; +ContentResolver cr = getContentResolver(); + +// The ID of the recurring event whose instances you are searching +// for in the Instances table +String selection = Instances.EVENT_ID + " = ?"; +String[] selectionArgs = new String[] {"207"}; + +// Construct the query with the desired date range. +Uri.Builder builder = Instances.CONTENT_URI.buildUpon(); +ContentUris.appendId(builder, startMillis); +ContentUris.appendId(builder, endMillis); + +// Submit the query +cur = cr.query(builder.build(), + INSTANCE_PROJECTION, + selection, + selectionArgs, + null); + +while (cur.moveToNext()) { + String title = null; + long eventID = 0; + long beginVal = 0; + + // Get the field values + eventID = cur.getLong(PROJECTION_ID_INDEX); + beginVal = cur.getLong(PROJECTION_BEGIN_INDEX); + title = cur.getString(PROJECTION_TITLE_INDEX); + + // Do something with the values. + Log.i(DEBUG_TAG, "Event: " + title); + Calendar calendar = Calendar.getInstance(); + calendar.setTimeInMillis(beginVal); + DateFormat formatter = new SimpleDateFormat("MM/dd/yyyy"); + Log.i(DEBUG_TAG, "Date: " + formatter.format(calendar.getTime())); + } + }</pre> + +<h2 id="intents">Calendar Intents</h2> +<p>Your application doesn't need <a href="#manifest">permissions</a> to read and write calendar data. It can instead use intents supported by Android's Calendar application to hand off read and write operations to that application. The following table lists the intents supported by the Calendar Provider:</p> +<table> + <tr> + <th>Action</th> + <th>URI</th> + + <th>Description</th> + <th>Extras</th> + </tr> + <tr> + <td><br> + {@link android.content.Intent#ACTION_VIEW VIEW} <br></td> + <td><p><code>content://com.android.calendar/time/<ms_since_epoch></code></p> + You can also refer to the URI with +{@link android.provider.CalendarContract#CONTENT_URI CalendarContract.CONTENT_URI}. +For an example of using this intent, see <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-view">Using intents to view calendar data</a>. + + </td> + <td>Open calendar to the time specified by <code><ms_since_epoch></code>.</td> + <td>None.</td> + </tr> + <tr> + <td><p>{@link android.content.Intent#ACTION_VIEW VIEW} </p> + + </td> + <td><p><code>content://com.android.calendar/events/<event_id></code></p> + + You can also refer to the URI with +{@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}. +For an example of using this intent, see <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-view">Using intents to view calendar data</a>. + + </td> + <td>View the event specified by <code><event_id></code>.</td> + + <td>{@link android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_BEGIN_TIME}<br> + <br> + <br> + {@link android.provider.CalendarContract#EXTRA_EVENT_END_TIME CalendarContract.EXTRA_EVENT_END_TIME}</td> + </tr> + + <tr> + <td>{@link android.content.Intent#ACTION_EDIT EDIT} </td> + <td><p><code>content://com.android.calendar/events/<event_id></code></p> + + You can also refer to the URI with +{@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}. +For an example of using this intent, see <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-edit">Using an intent to edit an event</a>. + + + </td> + <td>Edit the event specified by <code><event_id></code>.</td> + + <td>{@link android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_BEGIN_TIME}<br> + <br> + <br> + {@link android.provider.CalendarContract#EXTRA_EVENT_END_TIME CalendarContract.EXTRA_EVENT_END_TIME}</td> + </tr> + + <tr> + <td>{@link android.content.Intent#ACTION_EDIT EDIT} <br> + <br> + {@link android.content.Intent#ACTION_INSERT INSERT} </td> + <td><p><code>content://com.android.calendar/events</code></p> + + You can also refer to the URI with +{@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}. +For an example of using this intent, see <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-insert">Using an intent to insert an event</a>. + + </td> + + <td>Create an event.</td> + <td>Any of the extras listed in the table below.</td> + </tr> +</table> + +<p>The following table lists the intent extras supported by the Calendar Provider: +</p> +<table> + <tr> + <th>Intent Extra</th> + <th>Description</th> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#TITLE Events.TITLE}</td> + <td>Name for the event.</td> + </tr> + <tr> + + <td>{@link android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME +CalendarContract.EXTRA_EVENT_BEGIN_TIME}</td> + <td>Event begin time in milliseconds from the epoch.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract#EXTRA_EVENT_END_TIME +CalendarContract.EXTRA_EVENT_END_TIME}</td> + + <td>Event end time in milliseconds from the epoch.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract#EXTRA_EVENT_ALL_DAY +CalendarContract.EXTRA_EVENT_ALL_DAY}</td> + + <td>A boolean that indicates that an event is all day. Value can be +<code>true</code> or <code>false</code>.</td> </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#EVENT_LOCATION +Events.EVENT_LOCATION}</td> + + <td>Location of the event.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#DESCRIPTION +Events.DESCRIPTION}</td> + + <td>Event description.</td> + </tr> + <tr> + <td> + {@link android.content.Intent#EXTRA_EMAIL Intent.EXTRA_EMAIL}</td> + <td>Email addresses of those to invite as a comma-separated list.</td> + </tr> + <tr> + <td> + {@link android.provider.CalendarContract.EventsColumns#RRULE Events.RRULE}</td> + <td>The recurrence rule for the event.</td> + </tr> + <tr> + <td> + {@link android.provider.CalendarContract.EventsColumns#ACCESS_LEVEL +Events.ACCESS_LEVEL}</td> + + <td>Whether the event is private or public.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#AVAILABILITY +Events.AVAILABILITY}</td> + + <td>If this event counts as busy time or is free time that can be scheduled over.</td> + +</table> +<p>The following sections describe how to use these intents.</p> + + +<h3 id="intent-insert">Using an intent to insert an event</h3> + +<p>Using the {@link android.content.Intent#ACTION_INSERT INSERT} Intent +lets your application hand off the event insertion task to the Calendar itself. +With this approach, your application doesn't even need to have the {@link +android.Manifest.permission#WRITE_CALENDAR} permission included in its <a +href="#manifest">manifest file</a>.</p> + + +<p>When users run an application that uses this approach, the application sends +them to the Calendar to finish adding the event. The {@link +android.content.Intent#ACTION_INSERT INSERT} Intent uses extra fields to +pre-populate a form with the details of the event in the Calendar. Users can +then cancel the event, edit the form as needed, or save the event to their +calendars.</p> + + + +<p>Here is a code snippet that schedules an event on January 19, 2012, that runs +from 7:30 a.m. to 8:30 a.m. Note the following about this code snippet:</p> + +<ul> + <li>It specifies {@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI} + as the Uri.</li> + + <li>It uses the {@link +android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME +CalendarContract.EXTRA_EVENT_BEGIN_TIME} and {@link +android.provider.CalendarContract#EXTRA_EVENT_END_TIME +CalendarContract.EXTRA_EVENT_END_TIME} extra fields to pre-populate the form +with the time of the event. The values for these times must be in UTC milliseconds +from the epoch.</li> + + <li>It uses the {@link android.content.Intent#EXTRA_EMAIL Intent.EXTRA_EMAIL} +extra field to provide a comma-separated list of invitees, specified by email address.</li> + +</ul> +<pre> +Calendar beginTime = Calendar.getInstance(); +beginTime.set(2012, 0, 19, 7, 30); +Calendar endTime = Calendar.getInstance(); +endTime.set(2012, 0, 19, 8, 30); +Intent intent = new Intent(Intent.ACTION_INSERT) + .setData(Events.CONTENT_URI) + .putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, beginTime.getTimeInMillis()) + .putExtra(CalendarContract.EXTRA_EVENT_END_TIME, endTime.getTimeInMillis()) + .putExtra(Events.TITLE, "Yoga") + .putExtra(Events.DESCRIPTION, "Group class") + .putExtra(Events.EVENT_LOCATION, "The gym") + .putExtra(Events.AVAILABILITY, Events.AVAILABILITY_BUSY) + .putExtra(Intent.EXTRA_EMAIL, "rowan@example.com,trevor@example.com"); +startActivity(intent); +</pre> + +<h3 id="intent-edit">Using an intent to edit an event</h3> + +<p>You can update an event directly, as described in <a +href="#update-event">Updating events</a>. But using the {@link +android.content.Intent#ACTION_EDIT EDIT} Intent allows an application that +doesn't have permission to hand off event editing to the Calendar application. +When users finish editing their event in Calendar, they're returned to the +original application.</p> <p>Here is an example of an intent that sets a new +title for a specified event and lets users edit the event in the Calendar.</p> + + +<pre>long eventID = 208; +Uri uri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); +Intent intent = new Intent(Intent.ACTION_EDIT) + .setData(uri) + .putExtra(Events.TITLE, "My New Title"); +startActivity(intent);</pre> + +<h3 id="intent-view">Using intents to view calendar data</h3> +<p>Calender Provider offers two different ways to use the {@link android.content.Intent#ACTION_VIEW VIEW} Intent:</p> +<ul> + <li>To open the Calendar to a particular date.</li> + <li>To view an event.</li> + +</ul> +<p>Here is an example that shows how to open the Calendar to a particular date:</p> +<pre>// A date-time specified in milliseconds since the epoch. +long startMillis; +... +Uri.Builder builder = CalendarContract.CONTENT_URI.buildUpon(); +builder.appendPath("time"); +ContentUris.appendId(builder, startMillis); +Intent intent = new Intent(Intent.ACTION_VIEW) + .setData(builder.build()); +startActivity(intent);</pre> + +<p>Here is an example that shows how to open an event for viewing:</p> +<pre>long eventID = 208; +... +Uri uri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); +Intent intent = new Intent(Intent.ACTION_VIEW) + .setData(uri); +startActivity(intent); +</pre> + + +<h2 id="sync-adapter">Sync Adapters</h2> + + +<p>There are only minor differences in how an application and a sync adapter +access the Calendar Provider:</p> + +<ul> + <li>A sync adapter needs to specify that it's a sync adapter by setting {@link android.provider.CalendarContract#CALLER_IS_SYNCADAPTER} to <code>true</code>.</li> + + + <li>A sync adapter needs to provide an {@link +android.provider.CalendarContract.SyncColumns#ACCOUNT_NAME} and an {@link +android.provider.CalendarContract.SyncColumns#ACCOUNT_TYPE} as query parameters in the URI. </li> + + <li>A sync adapter has write access to more columns than an application or widget. + For example, an application can only modify a few characteristics of a calendar, + such as its name, display name, visibility setting, and whether the calendar is + synced. By comparison, a sync adapter can access not only those columns, but many others, + such as calendar color, time zone, access level, location, and so on. +However, a sync adapter is restricted to the <code>ACCOUNT_NAME</code> and +<code>ACCOUNT_TYPE</code> it specified.</li> </ul> + +<p>Here is a helper method you can use to return a URI for use with a sync adapter:</p> +<pre> static Uri asSyncAdapter(Uri uri, String account, String accountType) { + return uri.buildUpon() + .appendQueryParameter(android.provider.CalendarContract.CALLER_IS_SYNCADAPTER,"true") + .appendQueryParameter(Calendars.ACCOUNT_NAME, account) + .appendQueryParameter(Calendars.ACCOUNT_TYPE, accountType).build(); + } +</pre> +<p>For a sample implementation of a sync adapter (not specifically related to Calendar), see +<a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">SampleSyncAdapter</a>. +</body> +</html> diff --git a/docs/html/guide/topics/providers/content-providers.jd b/docs/html/guide/topics/providers/content-providers.jd index 513886a..95331ce 100644 --- a/docs/html/guide/topics/providers/content-providers.jd +++ b/docs/html/guide/topics/providers/content-providers.jd @@ -19,6 +19,11 @@ page.title=Content Providers <li>{@link android.content.ContentResolver}</li> <li>{@link android.database.Cursor}</li> </ol> + +<h2>See also</h2> +<ol> + <li><a href="{@docRoot}guide/topics/providers/calendar-provider.html">Calendar Provider</a></li> +</ol> </div> </div> @@ -36,6 +41,10 @@ package. You can query these providers for the data they contain (although, for some, you must acquire the proper permission to read the data). </p> +<p class="note"><strong>Note:</strong> Android 4.0 introduces the Calendar +Provider. For more information, see <a +href="{@docRoot}guide/topics/providers/calendar-provider.html">Calendar +Provider</a>.</p> <p> If you want to make your own data public, you have two options: You can create your own content provider (a {@link android.content.ContentProvider} diff --git a/docs/html/guide/topics/resources/drawable-resource.jd b/docs/html/guide/topics/resources/drawable-resource.jd index ed9f990..5218c7e 100644 --- a/docs/html/guide/topics/resources/drawable-resource.jd +++ b/docs/html/guide/topics/resources/drawable-resource.jd @@ -646,6 +646,7 @@ In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> android:state_checkable=["true" | "false"] android:state_checked=["true" | "false"] android:state_enabled=["true" | "false"] + android:state_activated=["true" | "false"] android:state_window_focused=["true" | "false"] /> </selector> </pre> @@ -690,8 +691,8 @@ child of a <code><selector></code> element. <dd><em>Boolean</em>. "true" if this item should be used when the object is pressed (such as when a button is touched/clicked); "false" if this item should be used in the default, non-pressed state.</dd> <dt><code>android:state_focused</code></dt> - <dd><em>Boolean</em>. "true" if this item should be used when the object is focused (such as when a button -is highlighted using the trackball/d-pad); "false" if this item should be used in the default, + <dd><em>Boolean</em>. "true" if this item should be used when the object has input focus +(such as when the user selects a text input); "false" if this item should be used in the default, non-focused state.</dd> <dt><code>android:state_hovered</code></dt> <dd><em>Boolean</em>. "true" if this item should be used when the object is being hovered @@ -699,8 +700,11 @@ by a cursor; "false" if this item should be used in the default, non-hovered sta drawable may be the same drawable used for the "focused" state. <p>Introduced in API level 14.</p></dd> <dt><code>android:state_selected</code></dt> - <dd><em>Boolean</em>. "true" if this item should be used when the object is selected (such as when a -tab is opened); "false" if this item should be used when the object is not selected.</dd> + <dd><em>Boolean</em>. "true" if this item should be used when the object is the current +user selection when navigating with a directional control (such as when navigating through a list +with a d-pad); "false" if this item should be used when the object is not selected. +<p>The selected state is used when focus (<code>android:state_focused</code>) is not sufficient +(such as when list view has focus and an item within it is selected with a d-pad).</p></dd> <dt><code>android:state_checkable</code></dt> <dd><em>Boolean</em>. "true" if this item should be used when the object is checkable; "false" if this item should be used when the object is not checkable. (Only useful if the object can @@ -709,8 +713,14 @@ transition between a checkable and non-checkable widget.)</dd> <dd><em>Boolean</em>. "true" if this item should be used when the object is checked; "false" if it should be used when the object is un-checked.</dd> <dt><code>android:state_enabled</code></dt> - <dd><em>Boolean</em>. "true" if this item should be used when the object is enabled (capable of -receiving touch/click events); "false" if it should be used when the object is disabled.</dd> + <dd><em>Boolean</em>. "true" if this item should be used when the object is enabled +(capable of receiving touch/click events); "false" if it should be used when the object is +disabled.</dd> + <dt><code>android:state_activated</code></dt> + <dd><em>Boolean</em>. "true" if this item should be used when the object is activated as +the persistent selection (such as to "highlight" the previously selected list item in a persistent +navigation view); "false" if it should be used when the object is not activated. +<p>Introduced in API level 11.</p></dd> <dt><code>android:state_window_focused</code></dt> <dd><em>Boolean</em>. "true" if this item should be used when the application window has focus (the application is in the foreground), "false" if this item should be used when the application |