ContentProvider：数据共享

// ContentProvider 的六大核心抽象方法（必须由子类实现）
abstract class ContentProvider {
 
    // 初始化方法，在 Provider 被系统首次加载时调用
    // 返回 true 表示初始化成功
    abstract fun onCreate(): Boolean
 
    // 查询操作：根据 URI 和条件返回一个 Cursor（结果集）
    // uri: 要查询的数据资源标识
    // projection: 需要返回的列名数组（类似 SQL 的 SELECT 列列表）
    // selection: 筛选条件（类似 SQL 的 WHERE 子句）
    // selectionArgs: 筛选条件中占位符的值
    // sortOrder: 排序规则（类似 SQL 的 ORDER BY）
    abstract fun query(
        uri: Uri,                    // 定位到哪张"表"或哪条记录
        projection: Array<String>?,  // 要返回哪些"列"
        selection: String?,          // 过滤条件模板
        selectionArgs: Array<String>?, // 过滤条件参数
        sortOrder: String?           // 排序规则
    ): Cursor?
 
    // 插入操作：向指定 URI 对应的集合中插入一条新数据
    // 返回新插入数据的 URI（通常包含新生成的 ID）
    abstract fun insert(
        uri: Uri,                    // 定位到目标"表"
        values: ContentValues?       // 要插入的键值对数据
    ): Uri?
 
    // 更新操作：更新符合条件的数据行
    // 返回受影响的行数
    abstract fun update(
        uri: Uri,                    // 定位到目标"表"或特定记录
        values: ContentValues?,      // 需要更新的键值对
        selection: String?,          // 过滤条件
        selectionArgs: Array<String>? // 过滤条件参数
    ): Int
 
    // 删除操作：删除符合条件的数据行
    // 返回被删除的行数
    abstract fun delete(
        uri: Uri,                    // 定位到目标"表"或特定记录
        selection: String?,          // 过滤条件
        selectionArgs: Array<String>? // 过滤条件参数
    ): Int
 
    // 返回指定 URI 对应的 MIME 类型
    // 用于标识数据是单条记录还是记录集合，以及数据的具体类型
    abstract fun getType(uri: Uri): String?
}

// 客户端代码：通过 ContentResolver 读取通讯录中所有联系人的姓名
// 注意：客户端完全不需要知道联系人数据存储在哪个数据库、什么表结构
 
// 获取 ContentResolver 实例（每个 Context 都可以获取）
val resolver: ContentResolver = context.contentResolver
 
// 定义要查询的 Content URI（指向系统通讯录的联系人集合）
val uri: Uri = ContactsContract.Contacts.CONTENT_URI
 
// 定义只需要返回的列（投影）——这里只要显示名称
val projection: Array<String> = arrayOf(
    ContactsContract.Contacts.DISPLAY_NAME_PRIMARY  // 联系人显示名
)
 
// 执行查询：ContentResolver 会通过 Binder 将请求路由到通讯录 Provider
val cursor: Cursor? = resolver.query(
    uri,         // 目标 URI
    projection,  // 返回哪些列
    null,        // 不设筛选条件（返回全部）
    null,        // 无筛选参数
    null         // 不指定排序（使用默认）
)
 
// 遍历 Cursor 读取结果
cursor?.use { c ->  // use 扩展函数确保 Cursor 使用后自动关闭
    // 预先获取列索引，避免在循环中重复查找
    val nameIndex: Int = c.getColumnIndexOrThrow(
        ContactsContract.Contacts.DISPLAY_NAME_PRIMARY
    )
    // 逐行遍历
    while (c.moveToNext()) {
        // 读取当前行的联系人名称
        val name: String = c.getString(nameIndex)
        Log.d("Contacts", "联系人: $name")
    }
}

<!-- Provider 端：在 Manifest 中声明权限要求 -->
<provider
    android:name=".MyDataProvider"
    android:authorities="com.example.mydata"
    android:exported="true"
    android:readPermission="com.example.permission.READ_DATA"
    android:writePermission="com.example.permission.WRITE_DATA" />

<!-- Provider 端：对不同路径设置不同权限 -->
<provider
    android:name=".HealthProvider"
    android:authorities="com.example.health"
    android:exported="true"
    android:readPermission="com.example.permission.READ_HEALTH">
 
    <!-- /records/ 路径需要更高级别的权限 -->
    <path-permission
        android:pathPrefix="/records/"
        android:readPermission="com.example.permission.READ_MEDICAL_RECORDS" />
</provider>

// 发送端（文件管理器）：创建一个 Intent 并附带临时 URI 权限
// 构造指向特定文件的 Content URI（通常通过 FileProvider 生成）
val fileUri: Uri = FileProvider.getUriForFile(
    context,                              // 当前上下文
    "com.example.filemanager.fileprovider", // FileProvider 的 authority
    targetFile                            // 要分享的 File 对象
)
 
// 创建发送 Intent
val shareIntent: Intent = Intent(Intent.ACTION_SEND).apply {
    type = "image/jpeg"                   // 设置 MIME 类型
    putExtra(Intent.EXTRA_STREAM, fileUri) // 附带文件 URI
    // 关键：授予接收方对该 URI 的临时读取权限
    addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
}
 
// 启动选择器让用户选择接收应用
startActivity(Intent.createChooser(shareIntent, "分享图片"))

<!-- AndroidManifest.xml 中注册 ContentProvider -->
<!-- authorities 的值就是 Authority，全局唯一 -->
<provider
    android:name=".data.UserContentProvider"
    android:authorities="com.example.myapp.provider"
    android:exported="false" />

<!-- 同一个 Provider 响应两个不同的 Authority -->
<provider
    android:name=".data.UnifiedProvider"
    android:authorities="com.example.myapp.provider;com.example.myapp.legacy"
    android:exported="false" />

<!-- 使用占位符，Gradle 构建时自动替换为实际的 applicationId -->
<provider
    android:name=".data.UserContentProvider"
    android:authorities="${applicationId}.provider"
    android:exported="false" />

// 在代码中动态获取 Authority，与 Manifest 保持一致
// BuildConfig.APPLICATION_ID 会在编译时被替换为真实的 applicationId
companion object {
    // 拼接 Authority：applicationId + ".provider"
    const val AUTHORITY = "${BuildConfig.APPLICATION_ID}.provider"
}

// 手动拼接 URI 字符串，然后解析为 Uri 对象
// 这种方式简单直接，但拼接 ID 时容易出错（比如忘记加斜杠）
val tableUri: Uri = Uri.parse("content://com.example.myapp.provider/users")

// 基础表 URI，不含 ID
val baseUri: Uri = Uri.parse("content://com.example.myapp.provider/users")
 
// 使用 ContentUris.withAppendedId() 追加 ID 到路径末尾
// 结果：content://com.example.myapp.provider/users/42
val singleRowUri: Uri = ContentUris.withAppendedId(baseUri, 42L)
 
// 反向操作：从带 ID 的 URI 中提取出数字 ID
// 结果：42
val userId: Long = ContentUris.parseId(singleRowUri)

// Contract 类：ContentProvider 的"接口协议"
// 所有表名、列名、URI 常量集中在此，调用方只需引用这些常量
object MyContract {
 
    // Authority 常量，与 Manifest 中注册的保持一致
    const val AUTHORITY = "com.example.myapp.provider"
 
    // Users 表的协议定义
    object Users {
        // 表路径
        const val PATH = "users"
        // 完整的表级 URI（指向所有用户）
        val CONTENT_URI: Uri = Uri.parse("content://$AUTHORITY/$PATH")
        // 列名常量
        const val COLUMN_ID = "_id"
        const val COLUMN_NAME = "name"
        const val COLUMN_EMAIL = "email"
    }
 
