Photos Library/com.cloudike.sdk.photos.upload

Package-level declarations

Media uploader package.

Uploader

The uploader is used to upload media files. It can upload photos, videos and files with extensions (motion photos) in automatic, family or forced mode.

Uploader Configuration.

The uploader configuration is the main mechanism for interacting with it. With configuration you can:

Manage upload
Configure network policy
Configure operating policies for different system states

The following code example demonstrates changing the uploader configuration.

import com.cloudike.sdk.photos.PhotoManager
import com.cloudike.sdk.photos.upload.Uploader

val uploader: Uploader = PhotoManager.uploader

// Enable only photo auto upload.
val newConfiguration: UploaderConfiguration = uploader.configuration.copy(
    isAutoUploadEnabled = true,
    isAutoUploadVideoEnabled = true
)

uploader.configuration = newConfiguration

Manage Upload

Upload configuration includes four parameters. As shown in the following example.

import com.cloudike.sdk.photos.PhotoManager
import com.cloudike.sdk.photos.upload.Uploader
import com.cloudike.sdk.photos.upload.data.UploadConfiguration

val uploader: Uploader = PhotoManager.uploader

val newConfiguration: UploaderConfiguration = uploader.configuration.copy(
    
    // Default - false 
    isAutoUploadEnabled = true,

    // Default - false
    isAutoUploadVideoEnabled = true,

    // Default - 0.5
    videoUploadPriority = 0.5f,

    // Number of retries to upload a media file. Default - 3.
    maxRetryCount = 1
)

uploader.configuration = newConfiguration

Parameters:

isAutoUploadEnabled - Parameter responsible for the operation of the auto uploader. Important! Before start the uploader, you must perform local and backend scanning of media files.
isAutoUploadVideoEnabled - Can the auto uploader upload videos.
videoUploadPriority - Video loading priority.

Let’s take a special look at the priority of video loading. Parameter videoUploadPriority controls how many uploaders dedicated to upload both photos and videos. The parameter can take values from 0 to 1. The greater value, the more uploaders upload media including videos.

For example: videoUploadPriority == 0.3f means that 30% of upload workers will process both videos and photos. While 70% of uploaders will upload photos only. These photo-dedicated uploaders will begin upload videos when there are no more photos left in the queue. However, if new photos are added they switch back to photo uploading.

If flag isVideoUploadEnabled is set to false, no all-media uploaders are allocated. If isVideoUploadEnabled == true and videoUploadPriority == 0.0f, upload manager keeps running one all-media uploader that uploads both photos and videos.

Note. Uploaders never drop their current uploading. Changing the role of an uploader and getting next media file from the queue according to the new role happens only when current uploading is finished.

Network configuration

Network configuration includes three parameters. As shown in the following example.

import com.cloudike.sdk.photos.PhotoManager
import com.cloudike.sdk.photos.upload.Uploader

val uploader: Uploader = PhotoManager.uploader

val newConfiguration: UploaderConfiguration = uploader.configuration.copy(
    
    // If true - upload allowed when using cellular network. Default - false.
    isCellularUploadEnabled = true,

    // If true - upload allowed in roaming (using cellular network). Default - false.
    isRoamingUploadEnabled = true
)

uploader.configuration = newConfiguration

System configuration

Network configuration includes only one parameter. As shown in the following example.

import com.cloudike.sdk.photos.PhotoManager
import com.cloudike.sdk.photos.upload.Uploader

val uploader: Uploader = PhotoManager.uploader

val newConfiguration: UploaderConfiguration = uploader.configuration.copy(
    
    // Stop auto-upload when battery level reaches the specified value.
    // If 0.0 - not limited. Default - 0.3f.
    minBatteryLevel = 0.3f
)

uploader.configuration = newConfiguration

Monitor Upload Status

The status of the uploader is represented by the UploadStatus class. With its help you can get the status automatic uploader, priority uploader status, as well as a list of uploader factors.

The following code example demonstrates monitoring of uploader status.

import kotlinx.coroutines.CoroutineScope
import com.cloudike.sdk.photos.upload.Uploader

// ...

val scope: CoroutineScope
val uploader: Uploader

scope.launch {
    uploader.stateFlow.collect { uploadStatus ->
        val status: UploadStatus = uploadStatus
        
        val autoUploaderStatus: UploaderStatus = status.autoUploaderStatus
        val forcedUploaderStatus: UploaderStatus = status.forcedUploaderStatus
        val familyUploaderStatus: UploaderStatus = status.familyUploaderStatus
    }
}

Upload factors are particles that reflect the state of loading in general and the state of loaders in particular. Factors are described by the UploadFactors enum class.

The state of a specific loader is described by the UploaderStatus class. Using it, you can get information about the number of photos and videos in the upload queue, the number of active workers, a list of factors why the uploader is not active and another upload factors.

import kotlinx.coroutines.CoroutineScope
import com.cloudike.sdk.photos.upload.Uploader

// ...

val scope: CoroutineScope
val uploader: Uploader

