Core Library/com.cloudike.sdk.core.sharing

Package-level declarations

Managing shared links.

Sharing

Sharing methods are available from the SharingManager interface. These methods allow you to create and control shared links.

import com.cloudike.sdk.core.CoreManager
import com.cloudike.sdk.core.sharing.SharingManager

val coreContext: CoreContext = coreManager.build(/* ... */)
val sharingManager: SharingManager = coreContext.sharingManager

Important! This article contains documentation on the general methods of shared references. For more information on the specialized library methods that use this functionality as a base, see the corresponding articles.

Logging of link functionality is carried out using the "Sharing" tag.

[I] CreateSharedLink : [CL] [Sharing] An attempt to create shared link.

The shared link functionality is divided into two categories: Shared Link Management and Collaborator Management.

Shared Link Management

Create Shared Link

To create a shared link, use the createSharedLink method. The method configuration is represented by a set of parameters.:

Type Defines the logic of the shared link.

Public. Anyone who owns the link has access to its resources.
Password Protected. The link is password protected. Resources are available after authorization.
Limited To A List Of Users. Access to the link is only available to a limited set of users.

Permission. Determines the capabilities of the user who can access the shared link.

View Only. The user can read the content but not change it..
Allow Editing. The user can read and modify the contents of the shared link..

Password. Specified if the link type is "password protected".
Link Expiration Date. Sets the link expiration time. ISO format.
List Of Collaborators. Specified if the link type is "limited to a list of users".

Important! If the configuration contains conflicting values (example: type is public; password is not null), then the method throws an IllegalArgumentException.

val shareManager: SharingManager
val albumItem: AlbumItem
val fileItem: FileItem
val setShareLink = "" // albumItem.linkSetShare or fileItem.linkSetShare

lifecycleScope.launch(Dispatchers.IO) {
    val result: ShareOperationResult = shareManager.createSharedLink(
        setShareLink = mediaItem.linkSetShare,
        type = SharedLinkType.PUBLIC,
        permission = SharedLinkPermission.VIEW_ONLY,
        expires = "2039-03-03T10:37:48Z"

        // Or 

        // type = SharedLinkType.PASSWORD_PROTECTED,
        // permission = SharedLinkPermission.ALLOW_EDITING,
        // password = "*****"

        // Or

        // type = SharedLinkType.LIST_OF_USERS,
        // collaborators = listOf(
        //     CreateCollaboratorMeta(
        //         phoneOrEmail = "email1",
        //         permission = SharedLinkPermission.VIEW_ONLY
        //     ),
        //     CreateCollaboratorMeta(
        //         phoneOrEmail = "phone1",
        //         permission = SharedLinkPermission.ALLOW_EDITING
        //     ),
        //     CreateCollaboratorMeta(
        //         phoneOrEmail = "phone2",
        //         permission = SharedLinkPermission.ALLOW_EDITING
        //      )
        // )
    )
}

To share a set of photos, you must first create an album and then create a link.

val albums: Albums

lifecycleScope.launch(Dispatchers.IO) {
    val result = albums.create(
        userId = 0,
        name = "Album name",
        type = AlbumType.TEMP,
        mediaIds = emptySet(), // : Set<Long> = emptySet()
        mediaUris = emptyList() // : List<Uri> = emptyList()
    )

    val result: ShareOperationResult = sharingManager.createSharedLink(
        setShareLink = result.album.linkSetShare,
        type = SharedLinkType.PUBLIC,
        permission = SharedLinkPermission.VIEW_ONLY
    )
}

Getting A Shared Link

When a link is retrieved from a resource link, the library retrieves the shared link from the backend and then updates it in the database.

val shareManager: SharingManager
var sharedLinkItem: SharedLinkItem

lifecycleScope.launch(Dispatchers.IO) {
    sharedLinkItem = shareManager.getSharedLink(sharedLinkUrl = sharedLinkItem.linkSelf)
}

Opening A Shared Link

The operation of opening a shared public link is based on the utility method getPublicSharedLink. It is used by methods in other libraries (photos and files) to extract a resource (album or file) from a link. Therefore, any exceptions encountered will be transitively received.

val shareManager: SharingManager
val sharedLinkId = ""

lifecycleScope.launch(Dispatchers.IO) {
    val schema: PublicShareSchema = try {
        shareManager.getPublicSharedLink(
            sharedLinkId = sharedLinkId,
            password = "password" // If the link is password protected 
        )
    } catch (exception: IllegalArgumentException) {
        // Invalid password format if password needed
    } catch (exception: PasswordRequiredException) {
        // Requires a password to authorize in a shared link
    } catch (exception: SharedLinkExpiredException) {
        // Shared link expired
    } catch (exception: WrongPasswordException) {
        // Wrong password for shared link
    } catch (exception: InvalidParameterSpecException) {
        // Invalid configuration from backend
    } catch (exception: NotInTheCollaboratorListException) {
        // The account owner is not in the list of collaborators for the shared link
    }
}

Opening a shared album link.

val photoManager: PhotoManager
val publicLink = "public link"

lifecycleScope.launch(Dispatchers.IO) {
    val albumItem: AlbumItem = try {
        photoManager.albums.openSharedLink(
            sharedLink = publicLink,
            password = "*****" // If the link is password protected 
        )
    } catch (exception: IllegalArgumentException) {
        // Invalid password format if password needed
    } catch (exception: PasswordRequiredException) {
        // Requires a password to authorize in a shared link
    } catch (exception: SharedLinkExpiredException) {
        // Shared link expired
    } catch (exception: WrongPasswordException) {
        // Wrong password for shared link
    } catch (exception: InvalidParameterSpecException) {
        // Invalid configuration from backend
    } catch (exception: NotInTheCollaboratorListException) {
        // The account owner is not in the list of collaborators for the shared link
    }
}

