ایجاد وفق‌دهنده همگام‌سازی

توجه: WorkManager را به‌عنوان راهکار توصیه‌شده برای اکثر موارد استفاده از پردازش پس‌زمینه‌ای توصیه می‌کنیم. لطفاً به راهنمای پردازش پس‌زمینه مراجعه کنید تا ببینید کدام راه‌حل برای شما مناسب‌تر است.

مؤلفه وفق‌دهنده همگام‌سازی در برنامه شما کد مربوط به کارهایی را که داده‌ها را بین دستگاه و سرور منتقل می‌کنند کپسوله‌سازی می‌کند. براساس زمان‌بندی و راه‌اندازهایی که در برنامه‌تان ارائه می‌دهید، چارچوب وفق‌دهنده همگام‌سازی کد را در مؤلفه وفق‌دهنده همگام‌سازی اجرا می‌کند. برای افزودن مؤلفه وفق‌دهنده همگام‌سازی به برنامه‌تان، باید قطعات زیر را اضافه کنید:

کلاس وفق‌دهنده همگام‌سازی.

کلاسی که کد انتقال داده شما را در میانای سازگار با چارچوب وفق‌دهنده همگام‌سازی قرار می‌دهد.

‫Service محدود شد.

مؤلفه‌ای که به چارچوب وفق‌دهنده همگام‌سازی اجازه می‌دهد کد را در کلاس وفق‌دهنده همگام‌سازی شما اجرا کند.

فایل فراداده XML وفق‌دهنده همگام‌سازی.

فایلی حاوی اطلاعات مربوط به وفق‌دهنده همگام‌سازی شما. چارچوب این فایل را می‌خواند تا نحوه بار کردن و زمان‌بندی انتقال داده را پیدا کند.

اظهارنامه‌های موجود در مانیفست برنامه.

XML که خدمات محدودکننده را اعلام می‌کند و به فراداده‌های خاص وفق‌دهنده همگام‌سازی اشاره می‌کند.

این درس به شما نشان می‌دهد که چگونه این عناصر را تعریف کنید.

ایجاد کلاس وفق‌دهنده همگام‌سازی

در این بخش از درس، با نحوه ایجاد کلاس وفق‌دهنده همگام‌سازی که کد انتقال داده را کپسوله‌سازی می‌کند آشنا می‌شوید. ایجاد کلاس شامل گسترش کلاس پایه وفق‌دهنده همگام‌سازی، تعریف سازنده‌ها برای کلاس، و پیاده‌سازی روشی است که در آن تکالیف انتقال داده را تعریف می‌کنید.

گسترش کلاس وفق‌دهنده همگام‌سازی پایه

برای ایجاد مؤلفه وفق‌دهنده همگام‌سازی، ابتدا AbstractThreadedSyncAdapter را گسترش دهید و سازنده‌های آن را بنویسید. از سازنده‌ها برای اجرای تکالیف راه‌اندازی هر بار که مؤلفه وفق‌دهنده همگام‌سازی شما از ابتدا ایجاد می‌شود استفاده کنید، درست همان‌طور که از Activity.onCreate() برای راه‌اندازی یک فعالیت استفاده می‌کنید. برای مثال، اگر برنامه‌تان از ارائه‌دهنده محتوا برای ذخیره داده‌ها استفاده می‌کند، از سازنده‌ها برای دریافت نمونه ContentResolver استفاده کنید. ازآنجایی‌که شکل دومی از سازنده در نسخه ۳.۰ پلاتفرم Android برای پشتیبانی از آرگومان parallelSyncs اضافه شده است، باید دو شکل از سازنده را برای حفظ سازگاری ایجاد کنید.

توجه: چارچوب وفق‌دهنده همگام‌سازی برای کار با مؤلفه‌های وفق‌دهنده همگام‌سازی که نمونه‌های تک‌قلو هستند طراحی شده است. نمونه‌سازی مؤلفه وفق‌دهنده همگام‌سازی با جزئیات بیشتر در بخش مقید کردن وفق‌دهنده همگام‌سازی به چارچوب پوشش داده شده است.

