blob: 6d3a0d794908d092061cab5518b9594fbf9e1ad0 [file] [log] [blame]
Fred Drakec817e271998-08-10 18:40:22 +00001\section{\module{ic} ---
Fred Drakef6863c11999-03-02 16:37:17 +00002 Access to Internet Config}
3
Fred Drakefe7f3bc1998-07-23 17:55:31 +00004\declaremodule{builtin}{ic}
Fred Drakef6863c11999-03-02 16:37:17 +00005 \platform{Mac}
Fred Drake5ee808d1998-08-07 17:37:15 +00006\modulesynopsis{Access to Internet Config.}
Fred Drakefe7f3bc1998-07-23 17:55:31 +00007
Guido van Rossume229d861997-08-18 15:14:26 +00008
Brett Cannon7706c2d2005-02-13 22:50:04 +00009This module provides access to various internet-related preferences
10set through \program{System Preferences} or the \program{Finder}.
Guido van Rossume229d861997-08-18 15:14:26 +000011
Fred Drakeebce3701998-03-14 22:22:14 +000012There is a low-level companion module
13\module{icglue}\refbimodindex{icglue} which provides the basic
14Internet Config access functionality. This low-level module is not
Guido van Rossume229d861997-08-18 15:14:26 +000015documented, but the docstrings of the routines document the parameters
Fred Drakeebce3701998-03-14 22:22:14 +000016and the routine names are the same as for the Pascal or \C{} API to
17Internet Config, so the standard IC programmers' documentation can be
Guido van Rossume229d861997-08-18 15:14:26 +000018used if this module is needed.
19
Fred Drakeebce3701998-03-14 22:22:14 +000020The \module{ic} module defines the \exception{error} exception and
21symbolic names for all error codes Internet Config can produce; see
22the source for details.
Guido van Rossume229d861997-08-18 15:14:26 +000023
Fred Drakeebce3701998-03-14 22:22:14 +000024\begin{excdesc}{error}
25Exception raised on errors in the \module{ic} module.
26\end{excdesc}
Guido van Rossume229d861997-08-18 15:14:26 +000027
Fred Drakeebce3701998-03-14 22:22:14 +000028
Fred Drake5ab55031998-04-07 22:01:33 +000029The \module{ic} module defines the following class and function:
Fred Drakeebce3701998-03-14 22:22:14 +000030
Fred Drake5ab55031998-04-07 22:01:33 +000031\begin{classdesc}{IC}{\optional{signature\optional{, ic}}}
Fred Drake17f690f2001-07-14 02:14:42 +000032Create an Internet Config object. The signature is a 4-character creator
Guido van Rossume229d861997-08-18 15:14:26 +000033code of the current application (default \code{'Pyth'}) which may
34influence some of ICs settings. The optional \var{ic} argument is a
Fred Drakeebce3701998-03-14 22:22:14 +000035low-level \code{icglue.icinstance} created beforehand, this may be
36useful if you want to get preferences from a different config file,
37etc.
Fred Drake5ab55031998-04-07 22:01:33 +000038\end{classdesc}
Guido van Rossume229d861997-08-18 15:14:26 +000039
Fred Drakeebce3701998-03-14 22:22:14 +000040\begin{funcdesc}{launchurl}{url\optional{, hint}}
41\funcline{parseurl}{data\optional{, start\optional{, end\optional{, hint}}}}
42\funcline{mapfile}{file}
43\funcline{maptypecreator}{type, creator\optional{, filename}}
44\funcline{settypecreator}{file}
Guido van Rossume229d861997-08-18 15:14:26 +000045These functions are ``shortcuts'' to the methods of the same name,
46described below.
47\end{funcdesc}
48
49
Fred Drake5ab55031998-04-07 22:01:33 +000050\subsection{IC Objects}
Guido van Rossume229d861997-08-18 15:14:26 +000051
Fred Drake5ab55031998-04-07 22:01:33 +000052\class{IC} objects have a mapping interface, hence to obtain the mail
53address you simply get \code{\var{ic}['MailAddress']}. Assignment also
54works, and changes the option in the configuration file.
Guido van Rossume229d861997-08-18 15:14:26 +000055
56The module knows about various datatypes, and converts the internal IC
Fred Drake5ab55031998-04-07 22:01:33 +000057representation to a ``logical'' Python data structure. Running the
Fred Drakeebce3701998-03-14 22:22:14 +000058\module{ic} module standalone will run a test program that lists all
Fred Drakeeecdc7f2000-10-14 04:45:22 +000059keys and values in your IC database, this will have to serve as
Guido van Rossume229d861997-08-18 15:14:26 +000060documentation.
61
62If the module does not know how to represent the data it returns an
Fred Drakeebce3701998-03-14 22:22:14 +000063instance of the \code{ICOpaqueData} type, with the raw data in its
Fred Drake41788db1998-04-04 06:23:02 +000064\member{data} attribute. Objects of this type are also acceptable values
Guido van Rossume229d861997-08-18 15:14:26 +000065for assignment.
66
Fred Drake5ab55031998-04-07 22:01:33 +000067Besides the dictionary interface, \class{IC} objects have the
68following methods:
Guido van Rossume229d861997-08-18 15:14:26 +000069
Guido van Rossume229d861997-08-18 15:14:26 +000070
Fred Drake5ab55031998-04-07 22:01:33 +000071\begin{methoddesc}{launchurl}{url\optional{, hint}}
Raymond Hettinger565ea5a2004-10-02 11:02:59 +000072Parse the given URL, launch the correct application and pass it the
Guido van Rossume229d861997-08-18 15:14:26 +000073URL. The optional \var{hint} can be a scheme name such as
Fred Drakeebce3701998-03-14 22:22:14 +000074\code{'mailto:'}, in which case incomplete URLs are completed with this
75scheme. If \var{hint} is not provided, incomplete URLs are invalid.
Fred Drake5ab55031998-04-07 22:01:33 +000076\end{methoddesc}
Guido van Rossume229d861997-08-18 15:14:26 +000077
Fred Drake5ab55031998-04-07 22:01:33 +000078\begin{methoddesc}{parseurl}{data\optional{, start\optional{, end\optional{, hint}}}}
Guido van Rossume229d861997-08-18 15:14:26 +000079Find an URL somewhere in \var{data} and return start position, end
80position and the URL. The optional \var{start} and \var{end} can be
81used to limit the search, so for instance if a user clicks in a long
Fred Drakeeecdc7f2000-10-14 04:45:22 +000082text field you can pass the whole text field and the click-position in
Guido van Rossume229d861997-08-18 15:14:26 +000083\var{start} and this routine will return the whole URL in which the
Fred Drake41788db1998-04-04 06:23:02 +000084user clicked. As above, \var{hint} is an optional scheme used to
85complete incomplete URLs.
Fred Drake5ab55031998-04-07 22:01:33 +000086\end{methoddesc}
Guido van Rossume229d861997-08-18 15:14:26 +000087
Fred Drake5ab55031998-04-07 22:01:33 +000088\begin{methoddesc}{mapfile}{file}
Guido van Rossume229d861997-08-18 15:14:26 +000089Return the mapping entry for the given \var{file}, which can be passed
Brett Cannon7706c2d2005-02-13 22:50:04 +000090as either a filename or an \function{FSSpec()} result, and which
Fred Drake41788db1998-04-04 06:23:02 +000091need not exist.
Guido van Rossume229d861997-08-18 15:14:26 +000092
Fred Drakef6863c11999-03-02 16:37:17 +000093The mapping entry is returned as a tuple \code{(\var{version},
Fred Drake671fe9d1997-12-29 18:53:31 +000094\var{type}, \var{creator}, \var{postcreator}, \var{flags},
95\var{extension}, \var{appname}, \var{postappname}, \var{mimetype},
Fred Drakef6863c11999-03-02 16:37:17 +000096\var{entryname})}, where \var{version} is the entry version
Fred Drake41788db1998-04-04 06:23:02 +000097number, \var{type} is the 4-character filetype, \var{creator} is the
984-character creator type, \var{postcreator} is the 4-character creator
99code of an
Guido van Rossume229d861997-08-18 15:14:26 +0000100optional application to post-process the file after downloading,
101\var{flags} are various bits specifying whether to transfer in binary
102or ascii and such, \var{extension} is the filename extension for this
103file type, \var{appname} is the printable name of the application to
104which this file belongs, \var{postappname} is the name of the
105postprocessing application, \var{mimetype} is the MIME type of this
106file and \var{entryname} is the name of this entry.
Fred Drake5ab55031998-04-07 22:01:33 +0000107\end{methoddesc}
Guido van Rossume229d861997-08-18 15:14:26 +0000108
Fred Drake5ab55031998-04-07 22:01:33 +0000109\begin{methoddesc}{maptypecreator}{type, creator\optional{, filename}}
Fred Drake41788db1998-04-04 06:23:02 +0000110Return the mapping entry for files with given 4-character \var{type} and
Guido van Rossume229d861997-08-18 15:14:26 +0000111\var{creator} codes. The optional \var{filename} may be specified to
112further help finding the correct entry (if the creator code is
113\code{'????'}, for instance).
114
115The mapping entry is returned in the same format as for \var{mapfile}.
Fred Drake5ab55031998-04-07 22:01:33 +0000116\end{methoddesc}
Guido van Rossume229d861997-08-18 15:14:26 +0000117
Fred Drake5ab55031998-04-07 22:01:33 +0000118\begin{methoddesc}{settypecreator}{file}
Guido van Rossume229d861997-08-18 15:14:26 +0000119Given an existing \var{file}, specified either as a filename or as an
Brett Cannon7706c2d2005-02-13 22:50:04 +0000120\function{FSSpec()} result, set its creator and type correctly based
Fred Drakeebce3701998-03-14 22:22:14 +0000121on its extension. The finder is told about the change, so the finder
122icon will be updated quickly.
Fred Drake5ab55031998-04-07 22:01:33 +0000123\end{methoddesc}