添加注释

MiNotes-master/app/src/main/java/net/micode/notes/gtask/remote/GTaskSyncService.java

@@ -23,54 +23,72 @@ import android.content.Intent;
 import android.os.Bundle;
 import android.os.IBinder;
 
+/**
+ * Google Tasks同步服务
+ * 负责在后台执行笔记与Google Tasks的同步操作，支持启动、取消同步，并通过广播通知UI同步状态
+ */
 public class GTaskSyncService extends Service {
-    public final static String ACTION_STRING_NAME = "sync_action_type";
-
-    public final static int ACTION_START_SYNC = 0;
-
-    public final static int ACTION_CANCEL_SYNC = 1;
-
-    public final static int ACTION_INVALID = 2;
-
-    public final static String GTASK_SERVICE_BROADCAST_NAME = "net.micode.notes.gtask.remote.gtask_sync_service";
-
-    public final static String GTASK_SERVICE_BROADCAST_IS_SYNCING = "isSyncing";
-
-    public final static String GTASK_SERVICE_BROADCAST_PROGRESS_MSG = "progressMsg";
-
-    private static GTaskASyncTask mSyncTask = null;
-
-    private static String mSyncProgress = "";
-
+    // 服务操作类型常量
+    public final static String ACTION_STRING_NAME = "sync_action_type"; // 操作类型键名
+    public final static int ACTION_START_SYNC = 0; // 启动同步
+    public final static int ACTION_CANCEL_SYNC = 1; // 取消同步
+    public final static int ACTION_INVALID = 2; // 无效操作
+
+    // 广播相关常量
+    public final static String GTASK_SERVICE_BROADCAST_NAME = "net.micode.notes.gtask.remote.gtask_sync_service"; // 广播名称
+    public final static String GTASK_SERVICE_BROADCAST_IS_SYNCING = "isSyncing"; // 是否正在同步
+    public final static String GTASK_SERVICE_BROADCAST_PROGRESS_MSG = "progressMsg"; // 同步进度消息
+
+    private static GTaskASyncTask mSyncTask = null; // 同步任务实例
+    private static String mSyncProgress = ""; // 同步进度消息
+
+    /**
+     * 启动同步操作
+     */
     private void startSync() {
-        if (mSyncTask == null) {
+        if (mSyncTask == null) { // 避免重复启动
+            // 创建并执行异步同步任务
             mSyncTask = new GTaskASyncTask(this, new GTaskASyncTask.OnCompleteListener() {
+                @Override
                 public void onComplete() {
+                    // 同步完成后清理资源
                     mSyncTask = null;
-                    sendBroadcast("");
-                    stopSelf();
+                    sendBroadcast(""); // 发送同步完成广播
+                    stopSelf(); // 停止服务
                 }
             });
-            sendBroadcast("");
-            mSyncTask.execute();
+            sendBroadcast(""); // 发送同步开始广播
+            mSyncTask.execute(); // 执行同步任务
         }
     }
 
+    /**
+     * 取消同步操作
+     */
     private void cancelSync() {
         if (mSyncTask != null) {
-            mSyncTask.cancelSync();
+            mSyncTask.cancelSync(); // 调用异步任务的取消方法
         }
     }
 
     @Override
     public void onCreate() {
-        mSyncTask = null;
+        super.onCreate();
+        mSyncTask = null; // 服务创建时初始化同步任务
     }
 
+    /**
+     * 处理服务启动命令
+     * @param intent 启动意图，包含操作类型
+     * @param flags 启动标志
+     * @param startId 启动ID
+     * @return 服务启动模式
+     */
     @Override
     public int onStartCommand(Intent intent, int flags, int startId) {
         Bundle bundle = intent.getExtras();
         if (bundle != null && bundle.containsKey(ACTION_STRING_NAME)) {
+            // 根据操作类型执行相应操作
             switch (bundle.getInt(ACTION_STRING_NAME, ACTION_INVALID)) {
                 case ACTION_START_SYNC:
                     startSync();
@@ -81,48 +99,75 @@ public class GTaskSyncService extends Service {
                 default:
                     break;
             }
-            return START_STICKY;
+            return START_STICKY; // 服务被杀死后尝试重新启动
         }
         return super.onStartCommand(intent, flags, startId);
     }
 
+    /**
+     * 系统内存不足时的回调
+     * 取消正在进行的同步任务以释放资源
+     */
     @Override
     public void onLowMemory() {
+        super.onLowMemory();
         if (mSyncTask != null) {
-            mSyncTask.cancelSync();
+            mSyncTask.cancelSync(); // 内存不足时取消同步
         }
     }
 
+    @Override
     public IBinder onBind(Intent intent) {
-        return null;
+        return null; // 不支持绑定
     }
 
+    /**
+     * 发送同步状态广播
+     * @param msg 同步进度消息
+     */
     public void sendBroadcast(String msg) {
         mSyncProgress = msg;
         Intent intent = new Intent(GTASK_SERVICE_BROADCAST_NAME);
-        intent.putExtra(GTASK_SERVICE_BROADCAST_IS_SYNCING, mSyncTask != null);
-        intent.putExtra(GTASK_SERVICE_BROADCAST_PROGRESS_MSG, msg);
-        sendBroadcast(intent);
+        intent.putExtra(GTASK_SERVICE_BROADCAST_IS_SYNCING, mSyncTask != null); // 是否正在同步
+        intent.putExtra(GTASK_SERVICE_BROADCAST_PROGRESS_MSG, msg); // 同步消息
+        sendBroadcast(intent); // 发送广播
     }
 
+    // ==================== 静态调用方法 ====================
+    /**
+     * 静态方法：启动同步服务
+     * @param activity 调用此方法的Activity
+     */
     public static void startSync(Activity activity) {
-        GTaskManager.getInstance().setActivityContext(activity);
+        GTaskManager.getInstance().setActivityContext(activity); // 设置Activity上下文
         Intent intent = new Intent(activity, GTaskSyncService.class);
         intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_START_SYNC);
-        activity.startService(intent);
+        activity.startService(intent); // 启动服务并传递启动同步的意图
     }
 
+    /**
+     * 静态方法：取消同步服务
+     * @param context 上下文
+     */
     public static void cancelSync(Context context) {
         Intent intent = new Intent(context, GTaskSyncService.class);
         intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_CANCEL_SYNC);
-        context.startService(intent);
+        context.startService(intent); // 启动服务并传递取消同步的意图
     }
 
+    /**
+     * 静态方法：检查是否正在同步
+     * @return 是否正在同步
+     */
     public static boolean isSyncing() {
         return mSyncTask != null;
     }
 
+    /**
+     * 静态方法：获取当前同步进度消息
+     * @return 同步进度消息
+     */
     public static String getProgressString() {
         return mSyncProgress;
     }
-}
+}