\section{\module{cd} ---
SGIシステムのCD-ROMへのアクセス}

\declaremodule{builtin}{cd}
  \platform{IRIX}
\modulesynopsis{
Silicon GraphicsシステムのCD-ROMへのインターフェース}


このモジュールはSilicon Graphics CD ライブラリへのインターフェースを提供
します。
Silicon Graphics システムだけで利用可能です。

ライブラリは以下のように使われます。

CD-ROMデバイスを\function{open()}で開き、
\function{createparser()}でCDからデータをパースするためのパーザを作りま
す。
\function{open()}で返されるオブジェクトはCDからデータを読み込むのに使わ
れますが、CD-ROMデバイスのステータス情報や、CDの情報、たとえば目次などを
得るのにも使われます。
CDから得たデータはパーザに渡され、パーザはフレームをパースし、あらかじめ
加えられたコールバック関数を呼び出します。

オーディオCDはトラック\dfn{tracks}あるいはプログラム\dfn{programs}（同じ
意味で、どちらかの用語が使われます）に分けられます。
トラックはさらにインデックス\dfn{indices}に分けられます。
オーディオCDは、CD上の各トラックのスタート位置を示す
目次\dfn{table of contents}を持っています。
インデックス0は普通、トラックの始まりの前のポーズです。
目次から得られるトラックのスタート位置は通常、インデックス1のスタート位
置です。

CD上の位置は2通りの方法で得ることができます。
それはフレームナンバーと、分、秒、フレームの3つの値からなるタプ
ルの2つです。
ほとんどの関数は後者を使います。
位置はCDの開始位置とトラックの開始位置の両方に相対的になります。

モジュール\module{cd}は、以下の関数と定数を定義しています：

\begin{funcdesc}{createparser}{}
不透明なパーザオブジェクトを作って返します。
パーザオブジェクトのメソッドは下に記載されています。
\end{funcdesc}

\begin{funcdesc}{msftoframe}{minutes, seconds, frames}
絶対的なタイムコードである\code{(\var{minutes}, \var{seconds}, 
\var{frames})}の3つ組の表現を、相当するCDのフレームナンバーに変換しま
す。
\end{funcdesc}

\begin{funcdesc}{open}{\optional{device\optional{, mode}}}
CD-ROMデバイスを開きます。
不透明なプレーヤーオブジェクトを返します；
プレーヤーオブジェクトのメソッドは下に記載されています。
デバイス\var{device}はSCSIデバイスファイルの名前で、例えば
\code{'/dev/scsi/sc0d4l0'}あるいは\code{None}です。
もし省略したり、\code{None}なら、ハードウエアが検索されてCD-ROMデバイス
を割り当てます。
\var{mode}は、省略しないなら\code{'r'}にすべきです。
\end{funcdesc}

このモジュールでは以下の変数を定義しています：

\begin{excdesc}{error}
様々なエラーについて発生する例外です。
\end{excdesc}

\begin{datadesc}{DATASIZE}
オーディオデータの1フレームのサイズです。
これは\code{audio}タイプのコールバックへ渡されるオーディオデータのサイ
ズです。
\end{datadesc}

\begin{datadesc}{BLOCKSIZE}
オーディオデータが読み取られていないフレーム1つのサイズです。
\end{datadesc}

以下の変数は\function{getstatus()}で返されるステータス情報です：

\begin{datadesc}{READY}
オーディオCDがロードされて、ドライブが操作可能であることを示します。
\end{datadesc}

\begin{datadesc}{NODISC}
ドライブにCDがロードされていないことを示します。
\end{datadesc}

\begin{datadesc}{CDROM}
ドライブにCD-ROMがロードされていることを示します。
続いてplayあるいはreadの操作をすると、I/Oエラーを返します。
\end{datadesc}

\begin{datadesc}{ERROR}
ディスクや目次を読み込もうとしているときに起こるエラー。
\end{datadesc}

\begin{datadesc}{PLAYING}
ドライブがオーディオCDをCDプレーヤーモードでオーディオ端子から再生
していることを示します。
\end{datadesc}

\begin{datadesc}{PAUSED}
ドライブがCDプレーヤーモードで、再生を一時停止していることを示します。
\end{datadesc}

\begin{datadesc}{STILL}
\constant{PAUSED}と同じですが、古いモデル（non 3301）である
Toshiba CD-ROMドライブのものです。
このドライブはもうSGIから出荷されていません。
\end{datadesc}

