transfer::receiver(3tcl)

🌸 NAME 🌸

transfer::receiver — the Data source, but make it a whole vibe 💖

(you're in the transfer::receiver(3tcl) page of the Data transfer facilities, bestie, welcome 🫶)

---

✨ SYNOPSIS ✨

package require Tcl 8.5 9

package require snit ?1.0?

package require transfer::data::destination ?0.3?

package require transfer::connect ?0.3?

package require transfer::receiver ?0.3?

transfer::receiver object ?options...?

transfer::receiver stream channel chan host port ?arg...?

transfer::receiver stream file path host port ?arg...?

objectName method ?arg arg ...?

objectName destroy

objectName start

objectName busy

---

🦋 DESCRIPTION 🦋

So basically this package is the matchmaker 💅 — it pulls data destinations and connection setup together into one combined object, and that object is here to receive information coming in over a socket. Main character energy only.

And the glow-up? These objects understand all the options from objects created by the packages transfer::data::destination and transfer::connect. Every single one. No cap. 🔥

---

👑 API 👑

🎀 PACKAGE COMMANDS 🎀

• transfer::receiver object ?options...? — this command creates a brand new receiver object, and that object gets an associated Tcl command whose name is objectName. The whole deal with that object command is spelled out in the sections Object command and Object methods. And the set of options it supports? Explained in section Options.

Where does the object command live? Under the current namespace if objectName isn't fully qualified, and in the namespace you specified otherwise. And what does the command hand back to you? The fully qualified name of the object command, as its result. 🫶

• transfer::receiver stream channel chan host port ?arg...? — okay so this one is a fire-and-forget transfer 🔥. The data comes from the source at host/port (details below) and gets written to the channel chan, starting at the current seek location. The channel gets configured to use binary translation and encoding for the transfer. And heads up: the channel is not closed when the transfer has completed — that honour is left to the completion callback.

Now, the connection tea ☕: if both host and port are provided, an active connection to the data source is made. If only a port is specified (with host being the empty string), then a passive connection is made instead — meaning the receiver just sits there waiting for a connection by the transmitter.

Anything you pass after port is treated as options, and those configure the internal receiver object. Peep the section Options for the full list and what they mean. But wait — there's a plot twist 🙈: the signature of the command prefix you give for the -command callback is different from the signature for that same option on the receiver object. That callback only receives the number of bytes transferred, and possibly an error message. It gets no reference to the internally used receiver object. Periodt.

The result returned by the command is the empty string if it was set up to make an active connection, and the port the internal receiver object is listening on otherwise — i.e. when it's configured to connect passively. See also the package transfer::connect and the description of the method connect for where this behaviour comes from. 💜

• transfer::receiver stream file path host port ?arg...? — literally the same as stream channel, except the received data gets written to the file path, replacing any prior content. Bye bye old bytes 💀

🧚 OBJECT COMMAND 🧚

Every object created by the ::transfer::receiver command has this general form:

• objectName method ?arg arg ...? — the method method and its arg'uments determine the exact behaviour of the command. Section Object methods has the detailed specs. ✨

🌈 OBJECT METHODS 🌈

• objectName destroy — destroys the object. ⚠️ And doing this while a reception is on progress will cause errors later on, when the reception completes and tries to access the now-missing data structures of the destroyed object. Like, don't do that.
• objectName start — initiates the data reception: sets up the connection first, then copies the received information into the destination. This method will throw an error if a reception is already/still in progress. I.e. you can't run two receptions in parallel — only in sequence, bestie. Errors will also be thrown if the configuration of the data destination is invalid, or if no completion callback was specified. 🚨

The result returned by the method is the empty string for an object configured to make an active connection, and the port the object is listening on otherwise — i.e. when it's configured to connect passively. See also the package transfer::connect and the description of the method connect for where this behaviour comes from.

• objectName busy — returns a boolean telling you whether a reception is in progress (True) or not (False). Simple. Iconic. 🎀

💅 OPTIONS 💅

All receiver objects support the union of the options supported by their connect and data destination components, plus one of their own. See also the documentation for the packages transfer::data::destination and transfer::connect.

• -command cmdprefix — specifies the command to invoke when the reception of the information has been completed. The arguments given to this command are the same as the ones given to the completion callback of the command transfer::copy::do provided by the package transfer::copy. 🫶
• -mode mode — specifies the mode the object is in. It's optional and defaults to active mode. The two possible modes are:
  • active — in this mode the two options -host and -port are relevant, and they specify the host and TCP port the object has to connect to. The host is given by either name or IP address.
  • passive — in this mode the option -host has no relevance and is ignored should it be configured. The only option the object needs is -port, and it specifies the TCP port on which the listening socket is opened to await the connection from the partner.
• -host hostname-or-ipaddr — specifies the host to connect to in active mode, either by name or ip-address. An object configured for passive mode ignores this option. 🙈
• -port int — for active mode, this option specifies the port the object is expected to connect to. For passive mode though, it's the port where the object creates the listening socket waiting for a connection. It defaults to 0, which lets the OS choose the actual port to listen on. ✨
• -socketcmd command — lets you specify which command to use to open a socket. The default is to use the builtin ::socket. Anything compatible with that command is allowed.

The envisioned main use is the specfication of tls::socket. I.e. this option allows the creation of secure transfer channels, without making this package explicitly dependent on the tls package. Big brain move 🧠✨

See also section Secure connections.

• -encoding encodingname
• -eofchar eofspec
• -translation transspec

These three are the same as are recognized by the builtin command 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 connect). 💜