    // Orders 表的协议定义
    object Orders {
        const val PATH = "orders"
        val CONTENT_URI: Uri = Uri.parse("content://$AUTHORITY/$PATH")
        const val COLUMN_ID = "_id"
        const val COLUMN_USER_ID = "user_id"
        const val COLUMN_AMOUNT = "amount"
    }
}

// ContentProvider 的 query 方法内部需要区分 URI 类型
override fun query(
    uri: Uri,              // 调用方传入的 URI
    projection: Array<String>?,  // 要查询的列
    selection: String?,    // WHERE 条件
    selectionArgs: Array<String>?, // WHERE 参数
    sortOrder: String?     // 排序
): Cursor? {
    val db = dbHelper.readableDatabase  // 获取只读数据库
 
    // 使用 UriMatcher 判断 URI 类型（后面会详解）
    return when (uriMatcher.match(uri)) {
        // 匹配到集合 URI：content://authority/users
        CODE_USERS -> {
            // 直接用传入的 selection 查询全表
            db.query("users", projection, selection, selectionArgs, null, null, sortOrder)
        }
        // 匹配到单条 URI：content://authority/users/42
        CODE_USER_ID -> {
            // 从 URI 路径末尾提取 ID
            val id = ContentUris.parseId(uri)
            // 在 WHERE 条件中追加 _id 过滤
            // 如果调用方还传了额外的 selection，用 AND 拼接
            val finalSelection = "_id = $id" +
                if (!selection.isNullOrEmpty()) " AND ($selection)" else ""
            db.query("users", projection, finalSelection, selectionArgs, null, null, sortOrder)
        }
        // 未知 URI，抛出异常
        else -> throw IllegalArgumentException("Unknown URI: $uri")
    }
}

override fun insert(uri: Uri, values: ContentValues?): Uri? {
    // 仅允许对集合 URI 执行插入操作
    when (uriMatcher.match(uri)) {
        CODE_USERS -> {
            val db = dbHelper.writableDatabase
            // 插入数据并获取新行的 rowId（即 _id）
            val newRowId = db.insert("users", null, values)
            if (newRowId != -1L) {
                // 通知所有正在监听此 URI 的 ContentObserver 数据已变化
                context?.contentResolver?.notifyChange(uri, null)
                // 返回带有新 ID 的 URI：content://authority/users/newRowId
                return ContentUris.withAppendedId(uri, newRowId)
            }
        }
    }
    return null
}

class UserContentProvider : ContentProvider() {
 
    // 数据库 Helper，在 onCreate 中初始化
    private lateinit var dbHelper: UserDbHelper
 
    companion object {
        // Authority 常量
        private const val AUTHORITY = "com.example.myapp.provider"
 
        // 整型 code 常量：每个 URI 模式一个唯一的数字
        // 集合 URI 用偶数、单条 URI 用奇数——这只是一种命名惯例，非强制
        private const val CODE_USERS = 100       // 匹配 users 表全集合
        private const val CODE_USER_ID = 101     // 匹配 users 表单条记录
        private const val CODE_ORDERS = 200      // 匹配 orders 表全集合
        private const val CODE_ORDER_ID = 201    // 匹配 orders 表单条记录
 
        // 创建 UriMatcher，默认不匹配时返回 NO_MATCH（-1）
        private val uriMatcher = UriMatcher(UriMatcher.NO_MATCH).apply {
            // 注册规则：Authority + Path 模式 → 整型 code
            // "users" 精确匹配表路径
            addURI(AUTHORITY, "users", CODE_USERS)
            // "users/#" 中的 # 匹配任意数字（即记录 ID）
            addURI(AUTHORITY, "users/#", CODE_USER_ID)
            // orders 表同理
            addURI(AUTHORITY, "orders", CODE_ORDERS)
            addURI(AUTHORITY, "orders/#", CODE_ORDER_ID)
        }
    }
 
    override fun onCreate(): Boolean {
        // 初始化数据库 Helper
        dbHelper = UserDbHelper(context!!)
        return true  // 返回 true 表示 Provider 初始化成功
    }
 
    override fun query(
        uri: Uri,
        projection: Array<String>?,
        selection: String?,
        selectionArgs: Array<String>?,
        sortOrder: String?
    ): Cursor? {
        val db = dbHelper.readableDatabase
 
        // 根据 URI 模式分发到不同的查询逻辑
        val cursor = when (uriMatcher.match(uri)) {
            CODE_USERS -> {
                // 集合查询：直接使用调用方传入的 selection
                db.query("users", projection, selection, selectionArgs, null, null, sortOrder)
            }
            CODE_USER_ID -> {
                // 单条查询：从 URI 末尾提取 ID，追加到 WHERE 条件
                val id = ContentUris.parseId(uri)
                db.query(
                    "users", projection,
                    "_id = ?",             // WHERE _id = ?
                    arrayOf(id.toString()), // 参数化防注入
                    null, null, sortOrder
                )
            }
            CODE_ORDERS -> {
                db.query("orders", projection, selection, selectionArgs, null, null, sortOrder)
            }
            CODE_ORDER_ID -> {
                val id = ContentUris.parseId(uri)
                db.query(
                    "orders", projection,
                    "_id = ?",
                    arrayOf(id.toString()),
                    null, null, sortOrder
                )
            }
            // 无法匹配的 URI，说明调用方传了一个本 Provider 不认识的路径
            else -> throw IllegalArgumentException("Unknown URI: $uri")
        }
 
        // 为 Cursor 设置通知 URI
        // 当此 URI 对应的数据发生变化时，持有此 Cursor 的 Loader/LiveData 会自动重新查询
        cursor?.setNotificationUri(context?.contentResolver, uri)
        return cursor
    }
 
    // insert / update / delete / getType 省略，模式完全一致
    // 都是先 uriMatcher.match(uri)，再 when 分发
 
    override fun insert(uri: Uri, values: ContentValues?): Uri? { /* ... */ return null }
    override fun update(uri: Uri, values: ContentValues?, selection: String?, selectionArgs: Array<String>?): Int { return 0 }
    override fun delete(uri: Uri, selection: String?, selectionArgs: Array<String>?): Int { return 0 }
    override fun getType(uri: Uri): String? { /* ... */ return null }
}

// 一个完整的 Content URI 示例
// content://com.example.myapp.provider/users/42?notify=true#section1
//
// ┌─────────┐ ┌──────────────────────────────┐ ┌─────┐ ┌──┐ ┌───────────┐ ┌────────┐
// │ scheme   │ │         authority             │ │path │ │id│ │  query    │ │fragment│
// │content://│ │com.example.myapp.provider     │ │users│ │42│ │notify=true│ │section1│
// └─────────┘ └──────────────────────────────┘ └─────┘ └──┘ └───────────┘ └────────┘
//
// uri.scheme        → "content"
// uri.authority     → "com.example.myapp.provider"
// uri.path          → "/users/42"
// uri.pathSegments  → ["users", "42"]
// uri.lastPathSegment → "42"
// ContentUris.parseId(uri) → 42L
// uri.getQueryParameter("notify") → "true"
// uri.fragment      → "section1"

uriMatcher.addURI("com.test.provider", "books", 1)
uriMatcher.addURI("com.test.provider", "books/#", 2)

