Merge commit '7c621da28f07e449ad90c387344f07a453927569' as 'tcllib'

7 files changed, 160 insertions, 0 deletions

diff --git a/tcllib/modules/transfer/include/complete.inc b/tcllib/modules/transfer/include/complete.inc
new file mode 100644
index 0000000..f0e5def
--- /dev/null
+++ b/tcllib/modules/transfer/include/complete.inc
@@ -0,0 +1,9 @@
+
+[opt_def -command [arg cmdprefix]]
+
+This option specifies the command to invoke when the [vset MODE] of
+the information has been completed.
+
+The arguments given to this command are the same as given to the
+completion callback of the command [cmd transfer::copy::do] provided
+by the package [package transfer::copy].
diff --git a/tcllib/modules/transfer/include/connect_options.inc b/tcllib/modules/transfer/include/connect_options.inc
new file mode 100644
index 0000000..288f240
--- /dev/null
+++ b/tcllib/modules/transfer/include/connect_options.inc
@@ -0,0 +1,63 @@
+
+[opt_def -mode [arg mode]]
+
+This option specifies the mode the object is in. It is optional and
+defaults to [const active] mode. The two possible modes are:
+
+[list_begin definitions]
+[def [const active]]
+
+In this mode the two options [option -host] and [option -port] are
+relevant and specify the host and TCP port the object has to connect
+to. The host is given by either name or IP address.
+
+[def [const passive]]
+
+In this mode the option [option -host] has no relevance and is ignored
+should it be configured.
+
+The only option the object needs is [option -port], and it specifies
+the TCP port on which the listening socket is opened to await the
+connection from the partner.
+
+[list_end]
+
+[opt_def -host [arg hostname-or-ipaddr]]
+
+This option specifies the host to connect to in [term active] mode,
+either by name or ip-address. An object configured for [term passive]
+mode ignores this option.
+
+[opt_def -port [arg int]]
+
+For [term active] mode this option specifies the port the object is
+expected to connect to. For [term passive] mode however it is the port
+where the object creates the listening socket waiting for a
+connection. It defaults to [const 0], which allows the OS to choose
+the actual port to listen on.
+
+[opt_def -socketcmd [arg command]]
+
+This option allows the user to specify which command to use to open a
+socket. The default is to use the builtin [cmd ::socket]. Any
+compatible with that command is allowed.
+
+[para]
+
+The envisioned main use is the specfication of [cmd tls::socket]. I.e.
+this option allows the creation of secure transfer channels, without
+making this package explicitly dependent on the [package tls] package.
+
+[para]
+
+See also section [sectref {Secure connections}].
+
+
+[opt_def -encoding encodingname]
+[opt_def -eofchar eofspec]
+[opt_def -translation transspec]
+
+These options are the same as are recognized by the builtin command
+[cmd fconfigure]. They provide the configuration to be set for the
+channel between the two partners after it has been established, but
+before the callback is invoked (See method [method connect]).
diff --git a/tcllib/modules/transfer/include/connect_result.inc b/tcllib/modules/transfer/include/connect_result.inc
new file mode 100644
index 0000000..7f2dde1
--- /dev/null
+++ b/tcllib/modules/transfer/include/connect_result.inc
@@ -0,0 +1,4 @@
+The result returned by the [vset RETURNER] is the empty string
+[vset OBJECT] to make an [term active] connection, and the port the
+[vset QUALIFIER] object is listening on otherwise, i.e when it is
+configured to connect [term passive]ly.
diff --git a/tcllib/modules/transfer/include/connect_result_ref.inc b/tcllib/modules/transfer/include/connect_result_ref.inc
new file mode 100644
index 0000000..8e5313d
--- /dev/null
+++ b/tcllib/modules/transfer/include/connect_result_ref.inc
@@ -0,0 +1,4 @@
+[include connect_result.inc]
+
+See also the package [package transfer::connect] and the description
+of the method [method connect] for where this behaviour comes from.
diff --git a/tcllib/modules/transfer/include/ddest_options.inc b/tcllib/modules/transfer/include/ddest_options.inc
new file mode 100644
index 0000000..0c84070
--- /dev/null
+++ b/tcllib/modules/transfer/include/ddest_options.inc
@@ -0,0 +1,27 @@
+
+[opt_def -channel  [arg handle]]
+
+This option specifies that the destination of the data is a channel,
+and its associated argument is the handle of the channel to write the
+received data to.
+
+[opt_def -file     [arg path]]
+
+This option specifies that the destination of the data is a file, and
+its associated argument is the path of the file to write the received
+data to.
+
+[opt_def -variable [arg varname]]
+
+This option specifies that the destination of the data is a variable,
+and its associated argument contains the name of the variable to write
+the received data to. The variable is assumed to be global or
+namespaced, anchored at the global namespace.
+
+[opt_def -progress [arg command]]
+
+This option, if specified, defines a command to be invoked for each
+chunk of bytes received, allowing the user to monitor the progress of
+the reception of the data. The callback is always invoked with one
+additional argument, the number of bytes received so far.
+
diff --git a/tcllib/modules/transfer/include/dsource_options.inc b/tcllib/modules/transfer/include/dsource_options.inc
new file mode 100644
index 0000000..9d09d4b
--- /dev/null
+++ b/tcllib/modules/transfer/include/dsource_options.inc
@@ -0,0 +1,35 @@
+[opt_def -string   [arg text]]
+
+This option specifies that the source of the data is an immediate
+string, and its associated argument contains the string in question.
+
+[opt_def -channel  [arg handle]]
+
+This option specifies that the source of the data is a channel, and
+its associated argument is the handle of the channel containing the
+data.
+
+[opt_def -file     [arg path]]
+
+This option specifies that the source of the data is a file, and its
+associated argument is the path of the file containing the data.
+
+[opt_def -variable [arg varname]]
+
+This option specifies that the source of the data is a string stored
+in a variable, and its associated argument contains the name of the
+variable in question. The variable is assumed to be global or
+namespaced, anchored at the global namespace.
+
+[opt_def -size     [arg int]]
+
+This option specifies the size of the data transfer. It is optional
+and defaults to -1. This value, and any other value less than zero
+signals to transfer all the data from the source.
+
+[opt_def -progress [arg command]]
+
+This option, if specified, defines a command to be invoked for each
+chunk of bytes transmitted, allowing the user to monitor the progress
+of the transmission of the data. The callback is always invoked with
+one additional argument, the number of bytes transmitted so far.
diff --git a/tcllib/modules/transfer/include/secure.inc b/tcllib/modules/transfer/include/secure.inc
new file mode 100644
index 0000000..d38d0c7
--- /dev/null
+++ b/tcllib/modules/transfer/include/secure.inc
@@ -0,0 +1,18 @@
+[section {Secure connections}]
+
+One way to secure connections made by objects of this package is to
+require the package [package tls] and then configure the option
+[option -socketcmd] to force the use of command [cmd tls::socket] to
+open the socket.
+
+[example_begin]
+    # Load and initialize tls
+    package require tls
+    tls::init -cafile /path/to/ca/cert -keyfile ...
+
+    # Create a connector with secure socket setup,
+    [vset OBJCREATE] -socketcmd tls::socket ...
+    ...
+[example_end]
+
+[include ../../common-text/tls-security-notes.inc]