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