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