\begin{datadesc}{audio}
\dataline{pnum}
\dataline{index}
\dataline{ptime}
\dataline{atime}
\dataline{catalog}
\dataline{ident}
\dataline{control}
これらは整数の定数で、パーザのいろいろなタイプのコールバックを示していま
す。コールバックはCDパーザオブジェクトの\method{addcallback()}で設定でき
ます（下記参照）。
\end{datadesc}


\subsection{
プレーヤーオブジェクト}
\label{player-objects}

プレーヤーオブジェクト（\function{open()}で返されます）には以下のメソッ
ドがあります：

\begin{methoddesc}[CD player]{allowremoval}{}
CD-ROMドライブのイジェクトボタンのロックを解除して、ユーザがCDキャディを
排出するのを許可します。
\end{methoddesc}

\begin{methoddesc}[CD player]{bestreadsize}{}
メソッド\method{readda()}のパラメータ\var{num_frames}として最適の値を返
します。
最適値はCD-ROMドライブからの連続したデータフローが許可される値が定義され
ます。
\end{methoddesc}

\begin{methoddesc}[CD player]{close}{}
プレーヤーオブジェクトと関連付けられたリソースを解放します。
\method{close()}を呼び出したあとでは、そのオブジェクトに対するメソッドは
使用できません。
\end{methoddesc}

\begin{methoddesc}[CD player]{eject}{}
CD-ROMドライブからキャディを排出します。
\end{methoddesc}

\begin{methoddesc}[CD player]{getstatus}{}
CD-ROMドライブの現在の状態に関する情報を返します。
返される情報は以下の値からなるタプルです：
\var{state}、\var{track}、\var{rtime}、\var{atime}、\var{ttime}、
\var{first}、\var{last}、\var{scsi_audio}、\var{cur_block}。
\var{rtime}は現在のトラックの初めからの相対的な時間；
\var{atime}はディスクの初めからの相対的な時間；
\var{ttime}はディスクの全時間です。
それぞれの値の詳細については、マニュアルページ
\manpage{CDgetstatus}{3dm}を参照してください。
\var{state}の値は以下のうちのどれか一つです：
\constant{ERROR}、\constant{NODISC}、\constant{READY}、
\constant{PLAYING}、\constant{PAUSED}、\constant{STILL}、
\constant{CDROM}。
\end{methoddesc}

\begin{methoddesc}[CD player]{gettrackinfo}{track}
特定のトラックについての情報を返します。
返される情報は、トラックの開始時刻とトラックの時間の長さの二つの要素から
なるタプルです。
\end{methoddesc}

\begin{methoddesc}[CD player]{msftoblock}{min, sec, frame}
分、秒、フレームの3つからなる絶対的なタイムコードを、与えられたCD-ROMド
ライブの相当する論理ブロック番号に変換します。
時刻を比較するには\method{msftoblock()}よりも\function{msftoframe()}を
使うべきです。
論理ブロック番号は、CD-ROMドライブによって必要とされるオフセット値が違う
ため、フレームナンバーと異なります。
\end{methoddesc}

\begin{methoddesc}[CD player]{play}{start, play}
CD-ROMドライブのオーディオCDの特定のトラックから再生を開始します。
CD-ROMドライブのヘッドフォン端子と（備えているなら）オーディオ端子から出
力されます。
ディスクの最後で再生は停止します。
\var{start}は再生を開始するCDのトラックナンバーです；
\var{play}が0なら、CDは最初の一時停止状態になります。
その状態からメソッド\method{togglepause()}で再生を開始できます。
\end{methoddesc}

\begin{methoddesc}[CD player]{playabs}{minutes, seconds, frames, play}
\method{play()}と似ていますが、開始位置をトラックナンバーの代わりに分、
秒、フレームで与えます。
\end{methoddesc}

\begin{methoddesc}[CD player]{playtrack}{start, play}
\method{play()}と似ていますが、トラックの終わりで再生を停止します。
\end{methoddesc}

\begin{methoddesc}[CD player]{playtrackabs}{track, minutes, seconds, frames, play}
\method{play()}と似ていますが、指定した絶対的な時刻から再生を開始して、
指定したトラックで終了します。
\end{methoddesc}

\begin{methoddesc}[CD player]{preventremoval}{}
CD-ROMドライブのイジェクトボタンをロックして、ユーザがCDキャディを排出で
きないようにします。
\end{methoddesc}

