1[comment {-*- tcl -*- doctools manpage}]
2[manpage_begin transfer::connect n 0.2]
3[keywords active]
4[keywords channel]
5[keywords connection]
6[keywords passive]
7[keywords secure]
8[keywords ssl]
9[keywords tls]
10[keywords transfer]
11[copyright {2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
12[moddesc   {Data transfer facilities}]
13[titledesc {Connection setup}]
14[category  {Transfer module}]
15[require Tcl               8.4]
16[require snit              [opt 1.0]]
17[require transfer::connect [opt 0.2]]
18[description]
19[para]
20
21This package provides objects holding enough information to enable
22them to either actively connect to a counterpart, or to passively wait
23for a connection from said counterpart.
24
25I.e. any object created by this packages is always in one of two
26complementary modes, called [term active] (the object initiates the
27connection) and [term passive] (the object receives the connection).
28
29[para]
30
31Of the two objects in a connecting pair one has to be configured for
32[term active] mode, and the other then has to be configured for
33[term passive] mode. This establishes which of the two partners
34connects to whom (the [term active] to the other), or, who is waiting
35on whom (the [term passive] on the other).
36
37Note that this is completely independent of the direction of any data
38transmission using the connection after it has been established.
39
40An active object can, after establishing the connection, either
41transmit or receive data. Equivalently the passive object can do the
42same after the waiting for its partner has ended.
43
44[section API]
45[subsection {Package commands}]
46
47[list_begin definitions]
48
49[call [cmd transfer::connect] \
50	[arg objectName] \
51	[opt [arg options]...]]
52
53This command creates a new connection object with an associated Tcl
54command whose name is [arg objectName].
55
56This [term object] command is explained in full detail in the sections
57[sectref {Object command}] and [sectref {Object methods}]. The set of
58supported [arg options] is explained in section [sectref {Options}].
59
60[para]
61
62The object command will be created under the current namespace if the
63[arg objectName] is not fully qualified, and in the specified
64namespace otherwise.
65
66The fully qualified name of the object command is returned as the
67result of the command.
68
69[list_end]
70
71[subsection {Object command}]
72
73All objects created by the [cmd ::transfer::connect] command have the
74following general form:
75
76[list_begin definitions]
77
78[call [arg objectName] [method method] [opt [arg "arg arg ..."]]]
79
80The method [method method] and its [arg arg]'uments determine the
81exact behavior of the command.
82
83See section [sectref {Object methods}] for the detailed
84specifications.
85
86[list_end]
87
88[subsection {Object methods}]
89
90[list_begin definitions][comment ----methods]
91
92[call [arg objectName] [method destroy]]
93
94This method destroys the object.
95
96This is safe to do for an [term active] object when a connection has
97been started, as the completion callback is synchronous.
98
99For a [term passive] object currently waiting for its partner to
100establish the connection however this is not safe and will cause
101errors later on, when the connection setup completes and tries to
102access the now missing data structures of the destroyed object.
103
104[call [arg objectName] [method connect] [arg command]]
105
106This method starts the connection setup per the configuration of the
107object. When the connection is established the callback [arg command]
108will be invoked with one additional argument, the channel handle of
109the socket over which data can be transfered.
110
111[para]
112
113The detailed behaviour of the method depends on the configured
114mode.
115
116[list_begin definitions][comment ----mode-behaviour]
117[def [term active]]
118The connection setup is done synchronously. The object waits until the
119connection is established. The method returns the empty string as its
120result.
121
122[def [term passive]]
123
124The connection setup is done asynchronously. The method returns
125immediately after a listening socket has been set up. The connection
126will be established in the background.
127
128The method returns the port number of the listening socket, for use by
129the caller. One important use is the transfer of this information to
130the counterpart so that it knows where it has to connect to.
131
132[para]
133
134This is necessary as the object might have been configured for port
135[const 0], allowing the operating system to choose the actual port it
136will listen on.
137
138[para]
139
140The listening port is closed immediately when the connection was
141established by the partner, to keep the time interval small within
142which a third party can connect to the port too.
143
144Even so it is recommended to use additional measures in the protocol
145outside of the connect and transfer object to ensure that a connection
146is not used with an unidentified/unauthorized partner
147
148One possibility for this is the use of SSL/TLS.
149See the option [option -socketcmd] and section
150[sectref {Secure connections}] for information on how to do this.
151
152[list_end][comment ----mode-behaviour]
153[list_end][comment ----methods]
154
155[subsection Options]
156
157Connection objects support the set of options listed below.
158
159[list_begin options]
160[include include/connect_options.inc]
161[list_end]
162
163[vset OBJCREATE {transfer::connect C}]
164[include include/secure.inc]
165
166[vset CATEGORY transfer]
167[include ../common-text/feedback.inc]
168[manpage_end]
169