张昌盛 202201002062

src/Notes-master/src/net/micode/notes/tool/BackupUtils.java

@@ -35,57 +35,66 @@ import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.PrintStream;
 
-
+// BackupUtils类用于处理笔记数据的备份相关功能，支持将笔记数据导出为文本格式等操作
 public class BackupUtils {
     private static final String TAG = "BackupUtils";
+      // 单例模式相关，用于保存唯一的BackupUtils实例
     // Singleton stuff
     private static BackupUtils sInstance;
-
+// 获取BackupUtils的单例实例，若不存在则创建新的实例
     public static synchronized BackupUtils getInstance(Context context) {
         if (sInstance == null) {
             sInstance = new BackupUtils(context);
         }
         return sInstance;
     }
-
+  /**
+     * 以下是用于表示备份或恢复状态的常量定义
+     */
+    // 当前外部存储（SD卡）未挂载的状态码
     /**
      * Following states are signs to represents backup or restore
      * status
      */
     // Currently, the sdcard is not mounted
     public static final int STATE_SD_CARD_UNMOUONTED           = 0;
+        // 备份文件不存在的状态码
     // The backup file not exist
     public static final int STATE_BACKUP_FILE_NOT_EXIST        = 1;
     // The data is not well formated, may be changed by other programs
+        // 数据格式不正确，可能被其他程序修改的状态码
     public static final int STATE_DATA_DESTROIED               = 2;
     // Some run-time exception which causes restore or backup fails
+    // 运行时出现异常导致备份或恢复失败的状态码
     public static final int STATE_SYSTEM_ERROR                 = 3;
     // Backup or restore success
+    // 备份或恢复成功的状态码
     public static final int STATE_SUCCESS                      = 4;
 
     private TextExport mTextExport;
-
+  // 私有构造函数，初始化时创建TextExport对象，用于文本导出相关操作
     private BackupUtils(Context context) {
         mTextExport = new TextExport(context);
     }
-
+// 判断外部存储（通常指SD卡）是否可用，通过比较外部存储状态与MEDIA_MOUNTED常量来判断
     private static boolean externalStorageAvailable() {
         return Environment.MEDIA_MOUNTED.equals(Environment.getExternalStorageState());
     }
-
+  // 调用TextExport的exportToText方法进行文本导出，并返回导出结果状态码
     public int exportToText() {
         return mTextExport.exportToText();
     }
-
+   // 获取导出的文本文件名，实际是通过TextExport对象获取其内部保存的文件名
     public String getExportedTextFileName() {
         return mTextExport.mFileName;
     }
-
+    // 获取导出的文本文件所在目录，通过TextExport对象获取其内部保存的文件目录
     public String getExportedTextFileDir() {
         return mTextExport.mFileDirectory;
     }
-
+ // TextExport内部类，主要负责具体的文本导出逻辑实现
     private static class TextExport {
+           // 查询笔记相关信息的投影数组，定义了要从数据库中获取的笔记字段
         private static final String[] NOTE_PROJECTION = {
                 NoteColumns.ID,
                 NoteColumns.MODIFIED_DATE,
@@ -98,7 +107,7 @@ public class BackupUtils {
         private static final int NOTE_COLUMN_MODIFIED_DATE = 1;
 
         private static final int NOTE_COLUMN_SNIPPET = 2;
-
+   // 查询笔记数据相关信息的投影数组，定义了要从数据库中获取的笔记数据字段
         private static final String[] DATA_PROJECTION = {
                 DataColumns.CONTENT,
                 DataColumns.MIME_TYPE,
@@ -116,6 +125,7 @@ public class BackupUtils {
 
         private static final int DATA_COLUMN_PHONE_NUMBER = 4;
 
+        // 用于格式化导出文本内容的字符串数组，通过资源获取，不同索引对应不同的格式化用途
         private final String [] TEXT_FORMAT;
         private static final int FORMAT_FOLDER_NAME          = 0;
         private static final int FORMAT_NOTE_DATE            = 1;
@@ -124,22 +134,25 @@ public class BackupUtils {
         private Context mContext;
         private String mFileName;
         private String mFileDirectory;
-
+ // 构造函数，初始化TEXT_FORMAT数组以及保存传入的上下文对象等信息
         public TextExport(Context context) {
             TEXT_FORMAT = context.getResources().getStringArray(R.array.format_for_exported_note);
             mContext = context;
             mFileName = "";
             mFileDirectory = "";
         }
-
+ // 根据传入的索引获取对应的格式化字符串
         private String getFormat(int id) {
             return TEXT_FORMAT[id];
         }
-
+ /**
+         * 将指定文件夹（通过folderId标识）中的笔记导出为文本格式，并写入到给定的PrintStream中
+         */
         /**
          * Export the folder identified by folder id to text
          */
         private void exportFolderToText(String folderId, PrintStream ps) {
+                       // 通过内容解析器查询属于该文件夹的笔记信息
             // Query notes belong to this folder
             Cursor notesCursor = mContext.getContentResolver().query(Notes.CONTENT_NOTE_URI,
                     NOTE_PROJECTION, NoteColumns.PARENT_ID + "=?", new String[] {
@@ -148,24 +161,29 @@ public class BackupUtils {
 
             if (notesCursor != null) {
                 if (notesCursor.moveToFirst()) {
-                    do {
+                    do {  // 格式化并打印笔记的最后修改日期
                         // Print note's last modified date
                         ps.println(String.format(getFormat(FORMAT_NOTE_DATE), DateFormat.format(
                                 mContext.getString(R.string.format_datetime_mdhm),
                                 notesCursor.getLong(NOTE_COLUMN_MODIFIED_DATE))));
+                                  // 获取当前笔记的ID，用于进一步查询该笔记相关的数据信息并导出
                         // Query data belong to this note
                         String noteId = notesCursor.getString(NOTE_COLUMN_ID);
                         exportNoteToText(noteId, ps);
                     } while (notesCursor.moveToNext());
                 }
+                    // 关闭游标，释放资源
                 notesCursor.close();
             }
         }
-
+ /**
+         * 将指定ID的笔记导出为文本格式，并写入到给定的PrintStream中
+         */
         /**
          * Export note identified by id to a print stream
          */
         private void exportNoteToText(String noteId, PrintStream ps) {
+            // 通过内容解析器查询属于该笔记的相关数据信息
             Cursor dataCursor = mContext.getContentResolver().query(Notes.CONTENT_DATA_URI,
                     DATA_PROJECTION, DataColumns.NOTE_ID + "=?", new String[] {
                         noteId
@@ -174,6 +192,7 @@ public class BackupUtils {
             if (dataCursor != null) {
                 if (dataCursor.moveToFirst()) {
                     do {
+                         // 获取电话号码并打印（如果非空）
                         String mimeType = dataCursor.getString(DATA_COLUMN_MIME_TYPE);
                         if (DataConstants.CALL_NOTE.equals(mimeType)) {
                             // Print phone number
@@ -185,10 +204,12 @@ public class BackupUtils {
                                 ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT),
                                         phoneNumber));
                             }
+                             // 格式化并打印通话日期
                             // Print call date
                             ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT), DateFormat
                                     .format(mContext.getString(R.string.format_datetime_mdhm),
                                             callDate)));
+                                              // 打印通话附件位置（如果非空）
                             // Print call attachment location
                             if (!TextUtils.isEmpty(location)) {
                                 ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT),
@@ -203,8 +224,10 @@ public class BackupUtils {
                         }
                     } while (dataCursor.moveToNext());
                 }
+                   // 关闭游标，释放资源
                 dataCursor.close();
             }
+                   // 在每个笔记内容之间写入换行符，用于分隔不同笔记内容
             // print a line separator between note
             try {
                 ps.write(new byte[] {
@@ -214,11 +237,14 @@ public class BackupUtils {
                 Log.e(TAG, e.toString());
             }
         }
-
+ /**
+         * 执行将笔记导出为用户可读的文本格式的主要逻辑，整合了文件夹和笔记的导出操作
+         */
         /**
          * Note will be exported as text which is user readable
          */
         public int exportToText() {
+               // 首先判断外部存储是否可用，如果不可用则返回对应状态码并记录日志
             if (!externalStorageAvailable()) {
                 Log.d(TAG, "Media was not mounted");
                 return STATE_SD_CARD_UNMOUONTED;
@@ -229,6 +255,7 @@ public class BackupUtils {
                 Log.e(TAG, "get print stream error");
                 return STATE_SYSTEM_ERROR;
             }
+             // 第一步：查询并导出文件夹（特定条件筛选的文件夹，如通话记录文件夹等）及其内部笔记信息
             // First export folder and its notes
             Cursor folderCursor = mContext.getContentResolver().query(
                     Notes.CONTENT_NOTE_URI,
@@ -253,10 +280,10 @@ public class BackupUtils {
                         String folderId = folderCursor.getString(NOTE_COLUMN_ID);
                         exportFolderToText(folderId, ps);
                     } while (folderCursor.moveToNext());
-                }
+                } // 关闭游标，释放资源
                 folderCursor.close();
             }
-
+ // 第二步：查询并导出根文件夹下的笔记信息
             // Export notes in root's folder
             Cursor noteCursor = mContext.getContentResolver().query(
                     Notes.CONTENT_NOTE_URI,
@@ -274,14 +301,16 @@ public class BackupUtils {
                         String noteId = noteCursor.getString(NOTE_COLUMN_ID);
                         exportNoteToText(noteId, ps);
                     } while (noteCursor.moveToNext());
-                }
+                }   // 关闭游标，释放资源
                 noteCursor.close();
             }
             ps.close();
-
+   // 关闭PrintStream，完成文件写入操作
             return STATE_SUCCESS;
         }
-
+ /**
+         * 获取一个指向要导出的文本文件的PrintStream对象，用于后续写入导出内容
+         */
         /**
          * Get a print stream pointed to the file {@generateExportedTextFile}
          */
@@ -308,7 +337,9 @@ public class BackupUtils {
             return ps;
         }
     }
-
+ /**
+     * 在外部存储（SD卡）上生成用于存储导入数据的文本文件，如果生成过程出现异常则返回null
+     */
     /**
      * Generate the text file to store imported data
      */

src/Notes-master/src/net/micode/notes/tool/DataUtils.java

@@ -33,88 +33,118 @@ import net.micode.notes.ui.NotesListAdapter.AppWidgetAttribute;
 
 import java.util.ArrayList;
 import java.util.HashSet;
+// DataUtils类提供了一系列与笔记数据操作相关的实用方法，例如批量删除笔记、移动笔记到文件夹、查询各种数据状态等
 
 
 public class DataUtils {
     public static final String TAG = "DataUtils";
+      // 批量删除给定ID集合对应的笔记，跳过系统根文件夹（Notes.ID_ROOT_FOLDER）的删除操作
     public static boolean batchDeleteNotes(ContentResolver resolver, HashSet<Long> ids) {
+         // 如果传入的ID集合为null，记录日志并返回true，表示无需执行删除操作
         if (ids == null) {
             Log.d(TAG, "the ids is null");
             return true;
-        }
+        }// 如果ID集合为空，记录日志并返回true，表示没有要删除的笔记
         if (ids.size() == 0) {
             Log.d(TAG, "no id is in the hashset");
             return true;
         }
-
+ // 用于存储一系列内容提供器操作的列表，后续将批量执行这些操作来删除笔记
         ArrayList<ContentProviderOperation> operationList = new ArrayList<ContentProviderOperation>();
         for (long id : ids) {
+             // 不允许删除系统根文件夹，若当前ID是系统根文件夹ID，则记录错误日志并跳过该ID的删除操作
             if(id == Notes.ID_ROOT_FOLDER) {
                 Log.e(TAG, "Don't delete system folder root");
                 continue;
-            }
+            } // 创建一个用于删除指定笔记的内容提供器操作构建器，指定要删除的笔记的URI（通过ID构建）
             ContentProviderOperation.Builder builder = ContentProviderOperation
                     .newDelete(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id));
+                       // 将构建好的操作添加到操作列表中
             operationList.add(builder.build());
         }
         try {
+              // 批量应用内容提供器操作列表，执行删除笔记的操作，并获取操作结果数组
             ContentProviderResult[] results = resolver.applyBatch(Notes.AUTHORITY, operationList);
+             // 如果结果数组为null，或者长度为0，或者第一个结果为null，表示删除笔记失败，记录日志并返回false
+    
             if (results == null || results.length == 0 || results[0] == null) {
                 Log.d(TAG, "delete notes failed, ids:" + ids.toString());
                 return false;
             }
+              // 如果成功执行删除操作，返回true
             return true;
         } catch (RemoteException e) {
+               // 捕获远程异常，记录详细的错误日志（包含异常的toString和getMessage信息）
             Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage()));
         } catch (OperationApplicationException e) {
+             // 捕获操作应用异常，记录详细的错误日志（包含异常的toString和getMessage信息）
             Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage()));
         }
         return false;
     }
-
+    // 将指定ID的笔记从源文件夹移动到目标文件夹，通过更新笔记的相关字段来实现移动操作
     public static void moveNoteToFoler(ContentResolver resolver, long id, long srcFolderId, long desFolderId) {
+        // 创建一个ContentValues对象，用于存储要更新的字段和对应的值
         ContentValues values = new ContentValues();
+          // 设置笔记的新父文件夹ID（目标文件夹ID）
         values.put(NoteColumns.PARENT_ID, desFolderId);
+         // 设置笔记的原始父文件夹ID（源文件夹ID）
         values.put(NoteColumns.ORIGIN_PARENT_ID, srcFolderId);
+          // 设置本地修改标志为1，表示该笔记有本地修改操作
         values.put(NoteColumns.LOCAL_MODIFIED, 1);
+         // 通过内容解析器更新指定笔记（根据ID确定）的相关字段信息
         resolver.update(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id), values, null, null);
     }
-
+ // 批量将给定ID集合中的笔记移动到指定的文件夹，通过构建一系列更新操作并批量执行来实现
     public static boolean batchMoveToFolder(ContentResolver resolver, HashSet<Long> ids,
             long folderId) {
+                // 如果传入的ID集合为null，记录日志并返回true，表示无需执行移动操作
         if (ids == null) {
             Log.d(TAG, "the ids is null");
             return true;
         }
-
+ // 用于存储一系列内容提供器操作的列表，后续将批量执行这些操作来移动笔记
         ArrayList<ContentProviderOperation> operationList = new ArrayList<ContentProviderOperation>();
         for (long id : ids) {
+             // 创建一个用于更新指定笔记的内容提供器操作构建器，指定要更新的笔记的URI（通过ID构建）
             ContentProviderOperation.Builder builder = ContentProviderOperation
                     .newUpdate(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id));
+                     // 设置笔记的新父文件夹ID（目标文件夹ID）
             builder.withValue(NoteColumns.PARENT_ID, folderId);
+                 // 设置本地修改标志为1，表示该笔记有本地修改操作
             builder.withValue(NoteColumns.LOCAL_MODIFIED, 1);
+                  // 将构建好的操作添加到操作列表中
             operationList.add(builder.build());
         }
 
         try {
+             // 批量应用内容提供器操作列表，执行移动笔记的操作，并获取操作结果数组
             ContentProviderResult[] results = resolver.applyBatch(Notes.AUTHORITY, operationList);
+             // 如果结果数组为null，或者长度为0，或者第一个结果为null，表示移动笔记失败，记录日志并返回false
             if (results == null || results.length == 0 || results[0] == null) {
                 Log.d(TAG, "delete notes failed, ids:" + ids.toString());
                 return false;
             }
+             // 如果成功执行移动操作，返回true
             return true;
         } catch (RemoteException e) {
+             // 捕获远程异常，记录详细的错误日志（包含异常的toString和getMessage信息）
             Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage()));
         } catch (OperationApplicationException e) {
+            // 捕获操作应用异常，记录详细的错误日志（包含异常的toString和getMessage信息）
             Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage()));
         }
         return false;
     }
