xiaomi/GTaskSyncService.java

/*
 * Copyright (c) 2010 - 2011, The MiCode Open Source Community (www.micode.net)
 *
 * 遵循 Apache 许可证 2.0 版（“许可证”）；
 * 除非遵守许可证，否则不得使用此文件。
 * 你可以在以下网址获取许可证副本：
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 * 除非适用法律要求或书面同意，
 * 根据许可证分发的软件按“原样”分发，
 * 不附带任何明示或暗示的保证或条件。
 * 请参阅许可证，了解具体的权限和限制。
 */

package net.micode.notes.gtask.remote;

import android.app.Activity;
import android.app.Service;
import android.content.Context;
import android.content.Intent;
import android.os.Bundle;
import android.os.IBinder;

// GTaskSyncService 是一个 Android 服务类，用于管理 Google 任务（GTask）的同步操作
// 提供了启动同步、取消同步的功能，并通过广播通知同步状态和进度
public class GTaskSyncService extends Service {
    // 用于在 Intent 中传递同步操作类型的字符串名称
    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) {
            // 创建一个新的 GTaskASyncTask 实例，并传入当前服务上下文和一个任务完成监听器
            mSyncTask = new GTaskASyncTask(this, new GTaskASyncTask.OnCompleteListener() {
                // 当同步任务完成时，执行该方法
                public void onComplete() {
                    // 将同步任务实例置为 null
                    mSyncTask = null;
                    // 发送广播通知同步完成，消息为空字符串
                    sendBroadcast("");
                    // 停止当前服务
                    stopSelf();
                }
            });
            // 发送广播通知同步开始，消息为空字符串
            sendBroadcast("");
            // 执行同步任务
            mSyncTask.execute();
        }
    }

    // 取消同步任务的方法
    private void cancelSync() {
        // 如果同步任务正在进行
        if (mSyncTask!= null) {
            // 调用同步任务的取消同步方法
            mSyncTask.cancelSync();
        }
    }

    // 当服务创建时调用的方法
    @Override
    public void onCreate() {
        // 将同步任务实例置为 null
        mSyncTask = null;
    }

    // 当服务接收到启动命令时调用的方法
    @Override
    public int onStartCommand(Intent intent, int flags, int startId) {
        // 获取 Intent 中携带的额外数据
        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();
                    break;
                case ACTION_CANCEL_SYNC:
                    // 取消同步任务
                    cancelSync();
                    break;
                default:
                    break;
            }
            // 返回 START_STICKY 表示如果服务被系统杀死，在有足够内存时会自动重启
            return START_STICKY;
        }
        // 如果未包含同步操作类型字段，调用父类的 onStartCommand 方法
        return super.onStartCommand(intent, flags, startId);
    }

    // 当系统内存不足时调用的方法
    @Override
    public void onLowMemory() {
        // 如果同步任务正在进行
        if (mSyncTask!= null) {
            // 取消同步任务
            mSyncTask.cancelSync();
        }
    }

    // 当客户端绑定到服务时调用的方法，由于该服务不支持绑定，返回 null
    @Override
    public IBinder onBind(Intent intent) {
        return null;
    }

    // 发送广播的方法，用于通知同步状态和进度
    public void sendBroadcast(String msg) {
        // 更新同步进度消息
        mSyncProgress = msg;
        // 创建一个新的 Intent，设置广播名称
        Intent intent = new Intent(GTASK_SERVICE_BROADCAST_NAME);
        // 在 Intent 中添加是否正在同步的信息
        intent.putExtra(GTASK_SERVICE_BROADCAST_IS_SYNCING, mSyncTask!= null);
        // 在 Intent 中添加同步进度消息
        intent.putExtra(GTASK_SERVICE_BROADCAST_PROGRESS_MSG, msg);
        // 发送广播
        sendBroadcast(intent);
    }

    // 外部调用启动同步的静态方法
    public static void startSync(Activity activity) {
        // 设置 GTaskManager 的 Activity 上下文
        GTaskManager.getInstance().setActivityContext(activity);
        // 创建一个 Intent，指定要启动的服务为 GTaskSyncService
        Intent intent = new Intent(activity, GTaskSyncService.class);
        // 在 Intent 中添加启动同步的操作类型
        intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_START_SYNC);
        // 启动服务
        activity.startService(intent);
    }

    // 外部调用取消同步的静态方法
    public static void cancelSync(Context context) {
        // 创建一个 Intent，指定要启动的服务为 GTaskSyncService
        Intent intent = new Intent(context, GTaskSyncService.class);
        // 在 Intent 中添加取消同步的操作类型
        intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_CANCEL_SYNC);
        // 启动服务
        context.startService(intent);
    }

    // 判断是否正在进行同步的静态方法
    public static boolean isSyncing() {
        // 通过判断同步任务实例是否为 null 来确定是否正在同步
        return mSyncTask!= null;
    }

    // 获取当前同步进度消息的静态方法
    public static String getProgressString() {
        // 返回当前的同步进度消息
        return mSyncProgress;
    }
}