مثال زیر نحوه پیاده‌سازی AbstractThreadedSyncAdapterو سازنده‌های آن را نشان می‌دهد:

کاتلین

/**
 * Handle the transfer of data between a server and an
 * app, using the Android sync adapter framework.
 */
class SyncAdapter @JvmOverloads constructor(
        context: Context,
        autoInitialize: Boolean,
        /**
         * Using a default argument along with @JvmOverloads
         * generates constructor for both method signatures to maintain compatibility
         * with Android 3.0 and later platform versions
         */
        allowParallelSyncs: Boolean = false,
        /*
         * If your app uses a content resolver, get an instance of it
         * from the incoming Context
         */
        val mContentResolver: ContentResolver = context.contentResolver
) : AbstractThreadedSyncAdapter(context, autoInitialize, allowParallelSyncs) {
    ...
}

جاوا

/**
 * Handle the transfer of data between a server and an
 * app, using the Android sync adapter framework.
 */
public class SyncAdapter extends AbstractThreadedSyncAdapter {
    ...
    // Global variables
    // Define a variable to contain a content resolver instance
    ContentResolver contentResolver;
    /**
     * Set up the sync adapter
     */
    public SyncAdapter(Context context, boolean autoInitialize) {
        super(context, autoInitialize);
        /*
         * If your app uses a content resolver, get an instance of it
         * from the incoming Context
         */
        contentResolver = context.getContentResolver();
    }
    ...
    /**
     * Set up the sync adapter. This form of the
     * constructor maintains compatibility with Android 3.0
     * and later platform versions
     */
    public SyncAdapter(
            Context context,
            boolean autoInitialize,
            boolean allowParallelSyncs) {
        super(context, autoInitialize, allowParallelSyncs);
        /*
         * If your app uses a content resolver, get an instance of it
         * from the incoming Context
         */
        contentResolver = context.getContentResolver();
        ...
    }

افزودن کد انتقال داده

مؤلفه وفق‌دهنده همگام‌سازی انتقال داده را به‌طور خودکار انجام نمی‌دهد. درعوض، کد انتقال داده شما را کپسوله‌سازی می‌کند تا چارچوب وفق‌دهنده همگام‌سازی بتواند انتقال داده را در پس‌زمینه و بدون دخالت برنامه‌تان اجرا کند. وقتی چارچوب آماده همگام‌سازی داده‌های برنامه‌تان باشد، پیاده‌سازی شما از روش onPerformSync() را فراخوانی می‌کند.

برای تسهیل انتقال داده‌ها از کد برنامه اصلی به مؤلفه وفق‌دهنده همگام‌سازی، چارچوب وفق‌دهنده همگام‌سازی onPerformSync() را با آرگومان‌های زیر فراخوانی می‌کند:

حساب

یک شیء Account مرتبط با رویدادی که وفق‌دهنده همگام‌سازی را راه‌اندازی کرده است. اگر سرورتان از حساب استفاده نمی‌کند، لازم نیست از اطلاعات موجود در این شیء استفاده کنید.

جایزه‌ها

‫

Bundle حاوی پرچم‌هایی که توسط رویدادی که وفق‌دهنده همگام‌سازی را راه‌اندازی کرده است ارسال شده است.

صلاحیت

اختیار ارائه‌دهنده محتوا در سیستم. برنامه‌تان باید به این ارائه‌دهنده دسترسی داشته باشد. معمولاً مرجع با ارائه‌دهنده محتوا در برنامه خودتان مطابقت دارد.

مشتری ارائه‌دهنده محتوا

ContentProviderClient برای ارائه‌دهنده محتوا که توسط آرگومان مرجع به آن اشاره شده است. ContentProviderClient یک میانای عمومی سبک برای ارائه‌دهنده محتوا است. عملکرد اصلی آن مشابه ContentResolver است. اگر از ارائه‌دهنده محتوا برای ذخیره داده‌های برنامه‌تان استفاده می‌کنید، می‌توانید با این شیء به ارائه‌دهنده متصل شوید. درغیراین‌صورت، می‌توانید آن را نادیده بگیرید.

نتیجه همگام‌سازی

یک شیء SyncResult که از آن برای ارسال اطلاعات به چارچوب وفق‌دهنده همگام‌سازی استفاده می‌کنید.

قطعه کد زیر ساختار کلی onPerformSync() را نشان می‌دهد:

کاتلین

/*
 * Specify the code you want to run in the sync adapter. The entire
 * sync adapter runs in a background thread, so you don't have to set
 * up your own background processing.
 */
override fun onPerformSync(
        account: Account,
        extras: Bundle,
        authority: String,
        provider: ContentProviderClient,
        syncResult: SyncResult
) {
    /*
     * Put the data transfer code here.
     */
}

جاوا

/*
 * Specify the code you want to run in the sync adapter. The entire
 * sync adapter runs in a background thread, so you don't have to set
 * up your own background processing.
 */
@Override
public void onPerformSync(
        Account account,
        Bundle extras,
        String authority,
        ContentProviderClient provider,
        SyncResult syncResult) {
    /*
     * Put the data transfer code here.
     */
}

درحالی‌که پیاده‌سازی واقعی onPerformSync() مختص الزامات همگام‌سازی داده‌های برنامه شما و پروتکل‌های اتصال سرور است، چند تکلیف کلی وجود دارد که پیاده‌سازی شما باید انجام دهد:

اتصال به سرور

اگرچه می‌توانید فرض کنید که شبکه هنگام شروع انتقال داده دردسترس است، چارچوب وفق‌دهنده همگام‌سازی به‌طور خودکار به سرور متصل نمی‌شود.

بارگیری و بارگذاری داده‌ها

وفق‌دهنده همگام‌سازی هیچ‌کدام از تکالیف انتقال داده را خودکارسازی نمی‌کند. اگر می‌خواهید داده‌ها را از سرور بارگیری کنید و آن را در رساننده محتوا ذخیره کنید، باید کدی را ارائه دهید که داده‌ها را درخواست می‌کند، آن را بارگیری می‌کند و آن را در رساننده درج می‌کند. به‌طور مشابه، اگر می‌خواهید داده‌ها را به سرور ارسال کنید، باید آن‌ها را از فایل، پایگاه داده، یا ارائه‌دهنده بخوانید و درخواست بارگذاری لازم را ارسال کنید. همچنین باید خطاهای شبکه را که درحین اجرای انتقال داده رخ می‌دهد مدیریت کنید.

رسیدگی به تداخل داده‌ها یا تعیین میزان به‌روز بودن داده‌ها

وفق‌دهنده همگام‌سازی به‌طور خودکار تداخل‌های بین داده‌های موجود در سرور و داده‌های موجود در دستگاه را مدیریت نمی‌کند. همچنین، به‌طور خودکار تشخیص نمی‌دهد که داده‌های موجود در سرور جدیدتر از داده‌های موجود در دستگاه است یا برعکس. درعوض، باید الگوریتم‌های خودتان را برای رسیدگی به این وضعیت ارائه دهید.

پاک‌سازی کنید.

همیشه در پایان انتقال داده، اتصال به سرور را ببندید و فایل‌های موقت و حافظه‌های پنهان را پاک کنید.

توجه: چارچوب وفق‌دهنده همگام‌سازی onPerformSync() در رشته پس‌زمینه اجرا می‌شود، بنابراین لازم نیست پردازش پس‌زمینه خودتان را راه‌اندازی کنید.

علاوه‌بر کارهای مربوط به همگام‌سازی، باید سعی کنید کارهای معمول مربوط به شبکه را ترکیب کنید و آن‌ها را به onPerformSync() اضافه کنید. با متمرکز کردن همه تکالیف شبکه در این روش، در مصرف شارژ باتری که برای شروع و توقف میاناهای شبکه لازم است صرفه‌جویی می‌کنید. برای کسب اطلاعات بیشتر درباره کارآمدتر کردن دسترسی به شبکه، کلاس آموزشی انتقال داده بدون خالی کردن شارژ باتری را ببینید که چندین تکلیف دسترسی به شبکه را توصیف می‌کند که می‌توانید در کد انتقال داده‌تان بگنجانید.

Bind the sync adapter to the framework

اکنون کد انتقال داده‌تان را در مؤلفه وفق‌دهنده همگام‌سازی کپسوله‌سازی کرده‌اید، اما باید دسترسی به کدتان را برای چارچوب فراهم کنید. برای انجام این کار، باید Service مقیدی ایجاد کنید که شیء متصل‌کننده Android ویژه‌ای را از مؤلفه وفق‌دهنده همگام‌سازی به چارچوب منتقل کند. با این شیء binder، چارچوب می‌تواند روش onPerformSync() را فراخوانی کند و داده‌ها را به آن منتقل کند.

نمونه‌سازی مؤلفه وفق‌دهنده همگام‌سازی به‌عنوان تک‌قلو در روش onCreate() سرویس. با نمونه‌سازی مؤلفه در onCreate()، ایجاد آن را تا زمان شروع سرویس به‌تعویق می‌اندازید، که این اتفاق زمانی می‌افتد که چارچوب برای اولین‌بار تلاش می‌کند انتقال داده شما را اجرا کند. باید مؤلفه را به‌صورت ایمن ازنظر رشته نمونه‌سازی کنید، درصورتی‌که چارچوب وفق‌دهنده همگام‌سازی چندین اجرای وفق‌دهنده همگام‌سازی شما را در پاسخ به راه‌اندازها یا زمان‌بندی صف‌بندی کند.

برای مثال، تکه‌کد زیر نحوه ایجاد کلاسی را نشان می‌دهد که Service مقید را پیاده‌سازی می‌کند، مؤلفه وفق‌دهنده همگام‌سازی شما را نمونه‌سازی می‌کند، و شیء مقیدکننده Android را دریافت می‌کند:

کاتلین

package com.example.android.syncadapter
/**
 * Define a Service that returns an [android.os.IBinder] for the
 * sync adapter class, allowing the sync adapter framework to call
 * onPerformSync().
 */
class SyncService : Service() {
    /*
     * Instantiate the sync adapter object.
     */
    override fun onCreate() {
        /*
         * Create the sync adapter as a singleton.
         * Set the sync adapter as syncable
         * Disallow parallel syncs
         */
        synchronized(sSyncAdapterLock) {
            sSyncAdapter = sSyncAdapter ?: SyncAdapter(applicationContext, true)
        }
    }

