 |
ActiveTcl User Guide |
 |
[ Main table Of Contents | Tcllib Table Of Contents | Tcllib Index ]
transfer::connect(n) 0.1 "Data transfer facilities"
transfer::connect - Connection setup
TABLE OF
CONTENTS
SYNOPSIS
DESCRIPTION
API
KEYWORDS
COPYRIGHT
package require Tcl 8.4
package require snit ?1.0?
package require transfer::connect ?0.1?
This package provides objects holding enough information to
enable them to either connect to a counterpart, or to be connected
to by said counterpart. I.e. any object created by this packages is
always in one of two complementary modes, called active (the object initiates the
connection) and passive
(the object receives the connection).
Of the two objects in a connecting pair one has to be configured
for active mode, and the
other then has to be configured for passive mode. This establishes
which of the two partners connects to whom (the active to the other), or, who is
waiting on whom (the passive on the other). Note that
this is completely independent of the direction of any data
transmission using the connection after it has been established. An
active node can, after establishing the connection, either transmit
or receive data. Equivalently the passive node can do the same
after the waiting for it partner has ended.
- transfer::connect object
?options...?
- This command creates and configures a new connection object. The fully qualified name of the object command is
returned as the result of the command.
The recognized options are listed below.
- -mode mode
- This option specifies the mode the object is in. It is 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
- This option specifies the host to connect to in active mode, either by name or
ip-address. An object configured for passive mode ignores this
option.
- -port int
- For active mode this
option specifies the port the object is expected to connect to. For
passive mode however it
is the port where the object creates the listening socket waiting
for a connection. It defaults to 0, which allows
the OS to choose the actual port to listen on.
- -encoding encodingname
- -eofchar eofspec
- -translation transspec
- These options are the same as are 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).
- object
destroy
- This method destroys the object. This is safe to do for an
active object when a
connection has been started, as the completion callback is
synchronous. For a passive object currently waiting
for its parter to establish the connection however this is not safe
and will cause errors later on, when the connection setup completes
and tries to access the now missing data structures of the
destroyed object.
- object connect
command
- This method starts the connection setup per the configuration
of the object. When the connection is established the callback command will be invoked with one additional
argument, the channel handle of the socket over which data can be
transfered.
The detailed behaviour of the method depends on the configured
mode. For an active
object the connection setup is done synchronously. I.e. the object
will wait until the connection is established. In that mode the
method returns the empty string as its result.
A passive object
however operates asynchronously. The method will return immediately
after a listener has been set up and the connection will be
established in the background. In that mode the method returns the
port number of the listening socket, for use by the caller, like
transfering this information to the counterpart so that it may know
where to connect to.
This is necessary as the object might have been configured for
port 0, allowing the OS to choose the actual port
it will listen on.
The listening port is closed immediately when the connection was
established by the partner, to keep the time interval small within
which a third party can connect to the port too. Even so it is
recommended to use additional measures in the protocol outside of
the connect and transfer object to ensure that a connection is not
used with an unidentified/unauthorized partner.
active , channel , connection , passive , transfer
Copyright © 2006 Andreas Kupries
<andreas_kupries@users.sourceforge.net>