rdav: Interchange Files With 'WebDAV' Servers

Description

Provides functions to interchange files with WebDAV servers

Details

• download a file or a directory (recursively) from a WebDAV server

• upload a file or a directory (recursively) to a WebDAV server

• copy, move, delete files or directories on a WebDAV server

• list directories on the WebDAV server

Notice: when uploading or downloading files, they are overwritten without any warnings.

Author(s)

Gunther Krauss

See Also

Useful links:

• https://github.com/gk-crop/rdav

• Report bugs at https://github.com/gk-crop/rdav/issues

Examples

## Not run: 
# establish a connection, you will be asked for a password
r <- wd_connect("https://example.com/remote.php/webdav/","exampleuser")

# show files / directoriess in main directory
wd_dir(r)

# lists 'subdir', returns a dataframe
wd_dir(r, "subdir", as_df = TRUE)

# create directory 'mydirectory' on the server
wd_mkdir(r,"mydirectory")

# upload the local file testfile.R to the subdirectory 'mydirectory'
wd_upload(r, "testfile.R", "mydirectory/testfile.R")

# download content of 'mydirectory' from the server and
# store it in 'd:/data/fromserver' on your computer
wd_download(r, "mydirectory", "d:/data/fromserver")


## End(Not run)

Builds the Nextcloud base URL for a nextcloud server from host and user names

Description

Builds the Nextcloud base URL for a nextcloud server from host and user names

Usage

ncl_baseurl(hostname, username, path_prefix = "")

Arguments

Value

base url to use with wd_connect

Examples

ncl_baseurl("example.com","johndoe")
ncl_baseurl("example.com","johndoe","sub/dir/")

Builds the Nextcloud base URL for a public share from host and user names

Description

Builds the Nextcloud base URL for a public share from host and user names

Usage

ncl_shareurl(hostname, username, path_prefix = "")

Arguments

Value

share url to use with wd_connect

Examples

ncl_shareurl("example.com", "johndoe")

Creates the Nextcloud base URL for a share from a public share url

Description

Creates the Nextcloud base URL for a share from a public share url

Usage

ncl_shareurl_from_publicurl(url)

Arguments

Value

share url to use with wd_connect

Examples

ncl_shareurl_from_publicurl("https://example.com/s/87d7edad/")

Extracts the user name from a Nextcloud Base URL

Description

Extracts the user name from a Nextcloud Base URL

Usage

ncl_username_from_url(url)

Arguments

Value

user name

Examples

ncl_username_from_url("https://example.com/remote.php/dav/files/johndoe")

Creates a share

Description

Creates different share types:

Usage

ocs_create_share(
  req,
  path,
  share_type,
  share_with = NULL,
  password = NULL,
  permissions = 1,
  public_upload = FALSE,
  expire_date = NULL,
  label = "",
  note = "",
  send_mail = FALSE,
  attributes = NULL
)

ocs_create_share_link(
  req,
  path,
  password = NULL,
  permissions = 1,
  public_upload = FALSE,
  expire_date = NULL,
  note = "",
  label = ""
)

ocs_create_share_mail(
  req,
  path,
  email,
  password = NULL,
  permissions = 1,
  public_upload = FALSE,
  expire_date = NULL,
  note = "",
  label = "",
  send_mail = TRUE
)

ocs_create_share_user(
  req,
  path,
  user,
  permissions = 1,
  public_upload = FALSE,
  expire_date = NULL,
  note = "",
  label = "",
  send_mail = TRUE
)

ocs_create_share_group(
  req,
  path,
  group,
  permissions = 1,
  public_upload = FALSE,
  expire_date = NULL,
  note = "",
  label = "",
  send_mail = TRUE
)

ocs_create_share_federated(
  req,
  path,
  cloud_id,
  permissions = 1,
  public_upload = FALSE,
  expire_date = NULL,
  note = "",
  label = "",
  send_mail = TRUE
)

Arguments

Details

• ocs_create_share - generic method that takes share type as argument

• ocs_create_share_user - creates a share for a nextcloud user

