
:mod:`ic` --- Mac OS X インターネット設定へのアクセス
=====================================================

.. module:: ic
   :platform: Mac
   :synopsis: Mac OS X インターネット設定へのアクセス。
   :deprecated:


このモジュールでは、 :program:`システム設定` や :program:`Finder`
で設定したインターネット関連の設定へのアクセス機能を提供しています。

.. warning::

   このモジュールは 3.0 で削除されます。


.. index:: module: icglue

このモジュールには、 :mod:`icglue` という低水準の関連モジュールがあり、
インターネット設定への基本的なアクセス機能を提供しています。
この低水準のモジュールはドキュメント化されていませんが、各ルーチンの
docstring にはパラメタの説明があり、ルーチン名には Internet
Config に対する Pascal や C のインタフェースと同じ名前を使っているので、
このモジュールが必要な場合には標準の IC プログラマドキュメントを利用できます。

:mod:`ic` モジュールでは、例外 :exc:`error` と、インターネット設定\
から生じる全てのエラーコードに対するシンボル名を定義しています。詳しくは\
ソースコードを参照してください。


.. exception:: error

   :mod:`ic` モジュール内部でエラーが生じたときに送出される例外です。

:mod:`ic` モジュールは以下のクラスと関数を定義しています：


.. class:: IC([signature[, ic]])

   インターネット設定オブジェクトを作成します。
   *signature* は、IC の設定に影響を及ぼす可能性のある現在のアプリケーションを表す
   4 文字のクリエータコード (デフォルトは ``'Pyth'``) です。
   オプションの引数 *ic* は低水準モジュールであらかじめ作成しておいた
   ``icglue.icinstance`` で、別の設定ファイルなどから設定を得る場合に\
   便利です。


.. function:: launchurl(url[, hint])
              parseurl(data[, start[, end[, hint]]])
              mapfile(file)
              maptypecreator(type, creator[, filename])
              settypecreator(file)

   これらの関数は、後述する同名のメソッドへの「ショートカット」です。


IC オブジェクト
---------------

:class:`IC` オブジェクトはマップ型のインターフェースを持っているので、
メールアドレスの取得は単に ``ic['MailAddress']``
でできます。値の代入もでき、設定ファイルのオプションを変更できます。

このモジュールは各種のデータ型を知っていて、IC内部の表現を「論理的な」
Python データ構造に変換します。 :mod:`ic`
モジュールを単体で実行すると、テストプログラムが実行されて IC
データベースにある全てのキーと値のペアをリスト表示するので、文書代わりになります。

モジュールがデータの表現方法を推測できなかった場合、
:attr:`data` 属性に生のデータが入った ``ICOpaqueData``
型のインスタンスを返します。この型のオブジェクトも代入に利用できます。

:class:`IC` には辞書型のインターフェースの他にも以下のようなメソッドが\
あります。


.. method:: IC.launchurl(url[, hint])

   与えられたURLを解析し、適切なアプリケーションを起動してURLを渡します。省\
   略可能な *hint* は、 ``'mailto:'`` などのスキーム名で、不完全なURLはこ\
   のスキームにあわせて補完します。 *hint* を指定していない場合、
   不完全なURLは無効になります。


.. method:: IC.parseurl(data[, start[, end[, hint]]])

   *data* の中からURLを検索し、URLの開始位置、終了位置、URLそのものを\
   返します。オプションの引数 *start* と *end* を使うと検索範囲を制限\
   できます。例えば、ユーザーが長いテキストフィールドをクリックした場合に、
   このルーチンにテキストフィールド全体とクリック位置 *start* を渡すことで、
   ユーザーがクリックした場所にある URL 全体を返させられます。
   先に述べたように、 *hint* はオプションで、不完全なURLを補完するための\
   スキームです。


.. method:: IC.mapfile(file)

   *file* に対するマッピングエントリを返します。
   *file* にはファイル名か :func:`FSSpec` の戻り値を渡せます。実在\
   しないファイルであってもかまいません。

   マッピングエントリは
   ``(version, type, creator, postcreator, flags, extension, appname,
   postappname, mimetype, entryname)`` からなるタプルで返されます。
   *version* はエントリーのバージョン番号、
   *type* は4文字のファイルタイプ、
   *creator* は 4 文字のクリエータタイプ、
   *postcreator* はファイルのダウンロード後にオプションとして起動され、
   後処理を行うアプリケーションの 4 文字のクリエータコードです。
   *flags* は、転送をバイナリで行うかアスキー\
   で行うか、などの様々なフラグビットからなる値です。
   *extension* はこのファイルタイプに対するファイル名の拡張子、
   *appname* はファイルが属するアプリケーションの印字可能な名前、
   *postappname* は後処理用アプリケーション、
   *mimetype* はこのファイルのMIMEタイプ、最後の
   *entryname* はこのエントリの名前です。


.. method:: IC.maptypecreator(type, creator[, filename])

   4文字の *type* と *creator* コードを持つファイルに対するマッピン\
   グエントリを返します。(クリエータが ``'????'`` であるような場合に)
   正しいエントリが見つかりやすいようにオプションの *filename* を指定\
   できます。

   マッピングエントリーは *mapfile* と同じフォーマットで返されます。


.. method:: IC.settypecreator(file)

   実在のファイル *file* に対して、拡張子に基づいて適切なクリエータと\
   タイプを設定します。 *file* の指定は、ファイル名でも
   :func:`FSSpec` の戻り値でもかまいません。変更は Finder に\
   通知されるので、Finder 上のアイコンは即座に更新されます。
