111

src/net/micode/notes/data/Contact.java

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 
-package net.micode.notes.data;//导入包
+package net.micode.notes.data;                                                                      //导入包
-
+// 导入所需的Android类和接口
 import android.content.Context;
 import android.database.Cursor;
 import android.provider.ContactsContract.CommonDataKinds.Phone;
@@ -23,50 +23,77 @@ import android.provider.ContactsContract.Data;
 import android.telephony.PhoneNumberUtils;
 import android.util.Log;
 
-import java.util.HashMap;
+import java.util.HashMap;                                                                       // 哈希映射，用于实现缓存
+
+/**
+ * 联系人查询工具类
+ * 功能：通过电话号码查询系统联系人姓名，并实现结果缓存
+ */
+public class Contact {                                                                         //创建类
+    private static HashMap<String, String> sContactCache;                                     // 静态缓存HashMap，使用volatile保证多线程可见性
+    private static final String TAG = "Contact";                                              // 日志标签，用于调试
 
-public class Contact {//创建类
+/**
-    private static HashMap<String, String> sContactCache;
+     * 联系人查询SQL条件语句（常量）
-    private static final String TAG = "Contact";
+     * 结构说明：
+     * 1. PHONE_NUMBERS_EQUAL 比较电话号码是否匹配
+     * 2. 限定数据类型为电话类型（MIMETYPE）
+     * 3. 通过子查询优化性能（phone_lookup表是系统提供的电话号码快速索引表）
+     * 注意：其中的'+'是占位符，会被实际的最小匹配长度替换
+     */
 
-    private static final String CALLER_ID_SELECTION = "PHONE_NUMBERS_EQUAL(" + Phone.NUMBER
+    private static final String CALLER_ID_SELECTION = "PHONE_NUMBERS_EQUAL(" + Phone.NUMBER // 电话号码比较函数
     + ",?) AND " + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'"
-    + " AND " + Data.RAW_CONTACT_ID + " IN "
+    + " AND " + Data.RAW_CONTACT_ID + " IN "                                                // 关联raw_contact_id
-            + "(SELECT raw_contact_id "
+            + "(SELECT raw_contact_id "                                                     // 子查询开始
-            + " FROM phone_lookup"
+            + " FROM phone_lookup"                                                          // 系统电话索引表
-            + " WHERE min_match = '+')";
+            + " WHERE min_match = '+')";                                                    // 占位符将被替换
+
+     /**
+     * 根据电话号码查询联系人姓名（主方法）
+     * @param context      上下文对象（必须非空）
+     * @param phoneNumber  要查询的电话号码（需标准格式）
+     * @return 联系人姓名，未找到返回null
+     * @throws IllegalArgumentException 如果参数为null
+     */
 
     public static String getContact(Context context, String phoneNumber) {
         //初始化缓存
         if(sContactCache == null) {
             sContactCache = new HashMap<String, String>();
         }
-        // 检查缓存
+        // 缓存检查：如果命中则直接返回（减少数据库查询）
         if(sContactCache.containsKey(phoneNumber)) {
-            return sContactCache.get(phoneNumber);
+            return sContactCache.get(phoneNumber);// 返回缓存值
         }
         // 动态生成查询条件：设置最小匹配长度
         String selection = CALLER_ID_SELECTION.replace("+",
                 PhoneNumberUtils.toCallerIDMinMatch(phoneNumber));
-        Cursor cursor = context.getContentResolver().query(
-                Data.CONTENT_URI,
-                new String [] { Phone.DISPLAY_NAME },
-                selection,
-                new String[] { phoneNumber },
-                null);
 
-        if (cursor != null && cursor.moveToFirst()) {
+        // 执行内容提供者查询：
+        // URI: Data.CONTENT_URI - 系统联系人数据URI
+        // 投影: 只查询DISPLAY_NAME列（节省资源）
+        // 参数: 将phoneNumber作为selectionArgs传入
+
+        Cursor cursor = context.getContentResolver().query(
+                Data.CONTENT_URI,// 联系人数据URI
+                new String [] { Phone.DISPLAY_NAME },// 只返回姓名列
+                selection,// 动态生成的查询条件
+                new String[] { phoneNumber },// 查询参数（实际电话号码）
+                null);// 不排序
+        // 处理查询结果
+        if (cursor != null && cursor.moveToFirst()) {// 检查游标有效性且有数据
             try {
-                String name = cursor.getString(0);
+                String name = cursor.getString(0);// 获取第一列（索引0）的数据
-                sContactCache.put(phoneNumber, name);
+                sContactCache.put(phoneNumber, name); // 更新缓存
                 return name;
             } catch (IndexOutOfBoundsException e) {
                 Log.e(TAG, " Cursor get string error " + e.toString());
                 return null;
-            } finally {
+            } finally {// 确保关闭游标（避免内存泄漏）
                 cursor.close();
             }
-        } else {
+        } else { // 未找到匹配联系人
             Log.d(TAG, "No contact matched with number:" + phoneNumber);
             return null;
         }