    /**
     * Return an object that allows the system to invoke
     * the sync adapter.
     *
     */
    override fun onBind(intent: Intent): IBinder {
        /*
         * Get the object that allows external processes
         * to call onPerformSync(). The object is created
         * in the base class code when the SyncAdapter
         * constructors call super()
         *
         * We should never be in a position where this is called before
         * onCreate() so the exception should never be thrown
         */
        return sSyncAdapter?.syncAdapterBinder ?: throw IllegalStateException()
    }

    companion object {
        // Storage for an instance of the sync adapter
        private var sSyncAdapter: SyncAdapter? = null
        // Object to use as a thread-safe lock
        private val sSyncAdapterLock = Any()
    }
}

جاوا

package com.example.android.syncadapter;
/**
 * Define a Service that returns an <code><a href="/reference/android/os/IBinder.html">IBinder</a></code> for the
 * sync adapter class, allowing the sync adapter framework to call
 * onPerformSync().
 */
public class SyncService extends Service {
    // Storage for an instance of the sync adapter
    private static SyncAdapter sSyncAdapter = null;
    // Object to use as a thread-safe lock
    private static final Object sSyncAdapterLock = new Object();
    /*
     * Instantiate the sync adapter object.
     */
    @Override
    public void onCreate() {
        /*
         * Create the sync adapter as a singleton.
         * Set the sync adapter as syncable
         * Disallow parallel syncs
         */
        synchronized (sSyncAdapterLock) {
            if (sSyncAdapter == null) {
                sSyncAdapter = new SyncAdapter(getApplicationContext(), true);
            }
        }
    }
    /**
     * Return an object that allows the system to invoke
     * the sync adapter.
     *
     */
    @Override
    public IBinder onBind(Intent intent) {
        /*
         * Get the object that allows external processes
         * to call onPerformSync(). The object is created
         * in the base class code when the SyncAdapter
         * constructors call super()
         */
        return sSyncAdapter.getSyncAdapterBinder();
    }
}

توجه: برای دیدن نمونه دقیق‌تری از خدمات محدودکننده برای وفق‌دهنده همگام‌سازی، برنامه نمونه را ببینید.

افزودن حساب موردنیاز چارچوب

چارچوب وفق‌دهنده همگام‌سازی مستلزم این است که هر وفق‌دهنده همگام‌سازی نوع حساب داشته باشد. مقدار نوع حساب را در بخش افزودن فایل فراداده اصالت‌سنج اعلام کرده‌اید. اکنون باید این نوع حساب را در سیستم Android راه‌اندازی کنید. برای راه‌اندازی نوع حساب، با فراخوانی addAccountExplicitly()، حساب جای‌بان اضافه کنید که از نوع حساب استفاده می‌کند.

بهترین مکان برای فراخوانی روش در روش onCreate() فعالیت باز کردن برنامه است. تکه‌کد زیر نحوه انجام این کار را نشان می‌دهد:

کاتلین

...
// Constants
// The authority for the sync adapter's content provider
const val AUTHORITY = "com.example.android.datasync.provider"
// An account type, in the form of a domain name
const val ACCOUNT_TYPE = "example.com"
// The account name
const val ACCOUNT = "placeholderaccount"
...
class MainActivity : FragmentActivity() {

