File Transfer Client Module 1.0

1 Introduction

This File Transfer Client interface allows using of various file transfer protocols, including well-known ones, such as FTP, SFTP (SSH File Transfer Protocol), FTPS (FTP over implicit SSL/TLS), FTPES (FTP over explicit SSL/TLS), WebDAV (Web-based Distributed Authoring and Versioning), and WebDAVS (WebDAV encrypted via SSL), as well as custom defined protocols.

The specification was made so that to cover the operations involved as to managing (remote) resources (files and directories).

A custom protocol can make use of any number of the operations over files described below, in this manner assuring a very elastic approach of the (remote) resources (files and directories) management.

The convention for the directory paths is that they have to end with '/'.

2 The ft-client:connect function

This function is used to open a connection. It returns an xs:long representing the connection handle.

All data connections should originate from an authorized party (host and port). In case when a data connection originated from an unauthorized party, this is an error [err:FTC001].

In case when a server closes a connection, an error [err:FTC002] will be raised.

In case when credentials used (username, password, or private key) are wrong, an error [err:FTC005] will be raised.

In case when the protocol used is not supported, an error [err:FTC006] will be raised.

ft-client:connect($remote-host-uri as xs:anyURI) as xs:long
            

ft-client:connect($remote-host-uri as xs:anyURI,
		$options as xs:anyAtomicType) as xs:long
            

• $remote-host-uri is the URI of the host to connect to. See [rfc2396] in order to provide a correct syntax for this parameter.

• $options represents the options needed for the current operation.

3 The ft-client:list-resources function

This function gets the list of resources (files and directories) inside the directory indicated by $remote-directory-path.

ft-client:list-resources($connection-handle as xs:long,
	$remote-directory-path as xs:string) as element(ft-client:resources-list)
            

• $connection-handle is the connection handle.

• $remote-directory-path is the directory path (this path has to be an absolute path and has to end with '/'). If the path is not correct, this is an error [err:FTC003]. If the user has no rights to access the path, this is an error [err:FTC004]. If the path does not end with '/', this is an error [err:FTC008].

<ft-client:resource-list>
	(ft-client:resource*)
</ft-client:resource-list>

<ft-client:resource
    name = xs:string
    type = "directory" | "file" | "link"
    last-modified = xs:dateTime
    size = xs:integer
    human-readable-size = xs:string
    user = xs:string
    user-group = xs:string
    permissions = xs:string
    link-to = xs:string?>
    xs:string?
</ft-client:resource>

4 The ft-client:store-resource function

This function stores a resource (directory, file). It returns true if successfully completed, false if not.

This function is designated to accomplish the following tasks:

1. store a directory on the host, when $remote-resource-path ends with '/'; if the directory already exists, it will be overwritten;

2. store a file on the host, when $remote-resource-path does not end with '/'; if the file already exists, it is overwritten; the file's contents is passed through the $resource-contents parameter; in case when this parameter is empty or missing, the file will be empty;

ft-client:store-resource($connection-handle as xs:long,
	$remote-resource-path as xs:string,
	$resource-contents as xs:anyAtomicType?) as xs:boolean
		

• $connection-handle is the connection handle.

• $remote-resource-path is the path for resource to be created (this path has to be an absolute path). If the path is not correct, this is an error [err:FTC003]. If the user has no rights to access the path, this is an error [err:FTC004].

• $resource-contents is the contents of the resource to be stored (in case of storing a file).

5 The ft-client:retrieve-resource function

This function retrieves a resource from the host. It returns the resource retrieved, as content of the ft-client:resource element.

ft-client:retrieve-resource($connection-handle as xs:long,
	$remote-resource-path as xs:string) as element(ft-client:resource)
            

• $connection-handle is the connection handle.

• $remote-resource-path is the path for resource to be retrieved (this path has to be an absolute path). If the path is not correct, this is an error [err:FTC003]. If the user has no rights to access the path, this is an error [err:FTC004].

6 The ft-client:rename-resource function

This function renames a resource (directory, file, or link). It returns true if successfully completed, false if not.

ft-client:rename-resource($connection-handle as xs:long,
  $remote-resource-path as xs:string,
  $new-name as xs:string) as xs:boolean
            

• $connection-handle is the connection handle.

• $remote-resource-path is the path for resource to be renamed (this path has to be an absolute path). If the path is not correct, this is an error [err:FTC003]. If the user has no rights to access the path, this is an error [err:FTC004].

• $new-name is the new name for the resource.

7 The ft-client:copy-resource function

This function renames a resource (directory, file, or link). It returns true if successfully completed, false if not.

ft-client:copy-resource($connection-handle as xs:long,
  $remote-resource-path as xs:string,
  $new-name as xs:string) as xs:boolean
		

• $connection-handle is the connection handle.

• $remote-resource-path is the path for resource to be renamed (this path has to be an absolute path). If the path is not correct, this is an error [err:FTC003]. If the user has no rights to access the path, this is an error [err:FTC004].

• $new-name is the new name for the resource.

8 The ft-client:move-resource function

This function renames a resource (directory, file, or link). It returns true if successfully completed, false if not.

ft-client:move-resource($connection-handle as xs:long,
  $remote-resource-path as xs:string,
  $new-name as xs:string) as xs:boolean
		

• $connection-handle is the connection handle.

• $remote-resource-path is the path for resource to be renamed (this path has to be an absolute path). If the path is not correct, this is an error [err:FTC003]. If the user has no rights to access the path, this is an error [err:FTC004].

• $new-name is the new name for the resource.

9 The ft-client:delete-resource function

This function deletes a resource (directory (if empty), file, or link). It returns true if successfully completed, false if not.

ft-client:delete-resource($connection-handle as xs:long,
  $remote-resource-path as xs:string) as xs:boolean
            

• $connection-handle is the connection handle.

• $remote-resource-path is the path for resource to be deleted (this path has to be an absolute path). If the path is not correct, this is an error [err:FTC003]. If the user has no rights to access the path, this is an error [err:FTC004].

10 The ft-client:get-resource-metadata function

This function is used for getting the metadata of a resource (directory, file, or link). It returns the resource metadata as attributes of the ft-client:resource element.

ft-client:get-resource-metadata($connection-handle as xs:long,
	$remote-resource-path as xs:string) as element(ft-client:resource)
		

• $connection-handle is the connection handle.

• $remote-resource-path is the path of the resource (this path has to be an absolute path). If the path is not correct, this is an error [err:FTC003]. If the user has no rights to access the path, this is an error [err:FTC004].

11 The ft-client:set-resource-metadata function

This function is used for setting the metadata of a resource (directory, file, or link). It returns true if successfully completed, false if not.

ft-client:set-resource-metadata($connection-handle as xs:long,
	$remote-resource-path as xs:string,
	$new-resource-metadata as element(ft-client:resource)) as xs:boolean
		

• $connection-handle is the connection handle.

• $remote-resource-path is the path for resource to set metadata for (this path has to be an absolute path). If the path is not correct, this is an error [err:FTC003]. If the user has no rights to access the path, this is an error [err:FTC004].

• $new-resource-metadata is the new resource metadata.

12 The ft-client:disconnect function

This function closes an opened connection. Returns true or false indicating the success of closing the connection.

ft-client:disconnect($connection-handle as xs:long) as xs:boolean
		

• $connection-handle is the connection handle.