1[comment {-*- tcl -*- doctools manpage}] 2[manpage_begin transfer::transmitter n 0.2] 3[copyright {2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] 4[moddesc {Data transfer facilities}] 5[titledesc {Data source}] 6[category {Transfer module}] 7[require Tcl 8.4] 8[require snit [opt 1.0]] 9[require transfer::copy [opt 0.2]] 10[require transfer::data::source [opt 0.2]] 11[require transfer::connect [opt 0.2]] 12[require transfer::transmitter [opt 0.2]] 13[description] 14[keywords transfer copy channel {data source} transmitter ssl tls secure] 15[para] 16 17This package pulls data sources and connection setup together into a 18combined object for the transmission of information over a socket. 19 20These objects understand all the options from objects created 21by the packages [package transfer::data::source] and 22[package transfer::connect]. 23 24 25[section API] 26[subsection {Package commands}] 27 28[list_begin definitions] 29 30[call [cmd transfer::transmitter] \ 31 [arg objectName] \ 32 [opt [arg options]...]] 33 34This command creates a new transmitter object with an associated Tcl 35command whose name is [arg objectName]. 36 37This [term object] command is explained in full detail in the sections 38[sectref {Object command}] and [sectref {Object methods}]. The set of 39supported [arg options] is explained in section [sectref {Options}]. 40 41[para] 42 43The object command will be created under the current namespace if the 44[arg objectName] is not fully qualified, and in the specified 45namespace otherwise. 46 47The fully qualified name of the object command is returned as the 48result of the command. 49 50 51[call [cmd transfer::transmitter] [method {stream channel}] \ 52 [arg chan] [arg host] [arg port] [opt [arg arg]...]] 53 54This method creates a fire-and-forget transfer for the data contained 55in the channel [arg chan], starting at the current seek location. The 56channel is configured to use binary translation and encoding for the 57transfer. 58 59The channel is automatically closed when the transfer has completed. 60 61[para] 62 63If both [arg host] and [arg port] are provided an [const active] 64connection to the destination is made. If only a [arg port] is 65specified (with [arg host] the empty string) then a [const passive] 66connection is made instead. 67 68[para] 69 70Any arguments after the port are treated as options and are used to 71configure the internal transmitter object. 72 73See the section [sectref Options] for a list of the supported options 74and their meaning. 75 76[emph Note] however that the signature of the command prefix specified 77for the [option -command] callback differs from the signature for the 78same option of the transmitter object. 79 80This callback is only given the number of bytes and transfered, and 81possibly an error message. No reference to the internally used 82transmitter object is made. 83 84[para] 85[vset RETURNER command] 86[vset OBJECT {if it was set}] 87[vset QUALIFIER {internal transmitter}] 88[include include/connect_result_ref.inc] 89 90 91[call [cmd transfer::transmitter] [method {stream file}] \ 92 [arg path] [arg host] [arg port] [opt [arg arg]...]] 93 94This method is like [method {stream channel}], except that the data 95contained in the file [arg path] is transfered. 96 97[list_end] 98 99 100[subsection {Object command}] 101 102All objects created by the [cmd ::transfer::transmitter] command have 103the following general form: 104 105[list_begin definitions] 106 107[call [arg objectName] [method method] [opt [arg "arg arg ..."]]] 108 109The method [method method] and its [arg arg]'uments determine the 110exact behavior of the command. 111 112See section [sectref {Object methods}] for the detailed 113specifications. 114 115[list_end] 116 117 118[subsection {Object methods}] 119 120[list_begin definitions] 121 122[call [arg objectName] [method destroy]] 123 124This method destroys the object. Doing so while a transmission is in 125progress will cause errors later on, when the transmission completes 126and tries to access the now missing data structures of the destroyed 127object. 128 129 130[call [arg objectName] [method start]] 131 132This method initiates the data transmission, setting up the connection 133first and then copying the information. 134 135The method will throw an error if a transmission is already/still in 136progress. 137 138I.e. it is not possible to run two transmissions in parallel on a 139single object, only in sequence. Multiple transmitter objects are 140needed to manage parallel transfers, one per transmission. 141 142Errors will also be thrown if the configuration of the data source is 143invalid, or if no completion callback was specified. 144 145[para] 146[vset RETURNER method] 147[vset OBJECT {for an object configured}] 148[vset QUALIFIER {}] 149[include include/connect_result_ref.inc] 150 151 152[call [arg objectName] [method busy]] 153 154This method returns a boolean value telling us whether a transmission 155is in progress ([const True]), or not ([const False]). 156 157[list_end] 158 159 160[subsection Options] 161 162All transmitter objects support the union of the options supported 163by their connect and data source components, plus two of their own. 164 165See also the documentation for the packages 166[package transfer::data::source] and [package transfer::connect]. 167 168[list_begin options] 169[opt_def -blocksize [arg int]] 170 171This option specifies the size of the chunks to be transmitted in one 172block. Usage is optional, its default value is [const 1024]. 173 174[vset MODE transmission] [include include/complete.inc] 175 176[include include/connect_options.inc] 177[include include/dsource_options.inc] 178[list_end] 179 180[vset OBJCREATE {transfer::transmitter T}] 181[include include/secure.inc] 182 183[vset CATEGORY transfer] 184[include ../doctools2base/include/feedback.inc] 185[manpage_end] 186