    // Instance fields
    private lateinit var mAccount: Account
    ...
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
       ...
        // Create the placeholder account
        mAccount = createSyncAccount()
       ...
    }
    ...
    /**
     * Create a new placeholder account for the sync adapter
     */
    private fun createSyncAccount(): Account {
        val accountManager = getSystemService(Context.ACCOUNT_SERVICE) as AccountManager
        return Account(ACCOUNT, ACCOUNT_TYPE).also { newAccount ->
            /*
             * Add the account and account type, no password or user data
             * If successful, return the Account object, otherwise report an error.
             */
            if (accountManager.addAccountExplicitly(newAccount, null, null)) {
                /*
                 * If you don't set android:syncable="true" in
                 * in your <provider> element in the manifest,
                 * then call context.setIsSyncable(account, AUTHORITY, 1)
                 * here.
                 */
            } else {
                /*
                 * The account exists or some other error occurred. Log this, report it,
                 * or handle it internally.
                 */
            }
        }
    }
    ...
}

جاوا

public class MainActivity extends FragmentActivity {
    ...
    ...
    // Constants
    // The authority for the sync adapter's content provider
    public static final String AUTHORITY = "com.example.android.datasync.provider";
    // An account type, in the form of a domain name
    public static final String ACCOUNT_TYPE = "example.com";
    // The account name
    public static final String ACCOUNT = "placeholderaccount";
    // Instance fields
    Account mAccount;
    ...
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ...
        // Create the placeholder account
        mAccount = CreateSyncAccount(this);
        ...
    }
    ...
    /**
     * Create a new placeholder account for the sync adapter
     *
     * @param context The application context
     */
    public static Account CreateSyncAccount(Context context) {
        // Create the account type and default account
        Account newAccount = new Account(
                ACCOUNT, ACCOUNT_TYPE);
        // Get an instance of the Android account manager
        AccountManager accountManager =
                (AccountManager) context.getSystemService(
                        ACCOUNT_SERVICE);
        /*
         * Add the account and account type, no password or user data
         * If successful, return the Account object, otherwise report an error.
         */
        if (accountManager.addAccountExplicitly(newAccount, null, null)) {
            /*
             * If you don't set android:syncable="true" in
             * in your <provider> element in the manifest,
             * then call context.setIsSyncable(account, AUTHORITY, 1)
             * here.
             */
        } else {
            /*
             * The account exists or some other error occurred. Log this, report it,
             * or handle it internally.
             */
        }
    }
    ...
}

