1 page.title=Creating a Content Provider 2 @jd:body 3 <div id="qv-wrapper"> 4 <div id="qv"> 5 6 7 <h2>In this document</h2> 8 <ol> 9 <li> 10 <a href="#DataStorage">Designing Data Storage</a> 11 </li> 12 <li> 13 <a href="#ContentURI">Designing Content URIs</a> 14 </li> 15 <li> 16 <a href="#ContentProvider">Implementing the ContentProvider Class</a> 17 <ol> 18 <li> 19 <a href="#RequiredAccess">Required Methods</a> 20 </li> 21 <li> 22 <a href="#Query">Implementing the query() method</a> 23 </li> 24 <li> 25 <a href="#Insert">Implementing the insert() method</a> 26 </li> 27 <li> 28 <a href="#Delete">Implementing the delete() method</a> 29 </li> 30 <li> 31 <a href="#Update">Implementing the update() method</a> 32 </li> 33 <li> 34 <a href="#OnCreate">Implementing the onCreate() method</a> 35 </li> 36 </ol> 37 </li> 38 <li> 39 <a href="#MIMETypes">Implementing Content Provider MIME Types</a> 40 <ol> 41 <li> 42 <a href="#TableMIMETypes">MIME types for tables</a> 43 </li> 44 <li> 45 <a href="#FileMIMETypes">MIME types for files</a> 46 </li> 47 </ol> 48 </li> 49 <li> 50 <a href="#ContractClass">Implementing a Contract Class</a> 51 </li> 52 <li> 53 <a href="#Permissions">Implementing Content Provider Permissions</a> 54 </li> 55 <li> 56 <a href="#ProviderElement">The <provider> Element</a> 57 </li> 58 <li> 59 <a href="#Intents">Intents and Data Access</a> 60 </li> 61 </ol> 62 <h2>Key classes</h2> 63 <ol> 64 <li> 65 {@link android.content.ContentProvider} 66 </li> 67 <li> 68 {@link android.database.Cursor} 69 </li> 70 <li> 71 {@link android.net.Uri} 72 </li> 73 </ol> 74 <h2>Related Samples</h2> 75 <ol> 76 <li> 77 <a 78 href="{@docRoot}resources/samples/NotePad/index.html"> 79 Note Pad sample application 80 </a> 81 </li> 82 </ol> 83 <h2>See also</h2> 84 <ol> 85 <li> 86 <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> 87 Content Provider Basics</a> 88 </li> 89 <li> 90 <a href="{@docRoot}guide/topics/providers/calendar-provider.html"> 91 Calendar Provider</a> 92 </li> 93 </ol> 94 </div> 95 </div> 96 97 98 <p> 99 A content provider manages access to a central repository of data. You implement a 100 provider as one or more classes in an Android application, along with elements in 101 the manifest file. One of your classes implements a subclass 102 {@link android.content.ContentProvider}, which is the interface between your provider and 103 other applications. Although content providers are meant to make data available to other 104 applications, you may of course have activities in your application that allow the user 105 to query and modify the data managed by your provider. 106 </p> 107 <p> 108 The rest of this topic is a basic list of steps for building a content provider and a list 109 of APIs to use. 110 </p> 111 112 113 <!-- Before You Start Building --> 114 <h2 id="BeforeYouStart">Before You Start Building</h2> 115 <p> 116 Before you start building a provider, do the following: 117 </p> 118 <ol> 119 <li> 120 <strong>Decide if you need a content provider</strong>. You need to build a content 121 provider if you want to provide one or more of the following features: 122 <ul> 123 <li>You want to offer complex data or files to other applications.</li> 124 <li>You want to allow users to copy complex data from your app into other apps.</li> 125 <li>You want to provide custom search suggestions using the search framework.</li> 126 </ul> 127 <p> 128 You <em>don't</em> need a provider to use an SQLite database if the use is entirely within 129 your own application. 130 </p> 131 </li> 132 <li> 133 If you haven't done so already, read the topic 134 <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> 135 Content Provider Basics</a> to learn more about providers. 136 </li> 137 </ol> 138 <p> 139 Next, follow these steps to build your provider: 140 </p> 141 <ol> 142 <li> 143 Design the raw storage for your data. A content provider offers data in two ways: 144 <dl> 145 <dt> 146 File data 147 </dt> 148 <dd> 149 Data that normally goes into files, such as 150 photos, audio, or videos. Store the files in your application's private 151 space. In response to a request for a file from another application, your 152 provider can offer a handle to the file. 153 </dd> 154 <dt> 155 "Structured" data 156 </dt> 157 <dd> 158 Data that normally goes into a database, array, or similar structure. 159 Store the data in a form that's compatible with tables of rows and columns. A row 160 represents an entity, such as a person or an item in inventory. A column represents 161 some data for the entity, such a person's name or an item's price. A common way to 162 store this type of data is in an SQLite database, but you can use any type of 163 persistent storage. To learn more about the storage types available in the 164 Android system, see the section <a href="#DataStorage"> 165 Designing Data Storage</a>. 166 </dd> 167 </dl> 168 </li> 169 <li> 170 Define a concrete implementation of the {@link android.content.ContentProvider} class and 171 its required methods. This class is the interface between your data and the rest of the 172 Android system. For more information about this class, see the section 173 <a href="#ContentProvider">Implementing the ContentProvider Class</a>. 174 </li> 175 <li> 176 Define the provider's authority string, its content URIs, and column names. If you want 177 the provider's application to handle intents, also define intent actions, extras data, 178 and flags. Also define the permissions that you will require for applications that want 179 to access your data. You should consider defining all of these values as constants in a 180 separate contract class; later, you can expose this class to other developers. For more 181 information about content URIs, see the 182 section <a href="#ContentURI">Designing Content URIs</a>. 183 For more information about intents, see the 184 section <a href="#Intents">Intents and Data Access</a>. 185 </li> 186 <li> 187 Add other optional pieces, such as sample data or an implementation 188 of {@link android.content.AbstractThreadedSyncAdapter} that can synchronize data between 189 the provider and cloud-based data. 190 </li> 191 </ol> 192 193 194 <!-- Designing Data Storage --> 195 <h2 id="DataStorage">Designing Data Storage</h2> 196 <p> 197 A content provider is the interface to data saved in a structured format. Before you create 198 the interface, you must decide how to store the data. You can store the data in any form you 199 like, and then design the interface to read and write the data as necessary. 200 </p> 201 <p> 202 These are some of the data storage technologies that are available in Android: 203 </p> 204 <ul> 205 <li> 206 The Android system includes an SQLite database API that Android's own providers use 207 to store table-oriented data. The 208 {@link android.database.sqlite.SQLiteOpenHelper} class helps you create databases, and the 209 {@link android.database.sqlite.SQLiteDatabase} class is the base class for accessing 210 databases. 211 <p> 212 Remember that you don't have to use a database to implement your repository. A provider 213 appears externally as a set of tables, similar to a relational database, but this is 214 not a requirement for the provider's internal implementation. 215 </p> 216 </li> 217 <li> 218 For storing file data, Android has a variety of file-oriented APIs. 219 To learn more about file storage, read the topic 220 <a href="{@docRoot}guide/topics/data/data-storage.html">Data Storage</a>. If you're 221 designing a provider that offers media-related data such as music or videos, you can 222 have a provider that combines table data and files. 223 </li> 224 <li> 225 For working with network-based data, use classes in {@link java.net} and 226 {@link android.net}. You can also synchronize network-based data to a local data 227 store such as a database, and then offer the data as tables or files. 228 The <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> 229 Sample Sync Adapter</a> sample application demonstrates this type of synchronization. 230 </li> 231 </ul> 232 <h3 id="DataDesign"> 233 Data design considerations 234 </h3> 235 <p> 236 Here are some tips for designing your provider's data structure: 237 </p> 238 <ul> 239 <li> 240 Table data should always have a "primary key" column that the provider maintains 241 as a unique numeric value for each row. You can use this value to link the row to related 242 rows in other tables (using it as a "foreign key"). Although you can use any name 243 for this column, using {@link android.provider.BaseColumns#_ID BaseColumns._ID} is the best 244 choice, because linking the results of a provider query to a 245 {@link android.widget.ListView} requires one of the retrieved columns to have the name 246 <code>_ID</code>. 247 </li> 248 <li> 249 If you want to provide bitmap images or other very large pieces of file-oriented data, store 250 the data in a file and then provide it indirectly rather than storing it directly in a 251 table. If you do this, you need to tell users of your provider that they need to use a 252 {@link android.content.ContentResolver} file method to access the data. 253 </li> 254 <li> 255 Use the Binary Large OBject (BLOB) data type to store data that varies in size or has a 256 varying structure. For example, you can use a BLOB column to store a 257 <a href="http://code.google.com/p/protobuf">protocol buffer</a> or 258 <a href="http://www.json.org">JSON structure</a>. 259 <p> 260 You can also use a BLOB to implement a <em>schema-independent</em> table. In 261 this type of table, you define a primary key column, a MIME type column, and one or 262 more generic columns as BLOB. The meaning of the data in the BLOB columns is indicated 263 by the value in the MIME type column. This allows you to store different row types in 264 the same table. The Contacts Provider's "data" table 265 {@link android.provider.ContactsContract.Data} is an example of a schema-independent 266 table. 267 </p> 268 </li> 269 </ul> 270 <!-- Designing Content URIs --> 271 <h2 id="ContentURI">Designing Content URIs</h2> 272 <p> 273 A <strong>content URI</strong> is a URI that identifies data in a provider. Content URIs include 274 the symbolic name of the entire provider (its <strong>authority</strong>) and a 275 name that points to a table or file (a <strong>path</strong>). The optional id part points to 276 an individual row in a table. Every data access method of 277 {@link android.content.ContentProvider} has a content URI as an argument; this allows you to 278 determine the table, row, or file to access. 279 </p> 280 <p> 281 The basics of content URIs are described in the topic 282 <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> 283 Content Provider Basics</a>. 284 </p> 285 <h3>Designing an authority</h3> 286 <p> 287 A provider usually has a single authority, which serves as its Android-internal name. To 288 avoid conflicts with other providers, you should use Internet domain ownership (in reverse) 289 as the basis of your provider authority. Because this recommendation is also true for Android 290 package names, you can define your provider authority as an extension of the name 291 of the package containing the provider. For example, if your Android package name is 292 <code>com.example.<appname></code>, you should give your provider the 293 authority <code>com.example.<appname>.provider</code>. 294 </p> 295 <h3>Designing a path structure</h3> 296 <p> 297 Developers usually create content URIs from the authority by appending paths that point to 298 individual tables. For example, if you have two tables <em>table1</em> and 299 <em>table2</em>, you combine the authority from the previous example to yield the 300 content URIs 301 <code>com.example.<appname>.provider/table1</code> and 302 <code>com.example.<appname>.provider/table2</code>. Paths aren't 303 limited to a single segment, and there doesn't have to be a table for each level of the path. 304 </p> 305 <h3>Handling content URI IDs</h3> 306 <p> 307 By convention, providers offer access to a single row in a table by accepting a content URI 308 with an ID value for the row at the end of the URI. Also by convention, providers match the 309 ID value to the table's <code>_ID</code> column, and perform the requested access against the 310 row that matches. 311 </p> 312 <p> 313 This convention facilitates a common design pattern for apps accessing a provider. The app 314 does a query against the provider and displays the resulting {@link android.database.Cursor} 315 in a {@link android.widget.ListView} using a {@link android.widget.CursorAdapter}. 316 The definition of {@link android.widget.CursorAdapter} requires one of the columns in the 317 {@link android.database.Cursor} to be <code>_ID</code> 318 </p> 319 <p> 320 The user then picks one of the displayed rows from the UI in order to look at or modify the 321 data. The app gets the corresponding row from the {@link android.database.Cursor} backing the 322 {@link android.widget.ListView}, gets the <code>_ID</code> value for this row, appends it to 323 the content URI, and sends the access request to the provider. The provider can then do the 324 query or modification against the exact row the user picked. 325 </p> 326 <h3>Content URI patterns</h3> 327 <p> 328 To help you choose which action to take for an incoming content URI, the provider API includes 329 the convenience class {@link android.content.UriMatcher}, which maps content URI "patterns" to 330 integer values. You can use the integer values in a <code>switch</code> statement that 331 chooses the desired action for the content URI or URIs that match a particular pattern. 332 </p> 333 <p> 334 A content URI pattern matches content URIs using wildcard characters: 335 </p> 336 <ul> 337 <li> 338 <strong><code>*</code>:</strong> Matches a string of any valid characters of any length. 339 </li> 340 <li> 341 <strong><code>#</code>:</strong> Matches a string of numeric characters of any length. 342 </li> 343 </ul> 344 <p> 345 As an example of designing and coding content URI handling, consider a provider with the 346 authority <code>com.example.app.provider</code> that recognizes the following content URIs 347 pointing to tables: 348 </p> 349 <ul> 350 <li> 351 <code>content://com.example.app.provider/table1</code>: A table called <code>table1</code>. 352 </li> 353 <li> 354 <code>content://com.example.app.provider/table2/dataset1</code>: A table called 355 <code>dataset1</code>. 356 </li> 357 <li> 358 <code>content://com.example.app.provider/table2/dataset2</code>: A table called 359 <code>dataset2</code>. 360 </li> 361 <li> 362 <code>content://com.example.app.provider/table3</code>: A table called <code>table3</code>. 363 </li> 364 </ul> 365 <p> 366 The provider also recognizes these content URIs if they have a row ID appended to them, as 367 for example <code>content://com.example.app.provider/table3/1</code> for the row identified by 368 <code>1</code> in <code>table3</code>. 369 </p> 370 <p> 371 The following content URI patterns would be possible: 372 </p> 373 <dl> 374 <dt> 375 <code>content://com.example.app.provider/*</code> 376 </dt> 377 <dd> 378 Matches any content URI in the provider. 379 </dd> 380 <dt> 381 <code>content://com.example.app.provider/table2/*</code>: 382 </dt> 383 <dd> 384 Matches a content URI for the tables <code>dataset1</code> 385 and <code>dataset2</code>, but doesn't match content URIs for <code>table1</code> or 386 <code>table3</code>. 387 </dd> 388 <dt> 389 <code>content://com.example.app.provider/table3/#</code>: Matches a content URI 390 for single rows in <code>table3</code>, such as 391 <code>content://com.example.app.provider/table3/6</code> for the row identified by 392 <code>6</code>. 393 </dt> 394 </dl> 395 <p> 396 The following code snippet shows how the methods in {@link android.content.UriMatcher} work. 397 This code handles URIs for an entire table differently from URIs for a 398 single row, by using the content URI pattern 399 <code>content://<authority>/<path></code> for tables, and 400 <code>content://<authority>/<path>/<id></code> for single rows. 401 </p> 402 <p> 403 The method {@link android.content.UriMatcher#addURI(String, String, int) addURI()} maps an 404 authority and path to an integer value. The method {@link android.content.UriMatcher#match(Uri) 405 match()} returns the integer value for a URI. A <code>switch</code> statement 406 chooses between querying the entire table, and querying for a single record: 407 </p> 408 <pre class="prettyprint"> 409 public class ExampleProvider extends ContentProvider { 410 ... 411 // Creates a UriMatcher object. 412 private static final UriMatcher sUriMatcher; 413 ... 414 /* 415 * The calls to addURI() go here, for all of the content URI patterns that the provider 416 * should recognize. For this snippet, only the calls for table 3 are shown. 417 */ 418 ... 419 /* 420 * Sets the integer value for multiple rows in table 3 to 1. Notice that no wildcard is used 421 * in the path 422 */ 423 sUriMatcher.addURI("com.example.app.provider", "table3", 1); 424 425 /* 426 * Sets the code for a single row to 2. In this case, the "#" wildcard is 427 * used. "content://com.example.app.provider/table3/3" matches, but 428 * "content://com.example.app.provider/table3 doesn't. 429 */ 430 sUriMatcher.addURI("com.example.app.provider", "table3/#", 2); 431 ... 432 // Implements ContentProvider.query() 433 public Cursor query( 434 Uri uri, 435 String[] projection, 436 String selection, 437 String[] selectionArgs, 438 String sortOrder) { 439 ... 440 /* 441 * Choose the table to query and a sort order based on the code returned for the incoming 442 * URI. Here, too, only the statements for table 3 are shown. 443 */ 444 switch (sUriMatcher.match(uri)) { 445 446 447 // If the incoming URI was for all of table3 448 case 1: 449 450 if (TextUtils.isEmpty(sortOrder)) sortOrder = "_ID ASC"; 451 break; 452 453 // If the incoming URI was for a single row 454 case 2: 455 456 /* 457 * Because this URI was for a single row, the _ID value part is 458 * present. Get the last path segment from the URI; this is the _ID value. 459 * Then, append the value to the WHERE clause for the query 460 */ 461 selection = selection + "_ID = " uri.getLastPathSegment(); 462 break; 463 464 default: 465 ... 466 // If the URI is not recognized, you should do some error handling here. 467 } 468 // call the code to actually do the query 469 } 470 </pre> 471 <p> 472 Another class, {@link android.content.ContentUris}, provides convenience methods for working 473 with the <code>id</code> part of content URIs. The classes {@link android.net.Uri} and 474 {@link android.net.Uri.Builder} include convenience methods for parsing existing 475 {@link android.net.Uri} objects and building new ones. 476 </p> 477 478 <!-- Implementing the ContentProvider class --> 479 <h2 id="ContentProvider">Implementing the ContentProvider Class</h2> 480 <p> 481 The {@link android.content.ContentProvider} instance manages access 482 to a structured set of data by handling requests from other applications. All forms 483 of access eventually call {@link android.content.ContentResolver}, which then calls a concrete 484 method of {@link android.content.ContentProvider} to get access. 485 </p> 486 <h3 id="RequiredAccess">Required methods</h3> 487 <p> 488 The abstract class {@link android.content.ContentProvider} defines six abstract methods that 489 you must implement as part of your own concrete subclass. All of these methods except 490 {@link android.content.ContentProvider#onCreate() onCreate()} are called by a client application 491 that is attempting to access your content provider: 492 </p> 493 <dl> 494 <dt> 495 {@link android.content.ContentProvider#query(Uri, String[], String, String[], String) 496 query()} 497 </dt> 498 <dd> 499 Retrieve data from your provider. Use the arguments to select the table to 500 query, the rows and columns to return, and the sort order of the result. 501 Return the data as a {@link android.database.Cursor} object. 502 </dd> 503 <dt> 504 {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()} 505 </dt> 506 <dd> 507 Insert a new row into your provider. Use the arguments to select the 508 destination table and to get the column values to use. Return a content URI for the 509 newly-inserted row. 510 </dd> 511 <dt> 512 {@link android.content.ContentProvider#update(Uri, ContentValues, String, String[]) 513 update()} 514 </dt> 515 <dd> 516 Update existing rows in your provider. Use the arguments to select the table and rows 517 to update and to get the updated column values. Return the number of rows updated. 518 </dd> 519 <dt> 520 {@link android.content.ContentProvider#delete(Uri, String, String[]) delete()} 521 </dt> 522 <dd> 523 Delete rows from your provider. Use the arguments to select the table and the rows to 524 delete. Return the number of rows deleted. 525 </dd> 526 <dt> 527 {@link android.content.ContentProvider#getType(Uri) getType()} 528 </dt> 529 <dd> 530 Return the MIME type corresponding to a content URI. This method is described in more 531 detail in the section <a href="#MIMETypes">Implementing Content Provider MIME Types</a>. 532 </dd> 533 <dt> 534 {@link android.content.ContentProvider#onCreate() onCreate()} 535 </dt> 536 <dd> 537 Initialize your provider. The Android system calls this method immediately after it 538 creates your provider. Notice that your provider is not created until a 539 {@link android.content.ContentResolver} object tries to access it. 540 </dd> 541 </dl> 542 <p> 543 Notice that these methods have the same signature as the identically-named 544 {@link android.content.ContentResolver} methods. 545 </p> 546 <p> 547 Your implementation of these methods should account for the following: 548 </p> 549 <ul> 550 <li> 551 All of these methods except {@link android.content.ContentProvider#onCreate() onCreate()} 552 can be called by multiple threads at once, so they must be thread-safe. To learn 553 more about multiple threads, see the topic 554 <a href="{@docRoot}guide/components/processes-and-threads.html"> 555 Processes and Threads</a>. 556 </li> 557 <li> 558 Avoid doing lengthy operations in {@link android.content.ContentProvider#onCreate() 559 onCreate()}. Defer initialization tasks until they are actually needed. 560 The section <a href="#OnCreate">Implementing the onCreate() method</a> 561 discusses this in more detail. 562 </li> 563 <li> 564 Although you must implement these methods, your code does not have to do anything except 565 return the expected data type. For example, you may want to prevent other applications 566 from inserting data into some tables. To do this, you can ignore the call to 567 {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()} and return 568 0. 569 </li> 570 </ul> 571 <h3 id="Query">Implementing the query() method</h3> 572 <p> 573 The 574 {@link android.content.ContentProvider#query(Uri, String[], String, String[], String) 575 ContentProvider.query()} method must return a {@link android.database.Cursor} object, or if it 576 fails, throw an {@link java.lang.Exception}. If you are using an SQLite database as your data 577 storage, you can simply return the {@link android.database.Cursor} returned by one of the 578 <code>query()</code> methods of the {@link android.database.sqlite.SQLiteDatabase} class. 579 If the query does not match any rows, you should return a {@link android.database.Cursor} 580 instance whose {@link android.database.Cursor#getCount()} method returns 0. 581 You should return <code>null</code> only if an internal error occurred during the query process. 582 </p> 583 <p> 584 If you aren't using an SQLite database as your data storage, use one of the concrete subclasses 585 of {@link android.database.Cursor}. For example, the {@link android.database.MatrixCursor} class 586 implements a cursor in which each row is an array of {@link java.lang.Object}. With this class, 587 use {@link android.database.MatrixCursor#addRow(Object[]) addRow()} to add a new row. 588 </p> 589 <p> 590 Remember that the Android system must be able to communicate the {@link java.lang.Exception} 591 across process boundaries. Android can do this for the following exceptions that may be useful 592 in handling query errors: 593 </p> 594 <ul> 595 <li> 596 {@link java.lang.IllegalArgumentException} (You may choose to throw this if your provider 597 receives an invalid content URI) 598 </li> 599 <li> 600 {@link java.lang.NullPointerException} 601 </li> 602 </ul> 603 <h3 id="Insert">Implementing the insert() method</h3> 604 <p> 605 The {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()} method adds a 606 new row to the appropriate table, using the values in the {@link android.content.ContentValues} 607 argument. If a column name is not in the {@link android.content.ContentValues} argument, you 608 may want to provide a default value for it either in your provider code or in your database 609 schema. 610 </p> 611 <p> 612 This method should return the content URI for the new row. To construct this, append the new 613 row's <code>_ID</code> (or other primary key) value to the table's content URI, using 614 {@link android.content.ContentUris#withAppendedId(Uri, long) withAppendedId()}. 615 </p> 616 <h3 id="Delete">Implementing the delete() method</h3> 617 <p> 618 The {@link android.content.ContentProvider#delete(Uri, String, String[]) delete()} method 619 does not have to physically delete rows from your data storage. If you are using a sync adapter 620 with your provider, you should consider marking a deleted row 621 with a "delete" flag rather than removing the row entirely. The sync adapter can 622 check for deleted rows and remove them from the server before deleting them from the provider. 623 </p> 624 <h3 id="Update">Implementing the update() method</h3> 625 <p> 626 The {@link android.content.ContentProvider#update(Uri, ContentValues, String, String[]) 627 update()} method takes the same {@link android.content.ContentValues} argument used by 628 {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()}, and the 629 same <code>selection</code> and <code>selectionArgs</code> arguments used by 630 {@link android.content.ContentProvider#delete(Uri, String, String[]) delete()} and 631 {@link android.content.ContentProvider#query(Uri, String[], String, String[], String) 632 ContentProvider.query()}. This may allow you to re-use code between these methods. 633 </p> 634 <h3 id="OnCreate">Implementing the onCreate() method</h3> 635 <p> 636 The Android system calls {@link android.content.ContentProvider#onCreate() 637 onCreate()} when it starts up the provider. You should perform only fast-running initialization 638 tasks in this method, and defer database creation and data loading until the provider actually 639 receives a request for the data. If you do lengthy tasks in 640 {@link android.content.ContentProvider#onCreate() onCreate()}, you will slow down your 641 provider's startup. In turn, this will slow down the response from the provider to other 642 applications. 643 </p> 644 <p> 645 For example, if you are using an SQLite database you can create 646 a new {@link android.database.sqlite.SQLiteOpenHelper} object in 647 {@link android.content.ContentProvider#onCreate() ContentProvider.onCreate()}, 648 and then create the SQL tables the first time you open the database. To facilitate this, the 649 first time you call {@link android.database.sqlite.SQLiteOpenHelper#getWritableDatabase 650 getWritableDatabase()}, it automatically calls the 651 {@link android.database.sqlite.SQLiteOpenHelper#onCreate(SQLiteDatabase) 652 SQLiteOpenHelper.onCreate()} method. 653 </p> 654 <p> 655 The following two snippets demonstrate the interaction between 656 {@link android.content.ContentProvider#onCreate() ContentProvider.onCreate()} and 657 {@link android.database.sqlite.SQLiteOpenHelper#onCreate(SQLiteDatabase) 658 SQLiteOpenHelper.onCreate()}. The first snippet is the implementation of 659 {@link android.content.ContentProvider#onCreate() ContentProvider.onCreate()}: 660 </p> 661 <pre class="prettyprint"> 662 public class ExampleProvider extends ContentProvider 663 664 /* 665 * Defines a handle to the database helper object. The MainDatabaseHelper class is defined 666 * in a following snippet. 667 */ 668 private MainDatabaseHelper mOpenHelper; 669 670 // Defines the database name 671 private static final String DBNAME = "mydb"; 672 673 // Holds the database object 674 private SQLiteDatabase db; 675 676 public boolean onCreate() { 677 678 /* 679 * Creates a new helper object. This method always returns quickly. 680 * Notice that the database itself isn't created or opened 681 * until SQLiteOpenHelper.getWritableDatabase is called 682 */ 683 mOpenHelper = new MainDatabaseHelper( 684 getContext(), // the application context 685 DBNAME, // the name of the database) 686 null, // uses the default SQLite cursor 687 1 // the version number 688 ); 689 690 return true; 691 } 692 693 ... 694 695 // Implements the provider's insert method 696 public Cursor insert(Uri uri, ContentValues values) { 697 // Insert code here to determine which table to open, handle error-checking, and so forth 698 699 ... 700 701 /* 702 * Gets a writeable database. This will trigger its creation if it doesn't already exist. 703 * 704 */ 705 db = mOpenHelper.getWritableDatabase(); 706 } 707 } 708 </pre> 709 <p> 710 The next snippet is the implementation of 711 {@link android.database.sqlite.SQLiteOpenHelper#onCreate(SQLiteDatabase) 712 SQLiteOpenHelper.onCreate()}, including a helper class: 713 </p> 714 <pre class="prettyprint"> 715 ... 716 // A string that defines the SQL statement for creating a table 717 private static final String SQL_CREATE_MAIN = "CREATE TABLE " + 718 "main " + // Table's name 719 "(" + // The columns in the table 720 " _ID INTEGER PRIMARY KEY, " + 721 " WORD TEXT" 722 " FREQUENCY INTEGER " + 723 " LOCALE TEXT )"; 724 ... 725 /** 726 * Helper class that actually creates and manages the provider's underlying data repository. 727 */ 728 protected static final class MainDatabaseHelper extends SQLiteOpenHelper { 729 730 /* 731 * Instantiates an open helper for the provider's SQLite data repository 732 * Do not do database creation and upgrade here. 733 */ 734 MainDatabaseHelper(Context context) { 735 super(context, DBNAME, null, 1); 736 } 737 738 /* 739 * Creates the data repository. This is called when the provider attempts to open the 740 * repository and SQLite reports that it doesn't exist. 741 */ 742 public void onCreate(SQLiteDatabase db) { 743 744 // Creates the main table 745 db.execSQL(SQL_CREATE_MAIN); 746 } 747 } 748 </pre> 749 750 751 <!-- Implementing ContentProvider MIME Types --> 752 <h2 id="MIMETypes">Implementing ContentProvider MIME Types</h2> 753 <p> 754 The {@link android.content.ContentProvider} class has two methods for returning MIME types: 755 </p> 756 <dl> 757 <dt> 758 {@link android.content.ContentProvider#getType(Uri) getType()} 759 </dt> 760 <dd> 761 One of the required methods that you must implement for any provider. 762 </dd> 763 <dt> 764 {@link android.content.ContentProvider#getStreamTypes(Uri, String) getStreamTypes()} 765 </dt> 766 <dd> 767 A method that you're expected to implement if your provider offers files. 768 </dd> 769 </dl> 770 <h3 id="TableMIMETypes">MIME types for tables</h3> 771 <p> 772 The {@link android.content.ContentProvider#getType(Uri) getType()} method returns a 773 {@link java.lang.String} in MIME format that describes the type of data returned by the content 774 URI argument. The {@link android.net.Uri} argument can be a pattern rather than a specific URI; 775 in this case, you should return the type of data associated with content URIs that match the 776 pattern. 777 </p> 778 <p> 779 For common types of data such as as text, HTML, or JPEG, 780 {@link android.content.ContentProvider#getType(Uri) getType()} should return the standard 781 MIME type for that data. A full list of these standard types is available on the 782 <a href="http://www.iana.org/assignments/media-types/index.htm">IANA MIME Media Types</a> 783 website. 784 </p> 785 <p> 786 For content URIs that point to a row or rows of table data, 787 {@link android.content.ContentProvider#getType(Uri) getType()} should return 788 a MIME type in Android's vendor-specific MIME format: 789 </p> 790 <ul> 791 <li> 792 Type part: <code>vnd</code> 793 </li> 794 <li> 795 Subtype part: 796 <ul> 797 <li> 798 If the URI pattern is for a single row: <code>android.cursor.<strong>item</strong>/</code> 799 </li> 800 <li> 801 If the URI pattern is for more than one row: <code>android.cursor.<strong>dir</strong>/</code> 802 </li> 803 </ul> 804 </li> 805 <li> 806 Provider-specific part: <code>vnd.<name></code>.<code><type></code> 807 <p> 808 You supply the <code><name></code> and <code><type></code>. 809 The <code><name></code> value should be globally unique, 810 and the <code><type></code> value should be unique to the corresponding URI 811 pattern. A good choice for <code><name></code> is your company's name or 812 some part of your application's Android package name. A good choice for the 813 <code><type></code> is a string that identifies the table associated with the 814 URI. 815 </p> 816 817 </li> 818 </ul> 819 <p> 820 For example, if a provider's authority is 821 <code>com.example.app.provider</code>, and it exposes a table named 822 <code>table1</code>, the MIME type for multiple rows in <code>table1</code> is: 823 </p> 824 <pre> 825 vnd.android.cursor.<strong>dir</strong>/vnd.com.example.provider.table1 826 </pre> 827 <p> 828 For a single row of <code>table1</code>, the MIME type is: 829 </p> 830 <pre> 831 vnd.android.cursor.<strong>item</strong>/vnd.com.example.provider.table1 832 </pre> 833 <h3 id="FileMIMETypes">MIME types for files</h3> 834 <p> 835 If your provider offers files, implement 836 {@link android.content.ContentProvider#getStreamTypes(Uri, String) getStreamTypes()}. 837 The method returns a {@link java.lang.String} array of MIME types for the files your provider 838 can return for a given content URI. You should filter the MIME types you offer by the MIME type 839 filter argument, so that you return only those MIME types that the client wants to handle. 840 </p> 841 <p> 842 For example, consider a provider that offers photo images as files in <code>.jpg</code>, 843 <code>.png</code>, and <code>.gif</code> format. 844 If an application calls {@link android.content.ContentResolver#getStreamTypes(Uri, String) 845 ContentResolver.getStreamTypes()} with the filter string <code>image/*</code> (something that 846 is an "image"), 847 then the {@link android.content.ContentProvider#getStreamTypes(Uri, String) 848 ContentProvider.getStreamTypes()} method should return the array: 849 </p> 850 <pre> 851 { "image/jpeg", "image/png", "image/gif"} 852 </pre> 853 <p> 854 If the app is only interested in <code>.jpg</code> files, then it can call 855 {@link android.content.ContentResolver#getStreamTypes(Uri, String) 856 ContentResolver.getStreamTypes()} with the filter string <code>*\/jpeg</code>, and 857 {@link android.content.ContentProvider#getStreamTypes(Uri, String) 858 ContentProvider.getStreamTypes()} should return: 859 <pre> 860 {"image/jpeg"} 861 </pre> 862 <p> 863 If your provider doesn't offer any of the MIME types requested in the filter string, 864 {@link android.content.ContentProvider#getStreamTypes(Uri, String) getStreamTypes()} 865 should return <code>null</code>. 866 </p> 867 868 869 <!-- Implementing a Contract Class --> 870 <h2 id="ContractClass">Implementing a Contract Class</h2> 871 <p> 872 A contract class is a <code>public final</code> class that contains constant definitions for the 873 URIs, column names, MIME types, and other meta-data that pertain to the provider. The class 874 establishes a contract between the provider and other applications by ensuring that the provider 875 can be correctly accessed even if there are changes to the actual values of URIs, column names, 876 and so forth. 877 </p> 878 <p> 879 A contract class also helps developers because it usually has mnemonic names for its constants, 880 so developers are less likely to use incorrect values for column names or URIs. Since it's a 881 class, it can contain Javadoc documentation. Integrated development environments such as 882 Eclipse can auto-complete constant names from the contract class and display Javadoc for the 883 constants. 884 </p> 885 <p> 886 Developers can't access the contract class's class file from your application, but they can 887 statically compile it into their application from a <code>.jar</code> file you provide. 888 </p> 889 <p> 890 The {@link android.provider.ContactsContract} class and its nested classes are examples of 891 contract classes. 892 </p> 893 <h2 id="Permissions">Implementing Content Provider Permissions</h2> 894 <p> 895 Permissions and access for all aspects of the Android system are described in detail in the 896 topic <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>. 897 The topic <a href="{@docRoot}guide/topics/data/data-storage.html">Data Storage</a> also 898 described the security and permissions in effect for various types of storage. 899 In brief, the important points are: 900 </p> 901 <ul> 902 <li> 903 By default, data files stored on the device's internal storage are private to your 904 application and provider. 905 </li> 906 <li> 907 {@link android.database.sqlite.SQLiteDatabase} databases you create are private to your 908 application and provider. 909 </li> 910 <li> 911 By default, data files that you save to external storage are <em>public</em> and 912 <em>world-readable</em>. You can't use a content provider to restrict access to files in 913 external storage, because other applications can use other API calls to read and write them. 914 </li> 915 <li> 916 The method calls for opening or creating files or SQLite databases on your device's internal 917 storage can potentially give both read and write access to all other applications. If you 918 use an internal file or database as your provider's repository, and you give it 919 "world-readable" or "world-writeable" access, the permissions you set for your provider in 920 its manifest won't protect your data. The default access for files and databases in 921 internal storage is "private", and for your provider's repository you shouldn't change this. 922 </li> 923 </ul> 924 <p> 925 If you want to use content provider permissions to control access to your data, then you should 926 store your data in internal files, SQLite databases, or the "cloud" (for example, 927 on a remote server), and you should keep files and databases private to your application. 928 </p> 929 <h3>Implementing permissions</h3> 930 <p> 931 All applications can read from or write to your provider, even if the underlying data is 932 private, because by default your provider does not have permissions set. To change this, 933 set permissions for your provider in your manifest file, using attributes or child 934 elements of the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> 935 <provider></a></code> element. You can set permissions that apply to the entire provider, 936 or to certain tables, or even to certain records, or all three. 937 </p> 938 <p> 939 You define permissions for your provider with one or more 940 <code><a href="{@docRoot}guide/topics/manifest/permission-element.html"> 941 <permission></a></code> elements in your manifest file. To make the 942 permission unique to your provider, use Java-style scoping for the 943 <code><a href="{@docRoot}guide/topics/manifest/permission-element.html#nm"> 944 android:name</a></code> attribute. For example, name the read permission 945 <code>com.example.app.provider.permission.READ_PROVIDER</code>. 946 947 </p> 948 <p> 949 The following list describes the scope of provider permissions, starting with the 950 permissions that apply to the entire provider and then becoming more fine-grained. 951 More fine-grained permissions take precedence over ones with larger scope: 952 </p> 953 <dl> 954 <dt> 955 Single read-write provider-level permission 956 </dt> 957 <dd> 958 One permission that controls both read and write access to the entire provider, specified 959 with the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn"> 960 android:permission</a></code> attribute of the 961 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> 962 <provider></a></code> element. 963 </dd> 964 <dt> 965 Separate read and write provider-level permission 966 </dt> 967 <dd> 968 A read permission and a write permission for the entire provider. You specify them 969 with the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn"> 970 android:readPermission</a></code> and 971 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn"> 972 android:writePermission</a></code> attributes of the 973 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> 974 <provider></a></code> element. They take precedence over the permission required by 975 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn"> 976 android:permission</a></code>. 977 </dd> 978 <dt> 979 Path-level permission 980 </dt> 981 <dd> 982 Read, write, or read/write permission for a content URI in your provider. You specify 983 each URI you want to control with a 984 <code><a href="{@docRoot}guide/topics/manifest/path-permission-element.html"> 985 <path-permission></a></code> child element of the 986 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> 987 <provider></a></code> element. For each content URI you specify, you can specify a 988 read/write permission, a read permission, or a write permission, or all three. The read and 989 write permissions take precedence over the read/write permission. Also, path-level 990 permission takes precedence over provider-level permissions. 991 </dd> 992 <dt> 993 Temporary permission 994 </dt> 995 <dd> 996 A permission level that grants temporary access to an application, even if the application 997 doesn't have the permissions that are normally required. The temporary 998 access feature reduces the number of permissions an application has to request in 999 its manifest. When you turn on temporary permissions, the only applications that need 1000 "permanent" permissions for your provider are ones that continually access all 1001 your data. 1002 <p> 1003 Consider the permissions you need to implement an email provider and app, when you 1004 want to allow an outside image viewer application to display photo attachments from your 1005 provider. To give the image viewer the necessary access without requiring permissions, 1006 set up temporary permissions for content URIs for photos. Design your email app so 1007 that when the user wants to display a photo, the app sends an intent containing the 1008 photo's content URI and permission flags to the image viewer. The image viewer can 1009 then query your email provider to retrieve the photo, even though the viewer doesn't 1010 have the normal read permission for your provider. 1011 </p> 1012 <p> 1013 To turn on temporary permissions, either set the 1014 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn"> 1015 android:grantUriPermissions</a></code> attribute of the 1016 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> 1017 <provider></a></code> element, or add one or more 1018 <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"> 1019 <grant-uri-permission></a></code> child elements to your 1020 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> 1021 <provider></a></code> element. If you use temporary permissions, you have to call 1022 {@link android.content.Context#revokeUriPermission(Uri, int) 1023 Context.revokeUriPermission()} whenever you remove support for a content URI from your 1024 provider, and the content URI is associated with a temporary permission. 1025 </p> 1026 <p> 1027 The attribute's value determines how much of your provider is made accessible. 1028 If the attribute is set to <code>true</code>, then the system will grant temporary 1029 permission to your entire provider, overriding any other permissions that are required 1030 by your provider-level or path-level permissions. 1031 </p> 1032 <p> 1033 If this flag is set to <code>false</code>, then you must add 1034 <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"> 1035 <grant-uri-permission></a></code> child elements to your 1036 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> 1037 <provider></a></code> element. Each child element specifies the content URI or 1038 URIs for which temporary access is granted. 1039 </p> 1040 <p> 1041 To delegate temporary access to an application, an intent must contain 1042 the {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION} or the 1043 {@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION} flags, or both. These 1044 are set with the {@link android.content.Intent#setFlags(int) setFlags()} method. 1045 </p> 1046 <p> 1047 If the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn"> 1048 android:grantUriPermissions</a></code> attribute is not present, it's assumed to be 1049 <code>false</code>. 1050 </p> 1051 </dd> 1052 </dl> 1053 1054 1055 1056 <!-- The Provider Element --> 1057 <h2 id="ProviderElement">The <provider> Element</h2> 1058 <p> 1059 Like {@link android.app.Activity} and {@link android.app.Service} components, 1060 a subclass of {@link android.content.ContentProvider} 1061 must be defined in the manifest file for its application, using the 1062 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> 1063 <provider></a></code> element. The Android system gets the following information from 1064 the element: 1065 <dl> 1066 <dt> 1067 Authority 1068 (<a href="{@docRoot}guide/topics/manifest/provider-element.html#auth">{@code 1069 android:authorities}</a>) 1070 </dt> 1071 <dd> 1072 Symbolic names that identify the entire provider within the system. This 1073 attribute is described in more detail in the section 1074 <a href="#ContentURI">Designing Content URIs</a>. 1075 </dd> 1076 <dt> 1077 Provider class name 1078 (<code> 1079 <a href="{@docRoot}guide/topics/manifest/provider-element.html#nm">android:name</a> 1080 </code>) 1081 </dt> 1082 <dd> 1083 The class that implements {@link android.content.ContentProvider}. This class is 1084 described in more detail in the section 1085 <a href="#ContentProvider">Implementing the ContentProvider Class</a>. 1086 </dd> 1087 <dt> 1088 Permissions 1089 </dt> 1090 <dd> 1091 Attributes that specify the permissions that other applications must have in order to access 1092 the provider's data: 1093 <ul> 1094 <li> 1095 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn"> 1096 android:grantUriPermssions</a></code>: Temporary permission flag. 1097 </li> 1098 <li> 1099 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn"> 1100 android:permission</a></code>: Single provider-wide read/write permission. 1101 </li> 1102 <li> 1103 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn"> 1104 android:readPermission</a></code>: Provider-wide read permission. 1105 </li> 1106 <li> 1107 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn"> 1108 android:writePermission</a></code>: Provider-wide write permission. 1109 </li> 1110 </ul> 1111 <p> 1112 Permissions and their corresponding attributes are described in more 1113 detail in the section 1114 <a href="#Permissions">Implementing Content Provider Permissions</a>. 1115 </p> 1116 </dd> 1117 <dt> 1118 Startup and control attributes 1119 </dt> 1120 <dd> 1121 These attributes determine how and when the Android system starts the provider, the 1122 process characteristics of the provider, and other run-time settings: 1123 <ul> 1124 <li> 1125 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#enabled"> 1126 android:enabled</a></code>: Flag allowing the system to start the provider. 1127 </li> 1128 <li> 1129 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#exported"> 1130 android:exported</a></code>: Flag allowing other applications to use this provider. 1131 </li> 1132 <li> 1133 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#init"> 1134 android:initOrder</a></code>: The order in which this provider should be started, 1135 relative to other providers in the same process. 1136 </li> 1137 <li> 1138 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#multi"> 1139 android:multiProcess</a></code>: Flag allowing the system to start the provider 1140 in the same process as the calling client. 1141 </li> 1142 <li> 1143 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#proc"> 1144 android:process</a></code>: The name of the process in which the provider should 1145 run. 1146 </li> 1147 <li> 1148 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#sync"> 1149 android:syncable</a></code>: Flag indicating that the provider's data is to be 1150 sync'ed with data on a server. 1151 </li> 1152 </ul> 1153 <p> 1154 The attributes are fully documented in the dev guide topic for the 1155 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> 1156 <provider></a></code> 1157 element. 1158 </p> 1159 </dd> 1160 <dt> 1161 Informational attributes 1162 </dt> 1163 <dd> 1164 An optional icon and label for the provider: 1165 <ul> 1166 <li> 1167 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#icon"> 1168 android:icon</a></code>: A drawable resource containing an icon for the provider. 1169 The icon appears next to the provider's label in the list of apps in 1170 <em>Settings</em> > <em>Apps</em> > <em>All</em>. 1171 </li> 1172 <li> 1173 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#label"> 1174 android:label</a></code>: An informational label describing the provider or its 1175 data, or both. The label appears in the list of apps in 1176 <em>Settings</em> > <em>Apps</em> > <em>All</em>. 1177 </li> 1178 </ul> 1179 <p> 1180 The attributes are fully documented in the dev guide topic for the 1181 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> 1182 <provider></a></code> element. 1183 </p> 1184 </dd> 1185 </dl> 1186 1187 <!-- Intent Access --> 1188 <h2 id="Intents">Intents and Data Access</h2> 1189 <p> 1190 Applications can access a content provider indirectly with an {@link android.content.Intent}. 1191 The application does not call any of the methods of {@link android.content.ContentResolver} or 1192 {@link android.content.ContentProvider}. Instead, it sends an intent that starts an activity, 1193 which is often part of the provider's own application. The destination activity is in charge of 1194 retrieving and displaying the data in its UI. Depending on the action in the intent, the 1195 destination activity may also prompt the user to make modifications to the provider's data. 1196 An intent may also contain "extras" data that the destination activity displays 1197 in the UI; the user then has the option of changing this data before using it to modify the 1198 data in the provider. 1199 </p> 1200 <p> 1201 1202 </p> 1203 <p> 1204 You may want to use intent access to help ensure data integrity. Your provider may depend 1205 on having data inserted, updated, and deleted according to strictly defined business logic. If 1206 this is the case, allowing other applications to directly modify your data may lead to 1207 invalid data. If you want developers to use intent access, be sure to document it thoroughly. 1208 Explain to them why intent access using your own application's UI is better than trying to 1209 modify the data with their code. 1210 </p> 1211 <p> 1212 Handling an incoming intent that wishes to modify your provider's data is no different from 1213 handling other intents. You can learn more about using intents by reading the topic 1214 <a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>. 1215 </p> 1216