// ContentProvider 子类中必须重写的 query 方法
override fun query(
    uri: Uri,                      // 资源定位符，标识要查询的数据集合或特定行
    projection: Array<String>?,    // 投影列，指定返回哪些列（类似 SQL 的 SELECT 列表）
    selection: String?,            // 筛选条件，相当于 SQL 的 WHERE 子句（不含 WHERE 关键字）
    selectionArgs: Array<String>?, // 筛选参数，替换 selection 中的 ? 占位符，防止 SQL 注入
    sortOrder: String?             // 排序规则，相当于 SQL 的 ORDER BY 子句
): Cursor? {
    // 实现查询逻辑并返回 Cursor
}

// 图书管理 ContentProvider 的 query 实现
override fun query(
    uri: Uri,                      // 调用方传入的目标 URI
    projection: Array<String>?,    // 需要返回的列
    selection: String?,            // WHERE 条件
    selectionArgs: Array<String>?, // WHERE 条件的参数
    sortOrder: String?             // ORDER BY 子句
): Cursor? {
    // 获取可读的数据库实例（不需要写权限时应使用 readableDatabase）
    val db: SQLiteDatabase = dbHelper.readableDatabase
 
    // 用于构建查询的 SQLiteQueryBuilder，它能帮助我们安全地组装 SQL
    val queryBuilder = SQLiteQueryBuilder()
 
    // 根据 URI 类型决定查询范围
    when (uriMatcher.match(uri)) {
        // URI 匹配到集合路径 content://authority/books
        BOOKS_COLLECTION -> {
            // 设置查询的目标表名
            queryBuilder.tables = BookContract.TABLE_NAME
        }
        // URI 匹配到单条记录路径 content://authority/books/{id}
        BOOK_SINGLE_ITEM -> {
            // 同样设置目标表名
            queryBuilder.tables = BookContract.TABLE_NAME
            // 追加 WHERE 条件，限定只查询 URI 中指定 ID 的那一行
            // ContentUris.parseId() 从 URI 尾部提取数字 ID
            queryBuilder.appendWhere(
                "${BookContract.COLUMN_ID} = ${ContentUris.parseId(uri)}"
            )
        }
        // URI 无法匹配任何已知模式，说明调用方传入了非法 URI
        else -> throw IllegalArgumentException("未知 URI: $uri")
    }
 
    // 确定排序规则：调用方未指定时使用默认排序
    val finalSortOrder = if (sortOrder.isNullOrEmpty()) {
        // 默认按书名升序排列
        "${BookContract.COLUMN_TITLE} ASC"
    } else {
        // 使用调用方指定的排序规则
        sortOrder
    }
 
    // 执行查询，返回 Cursor 游标对象
    val cursor: Cursor = queryBuilder.query(
        db,              // 数据库实例
        projection,      // 投影列（SELECT 列表）
        selection,       // WHERE 子句
        selectionArgs,   // WHERE 参数
        null,            // GROUP BY（通常不在 Provider 层分组）
        null,            // HAVING（通常不在 Provider 层过滤分组）
        finalSortOrder   // ORDER BY 子句
    )
 
    // 关键：为 Cursor 设置通知 URI
    // 当该 URI 对应的数据发生变更时，使用此 Cursor 的 ContentObserver 会收到通知
    // 这是 ContentProvider 响应式数据更新机制的基础
    cursor.setNotificationUri(context?.contentResolver, uri)
 
    // 返回 Cursor 给调用方（跨进程时，Cursor 的数据通过共享内存传递）
    return cursor
}

// 在 Activity 或 ViewModel 中查询图书数据
fun loadBooks(context: Context): List<Book> {
    // 结果列表
    val books = mutableListOf<Book>()
 
    // 定义需要查询的列（投影），只取需要的列以优化性能
    val projection = arrayOf(
        BookContract.COLUMN_ID,     // 图书 ID
        BookContract.COLUMN_TITLE,  // 书名
        BookContract.COLUMN_AUTHOR  // 作者
    )
 
    // 定义筛选条件：查找作者名中包含指定关键字的图书
    val selection = "${BookContract.COLUMN_AUTHOR} LIKE ?"
    // 占位符的实际值，% 是 SQL 的通配符
    val selectionArgs = arrayOf("%Kotlin%")
 
    // 排序规则：按书名升序
    val sortOrder = "${BookContract.COLUMN_TITLE} ASC"
 
    // 通过 ContentResolver 发起跨进程查询
    // 返回的 Cursor 可能为 null（Provider 出错或数据为空时）
    val cursor: Cursor? = context.contentResolver.query(
        BookContract.CONTENT_URI, // 目标 URI: content://com.example.provider/books
        projection,               // 投影列
        selection,                // WHERE 条件
        selectionArgs,            // WHERE 参数
        sortOrder                 // ORDER BY
    )
 
    // 使用 Kotlin 的 use 扩展函数确保 Cursor 在使用后自动关闭
    // Cursor 实现了 Closeable 接口，不关闭会导致内存泄漏和资源耗尽
    cursor?.use { c ->
        // 预先获取列索引，避免在循环中反复调用 getColumnIndexOrThrow
        // 这是一个常见的性能优化技巧
        val idIndex = c.getColumnIndexOrThrow(BookContract.COLUMN_ID)
        val titleIndex = c.getColumnIndexOrThrow(BookContract.COLUMN_TITLE)
        val authorIndex = c.getColumnIndexOrThrow(BookContract.COLUMN_AUTHOR)
 
        // 遍历 Cursor 中的每一行数据
        while (c.moveToNext()) {
            // 从当前行中按列索引提取数据
            val book = Book(
                id = c.getLong(idIndex),       // 读取 Long 类型的 ID
                title = c.getString(titleIndex), // 读取 String 类型的书名
                author = c.getString(authorIndex) // 读取 String 类型的作者
            )
            // 添加到结果列表
            books.add(book)
        }
    }
 
    return books
}

// ContentProvider 子类中必须重写的 insert 方法
override fun insert(
    uri: Uri,                // 目标集合的 URI（如 content://authority/books）
    values: ContentValues?   // 要插入的键值对数据（列名 -> 值）
): Uri? {
    // 插入数据并返回新记录的 URI
}

// 图书管理 ContentProvider 的 insert 实现
override fun insert(uri: Uri, values: ContentValues?): Uri? {
    // 校验 URI 必须指向集合路径，不允许向单条记录路径执行 insert
    if (uriMatcher.match(uri) != BOOKS_COLLECTION) {
        throw IllegalArgumentException("insert 操作不支持此 URI: $uri")
    }
 
    // 防御性检查：ContentValues 不能为 null 或空
    requireNotNull(values) { "ContentValues 不能为 null" }
 
    // 可选：在此处进行业务校验
    // 例如检查必填字段是否存在
    require(values.containsKey(BookContract.COLUMN_TITLE)) {
        "缺少必填字段: ${BookContract.COLUMN_TITLE}"
    }
 
    // 获取可写的数据库实例
    val db: SQLiteDatabase = dbHelper.writableDatabase
 
    // 执行插入操作
    // 第二个参数 nullColumnHack：当 values 为空时，
    // SQLite 不允许插入完全为空的行，此参数指定一个列名用于插入 NULL 值
    // 由于我们已经检查了 values 非空，这里传 null 即可
    val rowId: Long = db.insert(
        BookContract.TABLE_NAME, // 目标表名
        null,                    // nullColumnHack
        values                   // 要插入的数据
    )
 
    // db.insert() 返回 -1 表示插入失败
    if (rowId == -1L) {
        // 记录日志，但通常不应抛出异常
        // 因为跨进程场景下异常的传递链较复杂
        Log.e(TAG, "向 $uri 插入数据失败")
        return null
    }
 
    // 构造新记录的 URI：在集合 URI 后追加新生成的行 ID
    // 例如 content://com.example.provider/books/42
    val newUri: Uri = ContentUris.withAppendedId(uri, rowId)
 
    // 关键：通知所有注册在该 URI 上的 ContentObserver 数据已变更
    // 第二个参数 observer 传 null 表示通知所有观察者
    context?.contentResolver?.notifyChange(newUri, null)
 
    // 返回新记录的完整 URI
    return newUri
}