-
+   /**
+     * 获取除系统文件夹（{@link Notes#TYPE_SYSTEM}类型的文件夹）之外的所有文件夹数量，通过数据库查询统计符合条件的文件夹数量
+     */
     /**
      * Get the all folder count except system folders {@link Notes#TYPE_SYSTEM}}
      */
     public static int getUserFolderCount(ContentResolver resolver) {
+         // 执行数据库查询，从Notes.CONTENT_NOTE_URI对应的表中查询符合条件的文件夹数量，
+        // 查询条件是文件夹类型为普通文件夹（Notes.TYPE_FOLDER）且父文件夹ID不是回收站文件夹ID（Notes.ID_TRASH_FOLER）
         Cursor cursor =resolver.query(Notes.CONTENT_NOTE_URI,
                 new String[] { "COUNT(*)" },
                 NoteColumns.TYPE + "=? AND " + NoteColumns.PARENT_ID + "<>?",
@@ -125,18 +155,23 @@ public class DataUtils {
         if(cursor != null) {
             if(cursor.moveToFirst()) {
                 try {
+                     // 尝试从查询结果游标中获取第一列（即统计的数量值）并赋值给count变量
                     count = cursor.getInt(0);
                 } catch (IndexOutOfBoundsException e) {
+                     // 若获取数据时出现越界异常，记录错误日志
                     Log.e(TAG, "get folder count failed:" + e.toString());
                 } finally {
+                       // 无论是否出现异常，都关闭游标，释放资源
                     cursor.close();
                 }
             }
         }
         return count;
     }
-
+ // 检查指定ID和类型的笔记是否在笔记数据库中可见（不在回收站文件夹中），通过查询数据库判断是否存在符合条件的笔记
+ 
     public static boolean visibleInNoteDatabase(ContentResolver resolver, long noteId, int type) {
+         // 执行数据库查询，从Notes.CONTENT_NOTE_URI对应的表中查询指定ID和类型且不在回收站文件夹中的笔记是否存在
         Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId),
                 null,
                 NoteColumns.TYPE + "=? AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER,
@@ -145,60 +180,73 @@ public class DataUtils {
 
         boolean exist = false;
         if (cursor != null) {
+             // 如果查询结果游标中的记录数量大于0，表示存在符合条件的笔记，将exist设为true
             if (cursor.getCount() > 0) {
                 exist = true;
             }
+             // 关闭游标，释放资源
             cursor.close();
         }
         return exist;
     }
-
+// 检查指定ID的笔记是否存在于笔记数据库中，通过简单查询判断是否有对应记录
     public static boolean existInNoteDatabase(ContentResolver resolver, long noteId) {
-        Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId),
+         // 执行数据库查询，从Notes.CONTENT_NOTE_URI对应的表中查询指定ID的笔记是否存在，无其他额外查询条件
+     Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId),
                 null, null, null, null);
 
         boolean exist = false;
         if (cursor != null) {
+             // 如果查询结果游标中的记录数量大于0，表示存在符合条件的笔记，将exist设为true
             if (cursor.getCount() > 0) {
                 exist = true;
             }
+               // 关闭游标，释放资源
             cursor.close();
         }
         return exist;
     }