scope.launch {
    uploader.stateFlow.collect { uploadStatus ->
        val autoUploaderStatus = uploadStatus.autoUploaderStatus

        // The number of media files that are currently uploading.
        autoUploaderStatus.activeMediaCount
        
        // The number of photos that are in the queue for uploading.
        autoUploaderStatus.inQueuePhotoCount

        // The number of videos that are in the queue for uploading.
        autoUploaderStatus.inQueueVideoCount
        
        // List of factors why upload is inactive. The uploader is inactive if the set is empty.
        autoUploaderStatus.inactiveFactors

        // List of non critical factors.
        autoUploaderStatus.factors
    }	
}

Assign Media To Uploader

With a uploader, you can assign specific media files to a specific uploader.

import kotlinx.coroutines.CoroutineScope
import com.cloudike.sdk.photos.upload.Uploader
import com.cloudike.sdk.photos.upload.data.UploaderType

// ...

val scope: CoroutineScope
val uploader: Uploader
val mediaIds: List<Long>

scope.launch {
    uploader.uploadMedia(mediaIds, UploaderType.FORCED)
}

You can use uris to upload media.

import android.net.Uri
import kotlinx.coroutines.CoroutineScope
import com.cloudike.sdk.photos.upload.Uploader
import com.cloudike.sdk.photos.upload.data.UploaderType

// ...

val scope: CoroutineScope
val uploader: Uploader
val mediaUris: List<Uri>

scope.launch {
    uploader.uploadMediaByUris(mediaUris, UploaderType.Family)
}

You can also wait for the media files you specified to upload.

import kotlinx.coroutines.CoroutineScope
import com.cloudike.sdk.photos.upload.Uploader
import com.cloudike.sdk.photos.upload.data.UploaderType

// ...

val scope: CoroutineScope
val uploader: Uploader
val mediaIds: List<Long>

scope.launch {
    val uploadResult = uploader.uploadMediaAndAwait(mediaIds, UploaderType.FORCED)
}

Set Notification Adapter

To add a notification, you can use the following code example.

import com.cloudike.sdk.photos.upload.Uploader
import com.cloudike.sdk.photos.upload.data.UploaderType

// ...

val uploader: Uploader
val mediaIds: List<Long>

val adapter = object : UploadNotificationAdapter {
    override fun statusToNotification(uploadStatus: UploadStatus): Notification {
        // impl...
    }
}
val uploadResult = uploader.setNotificationAdapter(adapter)

Monitor Uploaded Media

To track uploaded media files, you can use the following code example.

import kotlinx.coroutines.CoroutineScope
import com.cloudike.sdk.photos.upload.Uploader

// ...

val scope: CoroutineScope
val uploader: Uploader

scope.launch {
    uploader.uploadedMediaIdsSharedFlow.collect { mediaIds ->
        // do something...
    }	
}

Introduction To Uploader Logging

This section describes logging the main uploader subsystems. The uploader uses the logging prefix "Uploader". Log example.

UploaderLauncher : [Ph] [Upload] Uploader launched!

An example of a uploader status log. This log will allow you to find out the status of the upload and loaders separately, and the number of elements in the queue.

UploadStatusProvider : [Ph] [Upload] Status updated!
    AUTO Uploader Status [Inactive]: Nothing to upload!
        Factors - [Backend low volume]
        Inactive Factors - [Backend not read, Uploader disabled]
    FORCED Uploader Status [Inactive]: Nothing to upload!
        Factors - [Backend low volume]
        Inactive Factors - [Backend not read]
    FAMILY Uploader Status [Inactive]: Nothing to upload!
        Inactive Factors - [Backend not read]
...

UploadStatusProvider : [Ph] [Upload] Status updated!
    AUTO Uploader Status [Active]: In Upload - 5. In Queue - 106 [Photo - 106; Video - 0]
    FORCED Uploader Status [Active]: Nothing to upload!
    FAMILY Uploader Status [Active]: Nothing to upload!

An example of a uploader configurator log.

UploaderConfigurator : [Ph] [Upload] Configuration changed!
    auto upload	- true	| min battery level - 0.0
    video       - false	| video upload priority - 0.5
    cellular    - false	| max retry count - 3
    roaming     - false	|

An example of a uploader worker log. The "AUTO", "FAMILY" and "FORCED" tags are responsible for auto, family and force uploaders, respectively.

MarkPhotoDoneOp	: [Ph] [Upload] [AUTO] [Worker - 4] [id - `7`] Photo marked done!
MarkPhotoDoneOp	: [Ph] [Upload] [FORCED] [Worker - 5] [id - `2`] Photo marked done!
MarkPhotoDoneOp	: [Ph] [Upload] [FAMILY] [Worker - 6] [id - `17`] Photo marked done!

Types

Uploader

interface Uploader

Media files uploader.

UploadNotificationAdapter

interface UploadNotificationAdapter

An interface to implement an adapter that translates the uploading state into a notification. The uploader uses it to display notifications during boot.