// 在 Activity 或 ViewModel 中插入一条新图书记录
fun addBook(context: Context, title: String, author: String): Uri? {
    // 构造要插入的数据
    val values = ContentValues().apply {
        // put 方法会根据参数类型自动选择合适的存储方式
        put(BookContract.COLUMN_TITLE, title)   // 书名
        put(BookContract.COLUMN_AUTHOR, author) // 作者
        // 注意：不需要手动指定 _id 列，数据库会自动生成自增主键
    }
 
    // 通过 ContentResolver 发起跨进程插入
    // 返回新记录的 URI，如 content://com.example.provider/books/42
    val newBookUri: Uri? = context.contentResolver.insert(
        BookContract.CONTENT_URI, // 集合 URI
        values                    // 要插入的数据
    )
 
    // 如果需要获取新记录的 ID，可以从返回的 URI 中提取
    newBookUri?.let {
        val newId: Long = ContentUris.parseId(it) // 提取 URI 尾部的数字 ID
        Log.d(TAG, "新图书 ID: $newId")
    }
 
    return newBookUri
}

// 重写 bulkInsert 实现高效批量插入
override fun bulkInsert(uri: Uri, valuesArray: Array<ContentValues>): Int {
    // 获取可写的数据库实例
    val db: SQLiteDatabase = dbHelper.writableDatabase
    // 记录成功插入的行数
    var insertCount = 0
 
    // 开启数据库事务，将多次插入合并为一个原子操作
    // 事务内的所有操作共享同一次磁盘写入，性能可提升 10~100 倍
    db.beginTransaction()
    try {
        // 遍历所有待插入的数据
        for (values in valuesArray) {
            // 逐条插入，但由于在事务内，不会每次都触发磁盘 I/O
            val id = db.insert(BookContract.TABLE_NAME, null, values)
            // 插入成功时累计计数
            if (id != -1L) {
                insertCount++
            }
        }
        // 标记事务成功，endTransaction 时会执行 COMMIT
        // 如果不调用此方法，endTransaction 会执行 ROLLBACK
        db.setTransactionSuccessful()
    } finally {
        // 无论成功与否都要结束事务，释放数据库锁
        db.endTransaction()
    }
 
    // 批量插入完成后统一发送一次变更通知（而非每条都通知）
    if (insertCount > 0) {
        context?.contentResolver?.notifyChange(uri, null)
    }
 
    // 返回实际成功插入的行数
    return insertCount
}

// ContentProvider 子类中必须重写的 update 方法
override fun update(
    uri: Uri,                      // 目标资源 URI（集合或单条记录）
    values: ContentValues?,        // 要更新的列及其新值
    selection: String?,            // WHERE 条件（仅在集合 URI 时有意义）
    selectionArgs: Array<String>?  // WHERE 条件的参数
): Int {
    // 执行更新操作并返回受影响的行数
}

// 图书管理 ContentProvider 的 update 实现
override fun update(
    uri: Uri,
    values: ContentValues?,
    selection: String?,
    selectionArgs: Array<String>?
): Int {
    // 获取可写数据库实例
    val db: SQLiteDatabase = dbHelper.writableDatabase
    // 记录受影响的行数
    val rowsUpdated: Int
 
    when (uriMatcher.match(uri)) {
        // 集合路径：更新满足 selection 条件的所有行
        BOOKS_COLLECTION -> {
            rowsUpdated = db.update(
                BookContract.TABLE_NAME, // 目标表名
                values,                  // 要更新的列值对
                selection,               // WHERE 条件
                selectionArgs            // WHERE 参数
            )
        }
        // 单条记录路径：只更新指定 ID 的行
        BOOK_SINGLE_ITEM -> {
            // 从 URI 中提取记录 ID
            val id = ContentUris.parseId(uri)
 
            // 构建最终的 WHERE 条件
            // 首先限定 ID，然后如果调用方还传入了额外的 selection 条件，
            // 使用 AND 将两个条件组合起来
            val finalSelection = "${BookContract.COLUMN_ID} = $id" +
                if (!selection.isNullOrEmpty()) " AND ($selection)" else ""
 
            rowsUpdated = db.update(
                BookContract.TABLE_NAME, // 目标表名
                values,                  // 要更新的列值对
                finalSelection,          // 组合后的 WHERE 条件
                selectionArgs            // WHERE 参数（对应 selection 中的 ? 占位符）
            )
        }
        // 未知 URI
        else -> throw IllegalArgumentException("update 不支持此 URI: $uri")
    }
 
    // 如果有行被更新，通知所有观察者
    if (rowsUpdated > 0) {
        context?.contentResolver?.notifyChange(uri, null)
    }
 
    // 返回受影响的行数
    return rowsUpdated
}

// 更新指定图书的标题
fun updateBookTitle(context: Context, bookId: Long, newTitle: String): Boolean {
    // 构造要更新的列值对
    val values = ContentValues().apply {
        // 只 put 需要修改的列，其他列保持不变
        put(BookContract.COLUMN_TITLE, newTitle)
    }
 
    // 构造指向特定图书记录的 URI
    val bookUri: Uri = ContentUris.withAppendedId(
        BookContract.CONTENT_URI, // 基础集合 URI
        bookId                    // 记录 ID
    )
 
    // 执行更新，返回受影响的行数
    val rowsUpdated: Int = context.contentResolver.update(
        bookUri, // 目标 URI: content://com.example.provider/books/42
        values,  // 要更新的数据
        null,    // 不需要额外的 WHERE 条件（URI 中已包含 ID）
        null     // 无 WHERE 参数
    )
 
    // 返回是否更新成功（至少有一行被修改）
    return rowsUpdated > 0
}

// ContentProvider 子类中必须重写的 delete 方法
override fun delete(
    uri: Uri,                      // 目标资源 URI
    selection: String?,            // WHERE 条件
    selectionArgs: Array<String>?  // WHERE 参数
): Int {
    // 执行删除操作并返回被删除的行数
}

// 图书管理 ContentProvider 的 delete 实现
override fun delete(
    uri: Uri,
    selection: String?,
    selectionArgs: Array<String>?
): Int {
    // 获取可写数据库实例
    val db: SQLiteDatabase = dbHelper.writableDatabase
    // 记录被删除的行数
    val rowsDeleted: Int
 
    when (uriMatcher.match(uri)) {
        // 集合路径：删除满足 selection 条件的所有行
        BOOKS_COLLECTION -> {
            rowsDeleted = db.delete(
                BookContract.TABLE_NAME, // 目标表名
                selection,               // WHERE 条件（null 表示删除所有行）
                selectionArgs            // WHERE 参数
            )
        }
        // 单条记录路径：只删除指定 ID 的行
        BOOK_SINGLE_ITEM -> {
            // 从 URI 提取 ID
            val id = ContentUris.parseId(uri)
 
            // 组合 ID 条件与调用方的 selection 条件
            val finalSelection = "${BookContract.COLUMN_ID} = $id" +
                if (!selection.isNullOrEmpty()) " AND ($selection)" else ""
 
            rowsDeleted = db.delete(
                BookContract.TABLE_NAME, // 目标表名
                finalSelection,          // 组合后的 WHERE 条件
                selectionArgs            // WHERE 参数
            )
        }
        // 未知 URI
        else -> throw IllegalArgumentException("delete 不支持此 URI: $uri")
    }
 
    // 即使 rowsDeleted 为 0，某些场景也可能需要通知
    // 但通常只在确实删除了数据时才通知，避免不必要的 UI 刷新
    if (rowsDeleted > 0) {
        context?.contentResolver?.notifyChange(uri, null)
    }
 
    // 返回被删除的行数
    return rowsDeleted
}

