summaryrefslogtreecommitdiffstats
path: root/Doc/libctb.tex
blob: d7302be4e25ad299d68a0e9ed4704c2222ba3b71 (plain)
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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
\section{Built-in Module \module{ctb}}
\label{module-ctb}
\bimodindex{ctb}

This module provides a partial interface to the Macintosh
Communications Toolbox. Currently, only Connection Manager tools are
supported.  It may not be available in all Mac Python versions.
\index{Communications Toolbox, Macintosh}
\index{Macintosh Communications Toolbox}
\index{Connection Manager}

\begin{datadesc}{error}
The exception raised on errors.
\end{datadesc}

\begin{datadesc}{cmData}
\dataline{cmCntl}
\dataline{cmAttn}
Flags for the \var{channel} argument of the \method{Read()} and
\method{Write()} methods.
\end{datadesc}

\begin{datadesc}{cmFlagsEOM}
End-of-message flag for \method{Read()} and \method{Write()}.
\end{datadesc}

\begin{datadesc}{choose*}
Values returned by \method{Choose()}.
\end{datadesc}

\begin{datadesc}{cmStatus*}
Bits in the status as returned by \method{Status()}.
\end{datadesc}

\begin{funcdesc}{available}{}
Return \code{1} if the Communication Toolbox is available, zero otherwise.
\end{funcdesc}

\begin{funcdesc}{CMNew}{name, sizes}
Create a connection object using the connection tool named
\var{name}. \var{sizes} is a 6-tuple given buffer sizes for data in,
data out, control in, control out, attention in and attention out.
Alternatively, passing \code{None} for \var{sizes} will result in
default buffer sizes.
\end{funcdesc}

\subsection{connection object}
\label{connection-object}

For all connection methods that take a \var{timeout} argument, a value
of \code{-1} is indefinite, meaning that the command runs to completion.

\begin{memberdesc}[connection]{callback}
If this member is set to a value other than \code{None} it should point
to a function accepting a single argument (the connection
object). This will make all connection object methods work
asynchronously, with the callback routine being called upon
completion.

\emph{Note:} for reasons beyond my understanding the callback routine
is currently never called. You are advised against using asynchronous
calls for the time being.
\end{memberdesc}


\begin{methoddesc}[connection]{Open}{timeout}
Open an outgoing connection, waiting at most \var{timeout} seconds for
the connection to be established.
\end{methoddesc}

\begin{methoddesc}[connection]{Listen}{timeout}
Wait for an incoming connection. Stop waiting after \var{timeout}
seconds. This call is only meaningful to some tools.
\end{methoddesc}

\begin{methoddesc}[connection]{accept}{yesno}
Accept (when \var{yesno} is non-zero) or reject an incoming call after
\method{Listen()} returned.
\end{methoddesc}

\begin{methoddesc}[connection]{Close}{timeout, now}
Close a connection. When \var{now} is zero, the close is orderly
(i.e.\ outstanding output is flushed, etc.)\ with a timeout of
\var{timeout} seconds. When \var{now} is non-zero the close is
immediate, discarding output.
\end{methoddesc}

\begin{methoddesc}[connection]{Read}{len, chan, timeout}
Read \var{len} bytes, or until \var{timeout} seconds have passed, from 
the channel \var{chan} (which is one of \constant{cmData},
\constant{cmCntl} or \constant{cmAttn}). Return a 2-tuple:\ the data
read and the end-of-message flag, \constant{cmFlagsEOM}.
\end{methoddesc}

\begin{methoddesc}[connection]{Write}{buf, chan, timeout, eom}
Write \var{buf} to channel \var{chan}, aborting after \var{timeout}
seconds. When \var{eom} has the value \constant{cmFlagsEOM}, an
end-of-message indicator will be written after the data (if this
concept has a meaning for this communication tool). The method returns
the number of bytes written.
\end{methoddesc}

\begin{methoddesc}[connection]{Status}{}
Return connection status as the 2-tuple \code{(\var{sizes},
\var{flags})}. \var{sizes} is a 6-tuple giving the actual buffer sizes used
(see \function{CMNew()}), \var{flags} is a set of bits describing the state
of the connection.
\end{methoddesc}

\begin{methoddesc}[connection]{GetConfig}{}
Return the configuration string of the communication tool. These
configuration strings are tool-dependent, but usually easily parsed
and modified.
\end{methoddesc}

\begin{methoddesc}[connection]{SetConfig}{str}
Set the configuration string for the tool. The strings are parsed
left-to-right, with later values taking precedence. This means
individual configuration parameters can be modified by simply appending
something like \code{'baud 4800'} to the end of the string returned by
\method{GetConfig()} and passing that to this method. The method returns
the number of characters actually parsed by the tool before it
encountered an error (or completed successfully).
\end{methoddesc}

\begin{methoddesc}[connection]{Choose}{}
Present the user with a dialog to choose a communication tool and
configure it. If there is an outstanding connection some choices (like
selecting a different tool) may cause the connection to be
aborted. The return value (one of the \constant{choose*} constants) will
indicate this.
\end{methoddesc}

\begin{methoddesc}[connection]{Idle}{}
Give the tool a chance to use the processor. You should call this
method regularly.
\end{methoddesc}

\begin{methoddesc}[connection]{Abort}{}
Abort an outstanding asynchronous \method{Open()} or \method{Listen()}.
\end{methoddesc}

\begin{methoddesc}[connection]{Reset}{}
Reset a connection. Exact meaning depends on the tool.
\end{methoddesc}

\begin{methoddesc}[connection]{Break}{length}
Send a break. Whether this means anything, what it means and
interpretation of the \var{length} parameter depends on the tool in
use.
\end{methoddesc}