Opening a shared file link.

val fileManager: FileManager
val publicLink = "public link"

lifecycleScope.launch(Dispatchers.IO) {
    val result: Any? = try {
        fileManager.sharing.openSharedLink(
            sharedLink = publicLink,
            password = "*****" // If the link is password protected
        )
    } catch (exception: IllegalArgumentException) {
        // Invalid password format if password needed
    } catch (exception: PasswordRequiredException) {
        // Requires a password to authorize in a shared link
    } catch (exception: SharedLinkExpiredException) {
        // Shared link expired
    } catch (exception: WrongPasswordException) {
        // Wrong password for shared link
    } catch (exception: InvalidParameterSpecException) {
        // Invalid configuration from backend
    } catch (exception: NotInTheCollaboratorListException) {
        // The account owner is not in the list of collaborators for the shared link
    }
    
    // result is FileItem or NotMyFSRootItem
}

Editing A Shared Link

Important! As with creating a shared link, the editSharedLink method throws an IllegalArgumentException if the parameters conflict.

val shareManager: SharingManager
val shareLinkItem: SharedLinkItem

lifecycleScope.launch(Dispatchers.IO) {
    val result: ShareOperationResult = shareManager.editSharedLink(
        sharedLinkId = sharedLinkItem.id,
        type = SharedLinkType.LIST_OF_USERS,
        collaborators = listOf(
            CreateCollaboratorMeta(
                phoneOrEmail = "email1",
                permission = SharedLinkPermission.VIEW_ONLY
            ),
            CreateCollaboratorMeta(
                phoneOrEmail = "phone1",
                permission = SharedLinkPermission.ALLOW_EDITING
            ),
            CreateCollaboratorMeta(
                phoneOrEmail = "phone2",
                permission = SharedLinkPermission.ALLOW_EDITING
            )
        )
    )
}

Important! When specifying a new list of collaborators, the editSharedLink method automatically removes and adds the necessary collaborators to match the new list.

Removing A Shared Link

val shareManager: SharingManager
val sharedLinkItem: SharedLinkItem

lifecycleScope.launch(Dispatchers.IO) {
    try {
        shareManager.deleteSharedLink(sharedLinkItem.id)
    } catch (exception: IllegalArgumentException) {
        // The shared link was not found in the database.
    }
}

Collaborator Management

SharingManager provides methods for managing collaborators.

Getting A List Of Collaborators

To get a list of collaborators, you can use the shared link ID.

val shareManager: SharingManager
val sharedLinkItem: SharedLinkItem

// 1. Subscribe to the list of collaborators
lifecycleScope.launch(Dispatchers.IO) {
    shareManager.createCollaboratorsFlow(sharedLinkItem.id).collect { collaborators ->
        // collaborators: List<CollaboratorItem>
        // Handle it...
    }
}

// 2. Starts the process of obtaining collaborators
lifecycleScope.launch(Dispatchers.IO) {
    try {
        shareManager.fetchCollaborators(sharedLinkItem.id)
    } catch (exception: IllegalArgumentException) {
        // The shared link was not found in the database.
    }
}

Adding A Collaborator

Several exceptions may occur when attempting to add a collaborator.

val shareManager: SharingManager
val sharedLinkItem: SharedLinkItem

lifecycleScope.launch(Dispatchers.IO) {
    try {
        shareManager.addCollaborator(
            sharedLinkId = sharedLinkItem.id,
            phoneOrEmail = "email",
            permission = SharedLinkPermission.READ
        )
    } catch (exception: AddYourselfException) {
        // Trying to add myself as a collaborator.
    } catch (exception: AlreadyExistException) {
        // The collaborator has already been added to the shared link.
    } catch (exception: CollaboratorsCountExceededException) {
        // The number of added collaborators has been exceeded.
    } catch (exception: IllegalArgumentException) {
        // The shared link was not found in the database.
    }
}

Editing A Collaborator

val shareManager: SharingManager
val collaborator: CollaboratorItem

lifecycleScope.launch(Dispatchers.IO) {
    val collaborator: CollaboratorItem = try {
        shareManager.editCollaborator(
            collaboratorId = collaborator.id,
            permission = SharedLinkPermission.READ
        )
    } catch (exception: IllegalArgumentException) {
        // Collaborator not found in the Database
    }
}

Removing A Collaborator

val shareManager: SharingManager
val collaborator: CollaboratorItem

lifecycleScope.launch(Dispatchers.IO) {
    try {
        shareManager.deleteCollaborator(
            collaboratorId = collaborator.id
        )
    } catch (exception: IllegalArgumentException) {
        // Collaborator not found in the Database
    }
}

Types

CollaboratorItem

data class CollaboratorItem : Parcelable

CreateCollaboratorMeta

data class CreateCollaboratorMeta(val phoneOrEmail: String, val permission: SharedLinkPermission) : Parcelable

NotMySharedLinkItem

data class NotMySharedLinkItem(val id: Long, val createdAt: String, val updatedAt: String, val permission: SharedLinkPermission, val expires: String? = null, val ownerName: String) : Parcelable

SharedLinkItem

data class SharedLinkItem : Parcelable

SharedLinkPermission

enum SharedLinkPermission : Enum<SharedLinkPermission>

Permission for shared link or shared link user.

SharedLinkType

enum SharedLinkType : Enum<SharedLinkType>

Type of shared link.

ShareOperationResult

sealed class ShareOperationResult

SharingManager

interface SharingManager