1fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams/* 2fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Copyright (C) 2013 The Android Open Source Project 3fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 4fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Licensed under the Apache License, Version 2.0 (the "License"); 5fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * you may not use this file except in compliance with the License. 6fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * You may obtain a copy of the License at 7fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 8fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * http://www.apache.org/licenses/LICENSE-2.0 9fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 10fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Unless required by applicable law or agreed to in writing, software 11fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * distributed under the License is distributed on an "AS IS" BASIS, 12fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * See the License for the specific language governing permissions and 14fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * limitations under the License. 15fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 16fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 17fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williamspackage android.content; 18fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 19fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williamsimport android.accounts.Account; 20fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williamsimport android.os.Bundle; 21fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williamsimport android.os.Parcel; 22fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williamsimport android.os.Parcelable; 23fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 24fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williamspublic class SyncRequest implements Parcelable { 25fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final String TAG = "SyncRequest"; 266222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams /** Account to pass to the sync adapter. May be null. */ 27fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final Account mAccountToSync; 28fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Authority string that corresponds to a ContentProvider. */ 29fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final String mAuthority; 306222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams /** Sync service identifier. May be null.*/ 31fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final ComponentName mComponentInfo; 32fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Bundle containing user info as well as sync settings. */ 33fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final Bundle mExtras; 346222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams /** Disallow this sync request on metered networks. */ 356222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams private final boolean mDisallowMetered; 36fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 37fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Anticipated upload size in bytes. 38fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * TODO: Not yet used - we put this information into the bundle for simplicity. 39fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 40fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final long mTxBytes; 41fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 42fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Anticipated download size in bytes. 43fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * TODO: Not yet used - we put this information into the bundle. 44fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 45fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final long mRxBytes; 46fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 47c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Amount of time before {@link #mSyncRunTimeSecs} from which the sync may optionally be 48fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * started. 49fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 50fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final long mSyncFlexTimeSecs; 51fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 52fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Specifies a point in the future at which the sync must have been scheduled to run. 53fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 54fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final long mSyncRunTimeSecs; 55fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Periodic versus one-off. */ 56fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final boolean mIsPeriodic; 57fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Service versus provider. */ 58fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final boolean mIsAuthority; 59fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Sync should be run in lieu of other syncs. */ 60fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final boolean mIsExpedited; 61fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 62fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 63fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 64fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return whether this sync is periodic or one-time. A Sync Request must be 65fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * either one of these or an InvalidStateException will be thrown in 66fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Builder.build(). 67fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 68fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public boolean isPeriodic() { 69fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mIsPeriodic; 70fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 71fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 726222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams /** 736222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * {@hide} 746222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * @return whether this is an expedited sync. 756222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams */ 76fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public boolean isExpedited() { 77fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mIsExpedited; 78fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 79fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 80fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 81fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 826222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * @return true if this sync uses an account/authority pair, or false if this sync is bound to 836222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * a Sync Service. 84fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 85fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public boolean hasAuthority() { 86fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mIsAuthority; 87fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 88fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 89fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 90fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 916222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * @return account object for this sync. 926222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * @throws IllegalArgumentException if this function is called for a request that does not 936222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * specify an account/provider authority. 94fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 956222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams public Account getAccount() { 96fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (!hasAuthority()) { 976222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams throw new IllegalArgumentException("Cannot getAccount() for a sync that does not" 986222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams + "specify an authority."); 99fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 1006222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams return mAccountToSync; 101fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 102fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 103fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 104fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 1056222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * @return provider for this sync. 1066222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * @throws IllegalArgumentException if this function is called for a request that does not 1076222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * specify an account/provider authority. 108fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 1096222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams public String getProvider() { 1106222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams if (!hasAuthority()) { 1116222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams throw new IllegalArgumentException("Cannot getProvider() for a sync that does not" 1126222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams + "specify a provider."); 113fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 1146222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams return mAuthority; 115fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 116fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 117fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 118fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 119fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Retrieve bundle for this SyncRequest. Will not be null. 120fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 121fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Bundle getBundle() { 122fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mExtras; 123fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 124fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 125fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 126fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 127fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return the earliest point in time that this sync can be scheduled. 128fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 129fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public long getSyncFlexTime() { 130fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mSyncFlexTimeSecs; 131fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 1326222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams 133fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 134fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 135fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return the last point in time at which this sync must scheduled. 136fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 137fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public long getSyncRunTime() { 138fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mSyncRunTimeSecs; 139fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 140fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 141fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public static final Creator<SyncRequest> CREATOR = new Creator<SyncRequest>() { 142fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 143fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams @Override 144fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public SyncRequest createFromParcel(Parcel in) { 145fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return new SyncRequest(in); 146fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 147fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 148fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams @Override 149fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public SyncRequest[] newArray(int size) { 150fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return new SyncRequest[size]; 151fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 152fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams }; 153fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 154fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams @Override 155fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public int describeContents() { 156fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return 0; 157fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 158fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 159fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams @Override 160fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public void writeToParcel(Parcel parcel, int flags) { 161fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeBundle(mExtras); 162fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeLong(mSyncFlexTimeSecs); 163fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeLong(mSyncRunTimeSecs); 164fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeInt((mIsPeriodic ? 1 : 0)); 1656222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams parcel.writeInt((mDisallowMetered ? 1 : 0)); 166fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeLong(mTxBytes); 167fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeLong(mRxBytes); 168fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeInt((mIsAuthority ? 1 : 0)); 169fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeInt((mIsExpedited? 1 : 0)); 170fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIsAuthority) { 171fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeParcelable(mAccountToSync, flags); 172fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeString(mAuthority); 173fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } else { 174fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeParcelable(mComponentInfo, flags); 175fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 176fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 177fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 178fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private SyncRequest(Parcel in) { 179fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mExtras = in.readBundle(); 180fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncFlexTimeSecs = in.readLong(); 181fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncRunTimeSecs = in.readLong(); 182fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsPeriodic = (in.readInt() != 0); 1836222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams mDisallowMetered = (in.readInt() != 0); 184fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mTxBytes = in.readLong(); 185fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mRxBytes = in.readLong(); 186fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsAuthority = (in.readInt() != 0); 187fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsExpedited = (in.readInt() != 0); 188fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIsAuthority) { 189fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mComponentInfo = null; 190fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAccountToSync = in.readParcelable(null); 191fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAuthority = in.readString(); 192fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } else { 193fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mComponentInfo = in.readParcelable(null); 194fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAccountToSync = null; 195fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAuthority = null; 196fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 197fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 198fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 199fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** {@hide} Protected ctor to instantiate anonymous SyncRequest. */ 200fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams protected SyncRequest(SyncRequest.Builder b) { 201fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncFlexTimeSecs = b.mSyncFlexTimeSecs; 202fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncRunTimeSecs = b.mSyncRunTimeSecs; 203fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAccountToSync = b.mAccount; 204fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAuthority = b.mAuthority; 205fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mComponentInfo = b.mComponentName; 206fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsPeriodic = (b.mSyncType == Builder.SYNC_TYPE_PERIODIC); 207fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsAuthority = (b.mSyncTarget == Builder.SYNC_TARGET_ADAPTER); 208fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsExpedited = b.mExpedited; 209fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mExtras = new Bundle(b.mCustomExtras); 21068e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams // For now we merge the sync config extras & the custom extras into one bundle. 21168e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams // TODO: pass the configuration extras through separately. 21268e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mExtras.putAll(b.mSyncConfigExtras); 2136222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams mDisallowMetered = b.mDisallowMetered; 214fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mTxBytes = b.mTxBytes; 215fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mRxBytes = b.mRxBytes; 216fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 217fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 218fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 2196222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * Builder class for a {@link SyncRequest}. As you build your SyncRequest this class will also 220fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * perform validation. 221fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 222fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public static class Builder { 223fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Unknown sync type. */ 224fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TYPE_UNKNOWN = 0; 225fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Specify that this is a periodic sync. */ 226fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TYPE_PERIODIC = 1; 227fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Specify that this is a one-time sync. */ 228fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TYPE_ONCE = 2; 229fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Unknown sync target. */ 230fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TARGET_UNKNOWN = 0; 231fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Specify that this is an anonymous sync. */ 232fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TARGET_SERVICE = 1; 233fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Specify that this is a sync with a provider. */ 234fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TARGET_ADAPTER = 2; 2356222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams /** Earliest point of displacement into the future at which this sync can occur. */ 236fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private long mSyncFlexTimeSecs; 2376222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams /** Latest point of displacement into the future at which this sync must occur. */ 238fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private long mSyncRunTimeSecs; 239fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 240fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Sync configuration information - custom user data explicitly provided by the developer. 241fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * This data is handed over to the sync operation. 242fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 243fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private Bundle mCustomExtras; 244fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 245fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Sync system configuration - used to store system sync configuration. Corresponds to 246fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * ContentResolver.SYNC_EXTRAS_* flags. 247fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * TODO: Use this instead of dumping into one bundle. Need to decide if these flags should 248fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * discriminate between equivalent syncs. 249fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 250fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private Bundle mSyncConfigExtras; 251fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Expected upload transfer in bytes. */ 252fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private long mTxBytes = -1L; 253fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Expected download transfer in bytes. */ 254fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private long mRxBytes = -1L; 255fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Whether or not this sync can occur on metered networks. Default false. */ 2566222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams private boolean mDisallowMetered; 257fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Priority of this sync relative to others from calling app [-2, 2]. Default 0. */ 258fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private int mPriority = 0; 259fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 260fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Whether this builder is building a periodic sync, or a one-time sync. 261fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 262fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private int mSyncType = SYNC_TYPE_UNKNOWN; 263fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Whether this will go to a sync adapter or to a sync service. */ 264fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private int mSyncTarget = SYNC_TARGET_UNKNOWN; 265fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Whether this is a user-activated sync. */ 266fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mIsManual; 267fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 268fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Whether to retry this one-time sync if the sync fails. Not valid for 269c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * periodic syncs. See {@link ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY}. 270fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 271fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mNoRetry; 272fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 273fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Whether to respect back-off for this one-time sync. Not valid for 274fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * periodic syncs. See 275c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF}; 276fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 277fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mIgnoreBackoff; 278fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 279fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Ignore sync system settings and perform sync anyway. */ 280fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mIgnoreSettings; 281fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 282fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** This sync will run in preference to other non-expedited syncs. */ 283fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mExpedited; 284fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 285fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 2866222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * The sync component that contains the sync logic if this is a provider-less sync, 2876222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * otherwise null. 288fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 289fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private ComponentName mComponentName; 290fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 291fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * The Account object that together with an Authority name define the SyncAdapter (if 292c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * this sync is bound to a provider), otherwise null. 293fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 294fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private Account mAccount; 295fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 296fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * The Authority name that together with an Account define the SyncAdapter (if 297c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * this sync is bound to a provider), otherwise null. 298fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 299fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private String mAuthority; 300fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 301fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder() { 302fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 303fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 304fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 3056222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * Request that a sync occur immediately. 306fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 307fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Example 308fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <pre> 3096222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * SyncRequest.Builder builder = (new SyncRequest.Builder()).syncOnce(); 310fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * </pre> 311fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 3126222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams public Builder syncOnce() { 313fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncType != SYNC_TYPE_UNKNOWN) { 314fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Sync type has already been defined."); 315fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 316fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncType = SYNC_TYPE_ONCE; 3176222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams setupInterval(0, 0); 318fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 319fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 320fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 321fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 322fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Build a periodic sync. Either this or syncOnce() <b>must</b> be called for this builder. 3236222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * Syncs are identified by target {@link android.provider}/{@link android.accounts.Account} 3246222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * and by the contents of the extras bundle. 3256222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * You cannot reuse the same builder for one-time syncs (by calling this function) after 3266222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * having specified a periodic sync. If you do, an <code>IllegalArgumentException</code> 327c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * will be thrown. 328c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 329fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Example usage. 330fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 331fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <pre> 332fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Request a periodic sync every 5 hours with 20 minutes of flex. 333fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest.Builder builder = 334fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * (new SyncRequest.Builder()).syncPeriodic(5 * HOUR_IN_SECS, 20 * MIN_IN_SECS); 335fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 336fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Schedule a periodic sync every hour at any point in time during that hour. 337fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest.Builder builder = 338fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * (new SyncRequest.Builder()).syncPeriodic(1 * HOUR_IN_SECS, 1 * HOUR_IN_SECS); 339fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * </pre> 340fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 341fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * N.B.: Periodic syncs are not allowed to have any of 3428cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY}, 3438cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF}, 3448cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_IGNORE_SETTINGS}, 3458cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_INITIALIZE}, 3468cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_FORCE}, 3478cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_EXPEDITED}, 3488cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_MANUAL} 349c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * set to true. If any are supplied then an <code>IllegalArgumentException</code> will 350fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * be thrown. 351fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 352fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param pollFrequency the amount of time in seconds that you wish 353fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * to elapse between periodic syncs. 354fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param beforeSeconds the amount of flex time in seconds before 355fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@code pollFrequency} that you permit for the sync to take 356fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * place. Must be less than {@code pollFrequency}. 357fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 358fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder syncPeriodic(long pollFrequency, long beforeSeconds) { 359fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncType != SYNC_TYPE_UNKNOWN) { 360fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Sync type has already been defined."); 361fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 362fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncType = SYNC_TYPE_PERIODIC; 363fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams setupInterval(pollFrequency, beforeSeconds); 364fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 365fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 366fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 367fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** {@hide} */ 368fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private void setupInterval(long at, long before) { 369fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (before > at) { 370fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Specified run time for the sync must be" + 371c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams " after the specified flex time."); 372fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 373fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncRunTimeSecs = at; 374fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncFlexTimeSecs = before; 375fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 376fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 377fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 3786222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * {@hide} 379c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Developer can provide insight into their payload size; optional. -1 specifies unknown, 380c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * so that you are not restricted to defining both fields. 381fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 382fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param rxBytes Bytes expected to be downloaded. 383fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param txBytes Bytes expected to be uploaded. 384fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 385fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setTransferSize(long rxBytes, long txBytes) { 386fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mRxBytes = rxBytes; 387fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mTxBytes = txBytes; 388fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 389fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 390fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 391fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 3926222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * @see android.net.ConnectivityManager#isActiveNetworkMetered() 3936222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * @param disallow true to enforce that this transfer not occur on metered networks. 3946222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * Default false. 395fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 3966222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams public Builder setDisallowMetered(boolean disallow) { 3976222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams mDisallowMetered = disallow; 398fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 399fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 400fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 401fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 4026222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * Specify an authority and account for this transfer. 403fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 4046222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * @param authority String identifying which content provider to sync. 4056222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * @param account Account to sync. Can be null unless this is a periodic sync. 406fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 407fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setSyncAdapter(Account account, String authority) { 408fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncTarget != SYNC_TARGET_UNKNOWN) { 409fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Sync target has already been defined."); 410fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 411632515b9d0960749ddb1636677d7f12f196d73f7Matthew Williams if (authority != null && authority.length() == 0) { 412632515b9d0960749ddb1636677d7f12f196d73f7Matthew Williams throw new IllegalArgumentException("Authority must be non-empty"); 413632515b9d0960749ddb1636677d7f12f196d73f7Matthew Williams } 414fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncTarget = SYNC_TARGET_ADAPTER; 415fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAccount = account; 416fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAuthority = authority; 417fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mComponentName = null; 418fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 419fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 420fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 421fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 4226222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * Optional developer-provided extras handed back in 4236222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * {@link AbstractThreadedSyncAdapter#onPerformSync(Account, Bundle, String, 4246222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * ContentProviderClient, SyncResult)} occurs. This bundle is copied into the SyncRequest 4256222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * returned by {@link #build()}. 426fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 427fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Example: 428fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <pre> 429fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * String[] syncItems = {"dog", "cat", "frog", "child"}; 430fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest.Builder builder = 431fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * new SyncRequest.Builder() 432fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * .setSyncAdapter(dummyAccount, dummyProvider) 433fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * .syncOnce(5 * MINUTES_IN_SECS); 434fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 435fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * for (String syncData : syncItems) { 436fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Bundle extras = new Bundle(); 437fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * extras.setString("data", syncData); 438fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * builder.setExtras(extras); 4396222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * ContentResolver.sync(builder.build()); // Each sync() request is for a unique sync. 440fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * } 441fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * </pre> 442fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Only values of the following types may be used in the extras bundle: 443fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <ul> 444fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Integer</li> 445fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Long</li> 446fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Boolean</li> 447fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Float</li> 448fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Double</li> 449fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>String</li> 450fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Account</li> 451fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>null</li> 452fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * </ul> 453fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * If any data is present in the bundle not of this type, build() will 454fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * throw a runtime exception. 455fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 456c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param bundle extras bundle to set. 457fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 458fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setExtras(Bundle bundle) { 459fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mCustomExtras = bundle; 460fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 461fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 462fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 463fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 464c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Convenience function for setting {@link ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY}. 465c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 466c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * A one-off sync operation that fails will be retried with exponential back-off unless 467c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * this is set to false. Not valid for periodic sync and will throw an 468c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * <code>IllegalArgumentException</code> in build(). 469fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 470c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param noRetry true to not retry a failed sync. Default false. 471fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 472c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams public Builder setNoRetry(boolean noRetry) { 473c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams mNoRetry = noRetry; 474fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 475fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 476fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 477fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 478c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Convenience function for setting {@link ContentResolver#SYNC_EXTRAS_IGNORE_SETTINGS}. 479c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 4806222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * A sync can specify that system sync settings be ignored (user has turned sync off). Not 4816222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * valid for periodic sync and will throw an <code>IllegalArgumentException</code> in 482c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link #build()}. 483c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 484c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param ignoreSettings true to ignore the sync automatically settings. Default false. 485fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 486fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setIgnoreSettings(boolean ignoreSettings) { 487fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIgnoreSettings = ignoreSettings; 488fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 489fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 490fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 491fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 4928cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * Convenience function for setting {@link ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF}. 493fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 4946222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * Force the sync scheduling process to ignore any back-off that was the result of a failed 4956222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * sync, as well as to invalidate any {@link SyncResult#delayUntil} value that may have 4966222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * been set by the adapter. Successive failures will not honor this flag. Not valid for 4976222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * periodic sync and will throw an <code>IllegalArgumentException</code> in 4986222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * {@link #build()}. 499c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 5006222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * @param ignoreBackoff ignore back-off settings. Default false. 501fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 502fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setIgnoreBackoff(boolean ignoreBackoff) { 503fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIgnoreBackoff = ignoreBackoff; 504fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 505fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 506fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 507fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 508c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Convenience function for setting {@link ContentResolver#SYNC_EXTRAS_MANUAL}. 509c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 5106222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * A manual sync is functionally equivalent to calling {@link #setIgnoreBackoff(boolean)} 5116222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * and {@link #setIgnoreSettings(boolean)}. Not valid for periodic sync and will throw an 5126222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * <code>IllegalArgumentException</code> in {@link #build()}. 513c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 514c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param isManual User-initiated sync or not. Default false. 515fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 516fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setManual(boolean isManual) { 517fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsManual = isManual; 518fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 519fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 520fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 521fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 5226222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * An expedited sync runs immediately and will preempt another non-expedited running sync. 523c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 524c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Not valid for periodic sync and will throw an <code>IllegalArgumentException</code> in 525c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link #build()}. 526c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 527c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param expedited whether to run expedited. Default false. 528fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 529fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setExpedited(boolean expedited) { 530fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mExpedited = expedited; 531fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 532fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 533fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 534fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 5356222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams * {@hide} 536c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param priority the priority of this request among all requests from the calling app. 537c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Range of [-2,2] similar to how this is done with notifications. 538fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 539fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setPriority(int priority) { 540fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (priority < -2 || priority > 2) { 541fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Priority must be within range [-2, 2]"); 542fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 543fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mPriority = priority; 544fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 545fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 546fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 547fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 548fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Performs validation over the request and throws the runtime exception 549c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * <code>IllegalArgumentException</code> if this validation fails. 550fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 551fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return a SyncRequest with the information contained within this 552fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * builder. 553fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 554fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public SyncRequest build() { 555fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mCustomExtras == null) { 556fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mCustomExtras = new Bundle(); 557fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 5586222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams // Validate the extras bundle 5596222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams ContentResolver.validateSyncExtrasBundle(mCustomExtras); 56068e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams // Combine builder extra flags into the config bundle. 56168e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras = new Bundle(); 562fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIgnoreBackoff) { 56368e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_IGNORE_BACKOFF, true); 564fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 5656222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams if (mDisallowMetered) { 5666222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_DISALLOW_METERED, true); 567fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 568fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIgnoreSettings) { 56968e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_IGNORE_SETTINGS, true); 570fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 571fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mNoRetry) { 57268e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_DO_NOT_RETRY, true); 573fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 574fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mExpedited) { 57568e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_EXPEDITED, true); 576fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 577fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIsManual) { 57868e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_MANUAL, true); 579fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 58068e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putLong(ContentResolver.SYNC_EXTRAS_EXPECTED_UPLOAD, mTxBytes); 58168e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putLong(ContentResolver.SYNC_EXTRAS_EXPECTED_DOWNLOAD, mRxBytes); 58268e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putInt(ContentResolver.SYNC_EXTRAS_PRIORITY, mPriority); 583fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncType == SYNC_TYPE_PERIODIC) { 58468e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams // If this is a periodic sync ensure than invalid extras were not set. 58568e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams validatePeriodicExtras(mCustomExtras); 58668e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams validatePeriodicExtras(mSyncConfigExtras); 5876222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams // Verify that account and provider are not null. 5886222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams if (mAccount == null) { 5896222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams throw new IllegalArgumentException("Account must not be null for periodic" 5906222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams + " sync."); 5916222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams } 5926222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams if (mAuthority == null) { 5936222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams throw new IllegalArgumentException("Authority must not be null for periodic" 5946222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams + " sync."); 5956222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams } 596fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } else if (mSyncType == SYNC_TYPE_UNKNOWN) { 597fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Must call either syncOnce() or syncPeriodic()"); 598fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 599fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams // Ensure that a target for the sync has been set. 600fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncTarget == SYNC_TARGET_UNKNOWN) { 6016222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams throw new IllegalArgumentException("Must specify an adapter with " 6026222288bfbae46550b4914ef1eb12c69dc1f716cMatthew Williams + "setSyncAdapter(Account, String"); 603fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 604fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return new SyncRequest(this); 605fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 60668e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams 60768e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams /** 60868e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams * Helper function to throw an <code>IllegalArgumentException</code> if any illegal 60968e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams * extras were set for a periodic sync. 61068e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams * 61168e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams * @param extras bundle to validate. 61268e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams */ 61368e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams private void validatePeriodicExtras(Bundle extras) { 61468e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams if (extras.getBoolean(ContentResolver.SYNC_EXTRAS_MANUAL, false) 61568e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams || extras.getBoolean(ContentResolver.SYNC_EXTRAS_DO_NOT_RETRY, false) 61668e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams || extras.getBoolean(ContentResolver.SYNC_EXTRAS_IGNORE_BACKOFF, false) 61768e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams || extras.getBoolean(ContentResolver.SYNC_EXTRAS_IGNORE_SETTINGS, false) 61868e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams || extras.getBoolean(ContentResolver.SYNC_EXTRAS_INITIALIZE, false) 61968e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams || extras.getBoolean(ContentResolver.SYNC_EXTRAS_FORCE, false) 62068e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams || extras.getBoolean(ContentResolver.SYNC_EXTRAS_EXPEDITED, false)) { 62168e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams throw new IllegalArgumentException("Illegal extras were set"); 62268e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams } 62368e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams } 624fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 625fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams} 626