// 删除指定 ID 的图书
fun deleteBook(context: Context, bookId: Long): Boolean {
    // 构造指向特定记录的 URI
    val bookUri = ContentUris.withAppendedId(BookContract.CONTENT_URI, bookId)
 
    // 执行删除
    val rowsDeleted = context.contentResolver.delete(
        bookUri, // 目标 URI
        null,    // 不需要额外 WHERE 条件
        null     // 无 WHERE 参数
    )
 
    return rowsDeleted > 0
}
 
// 删除某个作者的所有图书（基于集合 URI + selection 条件）
fun deleteBooksByAuthor(context: Context, author: String): Int {
    // 使用参数化查询防止 SQL 注入
    val selection = "${BookContract.COLUMN_AUTHOR} = ?"
    val selectionArgs = arrayOf(author)
 
    // 通过集合 URI 执行批量删除
    return context.contentResolver.delete(
        BookContract.CONTENT_URI, // 集合 URI
        selection,                // WHERE 条件
        selectionArgs             // WHERE 参数
    )
}

集合类型（多行数据）:  vnd.android.cursor.dir/vnd.<authority>.<table>
单项类型（单行数据）:  vnd.android.cursor.item/vnd.<authority>.<table>

// 图书管理 ContentProvider 的 getType 实现
override fun getType(uri: Uri): String? {
    // 根据 URI 模式返回对应的 MIME 类型
    return when (uriMatcher.match(uri)) {
        // 集合路径 content://com.example.provider/books
        // 返回目录类型的 MIME，表示查询结果是多行数据
        BOOKS_COLLECTION ->
            "vnd.android.cursor.dir/vnd.${BookContract.AUTHORITY}.${BookContract.TABLE_NAME}"
 
        // 单条记录路径 content://com.example.provider/books/{id}
        // 返回单项类型的 MIME，表示查询结果是单行数据
        BOOK_SINGLE_ITEM ->
            "vnd.android.cursor.item/vnd.${BookContract.AUTHORITY}.${BookContract.TABLE_NAME}"
 
        // 未知 URI 返回 null
        else -> null
    }
}

// BookContract.kt - 数据契约类，定义所有与外部共享的常量
object BookContract {
    // ContentProvider 的 authority，必须与 AndroidManifest.xml 中的声明一致
    const val AUTHORITY = "com.example.bookprovider"
 
    // 数据表名
    const val TABLE_NAME = "books"
 
    // 内容 URI：外部访问 books 集合的入口
    val CONTENT_URI: Uri = Uri.parse("content://$AUTHORITY/$TABLE_NAME")
 
    // MIME 类型常量：集合（目录）类型
    const val CONTENT_TYPE =
        "vnd.android.cursor.dir/vnd.$AUTHORITY.$TABLE_NAME"
 
    // MIME 类型常量：单条记录类型
    const val CONTENT_ITEM_TYPE =
        "vnd.android.cursor.item/vnd.$AUTHORITY.$TABLE_NAME"
 
    // 列名常量
    const val COLUMN_ID = "_id"       // 主键列（建议使用 _id 以兼容 CursorAdapter）
    const val COLUMN_TITLE = "title"  // 书名列
    const val COLUMN_AUTHOR = "author" // 作者列
}

// ActivityThread.handleBindApplication() 简化流程
private void handleBindApplication(AppBindData data) {
    // 第一步：创建 Application 对象（但不调用 onCreate）
    // 通过 Instrumentation.newApplication() 反射创建 Application 实例
    Application app = data.info.makeApplication(false, mInstrumentation);
 
    // 第二步：安装所有在 AndroidManifest 中声明的 ContentProvider
    // 这一步会遍历所有声明的 Provider，逐一实例化并调用其 onCreate()
    if (!data.restrictedBackupMode) {
        installContentProviders(app, data.providers);
        // 此时所有 ContentProvider 已经完成 onCreate()
    }
 
    // 第三步：调用 Application.onCreate()
    // 注意：这是在所有 ContentProvider.onCreate() 之后才执行的
    mInstrumentation.callApplicationOnCreate(app);
}

// installContentProviders 内部对每个 Provider 的处理
private void installProvider(Context context, ProviderInfo info) {
    // 1. 通过反射创建 ContentProvider 实例
    ContentProvider provider = (ContentProvider) cl.loadClass(info.name).newInstance();
 
    // 2. 调用 ContentProvider.attachInfo()
    //    该方法内部会调用 ContentProvider.onCreate()
    provider.attachInfo(context, info);
 
    // 3. 将 Provider 注册到 ActivityThread 的 ProviderMap 中
    //    后续的 ContentResolver 调用会通过这个 Map 找到对应的 Provider
}

// ❌ 错误示例：在 ContentProvider.onCreate() 中使用尚未初始化的全局单例
class MyProvider : ContentProvider() {
    override fun onCreate(): Boolean {
        // 假设 AppDatabase 在 Application.onCreate() 中才完成初始化
        // 此时 Application.onCreate() 还没有被调用！
        // 这行代码会抛出 NullPointerException 或类似的初始化异常
        val db = AppDatabase.getInstance()  // 💥 崩溃！
        return true
    }
}

// ✅ 正确示例：使用 lazy 延迟初始化，直到第一次真正需要时才获取实例
class MyProvider : ContentProvider() {
 
    // 使用 Kotlin 的 lazy 委托，在第一次访问 db 时才执行初始化
    // 此时 Application.onCreate() 早已执行完毕
    private val db by lazy { AppDatabase.getInstance(context!!) }
 
    override fun onCreate(): Boolean {
        // onCreate() 中只做轻量级的准备工作
        // 不要在这里访问可能尚未就绪的全局依赖
        return true
    }
 
    override fun query(
        uri: Uri,
        projection: Array<out String>?,
        selection: String?,
        selectionArgs: Array<out String>?,
        sortOrder: String?
    ): Cursor? {
        // 首次 query 时 db 才会被初始化
        // 此时所有全局依赖已经就绪
        return db.rawQuery("SELECT * FROM table", null)
    }
 
    // ... 其他 CRUD 方法
}

<!-- AndroidManifest.xml 中 App Startup 的典型配置 -->
<!-- 只需要一个 InitializationProvider，替代多个库各自的 ContentProvider -->
<provider
    android:name="androidx.startup.InitializationProvider"
    android:authorities="${applicationId}.androidx-startup"
    android:exported="false">
    <!-- 通过 meta-data 声明需要初始化的 Initializer -->
    <meta-data
        android:name="com.example.MyInitializer"
        android:value="androidx.startup" />
</provider>

class MyApplication : Application() {
 
    override fun attachBaseContext(base: Context) {
        // 这个方法在所有 ContentProvider.onCreate() 之前调用
        super.attachBaseContext(base)
        // 可以在这里做最基础的初始化
        // 例如 MultiDex 安装（在 minSdk < 21 时需要）
        // 或者极少数必须在 Provider 之前就绪的配置
    }
 
    override fun onCreate() {
        // 这个方法在所有 ContentProvider.onCreate() 之后调用
        super.onCreate()
        // 常规的全局初始化放在这里
    }
}