• ocs_create_share_group - creates a share for a nextcloud group

• ocs_create_share_link - create a public share link

• ocs_create_share_mail - creates an e-mail share

• ocs_create_share_federated - creates a federated share

Notice: if protecting a public link or e-mail share with a password, make sure that the password meets the services' password policy.

Value

information for the newly created share as data.frame

Examples

## Not run: 
r <- wd_connect("https://example.com/remote.php/dav/files/johndoe")
ocs_create_share(r, "myfolder/share", 4)
ocs_create_share_link(r, "myfolder/share")
ocs_create_share_mail(r, "myfolder/share", "[email protected]")
ocs_create_share_user(r, "myfolder/share", "jackdoe")


## End(Not run)

Deletes a share

Description

Deletes a share

Usage

ocs_delete_share(req, id)

Arguments

Value

invisible boolean TRUE on success and FALSE on failure

Examples

## Not run: 
r <- wd_connect("https://example.com/remote.php/dav/files/johndoe")
ocs_delete_share(r, 12342)

## End(Not run)

Modifies properties of a share

Description

If a parameter omitted or is NULL, then the coresponding property is not modified.

Usage

ocs_modify_share(
  req,
  id,
  password = NULL,
  permissions = NULL,
  public_upload = NULL,
  expire_date = NULL,
  label = NULL,
  note = NULL,
  send_mail = NULL,
  attributes = NULL
)

Arguments

Value

data.frame with the share properties

Examples

## Not run: 
r <- wd_connect("https://example.com/remote.php/dav/files/johndoe")
ocs_modify_share(r, 12345, permissions = 31, expire_date = "2025-11-01")

## End(Not run)

Notifies the user of a mail share

Description

Notifies the user of a mail share

Usage

ocs_send_mail(req, id, password = NULL)

Arguments

Value

invisible TRUE on success or FALSE on failure

Examples

## Not run: 
r <- wd_connect("https://example.com/remote.php/dav/files/johndoe")

# add a password to a mail share and notify the user
ocs_modify_share(r, 12342, password = "super_secret")
ocs_send_mail(r, 12342, password = "super_secret")

## End(Not run)

Get infor for a specific share

Description

Get infor for a specific share

Usage

ocs_share_info(req, id, columns = NULL)

Arguments

Value

one row data.frame with share properties

Examples

## Not run: 
r <- wd_connect("https://example.com/remote.php/dav/files/johndoe")
ocs_share_info(r, 158742)

## End(Not run)

Returns information for shares

Description

ocs_shares_extended returns extended information for shares. ocs_shares returns the shares of a file or folder, ocs_child_shares the shares of the files and subfolders of the given path.

Usage

ocs_shares_extended(
  req,
  path = "",
  as_df = TRUE,
  columns = NULL,
  subfiles = TRUE,
  reshares = FALSE
)

ocs_child_shares(
  req,
  path = "",
  as_df = TRUE,
  columns = c("share_type", "item_type", "permissions", "label", "uid_owner",
    "share_with_displayname")
)

ocs_shares(
  req,
  path = "/",
  as_df = TRUE,
  columns = c("share_type", "item_type", "permissions", "label", "uid_owner",
    "share_with_displayname")
)

Arguments

Value

data.frame or named vector of IDs

Examples

## Not run: 
r <- wd_connect("https://example.com/remote.php/dav/files/johndoe")
ocs_shares_extended(r, "myfolder/shares")
ocs_shares(r, "myfolder/shares")
ocs_child_shares(r, "myfolder")

## End(Not run)

Establishes a connection to a WebDAV server

Description

Creates and authenticate a request handle to the WebDAV server

Usage

wd_connect(url, username = ncl_username_from_url(url), password = NULL)

Arguments

Details

Notice: it's not recommended to write the password as plain text. Either omit the parameter (then you will be asked to enter a password interactively) or use for example the system credential store via keyring package.

Value

a httr2 request to the WebDAV server location

Examples

## Not run: 
# establish a connection, you will be asked for a password