-
+ // 检查指定ID的数据是否存在于数据数据库中（此处指与笔记相关的数据，例如可能是附件等数据），通过查询判断是否有对应记录
+    
     public static boolean existInDataDatabase(ContentResolver resolver, long dataId) {
+        // 执行数据库查询，从Notes.CONTENT_DATA_URI对应的表中查询指定ID的数据是否存在，无其他额外查询条件
         Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_DATA_URI, dataId),
                 null, null, null, null);
 
         boolean exist = false;
         if (cursor != null) {
+              // 如果查询结果游标中的记录数量大于0，表示存在符合条件的数据，将exist设为true
             if (cursor.getCount() > 0) {
                 exist = true;
             }
+                   // 关闭游标，释放资源
             cursor.close();
         }
         return exist;
     }
-
+ // 检查指定名称的文件夹是否在可见文件夹中（非系统文件夹且不在回收站文件夹中），通过查询数据库判断是否存在符合条件的文件夹
     public static boolean checkVisibleFolderName(ContentResolver resolver, String name) {
-        Cursor cursor = resolver.query(Notes.CONTENT_NOTE_URI, null,
+        // 执行数据库查询，从Notes.CONTENT_NOTE_URI对应的表中查询指定名称、类型为文件夹且不在回收站文件夹中的文件夹是否存在
+    Cursor cursor = resolver.query(Notes.CONTENT_NOTE_URI, null,
                 NoteColumns.TYPE + "=" + Notes.TYPE_FOLDER +
                 " AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER +
                 " AND " + NoteColumns.SNIPPET + "=?",
                 new String[] { name }, null);
         boolean exist = false;
         if(cursor != null) {
+              // 如果查询结果游标中的记录数量大于0，表示存在符合条件的文件夹，将exist设为true
             if(cursor.getCount() > 0) {
                 exist = true;
             }
+             // 关闭游标，释放资源
             cursor.close();
         }
         return exist;
     }
-
+ // 获取指定文件夹下所有笔记对应的小部件属性集合，通过查询数据库获取相关信息并构建属性集合
     public static HashSet<AppWidgetAttribute> getFolderNoteWidget(ContentResolver resolver, long folderId) {
-        Cursor c = resolver.query(Notes.CONTENT_NOTE_URI,
+        // 执行数据库查询，从Notes.CONTENT_NOTE_URI对应的表中查询指定文件夹下笔记的小部件ID和小部件类型信息
+         Cursor c = resolver.query(Notes.CONTENT_NOTE_URI,
                 new String[] { NoteColumns.WIDGET_ID, NoteColumns.WIDGET_TYPE },
                 NoteColumns.PARENT_ID + "=?",
                 new String[] { String.valueOf(folderId) },
@@ -210,40 +258,48 @@ public class DataUtils {
                 set = new HashSet<AppWidgetAttribute>();
                 do {
                     try {
+                        // 构建一个AppWidgetAttribute对象，用于存储小部件的属性信息
                         AppWidgetAttribute widget = new AppWidgetAttribute();
+                                 // 从查询结果游标中获取小部件ID并赋值给widget对象的对应属性
                         widget.widgetId = c.getInt(0);
+                         // 从查询结果游标中获取小部件类型并赋值给widget对象的对应属性
                         widget.widgetType = c.getInt(1);
+                          // 将构建好的widget对象添加到属性集合中
                         set.add(widget);
                     } catch (IndexOutOfBoundsException e) {
+                                   // 若获取数据时出现越界异常，记录错误日志
                         Log.e(TAG, e.toString());
                     }
                 } while (c.moveToNext());
-            }
+            }        // 关闭游标，释放资源
             c.close();
         }
         return set;
-    }
+    }   // 根据笔记ID获取对应的电话号码（从通话记录相关的笔记数据中获取），通过数据库查询获取电话号码信息
 
     public static String getCallNumberByNoteId(ContentResolver resolver, long noteId) {
-        Cursor cursor = resolver.query(Notes.CONTENT_DATA_URI,
+         // 执行数据库查询，从Notes.CONTENT_DATA_URI对应的表中查询指定笔记ID且类型为通话记录相关的电话号码信息
+       Cursor cursor = resolver.query(Notes.CONTENT_DATA_URI,
                 new String [] { CallNote.PHONE_NUMBER },
                 CallNote.NOTE_ID + "=? AND " + CallNote.MIME_TYPE + "=?",
                 new String [] { String.valueOf(noteId), CallNote.CONTENT_ITEM_TYPE },
                 null);
 
         if (cursor != null && cursor.moveToFirst()) {
-            try {
+            try {      // 尝试从查询结果游标中获取电话号码字符串并返回
                 return cursor.getString(0);
-            } catch (IndexOutOfBoundsException e) {
+            } catch (IndexOutOfBoundsException e) {        // 若获取数据时出现越界异常，记录错误日志
                 Log.e(TAG, "Get call number fails " + e.toString());
-            } finally {
+            } finally {           // 关闭游标，释放资源
                 cursor.close();
             }
         }
         return "";
     }
 
+   // 根据电话号码和通话日期获取对应的笔记ID（从通话记录相关数据中查找匹配的笔记），通过数据库查询获取笔记ID信息
     public static long getNoteIdByPhoneNumberAndCallDate(ContentResolver resolver, String phoneNumber, long callDate) {
+         // 执行数据库查询，从Notes.CONTENT_DATA_URI对应的表中查询指定电话号码、通话日期且类型为通话记录相关的笔记ID信息
         Cursor cursor = resolver.query(Notes.CONTENT_DATA_URI,
                 new String [] { CallNote.NOTE_ID },
                 CallNote.CALL_DATE + "=? AND " + CallNote.MIME_TYPE + "=? AND PHONE_NUMBERS_EQUAL("
@@ -253,18 +309,19 @@ public class DataUtils {
 
         if (cursor != null) {
             if (cursor.moveToFirst()) {
-                try {
+                try { // 尝试从查询结果游标中获取笔记ID并返回
                     return cursor.getLong(0);
-                } catch (IndexOutOfBoundsException e) {
+                } catch (IndexOutOfBoundsException e) {  // 若获取数据时出现越界异常，记录错误日志
                     Log.e(TAG, "Get call note id fails " + e.toString());
                 }
-            }
+            }  // 关闭游标，释放资源
             cursor.close();
         }
         return 0;
     }
-
+    // 根据笔记ID获取对应的摘要信息（通常是笔记的简短描述等内容），通过数据库查询获取摘要字符串
     public static String getSnippetById(ContentResolver resolver, long noteId) {
+          // 执行数据库查询，从Notes.CONTENT_NOTE_URI对应的表中查询指定笔记ID的摘要信息
         Cursor cursor = resolver.query(Notes.CONTENT_NOTE_URI,
                 new String [] { NoteColumns.SNIPPET },
                 NoteColumns.ID + "=?",
@@ -272,16 +329,18 @@ public class DataUtils {
                 null);
 
         if (cursor != null) {
+                // 若查询到结果，从游标中获取摘要字符串
             String snippet = "";
             if (cursor.moveToFirst()) {
                 snippet = cursor.getString(0);
             }
+                     // 关闭游标，释放资源
             cursor.close();
             return snippet;
-        }
+        }    // 如果查询失败（游标为null，表示没有找到对应笔记），抛出异常表示未找到指定ID的笔记
         throw new IllegalArgumentException("Note is not found with id: " + noteId);
     }
-
+// 对传入的摘要字符串进行格式化处理，去除两端空白字符，并截取到换行符之前的内容（如果有换行符）
     public static String getFormattedSnippet(String snippet) {
         if (snippet != null) {
             snippet = snippet.trim();

src/Notes-master/src/net/micode/notes/tool/GTaskStringUtils.java

@@ -15,99 +15,154 @@
  */
 
 package net.micode.notes.tool;
-
+// GTaskStringUtils类用于定义一系列与GTask操作、数据结构以及相关文件夹、元数据等有关的字符串常量。
+// 这些常量在涉及到GTask相关的JSON数据处理、文件夹标识和元数据管理等功能中会被使用到。
 public class GTaskStringUtils {
+ // 以下是与GTask JSON数据中动作（action）相关的字段名及对应动作类型值的常量定义
 
+    // JSON数据中表示动作（action）的唯一标识符的字段名，在整个操作流程中可用于区分不同的具体操作。
+    
     public final static String GTASK_JSON_ACTION_ID = "action_id";
-
+ // JSON数据中表示动作列表（action_list）的字段名，通常可能用来存放一组操作相关信息的集合，
+    // 比如包含多个具体操作的详细描述等内容。
     public final static String GTASK_JSON_ACTION_LIST = "action_list";
-
+// JSON数据中表示动作类型（action_type）的字段名，通过不同的值来区分具体是哪种操作行为，
+    // 例如创建、获取、移动、更新等操作。
     public final static String GTASK_JSON_ACTION_TYPE = "action_type";
-
+// JSON数据中表示创建（create）类型动作的具体值，当"action_type"字段取值为此常量时，
+    // 意味着对应的操作是创建相关的数据实体等操作。
     public final static String GTASK_JSON_ACTION_TYPE_CREATE = "create";
-
+// JSON数据中表示获取全部（get_all）类型动作的具体值，用于指示要获取所有相关数据的操作，
+    // 比如获取所有任务、所有列表等情况。
     public final static String GTASK_JSON_ACTION_TYPE_GETALL = "get_all";
-
+ // JSON数据中表示移动（move）类型动作的具体值，表明对应的操作是将某个数据实体从一个位置移动到另一个位置，
+    // 例如移动任务到不同的列表等情况。
     public final static String GTASK_JSON_ACTION_TYPE_MOVE = "move";
-
+ // JSON数据中表示更新（update）类型动作的具体值，代表要对已存在的数据实体进行更新修改的操作，
+    // 像更新任务的名称、属性等操作会用到此标识。
     public final static String GTASK_JSON_ACTION_TYPE_UPDATE = "update";
-
+// JSON数据中表示创建者（creator）的ID字段名，可用于确定执行创建操作的具体用户或者相关主体的唯一标识，
+    // 在涉及多用户或者多来源数据创建时，可借此追踪创建源头
     public final static String GTASK_JSON_CREATOR_ID = "creator_id";
-
+  // JSON数据中表示子实体（child_entity）的字段名，可能用于描述某个主实体下包含的子级相关的数据结构，
+    // 例如一个任务列表下包含的多个子任务等情况可以通过此字段来关联和表示。
     public final static String GTASK_JSON_CHILD_ENTITY = "child_entity";
-
+// JSON数据中表示客户端版本（client_version）的字段名，主要用于记录使用该GTask相关功能的客户端应用的版本信息，
+    // 在数据同步、兼容性处理等场景中可根据此版本信息来判断是否支持某些操作或进行相应的适配。
     public final static String GTASK_JSON_CLIENT_VERSION = "client_version";
-
+ // JSON数据中表示是否完成（completed）的字段名，常用于任务相关的数据中，用来标记某个任务是否已经完成，
+    // 例如任务完成状态的记录与判断会依赖于此字段。
     public final static String GTASK_JSON_COMPLETED = "completed";
-
+// JSON数据中表示当前列表（current_list_id）的ID字段名，可能用于标识当前操作所涉及的列表的唯一标识，
+    // 比如在任务移动操作中，可指明当前所在的列表以及要移动到的目标列表等情况。
     public final static String GTASK_JSON_CURRENT_LIST_ID = "current_list_id";
-
+  // JSON数据中表示默认列表（default_list_id）的ID字段名，用于指定某个默认的列表，
+    // 例如新创建任务时默认归属的列表等情况可以通过此标识来确定。
     public final static String GTASK_JSON_DEFAULT_LIST_ID = "default_list_id";
-
+ // JSON数据中表示是否已删除（deleted）的字段名，可用于标记某个数据实体是否已经被删除，
+    // 在数据清理、回收站相关功能或者同步时判断数据是否已不存在等场景中会用到。
     public final static String GTASK_JSON_DELETED = "deleted";
-
+// JSON数据中表示目标列表（dest_list）的字段名，常用于操作涉及到将数据移动或关联到其他列表的情况，
+    // 比如在移动任务操作中，此字段指明任务要移动到的目标列表的相关信息。
     public final static String GTASK_JSON_DEST_LIST = "dest_list";
-
+  // JSON数据中表示目标父级（dest_parent）的字段名，可用于表示某个数据实体在移动、关联等操作后的目标父级对象相关信息，
+    // 例如任务移动后所属的新的父任务或者父列表等情况通过此字段来体现。
     public final static String GTASK_JSON_DEST_PARENT = "dest_parent";
-
+ // JSON数据中表示目标父级类型（dest_parent_type）的字段名，配合"dest_parent"字段使用，
+    // 用于明确目标父级对象具体是什么类型，比如是任务组还是普通任务列表等类型区分。
     public final static String GTASK_JSON_DEST_PARENT_TYPE = "dest_parent_type";
-
+// JSON数据中表示实体变化量（entity_delta）的字段名，可能用于记录某个数据实体在更新、修改等操作前后的变化差异情况，
+    // 例如任务的某些属性值发生了改变，通过此字段可以详细记录具体的变化内容。
     public final static String GTASK_JSON_ENTITY_DELTA = "entity_delta";
-
+ // JSON数据中表示实体类型（entity_type）的字段名，用于区分不同的数据实体类型，
+    // 像任务（TASK）、任务组（GROUP）等不同类型的数据实体可以通过此字段来标识区分。
     public final static String GTASK_JSON_ENTITY_TYPE = "entity_type";
-
+  // JSON数据中表示获取已删除数据（get_deleted）的字段名，可能用于发起获取已被标记为删除的数据的相关操作，
+    // 比如在回收站功能或者数据同步时，查看哪些数据已被删除等情况会用到。
     public final static String GTASK_JSON_GET_DELETED = "get_deleted";
-
+   // JSON数据中表示数据实体的唯一标识符（id）的字段名，用于唯一确定某个具体的数据实体，
+    // 无论是任务、列表还是其他相关数据结构，都可以通过此ID进行查找、关联等操作。
     public final static String GTASK_JSON_ID = "id";
-
+   // JSON数据中表示索引（index）的字段名，可用于在有序的数据集合（如任务列表等）中确定某个数据实体的位置顺序，
+    // 例如在排序、定位特定位置的任务等场景中会使用到。
     public final static String GTASK_JSON_INDEX = "index";
-
+ // JSON数据中表示最后修改时间（last_modified）的字段名，用于记录某个数据实体最后一次被修改的时间戳，
+    // 在数据同步、版本控制以及判断数据是否有更新等场景中，此时间信息非常关键。
     public final static String GTASK_JSON_LAST_MODIFIED = "last_modified";
-
+  // JSON数据中表示最新同步点（latest_sync_point）的字段名，用于标记在数据同步过程中的最新有效同步位置或者时间点，
+    // 可帮助确定下次同步从何处开始、哪些数据需要重新同步等情况。
     public final static String GTASK_JSON_LATEST_SYNC_POINT = "latest_sync_point";
-
+// JSON数据中表示列表（list_id）的ID字段名，用于唯一标识不同的列表，
+    // 在涉及到多个列表管理、任务在不同列表间移动等操作时，通过此ID来区分不同的列表。
     public final static String GTASK_JSON_LIST_ID = "list_id";
-
+   // JSON数据中表示列表（lists）的字段名，通常可能用来存放多个列表相关信息的集合，
+    // 例如获取所有列表信息或者返回一组列表数据时，可通过此字段进行表示。
     public final static String GTASK_JSON_LISTS = "lists";
-
+  // JSON数据中表示名称（name）的字段名，常用于表示数据实体（如任务、列表等）的名称属性，
+    // 方便展示、查找以及用户识别不同的数据实体。
     public final static String GTASK_JSON_NAME = "name";
 
+    // JSON数据中表示新的标识符（new_id）的字段名，可能在某些操作（如数据复制、克隆或者重新生成ID等情况）下，
+    // 用于标记新产生的数据实体的唯一标识。
     public final static String GTASK_JSON_NEW_ID = "new_id";
-
+ // JSON数据中表示笔记（notes）的字段名，可能用于存放与任务、列表等相关的笔记信息，
+    // 比如用户针对某个任务添加的备注、说明等内容可通过此字段关联存储。
     public final static String GTASK_JSON_NOTES = "notes";
-
+  // JSON数据中表示父级ID（parent_id）的字段名，用于确定某个数据实体所属的父级对象的唯一标识，
+    // 例如任务所属的任务组或者列表的ID等情况通过此字段关联表示。
     public final static String GTASK_JSON_PARENT_ID = "parent_id";
-
+ // JSON数据中表示前一个兄弟节点ID（prior_sibling_id）的字段名，在有序的数据结构（如任务列表按顺序排列）中，
+    // 可用于定位某个数据实体前一个相邻的兄弟节点的标识，方便进行顺序调整、插入等操作。
     public final static String GTASK_JSON_PRIOR_SIBLING_ID = "prior_sibling_id";
-
+  // JSON数据中表示操作结果（results）的字段名，常用于存放执行某个操作（如创建、更新、移动等操作）后的返回结果信息，
+    // 比如操作是否成功、返回的数据等情况通过此字段进行传递和展示。
     public final static String GTASK_JSON_RESULTS = "results";
-
+   // JSON数据中表示源列表（source_list）的字段名，在涉及数据移动、复制等操作时，
+    // 用于指明操作数据的原始来源列表的相关信息，与目标列表（dest_list）相对应。
     public final static String GTASK_JSON_SOURCE_LIST = "source_list";
-
+   // JSON数据中表示任务（tasks）的字段名，通常用于存放一组任务相关信息的集合，
+    // 比如获取所有任务列表、返回一批任务数据等情况会通过此字段来表示。
     public final static String GTASK_JSON_TASKS = "tasks";
 
+    // JSON数据中表示类型（type）的字段名，和前面提到的"entity_type"类似，用于区分不同的数据实体类型，
+    // 不过可能使用场景更通用一些，可用于各种需要区分类型的情况。
     public final static String GTASK_JSON_TYPE = "type";
-
+   // JSON数据中表示任务组（GROUP）类型的具体值，用于明确某个数据实体是任务组类型，
+    // 在通过"type"或者"entity_type"字段判断类型时，此常量可作为对应的值来标识任务组。
     public final static String GTASK_JSON_TYPE_GROUP = "GROUP";
-
+// JSON数据中表示任务（TASK）类型的具体值，用于确定某个数据实体是普通任务类型，
+    // 同样在类型判断场景中，以此常量来标识任务类型的数据实体。
     public final static String GTASK_JSON_TYPE_TASK = "TASK";
-
+  // JSON数据中表示用户（user）的字段名，可能用于存放与操作相关的用户信息，
+    // 比如操作执行者的用户名、用户ID等相关属性，便于记录操作的归属主体等情况。
     public final static String GTASK_JSON_USER = "user";
+ // 以下是与特定文件夹相关的字符串常量定义，可能用于标识不同功能或用途的文件夹
 
+    // 表示与MIUI笔记相关的文件夹前缀字符串，用于在文件夹命名或者标识中区分出属于MIUI笔记相关的文件夹，
+    // 方便进行针对性的处理或者识别。
     public final static String MIUI_FOLDER_PREFFIX = "[MIUI_Notes]";
-
+ // 表示默认文件夹的名称常量，可能用于指代某个默认创建或者默认使用的文件夹，
+    // 例如新笔记、新任务等默认存放的文件夹可以用此名称来表示。
     public final static String FOLDER_DEFAULT = "Default";
-
+ // 表示通话记录笔记相关的文件夹名称常量，用于专门存放与通话记录笔记相关内容的文件夹标识，
+    // 便于对通话记录相关笔记进行分类管理和查找等操作。
     public final static String FOLDER_CALL_NOTE = "Call_Note";
-
+// 表示元数据（METADATA）相关的文件夹名称常量，可能用于存放各种数据的元数据信息的文件夹，
+    // 在数据管理、备份恢复以及数据关联等场景中，此文件夹的元数据起着重要作用。
     public final static String FOLDER_META = "METADATA";
+ // 以下是与元数据头部相关的字段名常量定义，用于明确元数据中不同部分的标识
 
+    // 表示元数据中GTask的ID（meta_gid）的字段名，在元数据结构里用于存放与之关联的GTask的唯一标识信息，
+    // 可用于数据关联、同步以及根据GTask查找对应元数据等操作。
     public final static String META_HEAD_GTASK_ID = "meta_gid";
-
+// 表示元数据中笔记（meta_note）相关信息的字段名，可能用于存放具体的笔记内容或者笔记相关属性等元数据信息，
+    // 在处理笔记的元数据时，通过此字段来获取对应的笔记相关数据。
     public final static String META_HEAD_NOTE = "meta_note";
-
+// 表示元数据中其他数据（meta_data）相关信息的字段名，可用于存放除了前面特定标识之外的其他各种数据的元数据，
+    // 例如一些自定义的扩展数据、辅助数据等的元数据都可以通过此字段来表示和管理。
     public final static String META_HEAD_DATA = "meta_data";
-
+// 表示元数据中其他数据（meta_data）相关信息的字段名，可用于存放除了前面特定标识之外的其他各种数据的元数据，
+    // 例如一些自定义的扩展数据、辅助数据等的元数据都可以通过此字段来表示和管理。
     public final static String META_NOTE_NAME = "[META INFO] DON'T UPDATE AND DELETE";
 
 }