// ✅ 正确做法：使用单例的 SQLiteOpenHelper，确保共享同一个数据库连接
class MyProvider : ContentProvider() {
 
    // 伴生对象持有单例的 Helper 引用
    companion object {
        // volatile 确保多线程可见性
        @Volatile
        private var dbHelper: MyDatabaseHelper? = null
 
        // 双重检查锁定获取单例
        private fun getHelper(context: Context): MyDatabaseHelper {
            return dbHelper ?: synchronized(this) {
                dbHelper ?: MyDatabaseHelper(context.applicationContext).also {
                    dbHelper = it
                }
            }
        }
    }
 
    override fun onCreate(): Boolean {
        // onCreate 中只做轻量准备，不在此处初始化数据库
        return true
    }
 
    override fun query(
        uri: Uri,
        projection: Array<out String>?,
        selection: String?,
        selectionArgs: Array<out String>?,
        sortOrder: String?
    ): Cursor? {
        // 通过单例 Helper 获取可读数据库实例（共享连接）
        val db = getHelper(context!!).readableDatabase
        // SQLiteDatabase 内部的锁机制会保护并发读操作
        return db.query("my_table", projection, selection, selectionArgs, null, null, sortOrder)
    }
 
    override fun insert(uri: Uri, values: ContentValues?): Uri? {
        // 通过同一个单例 Helper 获取可写数据库实例
        val db = getHelper(context!!).writableDatabase
        // SQLiteDatabase 内部的锁机制会保护写操作
        val id = db.insert("my_table", null, values)
        // 通知观察者数据已变化
        context?.contentResolver?.notifyChange(uri, null)
        // 返回新插入行的 URI
        return ContentUris.withAppendedId(uri, id)
    }
 
    // update / delete 类似，均通过同一个 Helper 获取数据库连接
    // ...
}

// 基于内存 Map 的 ContentProvider：使用读写锁提升并发性能
class InMemoryProvider : ContentProvider() {
 
    // 底层数据存储：普通 HashMap（非线程安全）
    private val dataStore = HashMap<Long, ContentValues>()
 
    // 读写锁：允许多个并发读，写操作排他
    private val lock = ReentrantReadWriteLock()
 
    // 自增 ID 生成器：使用 AtomicLong 保证原子性
    private val idGenerator = AtomicLong(0)
 
    override fun onCreate(): Boolean = true
 
    override fun query(
        uri: Uri,
        projection: Array<out String>?,
        selection: String?,
        selectionArgs: Array<out String>?,
        sortOrder: String?
    ): Cursor? {
        // 获取读锁：多个 query 可以同时执行
        lock.readLock().lock()
        try {
            // 在读锁保护下安全地遍历 dataStore
            val cursor = MatrixCursor(projection ?: arrayOf("_id", "name"))
            dataStore.forEach { (id, values) ->
                // 将每条数据添加到 MatrixCursor 中
                cursor.addRow(arrayOf(id, values.getAsString("name")))
            }
            return cursor
        } finally {
            // finally 块确保锁一定被释放，避免死锁
            lock.readLock().unlock()
        }
    }
 
    override fun insert(uri: Uri, values: ContentValues?): Uri? {
        // 获取写锁：排他访问，其他读写操作都必须等待
        lock.writeLock().lock()
        try {
            // 在写锁保护下安全地修改 dataStore
            val id = idGenerator.incrementAndGet()
            values?.let { dataStore[id] = it }
            // 通知观察者数据变化
            context?.contentResolver?.notifyChange(uri, null)
            return ContentUris.withAppendedId(uri, id)
        } finally {
            // 确保写锁释放
            lock.writeLock().unlock()
        }
    }
 
    // update / delete 同样需要获取写锁
    // ...
}

// 重写 applyBatch 以提供事务级别的原子性保证
override fun applyBatch(
    operations: ArrayList<ContentProviderOperation>
): Array<ContentProviderResult> {
    // 获取可写数据库实例
    val db = dbHelper.writableDatabase
    // 开启 SQLite 事务
    db.beginTransaction()
    try {
        // 调用父类的 applyBatch 逐一执行所有操作
        // 每个操作内部会调用对应的 insert/update/delete 方法
        val results = super.applyBatch(operations)
        // 标记事务成功：如果前面没有异常，所有操作会在 endTransaction 时提交
        db.setTransactionSuccessful()
        // 返回每个操作的执行结果
        return results
    } finally {
        // 结束事务：如果没有调用 setTransactionSuccessful()，所有操作会被回滚
        db.endTransaction()
    }
}

// 重写 bulkInsert 以使用事务优化批量插入性能
override fun bulkInsert(uri: Uri, values: Array<out ContentValues>): Int {
    val db = dbHelper.writableDatabase
    // 开启事务：批量插入在单个事务中完成，避免每行都触发磁盘同步
    db.beginTransaction()
    try {
        var insertCount = 0
        // 遍历所有待插入的 ContentValues
        for (value in values) {
            // 执行单行插入，-1 表示插入失败
            val id = db.insert("my_table", null, value)
            if (id != -1L) {
                // 插入成功，计数加一
                insertCount++
            }
        }
        // 标记事务成功
        db.setTransactionSuccessful()
        // 事务完成后统一发送一次变更通知（而非每行都通知）
        context?.contentResolver?.notifyChange(uri, null)
        // 返回成功插入的行数
        return insertCount
    } finally {
        // 确保事务结束（成功则提交，失败则回滚）
        db.endTransaction()
    }
}

<!-- ========== Provider 端：声明自定义权限并绑定到 Provider ========== -->
 
<!-- 第一步：自定义"读"权限，protectionLevel 决定了授权门槛 -->
<!-- "normal" 级别：安装时自动授予，用户无感知 -->
<!-- "dangerous" 级别：运行时需要用户手动同意（Android 6.0+） -->
<!-- "signature" 级别：只有与 Provider 应用签名相同的应用才能获得 -->
<permission
    android:name="com.example.myapp.READ_DATA"
    android:protectionLevel="signature" />
 
<!-- 第二步：自定义"写"权限，同样使用 signature 级别保护 -->
<permission
    android:name="com.example.myapp.WRITE_DATA"
    android:protectionLevel="signature" />
 
<!-- 第三步：将权限绑定到 Provider 声明上 -->
<provider
    android:name=".data.MyContentProvider"
    android:authorities="com.example.myapp.provider"
    android:exported="true"
    android:readPermission="com.example.myapp.READ_DATA"
    android:writePermission="com.example.myapp.WRITE_DATA" />
<!-- exported="true" 表示允许外部应用访问 -->
<!-- 但即使 exported，没有对应权限的应用依然会被拒绝 -->

<!-- ========== Client 端：申请权限 ========== -->
 
<!-- 声明需要使用 Provider 端定义的读权限 -->
<uses-permission android:name="com.example.myapp.READ_DATA" />
 
<!-- 声明需要使用 Provider 端定义的写权限 -->
<uses-permission android:name="com.example.myapp.WRITE_DATA" />

<!-- Provider 声明：整体使用较松的权限，特定路径使用更严格的权限 -->
<provider
    android:name=".data.ArticleProvider"
    android:authorities="com.example.articles"
    android:exported="true"
    android:readPermission="com.example.READ_PUBLIC">
 
    <!-- 对 /private/ 路径下的数据施加更严格的签名级权限 -->
    <!-- pathPrefix 表示"以此前缀开头的所有路径" -->
    <path-permission
        android:pathPrefix="/private/"
        android:readPermission="com.example.READ_PRIVATE"
        android:writePermission="com.example.WRITE_PRIVATE" />
 
    <!-- 对 /admin/ 路径使用精确匹配 -->
    <!-- path 表示完全匹配，不含通配 -->
    <path-permission
        android:path="/admin/config"
        android:readPermission="com.example.ADMIN_ACCESS"
        android:writePermission="com.example.ADMIN_ACCESS" />
