Doc/mac/libmacic.tex

   1 \section{\module{ic} ---
   2          Access to Internet Config}
   3
   4 \declaremodule{builtin}{ic}
   5   \platform{Mac}
   6 \modulesynopsis{Access to Internet Config.}
   7
   8
   9 This module provides access to Macintosh Internet
  10 Config\index{Internet Config} package,
  11 which stores preferences for Internet programs such as mail address,
  12 default homepage, etc. Also, Internet Config contains an elaborate set
  13 of mappings from Macintosh creator/type codes to foreign filename
  14 extensions plus information on how to transfer files (binary, ascii,
  15 etc).
  16
  17 There is a low-level companion module
  18 \module{icglue}\refbimodindex{icglue} which provides the basic
  19 Internet Config access functionality.  This low-level module is not
  20 documented, but the docstrings of the routines document the parameters
  21 and the routine names are the same as for the Pascal or \C{} API to
  22 Internet Config, so the standard IC programmers' documentation can be
  23 used if this module is needed.
  24
  25 The \module{ic} module defines the \exception{error} exception and
  26 symbolic names for all error codes Internet Config can produce; see
  27 the source for details.
  28
  29 \begin{excdesc}{error}
  30 Exception raised on errors in the \module{ic} module.
  31 \end{excdesc}
  32
  33
  34 The \module{ic} module defines the following class and function:
  35
  36 \begin{classdesc}{IC}{\optional{signature\optional{, ic}}}
  37 Create an internet config object. The signature is a 4-character creator
  38 code of the current application (default \code{'Pyth'}) which may
  39 influence some of ICs settings. The optional \var{ic} argument is a
  40 low-level \code{icglue.icinstance} created beforehand, this may be
  41 useful if you want to get preferences from a different config file,
  42 etc.
  43 \end{classdesc}
  44
  45 \begin{funcdesc}{launchurl}{url\optional{, hint}}
  46 \funcline{parseurl}{data\optional{, start\optional{, end\optional{, hint}}}}
  47 \funcline{mapfile}{file}
  48 \funcline{maptypecreator}{type, creator\optional{, filename}}
  49 \funcline{settypecreator}{file}
  50 These functions are ``shortcuts'' to the methods of the same name,
  51 described below.
  52 \end{funcdesc}
  53
  54
  55 \subsection{IC Objects}
  56
  57 \class{IC} objects have a mapping interface, hence to obtain the mail
  58 address you simply get \code{\var{ic}['MailAddress']}. Assignment also
  59 works, and changes the option in the configuration file.
  60
  61 The module knows about various datatypes, and converts the internal IC
  62 representation to a ``logical'' Python data structure. Running the
  63 \module{ic} module standalone will run a test program that lists all
  64 keys and values in your IC database, this will have to server as
  65 documentation.
  66
  67 If the module does not know how to represent the data it returns an
  68 instance of the \code{ICOpaqueData} type, with the raw data in its
  69 \member{data} attribute. Objects of this type are also acceptable values
  70 for assignment.
  71
  72 Besides the dictionary interface, \class{IC} objects have the
  73 following methods:
  74
  75
  76 \begin{methoddesc}{launchurl}{url\optional{, hint}}
  77 Parse the given URL, lauch the correct application and pass it the
  78 URL. The optional \var{hint} can be a scheme name such as
  79 \code{'mailto:'}, in which case incomplete URLs are completed with this
  80 scheme.  If \var{hint} is not provided, incomplete URLs are invalid.
  81 \end{methoddesc}
  82
  83 \begin{methoddesc}{parseurl}{data\optional{, start\optional{, end\optional{, hint}}}}
  84 Find an URL somewhere in \var{data} and return start position, end
  85 position and the URL. The optional \var{start} and \var{end} can be
  86 used to limit the search, so for instance if a user clicks in a long
  87 textfield you can pass the whole textfield and the click-position in
  88 \var{start} and this routine will return the whole URL in which the
  89 user clicked.  As above, \var{hint} is an optional scheme used to
  90 complete incomplete URLs.
  91 \end{methoddesc}
  92
  93 \begin{methoddesc}{mapfile}{file}
  94 Return the mapping entry for the given \var{file}, which can be passed
  95 as either a filename or an \function{macfs.FSSpec()} result, and which
  96 need not exist.
  97
  98 The mapping entry is returned as a tuple \code{(\var{version},
  99 \var{type}, \var{creator}, \var{postcreator}, \var{flags},
 100 \var{extension}, \var{appname}, \var{postappname}, \var{mimetype},
 101 \var{entryname})}, where \var{version} is the entry version
 102 number, \var{type} is the 4-character filetype, \var{creator} is the
 103 4-character creator type, \var{postcreator} is the 4-character creator
 104 code of an
 105 optional application to post-process the file after downloading,
 106 \var{flags} are various bits specifying whether to transfer in binary
 107 or ascii and such, \var{extension} is the filename extension for this
 108 file type, \var{appname} is the printable name of the application to
 109 which this file belongs, \var{postappname} is the name of the
 110 postprocessing application, \var{mimetype} is the MIME type of this
 111 file and \var{entryname} is the name of this entry.
 112 \end{methoddesc}
 113
 114 \begin{methoddesc}{maptypecreator}{type, creator\optional{, filename}}
 115 Return the mapping entry for files with given 4-character \var{type} and
 116 \var{creator} codes. The optional \var{filename} may be specified to
 117 further help finding the correct entry (if the creator code is
 118 \code{'????'}, for instance).
 119
 120 The mapping entry is returned in the same format as for \var{mapfile}.
 121 \end{methoddesc}
 122
 123 \begin{methoddesc}{settypecreator}{file}
 124 Given an existing \var{file}, specified either as a filename or as an
 125 \function{macfs.FSSpec()} result, set its creator and type correctly based
 126 on its extension.  The finder is told about the change, so the finder
 127 icon will be updated quickly.
 128 \end{methoddesc}