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