</provider>

<!-- 全局启用：该 Provider 的任何 URI 都可以被临时授权给其他应用 -->
<provider
    android:name=".data.FileShareProvider"
    android:authorities="com.example.files"
    android:exported="false"
    android:grantUriPermissions="true" />
<!-- 注意：即使 exported="false"，临时授权依然能让外部应用访问特定 URI -->
<!-- 这正是临时授权的精妙之处——整体不开放，按需单点突破 -->

<!-- 仅允许 /shared/ 路径下的 URI 被临时授权 -->
<provider
    android:name=".data.FileShareProvider"
    android:authorities="com.example.files"
    android:exported="false"
    android:grantUriPermissions="false">
 
    <!-- 只有以 /shared/ 开头的路径可以被临时授权 -->
    <grant-uri-permission android:pathPrefix="/shared/" />
 
    <!-- 也可以使用精确路径匹配 -->
    <grant-uri-permission android:path="/public/readme" />
</provider>
<!-- 当 grantUriPermissions="false" 时，必须有 <grant-uri-permission> 子标签 -->
<!-- 否则任何临时授权请求都会被拒绝 -->

// === 通过 Intent Flag 授予临时 URI 权限 ===
 
// 构建要分享的内容 URI（通常由 FileProvider 生成）
val contentUri: Uri = FileProvider.getUriForFile(
    context,                            // 当前上下文
    "com.example.myapp.fileprovider",   // 在 Manifest 中声明的 authority
    File(context.filesDir, "report.pdf") // 要分享的文件
)
 
// 创建用于打开 PDF 的 Intent
val shareIntent = Intent(Intent.ACTION_VIEW).apply {
    // 设置数据和 MIME 类型
    setDataAndType(contentUri, "application/pdf")
 
    // 【关键】添加临时读权限 Flag
    // FLAG_GRANT_READ_URI_PERMISSION: 授予目标应用对此 URI 的临时读权限
    addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
 
    // 如果还需要写权限，可以同时添加：
    // addFlags(Intent.FLAG_GRANT_WRITE_URI_PERMISSION)
}
 
// 启动目标 Activity
// 当目标 Activity 结束（或任务栈被清理）时，临时权限自动回收
startActivity(shareIntent)

// === 通过 API 显式授予和撤销临时 URI 权限 ===
 
// 要授权的目标应用包名
val targetPackage = "com.example.partner.app"
 
// 要共享的 URI
val dataUri = Uri.parse("content://com.example.myapp.provider/records/42")
 
// 显式授予读权限
// 参数：目标包名、URI、权限标志
context.grantUriPermission(
    targetPackage,                              // 精确指定哪个应用获得权限
    dataUri,                                    // 精确指定哪条 URI
    Intent.FLAG_GRANT_READ_URI_PERMISSION       // 读权限（也可用 WRITE 或两者 OR）
)
 
// ... 目标应用在此期间可以通过 ContentResolver 读取该 URI ...
 
// 当不再需要共享时，显式撤销权限
// 这比 Intent Flag 方式更精确——你完全控制权限的生命周期
context.revokeUriPermission(
    dataUri,                                    // 撤销此 URI 的临时权限
    Intent.FLAG_GRANT_READ_URI_PERMISSION       // 撤销读权限
)
// 撤销后，目标应用再访问该 URI 就会收到 SecurityException

// === 推荐的 Provider 权限设计模式 ===
 
// 1. 默认不导出，除非有明确的跨应用需求
// android:exported="false"
 
// 2. 如果确实需要跨应用共享，优先使用 signature 级权限
// 这样只有你自己的应用套件能访问
 
// 3. 对于"偶尔分享给第三方"的场景，使用 exported="false" + grantUriPermissions="true"
// 配合 Intent Flag 实现最小权限的临时授权
 
// 4. Provider 内部可以做额外校验（Defense in Depth，纵深防御）
class SecureProvider : ContentProvider() {
 
    override fun query(
        uri: Uri,                                   // 请求的 URI
        projection: Array<out String>?,             // 请求的列
        selection: String?,                         // 过滤条件
        selectionArgs: Array<out String>?,          // 过滤参数
        sortOrder: String?                          // 排序
    ): Cursor? {
        // 即使 AMS 已经做了权限校验，Provider 内部依然可以做额外的业务级检查
        // 这就是"纵深防御"思想
 
        // 获取调用方的包名（通过 Binder 获取调用方 UID，再查包名）
        val callingPackage = callingPackage          // ContentProvider 内置方法
            ?: throw SecurityException("Unable to identify calling package")
 
        // 可以根据调用方身份做更精细的数据过滤
        // 比如：即使有读权限，也只返回与该应用相关的数据行
        val filteredSelection = if (isExternalCaller(callingPackage)) {
            // 外部调用者只能看到"公开"标记的记录
            "(${selection ?: "1=1"}) AND is_public = 1"     // 追加公开过滤条件
        } else {
            selection                                        // 内部调用不限制
        }
 
        // 执行查询并返回结果
        return database.query(
            getTableName(uri),                      // 根据 URI 映射表名
            projection,                             // 投影列
            filteredSelection,                      // 可能被追加了过滤条件
            selectionArgs,                          // 过滤参数
            null,                                   // groupBy
            null,                                   // having
            sortOrder                               // 排序
        )
    }
 
    // 判断是否为外部调用者
    private fun isExternalCaller(pkg: String): Boolean {
        // 如果调用方包名与自身不同，视为外部调用
        return pkg != context?.packageName           // 比较包名
    }
}

<provider
    android:name=".MyProvider"
    android:authorities="com.example.provider"
    android:exported="false"
    android:grantUriPermissions="true" />

val intent = Intent(Intent.ACTION_VIEW)
intent.setDataAndType(uri, "image/png")
intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
startActivity(intent)

// ContentObserver 的构造需要传入一个 Handler
// 该 Handler 决定了 onChange 回调在哪个线程执行
val observer = object : ContentObserver(handler) {
    override fun onChange(selfChange: Boolean) {
        // selfChange: 表示是否是"自身"触发的变更（通常为 false）
        // 此回调运行在构造时传入的 Handler 所在的线程
    }
}

// === 注册观察者 ===
contentResolver.registerContentObserver(
    uri,                // 要监听的 Content URI
    notifyForDescendants, // 是否监听子 URI 的变化
    observer            // ContentObserver 实例
)
 
// === 注销观察者 ===
contentResolver.unregisterContentObserver(observer)

class MyObserver(handler: Handler) : ContentObserver(handler) {
 
    // === 最基础的重载（API 1+）===
    // 只知道"有变化发生"，不知道具体是哪个 URI 变了
    override fun onChange(selfChange: Boolean) {
        super.onChange(selfChange)
        // selfChange: 如果是自身操作触发的变更，为 true
        // 实际开发中这个参数几乎总是 false，少有实用价值
    }
 
    // === 带 URI 的重载（API 16+）===
    // 能知道具体是哪个 URI 发生了变化
    override fun onChange(selfChange: Boolean, uri: Uri?) {
        super.onChange(selfChange, uri)
        // uri: 发生变化的具体 URI
        // 例如可以据此判断是 users/42 还是 users/99 发生了变化
        // 从而做更精确的局部刷新，而非全量重新查询
    }
 