افزودن فایل فراداده وفق‌دهنده همگام‌سازی

برای وصل کردن مؤلفه وفق‌دهنده همگام‌سازی به چارچوب، باید فراداده‌ای را که مؤلفه را توصیف می‌کند و پرچم‌های اضافی ارائه می‌دهد به چارچوب ارائه دهید. فراداده نوع حسابی را که برای وفق‌دهنده همگام‌سازی‌تان ایجاد کرده‌اید مشخص می‌کند، مرجع ارائه‌دهنده محتوای مرتبط با برنامه‌تان را اعلام می‌کند، بخشی از میانای کاربر سیستم را که مربوط به وفق‌دهنده‌های همگام‌سازی است کنترل می‌کند، و پرچم‌های دیگر مربوط به همگام‌سازی را اعلام می‌کند. این فراداده را در فایل XML ویژه‌ای که در دایرکتوری /res/xml/ در پروژه برنامه‌تان ذخیره شده است اعلام کنید. می‌توانید هر نامی را به فایل بدهید، هرچند معمولاً syncadapter.xml نامیده می‌شود.

این فایل XML حاوی یک عنصر XML <sync-adapter> است که مشخصه‌های زیر را دارد:

android:contentAuthority

مرجع URI برای ارائه‌دهنده محتوای شما. اگر در درس قبلی ایجاد ارائه‌دهنده محتوای ساختگی، ارائه‌دهنده محتوای ساختگی برای برنامه‌تان ایجاد کرده‌اید، از مقداری که برای مشخصه android:authorities در عنصر <provider> که به مانیفست برنامه‌تان اضافه کرده‌اید استفاده کنید. این مشخصه با جزئیات بیشتر در بخش اعلام کردن ارائه‌دهنده در مانیفست شرح داده شده است.
اگر با وفق‌دهنده همگام‌سازی‌تان درحال انتقال داده از ارائه‌دهنده محتوا به سرور هستید، این مقدار باید با مرجع شناسه منبع یکسان محتوایی که برای آن داده استفاده می‌کنید یکسان باشد. این مقدار همچنین یکی از مراجعی است که در مشخصه android:authorities عنصر <provider> که ارائه‌دهنده شما را در مانیفست برنامه‌تان اعلام می‌کند مشخص می‌کنید.

