TRANSMITTER(3tcl)

💖 transfer::transmitter 💖

okay bestie, buckle UP, because this is the page for the data source of the Data transfer facilities in the 3tcl manual. it's giving ✨sending your bytes across a socket with style✨ and honestly? it ate. let's get into it.

---

🌸 NAME 🌸

transfer::transmitter — the data source. yeah. that's it. that's the whole name. she's simple, she's iconic. 👑

---

✨ SYNOPSIS ✨

so first, the packages you gotta require, in order, like a little pregame ritual:

package require Tcl 8.5 9

package require snit ?1.0?

package require transfer::copy ?0.3?

package require transfer::data::source ?0.3?

package require transfer::connect ?0.3?

package require transfer::transmitter ?0.3?

then the actual ways to make one:

transfer::transmitter objectName ?options...?

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

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

objectName method ?arg arg ...

objectName destroy

objectName start

objectName busy

those ?question marks? mean "optional, bestie". don't @ me.

---

🦋 DESCRIPTION 🦋

okay so the whole vibe of this package is that it pulls data sources and connection setup together into ONE combined object, so you can transmit information over a socket without juggling a million things yourself. literally a matchmaker. 💞

and the best part? these objects understand all the options from objects created by the packages transfer::data::source and transfer::connect. no cap. every single one.

---

🌈 API 🌈

💅 PACKAGE COMMANDS 💅

• transfer::transmitter objectName ?options...? — this one creates a brand-new transmitter object, and it comes with a Tcl command attached whose name is objectName. that object command is explained in full detail down in the sections Object command and Object methods (keep scrolling, it's worth it). the set of supported options lives in the Options section.

also: the object command gets created under the current namespace if objectName isn't fully qualified, and in whatever namespace you specify otherwise. the fully qualified name of the object command is what gets returned as the result of the command. so you always know where your baby lives. 🫶

• transfer::transmitter stream channel chan host port ?arg...? — this method creates a fire-and-forget transfer for the data sitting in the channel chan, starting at the current seek location. 🔥

the channel gets configured to use binary translation and encoding for the transfer, and the channel is automatically closed once the transfer has completed. so don't be surprised later, bestie.

if you give it both host and port, an active connection to the destination is made. if you give it only a port (with host being the empty string) then a passive connection is made instead. the way that flips is so clever honestly.

any arguments after the port are treated as options and are used to configure the internal transmitter object. see the section Options for the full list of supported options and what they mean. BUT — and this is the plot twist — the signature of the command prefix you specify for the -command callback is different from the signature for that same option on the transmitter object itself. this callback only gets the number of bytes transferred, and possibly an error message. no reference to the internally used transmitter object is made. periodt. 💅

the result returned by the command is the empty string if it was set to make an active connection, and the port the internal transmitter 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. iykyk. 🧚

• transfer::transmitter stream file path host port ?arg...? — this one is just like stream channel, except the data comes from the file at path instead. same energy, different source. 📁✨

👑 OBJECT COMMAND 👑

all objects created by the ::transfer::transmitter command have this general form:

• objectName method ?arg arg ...? — the method method and its arg'uments determine the exact behavior of the command. see the section Object methods for the detailed specifications. (yes, "arg'uments". that's how they wrote it. we love a quirky apostrophe. 🙈)

🎀 OBJECT METHODS 🎀

• objectName destroy — this method destroys the object. ⚠️ but heads up: doing this while a transmission is in progress will cause errors later on, when the transmission completes and tries to access the now-missing data structures of the destroyed object. so like... don't. it's giving chaos.
• objectName start — this method initiates the data transmission, setting up the connection first and then copying the information. 💫

it will throw an error if a transmission is already/still in progress. meaning: you cannot run two transmissions in parallel on a single object — only in sequence, one after the other. if you want parallel transfers you need multiple transmitter objects, one per transmission. that's the rule, bestie.

errors will also be thrown if the configuration of the data source is invalid, or if no completion callback was specified. so set your callback, fr fr. 😭

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 — this method returns a boolean value telling us whether a transmission is in progress (True) or not (False). vibe check for your transfer. ✅

---

⭐ OPTIONS ⭐

all transmitter objects support the union of the options supported by their connect and data source components, PLUS two of their own. see also the documentation for the packages transfer::data::source and transfer::connect. okay here comes the whole list, don't skip, i see you 👀

• -blocksize int — specifies the size of the chunks to be transmitted in one block. usage is optional, and its default value is 1024. little bite-sized blocks, cute. 🍓
• -command cmdprefix — specifies the command to invoke when the transmission of the information has been completed. the arguments given to this command are the same as those 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 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 entirely. 🙈
• -port int — for active mode this 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. letting the OS pick? main character energy. 💅
• -socketcmd command — lets you specify which command to use to open a socket. the default is to use the builtin ::socket. any command compatible with that one is allowed.

the envisioned main use is specifying tls::socket. so basically this option lets you create secure transfer channels without making this package explicitly dependent on the tls package. big brain. 🧠✨

see also the section Secure connections.

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

— these three options are the same as those 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).

• -string text — specifies that the source of the data is an immediate string, and its associated argument contains the string in question. 🎀
• -channel handle — specifies that the source of the data is a channel, and its associated argument is the handle of the channel containing the data.
• -file path — specifies that the source of the data is a file, and its associated argument is the path of the file containing the data. 📁
• -variable varname — 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. so like, don't get cute with local scoping. 🌸
• -size int — specifies the size of the data transfer. it's optional and defaults to -1. this value, and any other value less than zero, signals to transfer all the data from the source. 🦋
• -progress command — if specified, this defines a command to be invoked for each chunk of bytes transmitted, letting you 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. watching those numbers go up? lowkey addictive. 🔥

---

🔒 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 the command tls::socket to open the socket. like this:

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

# Create a connector with secure socket setup,
transfer::transmitter T -socketcmd tls::socket ...
...

secure that bag, bestie. 🔐✨

---

🌈 TLS SECURITY CONSIDERATIONS 🌈

okay so real talk, this package leans on the TLS package to handle all the security vibes for https urls and other socket connections. that's the whole job bestie. 💅

but here's the thing — policy decisions like which set of protocols to support and what ciphers to use? not the responsibility of TLS, and not of this package either. nope nope nope. those calls belong to whichever application is using the package, and they're probs gonna be influenced by the set of servers that app is gonna talk to. it's giving "you pick, you decide." 🫶

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 that change, the applications using TLS have to get patched — not this package, and not TLS itself. and honestly that patch might be as simple as generally activating tls1 support, like in this little cutie right here: ✨

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

... your own application code ...

slay. that's it. that's the whole patch. 👑

---

💀 BUGS, IDEAS, FEEDBACK 💀

ngl bestie, this document and the package it describes will undoubtedly contain bugs and other problems. it's just how it is, no cap. 😭

so if you find something, please report it in the category transfer of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. and if you've got any ideas for enhancements for the package and/or the documentation? also report those, we want them fr fr. 🫶

• when you're proposing code changes, please provide unified diffs, i.e. the output of diff -u
• also note: attachments are strongly preferred over inlined patches. you can attach stuff by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar ✨

okay that last part is very specific but it's the actual instructions, so like. follow them. 💅

---

🎀 KEYWORDS 🎀

channel, copy, data source, secure, ssl, tls, transfer, transmitter

iykyk. 🌸

---

🦋 CATEGORY 🦋

Transfer module

---

👑 COPYRIGHT 👑

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

---

and that's a wrap on this iconic little page, bestie!! 💖 it came from tcllib, version 0.3, and it's part of the transfer::transmitter(3tcl) family. go forth and transmit responsibly. 🫶✨💅