    // === 带 URI 和 flags 的重载（API 30+）===
    // 除了 URI，还能知道变化的类型（插入/更新/删除）
    override fun onChange(selfChange: Boolean, uri: Uri?, flags: Int) {
        super.onChange(selfChange, uri, flags)
        // flags 可能的值：
        // ContentResolver.NOTIFY_INSERT  (1) — 数据被插入
        // ContentResolver.NOTIFY_UPDATE  (2) — 数据被更新
        // ContentResolver.NOTIFY_DELETE  (4) — 数据被删除
        // 可通过位运算判断具体类型
    }
 
    // === 批量 URI 变更的重载（API 30+）===
    // 一次通知可能涉及多个 URI 的变化
    override fun onChange(
        selfChange: Boolean,
        uris: Collection<Uri>,  // 变化的 URI 集合
        flags: Int              // 变化类型 flags
    ) {
        super.onChange(selfChange, uris, flags)
        // 适用于批量操作（如 applyBatch）一次性变更多条数据的场景
        // 避免为每个 URI 单独触发一次 onChange
    }
}

class ContactListActivity : AppCompatActivity() {
 
    // 声明观察者为成员变量，以便在 onDestroy 中注销
    private lateinit var contactObserver: ContentObserver
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_contact_list)
 
        // 创建 ContentObserver，绑定到主线程 Handler
        // 这样 onChange 回调会在主线程执行
        contactObserver = object : ContentObserver(Handler(Looper.getMainLooper())) {
 
            // 重写带 URI 参数的版本，获取变更的具体 URI
            override fun onChange(selfChange: Boolean, uri: Uri?) {
                super.onChange(selfChange, uri)
                // 日志记录，方便调试
                Log.d("ContactObserver", "联系人数据变化，URI: $uri")
                // 触发异步重新查询联系人列表
                // 注意：不要在这里直接执行同步 query，因为当前在主线程
                refreshContactListAsync()
            }
        }
 
        // 注册观察者，监听联系人表级 URI
        // notifyForDescendants = true: 任何联系人子 URI 变更都会触发
        // （如某个具体联系人 content://com.android.contacts/contacts/123 的变更）
        contentResolver.registerContentObserver(
            ContactsContract.Contacts.CONTENT_URI, // 联系人表的 Content URI
            true,                                   // 监听所有后代 URI
            contactObserver                         // 观察者实例
        )
 
        // 初始加载联系人列表
        refreshContactListAsync()
    }
 
    // 异步查询联系人数据并刷新 UI
    private fun refreshContactListAsync() {
        // 使用协程在 IO 线程执行查询
        lifecycleScope.launch {
            val contacts = withContext(Dispatchers.IO) {
                // 在 IO 线程执行 ContentResolver 查询
                loadContactsFromProvider()
            }
            // 切回主线程更新 UI
            updateRecyclerView(contacts)
        }
    }
 
    override fun onDestroy() {
        super.onDestroy()
        // 必须注销观察者，否则会导致内存泄漏
        // 因为 ContentService 持有观察者的 Binder 引用
        contentResolver.unregisterContentObserver(contactObserver)
    }
}

class UserProvider : ContentProvider() {
 
    // 数据库帮助类实例
    private lateinit var dbHelper: UserDbHelper
 
    override fun insert(uri: Uri, values: ContentValues?): Uri? {
        // 获取可写数据库实例
        val db = dbHelper.writableDatabase
 
        // 通过 UriMatcher 判断请求的目标表
        val id: Long = when (uriMatcher.match(uri)) {
            CODE_USERS -> {
                // 向 users 表插入一行数据，返回新行的 rowId
                db.insert("users", null, values)
            }
            else -> throw IllegalArgumentException("不支持的 URI: $uri")
        }
 
        // 如果插入成功（id != -1），构建新行的 URI 并发出通知
        if (id != -1L) {
            // 构建新插入行的 URI，例如 content://com.example/users/42
            val newUri = ContentUris.withAppendedId(uri, id)
 
            // ★★★ 核心：通知所有监听该 URI 的观察者 ★★★
            // context 不可能为 null（Provider 已经被系统初始化）
            context?.contentResolver?.notifyChange(newUri, null)
 
            // 返回新行的 URI
            return newUri
        }
 
        // 插入失败返回 null
        return null
    }
 
    override fun update(uri: Uri, values: ContentValues?,
                        selection: String?, selectionArgs: Array<String>?): Int {
        val db = dbHelper.writableDatabase
        // 执行更新操作
        val rowsAffected = db.update("users", values, selection, selectionArgs)
 
        // 只有在确实有行被更新时才发出通知
        // 避免无意义的通知导致观察者做不必要的刷新
        if (rowsAffected > 0) {
            context?.contentResolver?.notifyChange(uri, null)
        }
 
        // 返回受影响的行数
        return rowsAffected
    }
 
    override fun delete(uri: Uri, selection: String?,
                        selectionArgs: Array<String>?): Int {
        val db = dbHelper.writableDatabase
        // 执行删除操作
        val rowsDeleted = db.delete("users", selection, selectionArgs)
 
        // 同样，只有在确实有行被删除时才通知
        if (rowsDeleted > 0) {
            context?.contentResolver?.notifyChange(uri, null)
        }
 
        // 返回被删除的行数
        return rowsDeleted
    }
}

// === 最基本的版本 ===
contentResolver.notifyChange(
    uri: Uri,              // 发生变化的数据 URI
    observer: ContentObserver? // 要排除通知的观察者（通常传 null）
)
 
// === 带 syncToNetwork 的版本 ===
contentResolver.notifyChange(
    uri: Uri,
    observer: ContentObserver?,
    syncToNetwork: Boolean  // 是否触发网络同步（SyncAdapter 机制）
)
 
// === API 30+ 带 flags 的版本 ===
contentResolver.notifyChange(
    uri: Uri,
    observer: ContentObserver?,
    flags: Int  // 通知标志位，可指定变更类型和同步行为
)

// API 30+ 示例：通知一条数据被插入，并且需要网络同步
contentResolver.notifyChange(
    newUri,                      // 新插入行的 URI
    null,                        // 不排除任何观察者
    ContentResolver.NOTIFY_INSERT or  // 标记为"插入"类型
    ContentResolver.NOTIFY_SYNC_TO_NETWORK // 同时触发网络同步
)

// 场景演示：不同注册方式的观察者收到通知的情况
 
// 观察者 A：监听整个 users 表，启用后代匹配
contentResolver.registerContentObserver(
    Uri.parse("content://com.example/users"), // 表级 URI
    true,     // notifyForDescendants = true
    observerA // 观察者 A
)
 
// 观察者 B：只精确监听 users 表级 URI
contentResolver.registerContentObserver(
    Uri.parse("content://com.example/users"), // 同样是表级 URI
    false,    // notifyForDescendants = false
    observerB // 观察者 B
)
 
// 观察者 C：精确监听 users/42
contentResolver.registerContentObserver(
    Uri.parse("content://com.example/users/42"), // 行级 URI
    false,    // notifyForDescendants = false
    observerC // 观察者 C
)
 
// --- 当 Provider 发出以下通知时 ---
 
// 通知1：notifyChange("content://com.example/users/42")
// 观察者 A → 触发 ✅ （祖先 URI + descendant=true）
// 观察者 B → 不触发 ❌ （祖先 URI 但 descendant=false，不匹配子路径）
// 观察者 C → 触发 ✅ （精确匹配）
 
// 通知2：notifyChange("content://com.example/users")
// 观察者 A → 触发 ✅ （精确匹配）
// 观察者 B → 触发 ✅ （精确匹配）
// 观察者 C → 不触发 ❌ （通知不向下传播到子 URI）