124 lines
5.1 KiB
TeX
124 lines
5.1 KiB
TeX
\section{\module{ic} ---
|
|
Access to Internet Config}
|
|
|
|
\declaremodule{builtin}{ic}
|
|
\platform{Mac}
|
|
\modulesynopsis{Access to Internet Config.}
|
|
|
|
|
|
This module provides access to various internet-related preferences
|
|
set through \program{System Preferences} or the \program{Finder}.
|
|
|
|
There is a low-level companion module
|
|
\module{icglue}\refbimodindex{icglue} which provides the basic
|
|
Internet Config access functionality. This low-level module is not
|
|
documented, but the docstrings of the routines document the parameters
|
|
and the routine names are the same as for the Pascal or \C{} API to
|
|
Internet Config, so the standard IC programmers' documentation can be
|
|
used if this module is needed.
|
|
|
|
The \module{ic} module defines the \exception{error} exception and
|
|
symbolic names for all error codes Internet Config can produce; see
|
|
the source for details.
|
|
|
|
\begin{excdesc}{error}
|
|
Exception raised on errors in the \module{ic} module.
|
|
\end{excdesc}
|
|
|
|
|
|
The \module{ic} module defines the following class and function:
|
|
|
|
\begin{classdesc}{IC}{\optional{signature\optional{, ic}}}
|
|
Create an Internet Config object. The signature is a 4-character creator
|
|
code of the current application (default \code{'Pyth'}) which may
|
|
influence some of ICs settings. The optional \var{ic} argument is a
|
|
low-level \code{icglue.icinstance} created beforehand, this may be
|
|
useful if you want to get preferences from a different config file,
|
|
etc.
|
|
\end{classdesc}
|
|
|
|
\begin{funcdesc}{launchurl}{url\optional{, hint}}
|
|
\funcline{parseurl}{data\optional{, start\optional{, end\optional{, hint}}}}
|
|
\funcline{mapfile}{file}
|
|
\funcline{maptypecreator}{type, creator\optional{, filename}}
|
|
\funcline{settypecreator}{file}
|
|
These functions are ``shortcuts'' to the methods of the same name,
|
|
described below.
|
|
\end{funcdesc}
|
|
|
|
|
|
\subsection{IC Objects}
|
|
|
|
\class{IC} objects have a mapping interface, hence to obtain the mail
|
|
address you simply get \code{\var{ic}['MailAddress']}. Assignment also
|
|
works, and changes the option in the configuration file.
|
|
|
|
The module knows about various datatypes, and converts the internal IC
|
|
representation to a ``logical'' Python data structure. Running the
|
|
\module{ic} module standalone will run a test program that lists all
|
|
keys and values in your IC database, this will have to serve as
|
|
documentation.
|
|
|
|
If the module does not know how to represent the data it returns an
|
|
instance of the \code{ICOpaqueData} type, with the raw data in its
|
|
\member{data} attribute. Objects of this type are also acceptable values
|
|
for assignment.
|
|
|
|
Besides the dictionary interface, \class{IC} objects have the
|
|
following methods:
|
|
|
|
|
|
\begin{methoddesc}{launchurl}{url\optional{, hint}}
|
|
Parse the given URL, launch the correct application and pass it the
|
|
URL. The optional \var{hint} can be a scheme name such as
|
|
\code{'mailto:'}, in which case incomplete URLs are completed with this
|
|
scheme. If \var{hint} is not provided, incomplete URLs are invalid.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{parseurl}{data\optional{, start\optional{, end\optional{, hint}}}}
|
|
Find an URL somewhere in \var{data} and return start position, end
|
|
position and the URL. The optional \var{start} and \var{end} can be
|
|
used to limit the search, so for instance if a user clicks in a long
|
|
text field you can pass the whole text field and the click-position in
|
|
\var{start} and this routine will return the whole URL in which the
|
|
user clicked. As above, \var{hint} is an optional scheme used to
|
|
complete incomplete URLs.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{mapfile}{file}
|
|
Return the mapping entry for the given \var{file}, which can be passed
|
|
as either a filename or an \function{FSSpec()} result, and which
|
|
need not exist.
|
|
|
|
The mapping entry is returned as a tuple \code{(\var{version},
|
|
\var{type}, \var{creator}, \var{postcreator}, \var{flags},
|
|
\var{extension}, \var{appname}, \var{postappname}, \var{mimetype},
|
|
\var{entryname})}, where \var{version} is the entry version
|
|
number, \var{type} is the 4-character filetype, \var{creator} is the
|
|
4-character creator type, \var{postcreator} is the 4-character creator
|
|
code of an
|
|
optional application to post-process the file after downloading,
|
|
\var{flags} are various bits specifying whether to transfer in binary
|
|
or ascii and such, \var{extension} is the filename extension for this
|
|
file type, \var{appname} is the printable name of the application to
|
|
which this file belongs, \var{postappname} is the name of the
|
|
postprocessing application, \var{mimetype} is the MIME type of this
|
|
file and \var{entryname} is the name of this entry.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{maptypecreator}{type, creator\optional{, filename}}
|
|
Return the mapping entry for files with given 4-character \var{type} and
|
|
\var{creator} codes. The optional \var{filename} may be specified to
|
|
further help finding the correct entry (if the creator code is
|
|
\code{'????'}, for instance).
|
|
|
|
The mapping entry is returned in the same format as for \var{mapfile}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{settypecreator}{file}
|
|
Given an existing \var{file}, specified either as a filename or as an
|
|
\function{FSSpec()} result, set its creator and type correctly based
|
|
on its extension. The finder is told about the change, so the finder
|
|
icon will be updated quickly.
|
|
\end{methoddesc}
|