android:accountType

نوع حساب موردنیاز چارچوب وفق‌دهنده همگام‌سازی. این مقدار باید با مقدار نوع حساب که هنگام ایجاد فایل فراداده اصالت‌سنج ارائه کردید یکسان باشد، همان‌طور که در بخش افزودن فایل فراداده اصالت‌سنج شرح داده شده است. این مقدار همچنین مقداری است که برای ثابت ACCOUNT_TYPE در تکه‌کد در بخش افزودن حساب موردنیاز چارچوب مشخص کرده‌اید.

مشخصه‌های تنظیمات

android:userVisible

نمایان بودن نوع حساب وفق‌دهنده همگام‌سازی را تنظیم می‌کند. به‌طور پیش‌فرض، نماد حساب و برچسب مرتبط با نوع حساب در بخش حساب‌ها در برنامه «تنظیمات» سیستم قابل‌مشاهده است، بنابراین باید وفق‌دهنده همگام‌سازی‌تان را نامرئی کنید، مگراینکه نوع حساب یا دامنه‌ای داشته باشید که به‌راحتی با برنامه‌تان مرتبط شود. اگر نوع حسابتان را نامرئی کنید، همچنان می‌توانید به کاربران اجازه دهید وفق‌دهنده همگام‌سازی‌تان را با میانای کاربر در یکی از فعالیت‌های برنامه‌تان کنترل کنند.

