1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin transfer::data::destination n 0.3]
[keywords channel]
[keywords copy]
[keywords {data destination}]
[keywords transfer]
[copyright {2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
[moddesc {Data transfer facilities}]
[titledesc {Data destination}]
[category {Transfer module}]
[require Tcl "8.5 9"]
[require snit [opt 1.0]]
[require transfer::data::destination [opt 0.3]]
[description]
[para]
This package provides objects mainly describing the destination of a
data transfer. They are also able to initiate the reception of
information from a channel into the described destination.
[section API]
[list_begin definitions]
[call [cmd transfer::data::destination] \
[arg objectName] \
[opt [arg options]...]]
This command creates a new data destination object with an associated
Tcl command whose name is [arg objectName].
This [term object] command is explained in full detail in the sections
[sectref {Object command}] and [sectref {Object methods}]. The set of
supported [arg options] is explained in section [sectref {Options}].
[para]
The object command will be created under the current namespace if the
[arg objectName] is not fully qualified, and in the specified
namespace otherwise.
The fully qualified name of the object command is returned as the
result of the command.
[list_end]
[subsection {Object command}]
All objects created by the [cmd ::transfer::data::destination] command
have the following general form:
[list_begin definitions]
[call [arg objectName] [method method] [opt [arg "arg arg ..."]]]
The method [method method] and its [arg arg]'uments determine the
exact behavior of the command.
See section [sectref {Object methods}] for the detailed
specifications.
[list_end]
[subsection {Object methods}]
[list_begin definitions]
[call [arg objectName] [method destroy]]
This method destroys the object. Doing so while the object is busy
with the reception of information from a channel will cause errors
later on, when the reception completes and tries to access the now
missing data structures of the destroyed object.
[call [arg objectName] [method put] [arg chunk]]
The main receptor method. Saves the received [arg chunk] of data into
the configured destination. It has to be called for each piece of data
received.
[call [arg objectName] [method done]]
The secondary receptor method. Finalizes the receiver. It has to be
called when the receiving channel signals EOF. Afterward neither
itself nor method [method put] can be called anymore.
[call [arg objectName] [method valid] [arg msgvar]]
This method checks the configuration of the object for validity. It
returns a boolean flag as result, whose value is [const True] if the
object is valid, and [const False] otherwise. In the latter case the
variable whose name is stored in [arg msgvar] is set to an error
message describing the problem found with the configuration. Otherwise
this variable is not touched.
[call [arg objectName] [method receive] [arg channel] [arg done]]
This method initiates the reception of data from the specified
[arg channel]. The received data will be stored into the configured
destination, via calls to the methods [method put] and [method done].
When the reception completes the command prefix [arg done] is invoked,
with the number of received characters appended to it as the sole
additional argument.
[list_end]
[subsection Options]
All data destinations support the options listed below. It should be
noted that all are semi-exclusive, each specifying a different type of
destination and associated information. If these options are specified
more than once then the last option specified is used to actually
configure the object.
[list_begin options]
[include include/ddest_options.inc]
[list_end]
[vset CATEGORY transfer]
[include ../common-text/feedback.inc]
[manpage_end]
|
