# SyncRequest.Builder

Added in[API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

# Builder

*** ** * ** ***

Kotlin\|[Java](https://developer.android.com/reference/android/content/SyncRequest.Builder "View this page in Java")  

```
open class Builder
```

|---|----------------------------------------------------------------------------------------------------------------------------|
| [kotlin.Any](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-any/index.html)                                             ||
| ↳ | [android.content.SyncRequest.Builder](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#) |

Builder class for a[SyncRequest](https://developer.android.com/reference/kotlin/android/content/SyncRequest). As you build your SyncRequest this class will also perform validation.

## Summary

|                                                  Public constructors                                                  ||
|--------------------------------------------------------------------------------------------------------------------|---|
| [Builder](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#Builder())`()` <br /> |

|                                                                                                                                                                                                                                                                                                      Public methods                                                                                                                                                                                                                                                                                                       ||
|-----------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| open[SyncRequest](https://developer.android.com/reference/kotlin/android/content/SyncRequest)!                  | [build](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#build())`()` Performs validation over the request and throws the runtime exception`IllegalArgumentException`if this validation fails.                                                                                                                                                                                                                                                                         |
| open[SyncRequest.Builder](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#)! | [setDisallowMetered](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#setDisallowMetered(kotlin.Boolean))`(`disallow:` `[Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html)`)` Will throw an`IllegalArgumentException`if called and[setIgnoreSettings(boolean ignoreSettings)](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#setIgnoreSettings(kotlin.Boolean))has already been called.            |
| open[SyncRequest.Builder](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#)! | [setExpedited](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#setExpedited(kotlin.Boolean))`(`expedited:` `[Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html)`)` An expedited sync runs immediately and can preempt other non-expedited running syncs.                                                                                                                                                                               |
| open[SyncRequest.Builder](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#)! | [setExtras](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#setExtras(android.os.Bundle))`(`bundle:` `[Bundle](https://developer.android.com/reference/kotlin/android/os/Bundle.html#)!`)` Developer-provided extras handed back when sync actually occurs.                                                                                                                                                                                                           |
| open[SyncRequest.Builder](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#)! | [setIgnoreBackoff](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#setIgnoreBackoff(kotlin.Boolean))`(`ignoreBackoff:` `[Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html)`)` Convenience function for setting[ContentResolver.SYNC_EXTRAS_IGNORE_BACKOFF](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF:kotlin.String).                                                  |
| open[SyncRequest.Builder](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#)! | [setIgnoreSettings](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#setIgnoreSettings(kotlin.Boolean))`(`ignoreSettings:` `[Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html)`)` Convenience function for setting[ContentResolver.SYNC_EXTRAS_IGNORE_SETTINGS](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_IGNORE_SETTINGS:kotlin.String).                                             |
| open[SyncRequest.Builder](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#)! | [setManual](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#setManual(kotlin.Boolean))`(`isManual:` `[Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html)`)` Convenience function for setting[ContentResolver.SYNC_EXTRAS_MANUAL](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_MANUAL:kotlin.String).                                                                                     |
| open[SyncRequest.Builder](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#)! | [setNoRetry](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#setNoRetry(kotlin.Boolean))`(`noRetry:` `[Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html)`)` Convenience function for setting[ContentResolver.SYNC_EXTRAS_DO_NOT_RETRY](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY:kotlin.String).                                                                        |
| open[SyncRequest.Builder](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#)! | [setRequiresCharging](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#setRequiresCharging(kotlin.Boolean))`(`requiresCharging:` `[Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html)`)` Specify whether the sync requires the phone to be plugged in.                                                                                                                                                                                  |
| open[SyncRequest.Builder](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#)  | [setScheduleAsExpeditedJob](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#setScheduleAsExpeditedJob(kotlin.Boolean))`(`scheduleAsExpeditedJob:` `[Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html)`)` Convenience function for setting[ContentResolver.SYNC_EXTRAS_SCHEDULE_AS_EXPEDITED_JOB](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_SCHEDULE_AS_EXPEDITED_JOB:kotlin.String). |
| open[SyncRequest.Builder](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#)! | [setSyncAdapter](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#setSyncAdapter(android.accounts.Account,%20kotlin.String))`(`account:` `[Account](https://developer.android.com/reference/kotlin/android/accounts/Account.html#)!`, `authority:` `[String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)!`)` Specify an authority and account for this transfer.                                                                           |
| open[SyncRequest.Builder](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#)! | [syncOnce](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#syncOnce())`()` Request that a sync occur immediately.                                                                                                                                                                                                                                                                                                                                                     |
| open[SyncRequest.Builder](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#)! | [syncPeriodic](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#syncPeriodic(kotlin.Long,%20kotlin.Long))`(`pollFrequency:` `[Long](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-long/index.html)`, `beforeSeconds:` `[Long](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-long/index.html)`)` Build a periodic sync.                                                                                                                                   |

## Public constructors

### Builder

Added in[API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
Builder()
```

## Public methods

### build

Added in[API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open fun build(): SyncRequest!
```

Performs validation over the request and throws the runtime exception`IllegalArgumentException`if this validation fails.

|                                                                            Return                                                                             ||
|--------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| [SyncRequest](https://developer.android.com/reference/kotlin/android/content/SyncRequest)! | a SyncRequest with the information contained within this builder. |

### setDisallowMetered

Added in[API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open fun setDisallowMetered(disallow: Boolean): SyncRequest.Builder!
```

Will throw an`IllegalArgumentException`if called and[setIgnoreSettings(boolean ignoreSettings)](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#setIgnoreSettings(kotlin.Boolean))has already been called.

|                                                                           Parameters                                                                           ||
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| `disallow` | [Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html):true to allow this transfer on metered networks. Default false. |

### setExpedited

Added in[API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open fun setExpedited(expedited: Boolean): SyncRequest.Builder!
```

An expedited sync runs immediately and can preempt other non-expedited running syncs. Not valid for periodic sync and will throw an`IllegalArgumentException`in[build()](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#build()).

|                                                                Parameters                                                                ||
|-------------|-----------------------------------------------------------------------------------------------------------------------------|
| `expedited` | [Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html):whether to run expedited. Default false. |

### setExtras

Added in[API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open fun setExtras(bundle: Bundle!): SyncRequest.Builder!
```

Developer-provided extras handed back when sync actually occurs. This bundle is copied into the SyncRequest returned by[build()](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#build()). Example:  

```kotlin
String[] syncItems = {"dog", "cat", "frog", "child"};
    SyncRequest.Builder builder =
      new SyncRequest.Builder()
        .setSyncAdapter(dummyAccount, dummyProvider)
        .syncOnce();
 
    for (String syncData : syncItems) {
      Bundle extras = new Bundle();
      extras.setString("data", syncData);
      builder.setExtras(extras);
      ContentResolver.sync(builder.build()); // Each sync() request creates a unique sync.
    }
  
```
Only values of the following types may be used in the extras bundle:

- Integer
- Long
- Boolean
- Float
- Double
- String
- Account
- null

If any data is present in the bundle not of this type, build() will throw a runtime exception.

<br />

|                                                    Parameters                                                     ||
|----------|---------------------------------------------------------------------------------------------------------|
| `bundle` | [Bundle](https://developer.android.com/reference/kotlin/android/os/Bundle.html#)!:extras bundle to set. |

### setIgnoreBackoff

Added in[API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open fun setIgnoreBackoff(ignoreBackoff: Boolean): SyncRequest.Builder!
```

Convenience function for setting[ContentResolver.SYNC_EXTRAS_IGNORE_BACKOFF](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF:kotlin.String). Ignoring back-off will force the sync scheduling process to ignore any back-off that was the result of a failed sync, as well as to invalidate any[SyncResult.delayUntil](https://developer.android.com/reference/kotlin/android/content/SyncResult#delayUntil:kotlin.Long)value that may have been set by the adapter. Successive failures will not honor this flag. Not valid for periodic sync and will throw an`IllegalArgumentException`in[build()](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#build()).

|                                                                  Parameters                                                                  ||
|-----------------|-----------------------------------------------------------------------------------------------------------------------------|
| `ignoreBackoff` | [Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html):ignore back off settings. Default false. |

### setIgnoreSettings

Added in[API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open fun setIgnoreSettings(ignoreSettings: Boolean): SyncRequest.Builder!
```

Convenience function for setting[ContentResolver.SYNC_EXTRAS_IGNORE_SETTINGS](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_IGNORE_SETTINGS:kotlin.String). Not valid for periodic sync and will throw an`IllegalArgumentException`in[build()](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#build()).

Throws`IllegalArgumentException`if called and[setDisallowMetered(boolean)](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#setDisallowMetered(kotlin.Boolean))has been set.

|                                                                             Parameters                                                                              ||
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| `ignoreSettings` | [Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html):true to ignore the sync automatically settings. Default false. |

### setManual

Added in[API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open fun setManual(isManual: Boolean): SyncRequest.Builder!
```

Convenience function for setting[ContentResolver.SYNC_EXTRAS_MANUAL](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_MANUAL:kotlin.String). Not valid for periodic sync and will throw an`IllegalArgumentException`in[build()](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#build()).

|                                                                Parameters                                                                 ||
|------------|-------------------------------------------------------------------------------------------------------------------------------|
| `isManual` | [Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html):User-initiated sync or not. Default false. |

### setNoRetry

Added in[API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open fun setNoRetry(noRetry: Boolean): SyncRequest.Builder!
```

Convenience function for setting[ContentResolver.SYNC_EXTRAS_DO_NOT_RETRY](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY:kotlin.String). A one-off sync operation that fails will be retried with exponential back-off unless this is set to false. Not valid for periodic sync and will throw an`IllegalArgumentException`in build().

|                                                                  Parameters                                                                   ||
|-----------|------------------------------------------------------------------------------------------------------------------------------------|
| `noRetry` | [Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html):true to not retry a failed sync. Default false. |

### setRequiresCharging

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open fun setRequiresCharging(requiresCharging: Boolean): SyncRequest.Builder!
```

Specify whether the sync requires the phone to be plugged in.

|                                                                               Parameters                                                                                ||
|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| `requiresCharging` | [Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html):true if sync requires the phone to be plugged in. Default false. |

### setScheduleAsExpeditedJob

Added in[API level 31](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open fun setScheduleAsExpeditedJob(scheduleAsExpeditedJob: Boolean): SyncRequest.Builder
```

Convenience function for setting[ContentResolver.SYNC_EXTRAS_SCHEDULE_AS_EXPEDITED_JOB](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_SCHEDULE_AS_EXPEDITED_JOB:kotlin.String).

Not to be confused with[ContentResolver.SYNC_EXTRAS_EXPEDITED](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_EXPEDITED:kotlin.String).

Not valid for periodic syncs, expedited syncs, and syncs that require charging - an`IllegalArgumentException`will be thrown in[build()](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#build()).

|                                                                              Parameters                                                                              ||
|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
| `scheduleAsExpeditedJob` | [Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html):whether to schedule as an expedited job. Default false. |

|                                                                 Return                                                                  ||
|------------------------------------------------------------------------------------------------------------|-----------------------------|
| [SyncRequest.Builder](https://developer.android.com/reference/kotlin/android/content/SyncRequest.Builder#) | This value cannot be`null`. |

### setSyncAdapter

Added in[API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open fun setSyncAdapter(
    account: Account!, 
    authority: String!
): SyncRequest.Builder!
```

Specify an authority and account for this transfer.

|                                                                                                                                 Parameters                                                                                                                                  ||
|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `authority` | [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)!:A String identifying the content provider to be synced.                                                                                                                      |
| `account`   | [Account](https://developer.android.com/reference/kotlin/android/accounts/Account.html#)!:Account to sync. Can be null unless this is a periodic sync, for which verification by the ContentResolver will fail. If a sync is performed without an account, the |

### syncOnce

Added in[API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open fun syncOnce(): SyncRequest.Builder!
```

Request that a sync occur immediately. Example  

```kotlin
SyncRequest.Builder builder = (new SyncRequest.Builder()).syncOnce();
  
```

<br />

### syncPeriodic

Added in[API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open fun syncPeriodic(
    pollFrequency: Long, 
    beforeSeconds: Long
): SyncRequest.Builder!
```

Build a periodic sync. Either this or syncOnce()**must** be called for this builder. Syncs are identified by target[android.provider](https://developer.android.com/reference/kotlin/android/provider/package-summary.html)and by the contents of the extras bundle. You cannot reuse the same builder for one-time syncs after having specified a periodic sync (by calling this function). If you do, an will be thrown.

The bundle for a periodic sync can be queried by applications with the correct permissions using[ContentResolver.getPeriodicSyncs(Account account, String provider)](https://developer.android.com/reference/kotlin/android/content/ContentResolver#getPeriodicSyncs(android.accounts.Account,%20kotlin.String)), so no sensitive data should be transferred here. Example usage.  

```kotlin
Request a periodic sync every 5 hours with 20 minutes of flex.
      SyncRequest.Builder builder =
          (new SyncRequest.Builder()).syncPeriodic(5 * HOUR_IN_SECS, 20 * MIN_IN_SECS);
 
      Schedule a periodic sync every hour at any point in time during that hour.
      SyncRequest.Builder builder =
          (new SyncRequest.Builder()).syncPeriodic(1 * HOUR_IN_SECS, 1 * HOUR_IN_SECS);
  
```
N.B.: Periodic syncs are not allowed to have any of[ContentResolver.SYNC_EXTRAS_DO_NOT_RETRY](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY:kotlin.String),[ContentResolver.SYNC_EXTRAS_IGNORE_BACKOFF](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF:kotlin.String),[ContentResolver.SYNC_EXTRAS_IGNORE_SETTINGS](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_IGNORE_SETTINGS:kotlin.String),[ContentResolver.SYNC_EXTRAS_INITIALIZE](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_INITIALIZE:kotlin.String),[ContentResolver.SYNC_EXTRAS_FORCE](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_FORCE:kotlin.String),[ContentResolver.SYNC_EXTRAS_EXPEDITED](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_EXPEDITED:kotlin.String),[ContentResolver.SYNC_EXTRAS_MANUAL](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_MANUAL:kotlin.String),[ContentResolver.SYNC_EXTRAS_SCHEDULE_AS_EXPEDITED_JOB](https://developer.android.com/reference/kotlin/android/content/ContentResolver#SYNC_EXTRAS_SCHEDULE_AS_EXPEDITED_JOB:kotlin.String)set to true. If any are supplied then an`IllegalArgumentException`will be thrown.

|                                                                                                                                       Parameters                                                                                                                                        ||
|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `pollFrequency` | [Long](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-long/index.html):the amount of time in seconds that you wish to elapse between periodic syncs. A minimum period of 1 hour is enforced.                                                                     |
| `beforeSeconds` | [Long](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-long/index.html):the amount of flex time in seconds before`pollFrequency`that you permit for the sync to take place. Must be less than`pollFrequency`and greater than MAX(5% of`pollFrequency`, 5 minutes) |