android:supportsUploading

به شما امکان می‌دهد داده‌ها را در فضای ابری بارگذاری کنید. اگر برنامه‌تان فقط داده بارگیری می‌کند، این را روی false تنظیم کنید.

android:allowParallelSyncs

به چندین نمونه از مؤلفه وفق‌دهنده همگام‌سازی شما اجازه می‌دهد به‌طور هم‌زمان اجرا شوند. اگر برنامه‌تان از چند حساب کاربری پشتیبانی می‌کند و می‌خواهید به چند کاربر اجازه دهید داده‌ها را به‌طور موازی منتقل کنند، از این گزینه استفاده کنید. اگر هرگز چندین انتقال داده را اجرا نکنید، این پرچم تأثیری ندارد.

android:isAlwaysSyncable

به چارچوب وفق‌دهنده همگام‌سازی نشان می‌دهد که می‌تواند وفق‌دهنده همگام‌سازی شما را در هر زمانی که مشخص کرده‌اید اجرا کند. اگر می‌خواهید به‌طور برنامه‌نویسی‌شده کنترل کنید که وفق‌دهنده همگام‌سازی شما چه زمانی می‌تواند اجرا شود، این پرچم را روی false تنظیم کنید و سپس requestSync() را برای اجرای وفق‌دهنده همگام‌سازی فراخوانی کنید. برای کسب اطلاعات بیشتر درباره اجرای وفق‌دهنده همگام‌سازی، درس اجرای وفق‌دهنده همگام‌سازی

را ببینید

مثال زیر XML را برای وفق‌دهنده همگام‌سازی نشان می‌دهد که از یک حساب جای‌بان استفاده می‌کند و فقط بارگیری انجام می‌دهد.

<?xml version="1.0" encoding="utf-8"?>
<sync-adapter
        xmlns:android="http://schemas.android.com/apk/res/android"
        android:contentAuthority="com.example.android.datasync.provider"
        android:accountType="com.android.example.datasync"
        android:userVisible="false"
        android:supportsUploading="false"
        android:allowParallelSyncs="false"
        android:isAlwaysSyncable="true"/>

اعلام وفق‌دهنده همگام‌سازی در مانیفست

پس‌از افزودن مؤلفه وفق‌دهنده همگام‌سازی به برنامه‌تان، باید اجازه‌های مربوط به استفاده از مؤلفه را درخواست کنید و باید Service محدودشده‌ای را که اضافه کرده‌اید اعلام کنید.

ازآنجایی‌که مؤلفه وفق‌دهنده همگام‌سازی کدی را اجرا می‌کند که داده‌ها را بین شبکه و دستگاه منتقل می‌کند، باید برای دسترسی به اینترنت درخواست اجازه کنید. علاوه‌براین، برنامه‌تان باید برای خواندن و نوشتن تنظیمات وفق‌دهنده همگام‌سازی درخواست اجازه کند تا بتوانید وفق‌دهنده همگام‌سازی را به‌صورت برنامه‌نویسی‌شده از دیگر مؤلفه‌های برنامه‌تان کنترل کنید. همچنین باید برای اجازه ویژه‌ای درخواست کنید که به برنامه‌تان امکان می‌دهد از مؤلفه اصالت‌سنجی‌ای که در درس ایجاد اصالت‌سنجی‌کننده ساختگی ایجاد کردید استفاده کند.

برای درخواست این اجازه‌ها، موارد زیر را به‌عنوان عناصر فرزند به مانیفست برنامه‌تان اضافه کنید <manifest>:

android.permission.INTERNET