• -channel handle — 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.
• -file path — 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.
• -variable varname — 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.
• -progress command — if specified, defines a command to be invoked for each chunk of bytes received, letting you monitor the progress of the reception of the data. This callback is always invoked with one additional argument: the number of bytes received so far. 📈

---

🔐 SECURE CONNECTIONS 🔐

One way to secure connections made by objects of this package is to require the package tls and then configure the option -socketcmd to force the use of command tls::socket to open the socket. Like so:

# Load and initialize tls
package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...

# Create a connector with secure socket setup,
transfer::receiver R -socketcmd tls::socket ...
...

---

🛡️ TLS SECURITY CONSIDERATIONS 🛡️

This package uses the TLS package to handle the security for https urls and other socket connections.

Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of TLS, nor of this package itself however. Such decisions are the responsibility of whichever application is using the package, and they're likely influenced by the set of servers the application will talk to as well. 👑

For example, in light of the recent POODLE attack [http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html] discovered by Google, many servers will disable support for the SSLv3 protocol. To handle this change, the applications using TLS must be patched — and not this package, nor TLS itself. Such a patch may be as simple as generally activating tls1 support, as shown in the example below. 🚨

package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol

... your own application code ...

🐛 BUGS, IDEAS, FEEDBACK 🐛

okay bestie, real talk time 💖 this doc, and honestly the whole package it's describing? it will have bugs and other problems. not being dramatic, it's just literally what the page says. so if you find one, pls don't suffer in silence 😭

• report bugs in the category transfer of the Tcllib Trackers → [http://core.tcl.tk/tcllib/reportlist]
• got ideas for enhancements? for the package? for the docs? for both? send those in too, they want them 🫶

---

🧾 if you're sending code changes

when you propose code changes, you gotta provide unified diffs — that means the output of diff -u 💅

diff -u

heads up! attachments are strongly preferred over inlined patches. to attach something: go to the Edit form of the ticket right after you create it, then use the left-most button in the secondary navigation bar. that's the move ✨

---

🔑 KEYWORDS

channel, copy, data destination, receiver, secure, ssl, tls, transfer

---

📦 CATEGORY

Transfer module

---

©️ COPYRIGHT

Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

and that's a wrap, bestie 🎀 this was tcllib version 0.3, the transfer::receiver(3tcl) page, and it's dated however long ago that footer says — go forth and receive your data securely, you absolute icon 👑💜