Technote 1129
LaserWriter 8.5.1: The Settings Library
|
目次
SettingsLib
と PrintingLib
SettingsLib
インタフェース
拡張 'PAPA' と
SettingsLib
要約
参考文献
|
プリンタ設定ライブラリ
(SettingsLib) は LaserWriter 8.5.1
で導入されました。これを使うと、デスクトッププリンタを作成したときに
LaserWriter 8
が作成する情報にアプリケーションからアクセスし、変更することができます。SettingsLib
は、プリンタドライバの異なる部分、異なるプリンタドライバとデスクトッププリントモニタなどのプリンタデータベースクライアント間でプリンタデータベースの衝突を防ぎます。プリンタデータベースは、LaserWriter
8
のプリファレンスファイルに保存されています。SettingsLib
は、LaserWriter 8 の 'PAPA'
リソース形式に依存する従来のアプリケーションで特に有効です。LaserWriter
8.5.1 が導入されて、'PAPA'
リソースのサイズが変わり、サイズに依存するアプリケーションは動作しなくなりました。リソースサイズは、今後も変わる可能性があるので、アップルはこの問題を回避するために
SettingsLib を導入しました。この TECHNOTE では
SettingsLib API の概要について説明します。
|
SettingsLib と
PrintingLib
SettingsLib は PrintingLib
ファイルに含まれるコードフラグメントです。SettingsLib
は、PrintingLib 内の他のコードフラグメントと LaserWriter 8
が、保存されたプリンタ情報にアクセスするために使用します。SettingsLib
API にアクセスするためには、PrintingLib
とリンクする必要があります。
SettingsLib
インタフェース
プリンタデータベースの衝突を避けるために、クライアントは決してプリンタデータベースを開いてはなりません。代わりに、このセクションのルーチンを使って、個々のプリンタ情報のコレクションを取得し、順にデータベース内のプリンタエントリを調べてください。
psGetPrintingPrefsFolder
SettingsLib
インタフェースの正しい使い方として、クライアントはプリンタデータベースをファイル名のみで表します。SettingsLib
は、プリンタデータベースのあるボリュームとフォルダはわかっていますので、個々のデータベースは名前で特定できます。現在、プリンタデータベースは“システム設定”フォルダ内の“印刷設定”フォルダに入っています。プリンタデータベースのあるフォルダの位置を取得するには、psGetPrintingPrefsFolder()
を使用してください。この API
は、プリント関連のデータの場所を知りたい場合にも使います。
OSStatus
psGetPrintingPrefsFolder(short *vRef, long
*folderId);
この関数は、現在のシステムの印刷設定フォルダを探し、必要な場合は作成します。関数の戻りで、印刷設定フォルダのボリュームを
*vRef に、ディレクトリ ID を *folderId
に設定します。フォルダが存在せず、作成することもできなければ、エラーを返します。
psGetPrefsPrinterInfo
クライアントは、プリンタデータベース名と特定のプリンタの
'PAPA' ハンドルがわかれば、psGetPrefsPrinterInfo()
を使ってそのプリンタの情報が入っているコレクションを取得することができます。コレクション内の個々の項目には、コレクションマネージャを使ってアクセスできます。クライアントは、コレクションマネージャの
DisposeCollection()
でコレクションを破棄しなければなりません。コレクションマネージャの詳細については、『Inside
Macintosh: QuickDraw GX Environment and
Utilities』を参照してください。
Collection
psGetPrefsPrinterInfo(StringPtr prefsName, Handle
papa);
'PAPA'
で指定したプリンタについての情報を含むコレクションを返します。情報は、prefsName
で名前が指定された印刷設定ファイルから取得します。コレクションが取得できない場合は、NULL
を返します。
ファイル名はプリンタデータベースを特定しますが、'PAPA'
を含むハンドルはデータベース内の個々のプリンタを特定します。'PAPA'
は、3 つの Pascal
文字列を束ねたものに、特定のプリンタに固有な通信方法を表すデータが続いたものです注1。このため、SettingsLib
は 3
つのパスカル文字列に続くデータは解釈しません。内容はクライアントが決定します。(*1)
'PAPA' の先頭の 3 つの Pascal
文字列は、プリンタ名、ネットワークオブジェクトタイプ、プリンタのゾーン名です。これらの
3
つの文字列は特定のプリンタデータベースエントリを識別します。つまりデータベースのキーになります。詳細については、TECHNOTE
1115「LaserWriter 8.5.1: 拡張 'PAPA'
リソース」を参照してください。
psUpdatePrefsPrinterInfo と psRemovePrefsPrinterInfo
クライアントが特定のプリンタを記述するコレクションを取得したら、コレクションマネージャを使ってそのプリンタ情報を追加、削除、変更することができます。クライアントは必要な変更を行ったら、psUpdatePrefsPrinterInfo()
で、指定のプリンタの既存のコレクションを新しいコレクションで置き換えます。psUpdatePrefsPrinterInfo()
を呼び出した場合でも、コレクションを破棄するのはクライアントの役目です。データベースからプリンタを完全に取り除くには、psRemovePrefsPrinterInfo()
を使用します。
OSErr
psUpdatePrefsPrinterInfo(StringPtr prefsName, Handle papa,
Collection prInfo);
コレクション prInfo 内の、PAPA で指定されたプリンタ情報を
prefsName という名前の設定データベースに保存します。PAPA
で指定したプリンタのすべての情報が prInfo
の情報で置き換えられます。
OSErr
psRemovePrefsPrinterInfo(StringPtr prefsName, Handle papa,
Collection prInfo);
PAPA で指定されたプリンタのすべての情報を prefsName
という印刷設定ファイルから取り除きます。PAPA が NULL
の場合、prInfo
をプリンタ名のヒントとして検索し、設定データベースから削除するエントリを選択するのに使います。
デベロッパが固有のデータを追加する場合は、'APPL'
と登録者のクリエータタイプを表す ID
を指定することをおすすめします。例えば、Adobe Acrobat
が固有データを保存する場合は、タグを 'APPL'、ID を 'CARO'
にします。このように、各アプリケーションはデータベース内のスロットを
1
つだけ使用します。さらに、スロットに保存するデータはフラットなコレクションにし、その中で任意のタグと
ID を使用することをおすすめします。
#define kHintAppPrivateTag APPL
#define kHintAppPrivateId // アプリケーションのクリエータタイプ
#define kHintAppPrivateVar // フラットなコレクション
|
注意:
アップルは 'APPL'
を予約しており、アプリケーションやドライバではないプログラムがプリンタデータベースや他の
PrintingLib
コレクションに情報を保存できるようにしています。ドライバでないプログラムは、登録済みのクリエータタイプをデータの
ID
として指定してください。データの内容はフラットなコレクションでなければなりません。
|
psCountPrefsPrinters および psGetPrefsIndName
データベース内のプリンタをすべて列挙する必要がある場合、クライアントはまず
psCountPrefsPrinters()
を呼び出して、データベース内のプリンタの台数を調べなければなりません。プリンタの総数がわかったら、psGetPrefsIndName()
にインデックスを 1 からプリンタの総数まで (総数も含む)
指定して、プリンタを列挙することができます。psGetPrefsIndName()
は、インデックスで指定されたプリンタ情報コレクションからプリンタ名とゾーン名を返します注2。
long psCountPrefsPrinters(StringPtr
prefsName);
prefsName
で指定されたプリンタデータベース内のプリンタの台数を返します。
OSErr psGetPrefsIndName(StringPtr
prefsName, long index, StringPtr name, StringPtr
zone);
psGetPrefsIndName() は、prefsName
で指定されたプリンタデータベース内のプリンタ情報コレクションを列挙します。インデックスは
1 から psCountPrefsPrinters() が返す値 (その値を含む)
まででなければなりません。各インデックスについて、関数は
name にプリンタ名を zone
にプリンタゾーンを返します。関数を呼び出すときには、name と
zone は少なくとも Str32
型の文字配列を指す必要があります。クライアントは返された
name と zone で、他の SettingsLib ルーチンに渡す 'PAPA'
を構築します。
拡張 'PAPA' と SettingsLib
PrintingLib 8.5.1 は、TECHNOTE
1115「LaserWriter 8.5.1: 拡張 'PAPA'
リソース」で説明されている拡張 'PAPA'
レコードの使用をサポートします。拡張 'PAPA'
フォーマットを直接扱わなければならないクライアントの数を減らすため、SettingsLib
は拡張 'PAPA' ハンドルの作成と 'PAPA'
内のタグ付きの値の設定と参照のためのルーチンを提供します。このセクションでは、そのための
API を説明します。
psSetPapPapa、psSetInfraredPapa、psSetFilePapa、psSetHoldPapa、psSetLprPapa、psSetCustomPapa
新しい拡張 'PAPA' レコードを作成するためには、SettingsLib
クライアントは NewHandle()
で新しいレコードを割り当て、そのハンドルと PAP
プリンタ名、オブジェクトタイプ、ゾーン、オプションで
AppleTalk のアドレスブロックを各種 psSetXXXPapa()
ルーチンに渡します。メモリブロックにはそのプリンタの拡張
'PAPA' レコードが設定されます。
OSStatus psSetPapPapa(Handle papaH,
const Byte * printer, const Byte * atType, const Byte *
zone, AddrBlock *addr);
この関数は、AppleTalk の PAP プリンタの名前 (printer
が指す値)、AppleTalk デバイスタイプ (atType)、AppleTalk
ゾーン (zone) が指定されると、ハンドル papaH
の指すブロックに 'PAPA' を構築します。papaH
はメモリブロックのハンドルで、最低 103 バイト必要です。addr
は AppleTalk
アドレスブロックへのポインタです。関数呼び出し時点で addr が
NULL でないと、'PAPA'
内のプリンタ＋タイプ＋ゾーン文字列の後ろにアドレスブロックをコピーします。
addr が NULL の場合は、'PAPA'
内のアドレスにゼロを設定します。
OSStatus psSetInfraredPapa(Handle
papaH, const Byte * printer, const Byte * zone);
この関数は、ハンドル papaH
の指すメモリに赤外線プリンタを記述する拡張 'PAPA'
を設定します。printer と zone
は特定のプリンタを識別するものです。両方でプリンタデータベースに情報を保存するためのキーとして使われます。papaH
はメモリブロックのハンドルで、最低 103 バイト必要です。
OSStatus psSetFilePapa(Handle papaH,
const Byte * printer, const Byte * zone);
この関数は、ハンドル papaH
の指すメモリに「ファイルに保存」デスクトッププリンタを記述する拡張
'PAPA' を設定します。printer と zone
は特定のプリンタを識別するものです。両方でプリンタデータベースに情報を保存するためのキーとして使われます。papaH
はメモリブロックのハンドルで、最低 103 バイト必要です。
OSStatus psSetHoldPapa(Handle papaH,
const Byte * printer, const Byte * zone);
この関数は、ハンドル papaH
の指すメモリに「保留」デスクトッププリンタを記述する拡張
'PAPA' を設定します。printer と zone
は特定のプリンタを識別するものです。両方でプリンタデータベースに情報を保存するためのキーとして使われます。papaH
はメモリブロックのハンドルで、最低 103 バイト必要です。
OSStatus psSetLprPapa(Handle papaH,
const Byte * printer, const Byte * zone, const Byte *
tcpAddr, const Byte * qName);
この関数は、ハンドル papaH
の指すメモリに「lpr」デスクトッププリンタを記述する拡張
'PAPA' を設定します。printer と zone
は特定のプリンタを識別するものです。両方でプリンタデータベースに情報を保存するためのキーとして使われます。tcpAddr
は lpr プリンタのネットワークアドレスです。
このアドレスは、名前 (例えば、\plaser.rbi.com)
でもドットで区切る形式 (例えば、\p204.188.109.155)
でもかまいません。qName は tcpAddr
上のスプーラのプリントキューの名前です。qName が NULL
の場合、プリンタ／スプーラのデフォルトキューが使われます。papaH
はメモリブロックのハンドルで、最低 1024 バイト必要です。
OSStatus psSetCustomPapa(Handle
papaH, const Byte * printer, const Byte * zone);
この関数は、ハンドル papaH
の指すメモリにカスタムデスクトッププリンタを記述する拡張
'PAPA' を設定します。printer と zone
は特定のプリンタを識別するものです。両方でプリンタデータベースに情報を保存するためのキーとして使われます。papaH
はメモリブロックのハンドルで、最低 103
バイト必要です。詳細については、TECHNOTE
1113「デスクトッププリンタユーティリティのカスタマイズ」を参照してください。
psPapaToCollection および psCollectionToPapa
クライアントは、拡張 'PAPA'
レコードへのハンドルを取得すると、psPapaToCollection() と
psCollectionToPapa() ルーチンで、拡張 'PAPA'
タグブロックへアクセスと設定を行うことができます。psPapaToCollection()
ルーチンは拡張 'PAPA'
レコードとコレクションへのハンドルを取得し、拡張 'PAPA'
からタグの値をコレクションにコピーします。クライアントはこのタグの値をコレクションマネージャで列挙、変更することができます。psCollectionToPapa()
はコレクションからタグを取り出し、拡張 'PAPA'
レコードにコピーします。既存のタグはすべて置き換えます。
OSStatus psPapaToCollection(Handle
papaH, Collection coll);
psPapaToCollection() は、'PAPA' レコードへのハンドル
papaH とコレクション coll を受け取り、'PAPA' タグを持ち、ID
が拡張 'PAPA'
レコード内のタグである一連のコレクションアイテムを coll
内に作成します。例えば、拡張 'PAPA' レコード papaH に TCP
タイプのタグがあると、そのタグのデータをタグは 'PAPA'、ID は
TCP として coll にコピーします。
OSStatus
psCollectionToPapa(Collection coll, Handle
papaH);
このルーチンは、コレクション coll を受け取り、'PAPA'
タグを持つコレクションアイテムを列挙し、ハンドル papaH
の指す拡張 'PAPA'
レコードに追加します。コレクションアイテムの ID は 'PAPA'
内のタグになります。papaH の指す 'PAPA'
レコード内の既存のタグはすべて置き換えられます。全部のタグが収まらないと、エラー
errNoRoomInPapa (-8941)
が返されます。全部のタグが収まる場合は 'PAPA'
に追加されます。
psGetDTPType
クライアントが拡張 'PAPA'
を取得済みの場合、psGetDTPType() で 'PAPA'
が記述するプリンタのタイプを調べることができます。
psGetDTPType() 関数を使って、'PAPA'
ハンドルが記述するデスクトッププリンタ (DTP) は、次の
DTPType のいずれかに分類されます。
typedef enum{
kInvalidDTP = 0, // 無効な DTP タイプ
kHoldDTP = '=Hld', // 保留 DTP からプリントキューにスプールされたジョブは
// 常に保留になる
kFileDTP = '=Fil', // 「ファイルに保存」設定の DTP は印刷されない。
// PS/PDF ファイルが作成されるだけ。
kLprDTP = '=LPR', // LPR プリンタは TCP を介して LPR スプーラ／プリンタに
// 送られる
kCustomDTP = '=Cst', // カスタム DTP は PostScript の後処理のため
// アプリケーションを起動する
kPapaDTP = 'PAP ', // AppleTalk PAP ネットワークプリンタ
kInfraRedDTP = '=Ird' // 赤外線リンクで接続されたプリンタ
} DTPType;
OSStatus psGetDTPType(Handle papaH,
DTPType *dtpTypeP);
このルーチンは、有効な 'PAPA' ハンドル papaH
が指定されると DTP タイプを *dtpTypeP
に設定します。エラーが発生するとエラー値を返し、*dtpTypeP を
kInvalidDTP に設定します。
psIsValidPapaHandle
psIsValidPapaHandle()
は、デバッグ時に便利なもので、'PAPA'
ハンドルが有効かどうか調べます。'PAPA'
が無効だと思われる場合は false を返します。
Boolean psIsValidPapaHandle(Handle
papaH);
papaH が有効な 'PAPA' ハンドルに思われる場合は true
を返します。
要約
プリンタデータベースのアクセス衝突を避けるために、LaserWriter
8
ドライバの特定部分にアクセスする必要があるデベロッパは、必ずここで説明したプリンタ設定ライブラリ
(SettingsLib) を使用することをおすすめします。
参考文献
注1 SettingsLib
には影響を与えないものの、プリンタドライバに起因する 'PAPA'
の制限があります。特に「MultiFinder
Friendly」ビットに対応するため、プリンタドライバは内部の
'PAPA'
リソースのサイズを変更できません。したがって、ドライバの
'PAPA' は固定サイズです。
注2 psGetPrefsIndName()
が返す値にはネットワークオブジェクト名が抜けています。現在、すべてのプリンタデータベースエントリのネットワークオブジェクト名は
"LaserWriter"
です。将来この制約を解決する新しいルーチンが追加される予定です。
| 