\begin{methoddesc}[CD player]{readda}{num_frames}
CD-ROMドライブにマウントされたオーディオCDから、指定したフレーム数を読み
込みます。
オーディオフレームのデータを示す文字列を返します。
この文字列はそのままパーザオブジェクトのメソッド\method{parseframe()}へ
渡すことができます。
\end{methoddesc}

\begin{methoddesc}[CD player]{seek}{minutes, seconds, frames}
CD-ROMから次にデジタルオーディオデータを読み込む開始位置のポインタを設定
します。
ポインタは\var{minutes}、\var{seconds}、\var{frames}で指定した絶対的なタ
イムコードの位置に設定されます。
返される値はポインタが設定された論理ブロック番号です。
\end{methoddesc}

\begin{methoddesc}[CD player]{seekblock}{block}
CD-ROMから次にデジタルオーディオデータを読み込む開始位置のポインタを設定
します。
ポインタは指定した論理ブロック番号に設定されます。
返される値はポインタが設定された論理ブロック番号です。
\end{methoddesc}

\begin{methoddesc}[CD player]{seektrack}{track}
CD-ROMから次にデジタルオーディオデータを読み込む開始位置のポインタを設定
します。
ポインタは指定したトラックに設定されます。
返される値はポインタが設定された論理ブロック番号です。
\end{methoddesc}

\begin{methoddesc}[CD player]{stop}{}
現在実行中の再生を停止します。
\end{methoddesc}

\begin{methoddesc}[CD player]{togglepause}{}
再生中ならCDを一時停止し、一時停止中なら再生します。
\end{methoddesc}


\subsection{パーザオブジェクト}
\label{cd-parser-objects}

パーザオブジェクト（\function{createparser()}で返されます）には以下のメ
ソッドがあります：

\begin{methoddesc}[CD parser]{addcallback}{type, func, arg}
パーザにコールバックを加えます。
デジタルオーディオストリームの8つの異なるデータタイプのためのコールバッ
クをパーザは持っています。
これらのタイプのための定数は\module{cd}モジュールのレベルで定義されてい
ます（上記参照）。
コールバックは以下のように呼び出されます：
\code{\var{func}(\var{arg}, type, data)}、ここで\var{arg}はユーザが与え
た引数、\var{type}はコールバックの特定のタイプ、\var{data}はこの
\var{type}のコールバックに渡されるデータです。
データのタイプは以下のようにコールバックのタイプによって決まります：

\begin{tableii}{l|p{4in}}{code}{Type}{Value}
  \lineii{audio}{
\function{al.writesamps()}へそのまま渡すことのできる文字列。}
  \lineii{pnum}{
プログラム（トラック）ナンバーを示す整数。}
  \lineii{index}{
インデックスナンバーを示す整数。}
  \lineii{ptime}{
プログラムの時間を示す分、秒、フレームからなるタプル。}
  \lineii{atime}{
絶対的な時刻を示す分、秒、フレームからなるタプル。}
  \lineii{catalog}{
CDのカタログナンバーを示す13文字の文字列。}
  \lineii{ident}{
録音のISRC識別番号を示す12文字の文字列。
文字列は2文字の国別コード、3文字の所有者コード、2文字の年号、5文字のシリ
アルナンバーからなります。}
  \lineii{control}{
CDのサブコードデータのコントロールビットを示す整数。}
\end{tableii}
\end{methoddesc}

\begin{methoddesc}[CD parser]{deleteparser}{}
パーザを消去して、使用していたメモリを解放します。
この呼び出しのあと、オブジェクトは使用できません。
オブジェクトへの最後の参照が削除されると、自動的にこのメソッドが呼び出さ
れます。
\end{methoddesc}

\begin{methoddesc}[CD parser]{parseframe}{frame}
\method{readda()}などから返されたデジタルオーディオCDのデータの1つあるい
はそれ以上のフレームをパースします。
データ内にどういうサブコードがあるかを決定します。
その前のフレームからサブコードが変化していたら、\method{parseframe()}
は対応するタイプのコールバックを起動して、フレーム内のサブコードデータを
コールバックに渡します。
\C{}の関数とは違って、1つ以上のデジタルオーディオデータのフレームをこの
メソッドに渡すことができます。
\end{methoddesc}

\begin{methoddesc}[CD parser]{removecallback}{type}
指定した\var{type}のコールバックを削除します。
\end{methoddesc}

\begin{methoddesc}[CD parser]{resetparser}{}
サブコードを追跡しているパーザのフィールドをリセットして、初期状態にしま
す。
ディスクを交換したあと、\method{resetparser()}を呼び出さなければなりませ
ん。
\end{methoddesc}