cpython/Doc/mac/libctb.tex

157 lines
5.5 KiB
TeX
Raw Normal View History

1998-08-10 15:40:22 -03:00
\section{\module{ctb} ---
1999-03-02 12:37:17 -04:00
Interface to the Communications Tool Box}
1999-03-02 12:37:17 -04:00
\declaremodule{builtin}{ctb}
\platform{Mac}
2000-10-14 01:49:36 -03:00
\modulesynopsis{Interfaces to the Communications Tool Box. Only the
Connection Manager is supported.}
1995-03-01 10:05:27 -04:00
This module provides a partial interface to the Macintosh
Communications Toolbox. Currently, only Connection Manager tools are
1995-04-10 08:34:00 -03:00
supported. It may not be available in all Mac Python versions.
1998-04-04 02:23:02 -04:00
\index{Communications Toolbox, Macintosh}
\index{Macintosh Communications Toolbox}
\index{Connection Manager}
1995-03-01 10:05:27 -04:00
\begin{datadesc}{error}
The exception raised on errors.
\end{datadesc}
\begin{datadesc}{cmData}
\dataline{cmCntl}
\dataline{cmAttn}
1998-04-04 02:23:02 -04:00
Flags for the \var{channel} argument of the \method{Read()} and
\method{Write()} methods.
1995-03-01 10:05:27 -04:00
\end{datadesc}
\begin{datadesc}{cmFlagsEOM}
1998-04-04 02:23:02 -04:00
End-of-message flag for \method{Read()} and \method{Write()}.
1995-03-01 10:05:27 -04:00
\end{datadesc}
\begin{datadesc}{choose*}
1998-04-04 02:23:02 -04:00
Values returned by \method{Choose()}.
1995-03-01 10:05:27 -04:00
\end{datadesc}
\begin{datadesc}{cmStatus*}
1998-04-04 02:23:02 -04:00
Bits in the status as returned by \method{Status()}.
1995-03-01 10:05:27 -04:00
\end{datadesc}
\begin{funcdesc}{available}{}
1998-04-04 02:23:02 -04:00
Return \code{1} if the Communication Toolbox is available, zero otherwise.
1995-03-01 10:05:27 -04:00
\end{funcdesc}
\begin{funcdesc}{CMNew}{name, sizes}
1995-03-01 10:05:27 -04:00
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.
1998-04-04 02:23:02 -04:00
Alternatively, passing \code{None} for \var{sizes} will result in
default buffer sizes.
1995-03-01 10:05:27 -04:00
\end{funcdesc}
1999-03-02 12:37:17 -04:00
\subsection{Connection Objects \label{connection-object}}
1998-04-04 02:23:02 -04:00
1995-03-01 10:05:27 -04:00
For all connection methods that take a \var{timeout} argument, a value
of \code{-1} is indefinite, meaning that the command runs to completion.
1998-04-04 02:23:02 -04:00
\begin{memberdesc}[connection]{callback}
1995-03-13 06:03:32 -04:00
If this member is set to a value other than \code{None} it should point
1995-03-01 10:05:27 -04:00
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
1995-03-13 06:03:32 -04:00
is currently never called. You are advised against using asynchronous
1995-03-01 10:05:27 -04:00
calls for the time being.
1998-04-04 02:23:02 -04:00
\end{memberdesc}
1995-03-01 10:05:27 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[connection]{Open}{timeout}
1995-03-01 10:05:27 -04:00
Open an outgoing connection, waiting at most \var{timeout} seconds for
the connection to be established.
1998-04-04 02:23:02 -04:00
\end{methoddesc}
1995-03-01 10:05:27 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[connection]{Listen}{timeout}
1995-03-01 10:05:27 -04:00
Wait for an incoming connection. Stop waiting after \var{timeout}
seconds. This call is only meaningful to some tools.
1998-04-04 02:23:02 -04:00
\end{methoddesc}
1995-03-01 10:05:27 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[connection]{accept}{yesno}
1995-03-01 10:05:27 -04:00
Accept (when \var{yesno} is non-zero) or reject an incoming call after
1998-04-04 02:23:02 -04:00
\method{Listen()} returned.
\end{methoddesc}
1995-03-01 10:05:27 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[connection]{Close}{timeout, now}
1995-03-01 10:05:27 -04:00
Close a connection. When \var{now} is zero, the close is orderly
(outstanding output is flushed, etc.)\ with a timeout of
1995-03-01 10:05:27 -04:00
\var{timeout} seconds. When \var{now} is non-zero the close is
1995-03-13 06:03:32 -04:00
immediate, discarding output.
1998-04-04 02:23:02 -04:00
\end{methoddesc}
1995-03-01 10:05:27 -04:00
1998-04-04 02:23:02 -04:00
\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}
1995-03-01 10:05:27 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[connection]{Write}{buf, chan, timeout, eom}
1995-03-01 10:05:27 -04:00
Write \var{buf} to channel \var{chan}, aborting after \var{timeout}
1998-04-04 02:23:02 -04:00
seconds. When \var{eom} has the value \constant{cmFlagsEOM}, an
1995-03-01 10:05:27 -04:00
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.
1998-04-04 02:23:02 -04:00
\end{methoddesc}
1995-03-01 10:05:27 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[connection]{Status}{}
1995-03-13 06:03:32 -04:00
Return connection status as the 2-tuple \code{(\var{sizes},
\var{flags})}. \var{sizes} is a 6-tuple giving the actual buffer sizes used
1998-04-04 02:23:02 -04:00
(see \function{CMNew()}), \var{flags} is a set of bits describing the state
1995-03-01 10:05:27 -04:00
of the connection.
1998-04-04 02:23:02 -04:00
\end{methoddesc}
1995-03-01 10:05:27 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[connection]{GetConfig}{}
1995-03-01 10:05:27 -04:00
Return the configuration string of the communication tool. These
configuration strings are tool-dependent, but usually easily parsed
and modified.
1998-04-04 02:23:02 -04:00
\end{methoddesc}
1995-03-01 10:05:27 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[connection]{SetConfig}{str}
1995-03-01 10:05:27 -04:00
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
1998-04-04 02:23:02 -04:00
\method{GetConfig()} and passing that to this method. The method returns
1995-03-01 10:05:27 -04:00
the number of characters actually parsed by the tool before it
encountered an error (or completed successfully).
1998-04-04 02:23:02 -04:00
\end{methoddesc}
1995-03-01 10:05:27 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[connection]{Choose}{}
1995-03-01 10:05:27 -04:00
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
1998-04-04 02:23:02 -04:00
aborted. The return value (one of the \constant{choose*} constants) will
1995-03-01 10:05:27 -04:00
indicate this.
1998-04-04 02:23:02 -04:00
\end{methoddesc}
1995-03-01 10:05:27 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[connection]{Idle}{}
1995-03-01 10:05:27 -04:00
Give the tool a chance to use the processor. You should call this
method regularly.
1998-04-04 02:23:02 -04:00
\end{methoddesc}
1995-03-01 10:05:27 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[connection]{Abort}{}
Abort an outstanding asynchronous \method{Open()} or \method{Listen()}.
\end{methoddesc}
1995-03-01 10:05:27 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[connection]{Reset}{}
1995-03-01 10:05:27 -04:00
Reset a connection. Exact meaning depends on the tool.
1998-04-04 02:23:02 -04:00
\end{methoddesc}
1995-03-01 10:05:27 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[connection]{Break}{length}
1995-03-01 10:05:27 -04:00
Send a break. Whether this means anything, what it means and
1998-04-04 02:23:02 -04:00
interpretation of the \var{length} parameter depends on the tool in
1995-03-01 10:05:27 -04:00
use.
1998-04-04 02:23:02 -04:00
\end{methoddesc}