Locks

A Lock can be used by your custom-developed applications to implement file locking and concurrency features. These locks are advisory, meaning that while a lock can be created, it does not prevent other API requests from being processed concurrently. You are responsible for checking locks prior to accessing a file.

The lock feature is designed to emulate the locking functionality provided by WebDAV. For a deeper understanding of how the lock mechanism works, refer to the WebDAV specification, which outlines how these endpoints function.

Files.com's WebDAV offering and desktop app leverage this locking API to manage concurrent file operations, ensuring consistency when multiple users or systems interact with the same files. It is not used within the Files.com web interface.

The optional owner parameter is a descriptive label, not the lock creator or a grant of permission. It can be set when creating a lock; refreshing a lock or replacing its token preserves it.

To refresh only an existing lock or replace its token, send expected_token, token, and timeout to the create endpoint. Set token to expected_token to refresh, or to a different value to replace. The expected token must identify an existing, unexpired lock on that path, and the caller must have permission to modify it. The token check and update happen together; invalid replacement values leave the stored lock unchanged.

A missing, expired, or mismatched expected token returns processing-failure/resource-locked with data.lock_token containing an active token on that path, or an empty string when none exists. Omitting expected_token retains the existing acquire-or-refresh behavior. Shared locks retain their existing semantics.

List Locks by Path

SDK Method

lock.ListFor()

Return Values

Returns a *lock.Iter and an error. Range over All() to receive files_sdk.Lock values and errors. Check each loop error before using its resource. Next() and Err() remain supported.

Authorization Requirement

Available to all authenticated keys or sessions.

LockListForParams Fields

FieldDescription
Path
string
Required		Path to operate on.
IncludeChildren
boolean		Include locks from children objects?

Additional Arguments

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/lock"
)

lockIterator, err := lock.ListFor(files_sdk.LockListForParams{Path: "path"})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
    } else {
        fmt.Printf("Request failed: %v\n", err)
    }
    return
}

for lock, err := range lockIterator.All() {
    if err != nil {
        var respErr files_sdk.ResponseError
        if errors.As(err, &respErr) {
            fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
        } else {
            fmt.Printf("Request failed: %v\n", err)
        }
        return
    }
    fmt.Println(lock)
}

Create Lock

SDK Method

lock.Create()

Return Values

Returns a files_sdk.Lock value and an error.

Authorization Requirement

Available to all authenticated keys or sessions.

LockCreateParams Fields

FieldDescription
Path
string
Required		Path
Token
string		Lock token. With expected_token, use the same value to refresh or a different value to replace the existing token.
ExpectedToken
string		Require this existing, unexpired token before refreshing or replacing a lock. Set token to the same value to refresh, or a different value to replace.
AllowAccessByAnyUser
boolean		Can lock be modified by users other than its creator?
Exclusive
boolean		Is lock exclusive?
Recursive
boolean		Does lock apply to subfolders?
Owner
string		Arbitrary descriptive label for the lock. Does not change the lock creator or permissions.
Timeout
int64		Lock timeout in seconds

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/lock"
)

lock, err := lock.Create(files_sdk.LockCreateParams{Path: "locked_file"})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
    } else {
        fmt.Printf("Request failed: %v\n", err)
    }
    return
}
fmt.Println(lock)

Delete Lock

SDK Method

lock.Delete()

Return Values

Returns an error, or nil on success.

Authorization Requirement

Available to all authenticated keys or sessions.

LockDeleteParams Fields

FieldDescription
Path
string
Required		Path
Token
string
Required		Lock token

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/lock"
)

err := lock.Delete(files_sdk.LockDeleteParams{
  Path: "locked_file",
  Token: "token",
})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
    } else {
        fmt.Printf("Request failed: %v\n", err)
    }
    return
}

The Lock Object

Some of the methods above return a Lock object. The attributes of this object are listed below.

AttributeDescription
Path
string		Path. This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
Timeout
int64		Lock timeout in seconds
Depth
string
Recursive
boolean		Does lock apply to subfolders?
Owner
string		Arbitrary descriptive label for the lock. Does not change the lock creator or permissions.
Scope
string
Exclusive
boolean		Is lock exclusive?
Token
string		Lock token. Use to release lock.
Type
string
AllowAccessByAnyUser
boolean		Can lock be modified by users other than its creator?
UserId
int64		Lock creator user ID
Username
string		Lock creator username