r <- wd_connect("https://example.com/remote.php/webdav/","exampleuser")


# establish a connection, use keyring package to retrieve the password

keyring::key_set("mydav", "exampleuser") # call only once

r <- wd_connect("https://example.com/remote.php/webdav/",
                "exampleuser",
                keyring::key_get("mydav", "exampleuser"))

## End(Not run)

Copies a file or directory on the WebDAV server

Description

Copies a file or directory on the WebDAV server

Usage

wd_copy(req, source, target, overwrite = TRUE)

Arguments

Value

TRUE on success, FALSE on failure (invisibly)

Examples

## Not run: 

wd_copy(r, "testfile.R", "testfile_old.R")


## End(Not run)

Deletes a file or directory (collection) on WebDAV server

Description

Deletes a file or directory (collection) on WebDAV server

Usage

wd_delete(req, file)

Arguments

Value

TRUE on success, FALSE on failure (invisibly)

Examples

## Not run: 

wd_delete(r, "testfile.R")


## End(Not run)

Lists the content of a WebDAV directory

Description

Lists the content of a WebDAV directory

Usage

wd_dir(req, directory = "", full_names = FALSE, as_df = FALSE)

Arguments

Value

a vector of filenames or a dataframe (when as_df is TRUE) with detailed file information (filename, path, isdir, size, lastmodified)

Examples

## Not run: 

# lists names of files and directories in the main directory
wd_dir(r)

# lists names of files and directories in the subdirectory "mydirectory"
wd_dir(r, "mydirectory")

# lists names of files and directories with the relative path
wd_dir(r, "mydirectory", full_names=TRUE)

# returns a data.frame with the columns filename, size and isdir (whether
# it's a directory or file
wd_dir(r, "mydirectory", as_df=TRUE)


## End(Not run)

Fetches a file or directory (recursively) from the WebDAV server

Description

Directories are downloaded recursively. If the source is a file and the target a directory, then the file is downloaded to the target directory. If the target is omitted, then the file or directory name (basename) will be used.

Usage

wd_download(req, source, target = "")

Arguments

Value

vector of downloaded files (invisibly)

Examples

## Not run: 

wd_download(r, "weatherfiles", "d:/data/weather")
wd_download(r, "test/xyz.txt", "d:/data/abc.txt")


## End(Not run)

Checks if the resource on WebDAV is a directory

Description

Checks if the resource on WebDAV is a directory

Usage

wd_isdir(req, directory, silent = FALSE)

Arguments

Value

TRUE if it is a directory, FALSE else

Examples

## Not run: 

wd_isdir(r, "testfile.R") # FALSE
wd_isdir(r, "mydirectory")   # TRUE


## End(Not run)

Creates a directory (collection) on WebDAV server

Description

When creating a subdirectoy, all parent directories have to exist on the server.

Usage

wd_mkdir(req, directory)

Arguments

Value

TRUE on success, FALSE on failure (invisibly)

Examples

## Not run: 

# creates 'newdir' inside the subdirectory 'existing/directory'
wd_mkdir(r, "existing/directory/newdir")


## End(Not run)

Moves a file or directory on the server

Description

Moves a file or directory on the server

Usage

wd_move(req, source, target, overwrite = TRUE)

Arguments

Value

TRUE on success, FALSE on failure (invisibly)

Examples

## Not run: 

wd_move(r, "testfile.R", "testfile_old.R")


## End(Not run)

Uploads a file or directory to WebDAV

Description

Directories are uploaded recursively. If the source is a file and the target a directory, then the file is uploaded into the directory. If the target is omitted, then the file or directory name (basename) will be used.

Usage

wd_upload(req, source, target = "")

Arguments

Value

vector of uploaded files (invisibly)

Examples

## Not run: 

wd_upload(r, "d:/data/weather", "weatherfiles")
wd_upload(r, "d:/data/abc.txt", "test/xyz.txt")
wd_upload(r, "d:/data/abc.txt", "test") # uploaded file will be test/abc.txt


## End(Not run)