1transfer::connect(n) Data transfer facilities transfer::connect(n)
2______________________________________________________________________________
6
8 transfer::connect - Connection setup
9
11 package require Tcl 8.4
12 package require snit ?1.0?
14 package require transfer::connect ?0.1?
16 transfer::connect object ?options...?
18 object destroy
20 object connect command
22_________________________________________________________________
24
26 This package provides objects holding enough information to enable them
27 to either connect to a counterpart, or to be connected to by said coun‐
28 terpart. I.e. any object created by this packages is always in one of
29 two complementary modes, called active (the object initiates the con‐
30 nection) and passive (the object receives the connection).
31 Of the two objects in a connecting pair one has to be configured for
33 active mode, and the other then has to be configured for passive mode.
34 This establishes which of the two partners connects to whom (the active
35 to the other), or, who is waiting on whom (the passive on the other).
36 Note that this is completely independent of the direction of any data
37 transmission using the connection after it has been established. An
38 active node can, after establishing the connection, either transmit or
39 receive data. Equivalently the passive node can do the same after the
40 waiting for it partner has ended.
41
43 transfer::connect object ?options...?
44 This command creates and configures a new connection object. The
45 fully qualified name of the object command is returned as the
46 result of the command.
47 The recognized options are listed below.
49 -mode mode
51 This option specifies the mode the object is in. It is
52 optional and defaults to active mode. The two possible
53 modes are:
54 active In this mode the two options -host and -port are
56 relevant and specify the host and TCP port the
57 object has to connect to. The host is given by
58 either name or IP address.
59 passive
61 In this mode the option -host has no relevance and
62 is ignored should it be configured. The only
63 option the object needs is -port, and it specifies
64 the TCP port on which the listening socket is
65 opened to await the connection from the partner.
66 -host hostname-or-ipaddr
68 This option specifies the host to connect to in active
69 mode, either by name or ip-address. An object configured
70 for passive mode ignores this option.
71 -port int
73 For active mode this option specifies the port the object
74 is expected to connect to. For passive mode however it is
75 the port where the object creates the listening socket
76 waiting for a connection. It defaults to 0, which allows
77 the OS to choose the actual port to listen on.
78 -encoding encodingname
80 -eofchar eofspec
82 -translation transspec
84 These options are the same as are recognized by the
85 builtin command fconfigure. They provide the configura‐
86 tion to be set for the channel between the two partners
87 after it has been established, but before the callback is
88 invoked (See method connect).
89 object destroy
91 This method destroys the object. This is safe to do for an
92 active object when a connection has been started, as the comple‐
93 tion callback is synchronous. For a passive object currently
94 waiting for its parter to establish the connection however this
95 is not safe and will cause errors later on, when the connection
96 setup completes and tries to access the now missing data struc‐
97 tures of the destroyed object.
98 object connect command
100 This method starts the connection setup per the configuration of
101 the object. When the connection is established the callback com‐
102 mand will be invoked with one additional argument, the channel
103 handle of the socket over which data can be transfered.
104 The detailed behaviour of the method depends on the configured
106 mode. For an active object the connection setup is done syn‐
107 chronously. I.e. the object will wait until the connection is
108 established. In that mode the method returns the empty string as
109 its result.
110 A passive object however operates asynchronously. The method
112 will return immediately after a listener has been set up and the
113 connection will be established in the background. In that mode
114 the method returns the port number of the listening socket, for
115 use by the caller, like transfering this information to the
116 counterpart so that it may know where to connect to.
117 This is necessary as the object might have been configured for
119 port 0, allowing the OS to choose the actual port it will listen
120 on.
121 The listening port is closed immediately when the connection was
123 established by the partner, to keep the time interval small
124 within which a third party can connect to the port too. Even so
125 it is recommended to use additional measures in the protocol
126 outside of the connect and transfer object to ensure that a con‐
127 nection is not used with an unidentified/unauthorized partner.
128
130 This document, and the package it describes, will undoubtedly contain
131 bugs and other problems. Please report such in the category transfer
132 of the Tcllib SF Trackers [http://source‐
133 forge.net/tracker/?group_id=12883]. Please also report any ideas for
134 enhancements you may have for either package and/or documentation.
135
137 active, channel, connection, passive, transfer
138
140 Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net>
141transfer 0.1 transfer::connect(n)