FilesModule

public class FilesModule

Provides File management.

  • Get information about a file.

    Declaration

    Swift

    public func get(
    fileId: String,
    fields: [String]? = nil,
    completion: @escaping Callback<File>
)

    Parameters

    fileId

    The ID of the file on which to retrieve information.
    fields

    String array of fields to include in the response. Any attribute in the full file be passed in with the fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default.
    completion

    Returns a standard file object or an error if the fileId is invalid or the user doesn’t have access to the file.

  • Update the information about a file, including renaming or moving the file.

    Declaration

    Swift

    public func update(
    fileId: String,
    name: String? = nil,
    description: String? = nil,
    parentId: String? = nil,
    sharedLink: NullableParameter<SharedLinkData>? = nil,
    tags: [String]? = nil,
    collections: [String]? = nil,
    lock: NullableParameter<LockData>? = nil,
    ifMatch: String? = nil,
    fields: [String]? = nil,
    completion: @escaping Callback<File>
)

    Parameters

    fileId

    The ID of the file on which to perform the update.
    updateFileInfo

    The new values with which to update the file.
    ifMatch

    This is in the ‘etag’ field of the file object, which can be included to prevent race conditions.
    fields

    String array of fields to include in the response. Any attribute in the full file be passed in with the fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default.
    completion

    Returns a standard file object or an error if the fileId is invalid or the user doesn’t have access to the file.

  • Create a copy of a file in another folder. The original version of the file will not be altered.

    Declaration

    Swift

    public func copy(
    fileId: String,
    parentId: String,
    name: String? = nil,
    version: String? = nil,
    fields: [String]? = nil,
    completion: @escaping Callback<File>
)

    Parameters

    fileId

    The ID of the source file to copy.
    parentId

    The ID of the destination folder.
    name

    An optional new name for the file. Box supports file names of 255 characters or less. Names containing non-printable ASCII characters, / or \, names with trailing spaces, and the special names “.” and “..” are also not allowed.
    version

    An optional file version ID if you want to copy a specific file version
    fields

    String array of fields to include in the response. Any attribute in the full file be passed in with the fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default.
    completion

    Returns a standard file object or an error if the fileId is invalid or the update is not successful. An error will be returned if the destination folder is invalid or if a file name collision occurs.

  • Upload a file to a specified folder.

    Declaration

    Swift

    public func upload(
    data: Data,
    name: String,
    parentId: String,
    progress: @escaping (Progress) -> Void = { _ in },
    performPreflightCheck: Bool = false,
    completion: @escaping Callback<File>
)

    Parameters

    name

    The name of the file. Box supports file names of 255 characters or less. Names containing non-printable ASCII characters, / or \, names with trailing spaces, and the special names “.” and “..” are also not allowed.
    parentId

    The ID of the parent folder. Use 0 for the root folder.
    progress

    Shows the progress of the upload
    performPreflightCheck

    Defines whether to first perform prelfight check request to decide whether file of this size can be uploaded and whether specified name is unique and won’t cause conflicts.
    completion

    Returns a standard file object or an error if the parentId is invalid or if a file name collision occurs.

  • Upload a file to a specified folder.

    Declaration

    Swift

    public func uploadVersion(
    forFile fileId: String,
    name: String? = nil,
    contentModifiedAt: String? = nil,
    data: Data,
    progress: @escaping (Progress) -> Void = { _ in },
    performPreflightCheck: Bool = false,
    completion: @escaping Callback<File>
)

    Parameters

    fileId

    The ID of the file
    name

    The name of the file. Box supports file names of 255 characters or less. Names containing non-printable ASCII characters, / or \, names with trailing spaces, and the special names “.” and “..” are also not allowed.
    progress

    Shows the progress of the upload
    performPreflightCheck

    Checks whether new file version will be accepted before whole new version is uploaded.
    completion

    Returns a standard file object or an error.

  • Upload a file to a specified folder.

    Declaration

    Swift

    public func streamUpload(
    stream: InputStream,
    fileSize: Int,
    name: String,
    parentId: String,
    progress: @escaping (Progress) -> Void = { _ in },
    performPreflightCheck: Bool = false,
    completion: @escaping Callback<File>
)

    Parameters

    stream

    An InputStream of data for been uploaded.
    dataLength

    The lenght of the InputStream
    parentId

    The ID of the parent folder. Use 0 for the root folder.
    name

    The name of the file. Box supports file names of 255 characters or less. Names containing non-printable ASCII characters, / or \, names with trailing spaces, and the special names “.” and “..” are also not allowed.
    progress

    Shows the progress of the upload
    performPreflightCheck

    Defines whether to perform preflight request first check to see whether uploaded file parameters such as size and name won’t cause an upload error.
    completion

    Returns a standard file object or an error if the parentId is invalid or if a file name collision occurs.

  • Verifies that new file will be accepted by Box before you send all the bytes over the wire. Verifies all permissions as if the file was actually uploaded including: folder upload permission, file name collisions, file size caps, folder and file name restrictions, folder and account storage quota.

    Declaration

    Swift

    public func preflightCheck(
    name: String,
    parentId: String,
    size: Int64? = nil,
    completion: @escaping Callback<Void>
)

    Parameters

    name

    The name of the file
    parantId

    The ID of the parent folder. Use 0 for the root folder.
    size

    The size of the file in bytes
    completion

    Returns a empty resppnse in case of the checks have been passed and user can proceed to make a upload call or an error.

  • Verifies that an updated file will be accepted by Box before you send all the bytes over the wire. It’s used before uploading new versions of an existing File. Verifies all permissions as if the file was actually uploaded including: folder upload permission, file name collisions, file size caps, folder and file name restrictions, folder and account storage quota.

    Declaration

    Swift

    public func preflightCheckForNewVersion(
    forFile fileId: String,
    name: String? = nil,
    size: Int64? = nil,
    completion: @escaping Callback<Void>
)

    Parameters

    fileId

    The ID of the updated file.
    name

    The name of the file.
    parantId

    The ID of the parent folder. Use 0 for the root folder.
    size

    The size of the file in bytes
    completion

    Returns a empty response in case of the checks have been passed and user can proceed to make a upload call or an error.

  • Declaration

    Swift

    public func lock(
    fileId: String,
    expiresAt: Date? = nil,
    isDownloadPrevented: Bool? = nil,
    fields: [String]? = nil,
    completion: @escaping Callback<File>
)

    Parameters

    fileId

    The ID of the file
    expiresAt

    The time the lock expires
    isDownloadPrevented

    Whether or not the file can be downloaded while locked
    fields

    String array of fields to include in the response. Any attribute in the full file be passed in with the fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default.
    completion

    Returns a standard file object or an error

  • Unlock a file.

    Declaration

    Swift

    public func unlock(
    fileId: String,
    fields: [String]? = nil,
    completion: @escaping Callback<File>
)

    Parameters

    fileId

    The ID of the file
    fields

    String array of fields to include in the response. Any attribute in the full file be passed in with the fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default.
    completion

    Returns a standard file object or an error

  • Declaration

    Swift

    public func getThumbnail(
    forFile fileId: String,
    extension: ThumbnailExtension,
    minHeight: Int? = nil,
    minWidth: Int? = nil,
    maxHeight: Int? = nil,
    maxWidth: Int? = nil,
    completion: @escaping Callback<Data>
)

    Parameters

    fileId

    The ID of the file
    extension

    Specifies the thumbnail image file extension
    minHeight

    The minimum height of the thumbnail
    minWidth

    The minimum width of the thumbnail
    maxHeight

    The maximum height of the thumbnail
    maxWidth

    The maximum width of the thumbnail

  • Get a URL for creating an embedded preview session.

    Declaration

    Swift

    public func getEmbedLink(
    forFile fileId: String,
    completion: @escaping Callback<ExpiringEmbedLink>
)

    Parameters

    fileId

    The ID of the file
    fields

    String array of fields to include in the response. Any attribute in the full file be passed in with the fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default.
    completion

    Returns a standard embed link or an error

  • Get all of the collaborations on a file (i.e. all of the users that have access to that file).

    Declaration

    Swift

    public func listCollaborations(
    forFile fileId: String,
    marker: String? = nil,
    limit: Int? = nil,
    fields: [String]? = nil
) -> PaginationIterator<Collaboration>

    Parameters

    fileId

    The ID of the file
    marker

    The position marker at which to begin the response. See marker-based paging for details. This parameter cannot be used simultaneously with the ‘offset’ parameter.
    limit

    The maximum number of items to return
    fields

    String array of fields to include in the response. Any attribute in the full file be passed in with the fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default.

  • Get all of the comments on a file.

    Declaration

    Swift

    public func listComments(
    forFile fileId: String,
    offset: Int?,
    limit: Int?,
    fields: [String]? = nil
) -> PaginationIterator<Comment>

    Parameters

    fileId

    The ID of the file
    offset

    The offset of the item at which to begin the response. See offset-based paging for details. This parameter cannot be used simultaneously with the ‘marker’ parameter.
    limit

    The maximum number of items to return.
    fields

    String array of fields to include in the response. Any attribute in the full file be passed in with the fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default.

    Return Value

    Returns all of the comments on the file using offset-based paging.

  • Get all of the tasks for a file.

    Declaration

    Swift

    public func listTasks(
    forFile fileId: String,
    fields: [String]? = nil
) -> PaginationIterator<Task>

    Parameters

    fileId

    The ID of the file
    fields

    String array of fields to include in the response. Any attribute in the full file be passed in with the fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default.
    completion

    Returns all of the tasks on the file

  • Download a file to a specified folder.

    Declaration

    Swift

    public func download(
    fileId: String,
    destinationURL: URL,
    version: String? = nil,
    progress: @escaping (Progress) -> Void = { _ in },
    completion: @escaping Callback<Void>
)

    Parameters

    fileId

    The ID of the file
    destinationURL

    A URL for the location on device that we want to store the file once been donwloaded
    version

    Optional file version ID to download (defaults to the current version)
    progress

    Shows the progress of the upload
    completion

    Returns an empty response or an error

  • Discards a file to the trash. The etag of the file can be included as an ‘If-Match’ header to prevent race conditions. Depending on the enterprise settings for this user, the item will either be actually deleted from Box or moved to the trash.

    Declaration

    Swift

    public func delete(
    fileId: String,
    ifMatch: String? = nil,
    completion: @escaping Callback<Void>
)

    Parameters

    fileId

    Id of the file that should be deleted.
    ifMatch

    The etag of the file. This is in the etag field of the file object.
    completion

    Empty response in case of success or an error.

  • Add file to favorites

    Declaration

    Swift

    public func addToFavorites(
    fileId: String,
    completion: @escaping Callback<File>
)

    Parameters

    fileId

    The ID of the file
    completion

    Returns the updated file or an error

  • Add file to particular collection

    Declaration

    Swift

    public func addToCollection(
    fileId: String,
    collectionId: String,
    completion: @escaping Callback<File>
)

    Parameters

    fileId

    The ID of the file
    collectionId

    The ID of the collection
    completion

    Returns the updated file or an error

  • Remove file from favorites

    Declaration

    Swift

    public func removeFromFavorites(
    fileId: String,
    completion: @escaping Callback<File>
)

    Parameters

    fileId

    The ID of the file
    completion

    Returns the updated file or an error

  • Add file to particular collection

    Declaration

    Swift

    public func removeFromCollection(
    fileId: String,
    collectionId: String,
    completion: @escaping Callback<File>
)

    Parameters

    fileId

    The ID of the file
    collectionId

    The ID of the collection
    completion

    Returns the updated file or an error

  • Retrieves all file versions on a specified file.

    Declaration

    Swift

    public func listVersions(
    fileId: String,
    offset: Int? = nil,
    limit: Int? = nil,
    fields: [String]? = nil
) -> PaginationIterator<FileVersion>

    Parameters

    fileId

    The id to retrieve all versions on.
    offset

    The offset of the item at which to begin the response. See offset-based paging for details.
    limit

    The maximum number of items to return. The default is 100 and the maximum is 1,000.
    fields

    Comma-separated list of fields to include in the response.

  • Retrieves a specified file version.

    Declaration

    Swift

    public func getVersion(
    fileId: String,
    fileVersionId: String,
    fields: [String]? = nil,
    completion: @escaping Callback<FileVersion>
)

    Parameters

    fileId

    The id the file the file version belongs to.
    fieldVersionId

    The id of the file version to retrieve.
    fields

    Comma-separated list of fields to include in the response.
    completion

    Returns a full file version object or an error.

  • Promotes the specified file version to the current file version.

    Declaration

    Swift

    public func promoteVersion(
    fileId: String,
    fileVersionId: String,
    fields: [String]? = nil,
    completion: @escaping Callback<FileVersion>
)

    Parameters

    fileId

    The id of the file the file version to promote belongs to.
    fileVersionId

    The id of the file version to promote.
    fields

    Comma-separated list of fields to include in the response.
    completion

    Returns a full file version object or an error.

  • Discards the specified file version to the trash.

    Declaration

    Swift

    public func deleteVersion(
    fileId: String,
    fileVersionId: String,
    ifMatch: String? = nil,
    completion: @escaping Callback<Void>
)

    Parameters

    fileId

    The id of the file the file version to delete belongs to.
    fileVersionId

    The file version to delete.
    ifMatch

    The etag of the file version. This is unique to the file version and prevents simultaneous updates.
    completion

    Returns a empty reponse or an error.

  • Retrieves the watermark on a specified file.

    Declaration

    Swift

    public func getWatermark(
    fileId: String,
    completion: @escaping Callback<Watermark>
)

    Parameters

    fileId

    The id of the file to retrieve the watermark from.
    completion

    Returns a watermark object or an error.

  • Apply or update the watermark on a specified file.

    Declaration

    Swift

    public func applyWatermark(
    fileId: String,
    completion: @escaping Callback<Watermark>
)

    Parameters

    fileId

    The id of the file to update the watermark for.
    completion

    Returns a watermark object or an error.

  • Remove the watermark from a specified file.

    Declaration

    Swift

    public func removeWatermark(
    fileId: String,
    completion: @escaping Callback<Void>
)

    Parameters

    fileId

    The id of the file to remove the watermark from.
    completion

    Returns an empty response or an error.

  • Gets file with updated shared link

    Declaration

    Swift

    public func getSharedLink(
    forFile fileId: String,
    completion: @escaping Callback<SharedLink>
)

    Parameters

    fileId

    The ID of the file
    completion

    Returns a standard SharedLink object or an error

  • Creates of updates shared link for a file

    Declaration

    Swift

    public func setSharedLink(
    forFile fileId: String,
    unsharedAt: NullableParameter<Date>? = nil,
    access: SharedLinkAccess? = nil,
    password: NullableParameter<String>? = nil,
    canDownload: Bool? = nil,
    completion: @escaping Callback<SharedLink>
)

    Parameters

    fileId

    The ID of the file
    stopSharingAt

    The date-time that this link will become disabled. This field can only be set by users with paid accounts
    access

    The level of access. If you omit this field then the access level will be set to the default access level specified by the enterprise admin
    password

    The password required to access the shared link. Set to .empty to delete the password
    canDownload

    Whether the shared link allows downloads
    completion

    Returns a standard SharedLink object or an error

  • Removes shared link for a file

    Declaration

    Swift

    public func deleteSharedLink(
    forFile fileId: String,
    completion: @escaping Callback<Void>
)

    Parameters

    fileId

    The ID of the file
    completion

    Returns an empty response or an error

  • Create an upload session for uploading a new file.

    Declaration

    Swift

    func createUploadSession(
    folderId: String,
    fileName: String,
    fileSize: Int32,
    completion: @escaping Callback<UploadSession>
)

    Parameters

    folderId

    The ID of the folder that will contain the new file.
    fileName

    Name of new file.
    fileSize

    The total number of bytes in the file to be uploaded.
    completion

    Returns a upload session object or an error if upload session cannot be created, for example when folder with specified ID doesn’t exist

  • Create an upload session for uploading a new file version.

    Declaration

    Swift

    func createUploadSessionForNewVersion(
    ofFile fileId: String,
    fileName: String? = nil,
    fileSize: Int32,
    completion: @escaping Callback<UploadSession>
)

    Parameters

    fileId

    The ID of the file of which version is uploaded.
    fileName

    Optional name of new file. If provided, the file name will be changed to this value upon successful upload.
    fileSize

    The total number of bytes in the file to be uploaded.
    completion

    Returns a upload session object or an error if upload session cannot be created

  • Upload a part of the file to this session.

    Declaration

    Swift

    func uploadPart(
    sessionId: String,
    data: Data,
    offset: Int,
    totalSize: Int,
    progress: @escaping (Progress) -> Void = { _ in },
    completion: @escaping Callback<UploadPart>
)

    Parameters

    sessionId

    ID of upload session object.
    data

    The part content as binary data.
    offset

    The first byte of uploaded part
    totalSize

    total size of uploaded data
    progress

    Closure where upload progress will be reported
    completion

    Returns a upload part object or an error if part upload failed

  • Get list of parts of chunked upload session.

    Declaration

    Swift

    func listUploadSessionParts(
    sessionId: String,
    offset: Int? = nil,
    limit: Int? = nil
) -> OffsetPaginationIterator<UploadPartDescription>

    Parameters

    sessionId

    ID of upload session object.
    offset

    The offset of the item at which to begin the response. See offset-based paging for details.
    limit

    The maximum number of items to return. The default is 100 and the maximum is 1,000.

  • Commit upload session after successful upload of all parts.

    Declaration

    Swift

    func commitUpload(
    sessionId: String,
    parts: [UploadPartDescription],
    sha1: String,
    description: String? = nil,
    sharedLink: SharedLinkData? = nil,
    tags: [String]? = nil,
    collections: [String]? = nil,
    lock: LockData? = nil,
    contentCreatedAt: Date? = nil,
    contentModifiedAt: Date? = nil,
    completion: @escaping Callback<File>
)

    Parameters

    sessionId

    ID of upload session object.
    parts

    Array of upload part descriptions
    sha1

    Base64 encoded SHA1 digest from the whole uploaded file.
    description

    Optional. The description of this file.
    sharedLink

    Optional. The shared link object for this file.
    tags

    Optional. All tags applied to this file
    collections

    Optional. The collections that the file belongs to
    lock

    Optional. The lock held on this file. If there is no lock, this can either be null or have a timestamp in the past.
    contentCreatedAt

    Optional. When the content of this file was created.
    contentModifiedAt

    Optional. When the content of this file was last modified.
    completion

    Returns an array of files or an error if part upload failed

  • Abort chunked upload session.

    Declaration

    Swift

    func abortUpload(
    sessionId: String,
    completion: @escaping Callback<Void>
)

    Parameters

    sessionId

    ID of upload session object.
    completion

    Returns a success or an error if aborting failed

  • Get chunked upload session with ID.

    Declaration

    Swift

    func getUploadSession(
    sessionId: String,
    completion: @escaping Callback<UploadSession>
)

    Parameters

    sessionId

    ID of existing chunked upload session.
    completion

    Returns a upload session or an error if session cannot be returned

  • Get representations for a file.

    Declaration

    Swift

    func listRepresentations(
    fileId: String,
    representationHint: FileRepresentationHint? = nil,
    completion: @escaping Callback<[FileRepresentation]>
)

    Parameters

    fileId

    The id of the file to retrieve representations for.
    representationHint

    The representation to retrieve for the file. It can be one of predefined options or custom representation, see representation documentation.
    completion

    Returns an array of the specified representations.

  • Get particular representation for a file.

    Declaration

    Swift

    func getRepresentationContent(
    fileId: String,
    representationHint: FileRepresentationHint,
    assetPath: String = "",
    destinationURL: URL,
    progress: @escaping (Progress) -> Void = { _ in },
    completion: @escaping Callback<Void>
)

    Parameters

    fileId

    The id of the file to retrieve representations for.
    representationHint

    The representation to retrieve for the file. It can be one of predefined options or custom representation. If multiple representations match the representationHint, the behavior is undefined - used representation is selected nondeterministically. See representation documentation.
    assetPath

    Asset path for representations with multiple files
    destinationURL

    A URL for the location on device that we want to store the file once been donwloaded
    completion

    Returns an array of the specified representations.

  • Download a file to a specified folder.

    Declaration

    Swift

    public func downloadRepresentation(
    sourceURL: URL,
    destinationURL: URL,
    progress: @escaping (Progress) -> Void = { _ in },
    completion: @escaping Callback<Void>
)

    Parameters

    fileId

    The ID of the file
    destinationURL

    A URL for the location on device that we want to store the file once been donwloaded
    version

    Optional file version ID to download (defaults to the current version)
    progress

    Shows the progress of the upload
    completion

    Returns an empty response or an error

  • Retrieves information about a file version retention policy.

    Declaration

    Swift

    func getVersionRetention(
    retentionId id: String,
    completion: @escaping Callback<FileVersionRetention>
)

    Parameters

    id

    Identifier of retention policy of a file version.
    completion

    Either specified file version retention will be returned upon success or an error.

  • Retrieves all file version retentions for the given enterprise.

    Declaration

    Swift

    func listVersionRetentions(
    fileId: String? = nil,
    fileVersionId: String? = nil,
    policyId: String? = nil,
    dispositionAction: DispositionAction? = nil,
    dispositionBefore: Date? = nil,
    dispositionAfter: Date? = nil,
    limit: Int? = nil,
    marker: String? = nil
) -> PaginationIterator<FileVersionRetention>

    Parameters

    fileId

    A file id to filter the file version retentions by.
    fileVersionId

    A file version id to filter the file version retentions by.
    policyId

    A policy id to filter the file version retentions by.
    dispositionAction

    The disposition action of the retention policy.
    dispositionBefore

    Filter retentions with disposition date before provided date.
    dispositionAfter

    Filter retentions with disposition date after provided date.
    limit

    The maximum number of items to return in a page.
    marker

    The position marker at which to begin the response. See marker-based paging for details.

    Return Value

    Returns either the list of all file version retentions for the enterprise or an error. If optional parameters are given, only the file version retentions that match the query parameters are returned.