1transfer::connect(n)       Data transfer facilities       transfer::connect(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       transfer::connect - Connection setup
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require snit  ?1.0?
14
15       package require transfer::connect  ?0.1?
16
17       transfer::connect object ?options...?
18
19       object destroy
20
21       object connect command
22
23_________________________________________________________________
24

DESCRIPTION

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
32       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

API

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
48              The recognized options are listed below.
49
50              -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
55                     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
60                     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
67              -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
72              -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
79              -encoding encodingname
80
81              -eofchar eofspec
82
83              -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
90       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
99       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
105              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
111              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
118              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
122              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

BUGS, IDEAS, FEEDBACK

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

KEYWORDS

137       active, channel, connection, passive, transfer
138
140       Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net>
141
142
143
144
145transfer                              0.1                 transfer::connect(n)
Impressum