به کد وفق‌دهنده همگام‌سازی اجازه می‌دهد به اینترنت دسترسی داشته باشد تا بتواند داده‌ها را از دستگاه در سرور بارگیری یا بارگذاری کند. اگر قبلاً این اجازه را درخواست کرده‌اید، لازم نیست دوباره آن را اضافه کنید.

android.permission.READ_SYNC_SETTINGS

به برنامه شما اجازه می‌دهد تنظیمات فعلی وفق‌دهنده همگام‌سازی را بخواند. برای مثال، برای تماس با getIsSyncable() به این اجازه نیاز دارید.

android.permission.WRITE_SYNC_SETTINGS

به برنامه شما اجازه می‌دهد تنظیمات وفق‌دهنده همگام‌سازی را کنترل کند. برای تنظیم اجرای دوره‌ای وفق‌دهنده همگام‌سازی بااستفاده از addPeriodicSync()، به این اجازه نیاز دارید. این اجازه برای تماس با requestSync() لازم نیست. برای کسب اطلاعات بیشتر درباره اجرای وفق‌دهنده همگام‌سازی، به اجرای وفق‌دهنده همگام‌سازی مراجعه کنید.

قطعه کد زیر نحوه افزودن اجازه‌ها را نشان می‌دهد:

<manifest>
...
    <uses-permission
            android:name="android.permission.INTERNET"/>
    <uses-permission
            android:name="android.permission.READ_SYNC_SETTINGS"/>
    <uses-permission
            android:name="android.permission.WRITE_SYNC_SETTINGS"/>
    <uses-permission
            android:name="android.permission.AUTHENTICATE_ACCOUNTS"/>
...
</manifest>

درنهایت، برای اعلام Service محدودشده‌ای که چارچوب برای تعامل با وفق‌دهنده همگام‌سازی شما استفاده می‌کند، XML زیر را به‌عنوان عنصر فرزند <application> به مانیفست برنامه‌تان اضافه کنید:

        <service
                android:name="com.example.android.datasync.SyncService"
                android:exported="false"
                android:process=":sync">
            <intent-filter>
                <action android:name="android.content.SyncAdapter"/>
            </intent-filter>
            <meta-data android:name="android.content.SyncAdapter"
                    android:resource="@xml/syncadapter" />
        </service>

عنصر <intent-filter> فیلتری را راه‌اندازی می‌کند که با کنش هدف android.content.SyncAdapter راه‌اندازی می‌شود، که توسط سیستم برای اجرای وفق‌دهنده همگام‌سازی ارسال می‌شود. وقتی فیلتر راه‌اندازی می‌شود، سیستم خدمات محدودکننده‌ای را که ایجاد کرده‌اید شروع می‌کند، که در این مثال SyncService است. مشخصه android:exported="false" فقط به برنامه شما و سیستم اجازه می‌دهد به Service دسترسی داشته باشند. مشخصه android:process=":sync" به سیستم می‌گوید که Service را در فرایند مشترک جهانی به‌نام sync اجرا کند. اگر چند وفق‌دهنده همگام‌سازی در برنامه‌تان دارید، آن‌ها می‌توانند این فرایند را هم‌رسانی کنند، که این کار سربار را کاهش می‌دهد.

عنصر <meta-data> نام فایل XML فراداده وفق‌دهنده همگام‌سازی را که قبلاً ایجاد کرده‌اید ارائه می‌دهد. مشخصه android:name نشان می‌دهد که این فراداده برای چارچوب وفق‌دهنده همگام‌سازی است. عنصر android:resource نام فایل فراداده را مشخص می‌کند.

اکنون همه مؤلفه‌های وفق‌دهنده همگام‌سازی را دارید. درس بعدی به شما نشان می‌دهد که چگونه به چارچوب وفق‌دهنده همگام‌سازی بگویید وفق‌دهنده همگام‌سازی شما را اجرا کند، چه در پاسخ به یک رویداد یا طبق یک برنامه منظم.