--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/cd.rst Fri Jul 31 15:01:17 2009 +0100
@@ -0,0 +1,340 @@
+
+:mod:`cd` --- CD-ROM access on SGI systems
+==========================================
+
+.. module:: cd
+ :platform: IRIX
+ :synopsis: Interface to the CD-ROM on Silicon Graphics systems.
+ :deprecated:
+
+
+.. deprecated:: 2.6
+ The :mod:`cd` module has been deprecated for removal in Python 3.0.
+
+
+This module provides an interface to the Silicon Graphics CD library. It is
+available only on Silicon Graphics systems.
+
+The way the library works is as follows. A program opens the CD-ROM device with
+:func:`open` and creates a parser to parse the data from the CD with
+:func:`createparser`. The object returned by :func:`open` can be used to read
+data from the CD, but also to get status information for the CD-ROM device, and
+to get information about the CD, such as the table of contents. Data from the
+CD is passed to the parser, which parses the frames, and calls any callback
+functions that have previously been added.
+
+An audio CD is divided into :dfn:`tracks` or :dfn:`programs` (the terms are used
+interchangeably). Tracks can be subdivided into :dfn:`indices`. An audio CD
+contains a :dfn:`table of contents` which gives the starts of the tracks on the
+CD. Index 0 is usually the pause before the start of a track. The start of the
+track as given by the table of contents is normally the start of index 1.
+
+Positions on a CD can be represented in two ways. Either a frame number or a
+tuple of three values, minutes, seconds and frames. Most functions use the
+latter representation. Positions can be both relative to the beginning of the
+CD, and to the beginning of the track.
+
+Module :mod:`cd` defines the following functions and constants:
+
+
+.. function:: createparser()
+
+ Create and return an opaque parser object. The methods of the parser object are
+ described below.
+
+
+.. function:: msftoframe(minutes, seconds, frames)
+
+ Converts a ``(minutes, seconds, frames)`` triple representing time in absolute
+ time code into the corresponding CD frame number.
+
+
+.. function:: open([device[, mode]])
+
+ Open the CD-ROM device. The return value is an opaque player object; methods of
+ the player object are described below. The device is the name of the SCSI
+ device file, e.g. ``'/dev/scsi/sc0d4l0'``, or ``None``. If omitted or ``None``,
+ the hardware inventory is consulted to locate a CD-ROM drive. The *mode*, if
+ not omitted, should be the string ``'r'``.
+
+The module defines the following variables:
+
+
+.. exception:: error
+
+ Exception raised on various errors.
+
+
+.. data:: DATASIZE
+
+ The size of one frame's worth of audio data. This is the size of the audio data
+ as passed to the callback of type ``audio``.
+
+
+.. data:: BLOCKSIZE
+
+ The size of one uninterpreted frame of audio data.
+
+The following variables are states as returned by :func:`getstatus`:
+
+
+.. data:: READY
+
+ The drive is ready for operation loaded with an audio CD.
+
+
+.. data:: NODISC
+
+ The drive does not have a CD loaded.
+
+
+.. data:: CDROM
+
+ The drive is loaded with a CD-ROM. Subsequent play or read operations will
+ return I/O errors.
+
+
+.. data:: ERROR
+
+ An error occurred while trying to read the disc or its table of contents.
+
+
+.. data:: PLAYING
+
+ The drive is in CD player mode playing an audio CD through its audio jacks.
+
+
+.. data:: PAUSED
+
+ The drive is in CD layer mode with play paused.
+
+
+.. data:: STILL
+
+ The equivalent of :const:`PAUSED` on older (non 3301) model Toshiba CD-ROM
+ drives. Such drives have never been shipped by SGI.
+
+
+.. data:: audio
+ pnum
+ index
+ ptime
+ atime
+ catalog
+ ident
+ control
+
+ Integer constants describing the various types of parser callbacks that can be
+ set by the :meth:`addcallback` method of CD parser objects (see below).
+
+
+.. _player-objects:
+
+Player Objects
+--------------
+
+Player objects (returned by :func:`open`) have the following methods:
+
+
+.. method:: CD player.allowremoval()
+
+ Unlocks the eject button on the CD-ROM drive permitting the user to eject the
+ caddy if desired.
+
+
+.. method:: CD player.bestreadsize()
+
+ Returns the best value to use for the *num_frames* parameter of the
+ :meth:`readda` method. Best is defined as the value that permits a continuous
+ flow of data from the CD-ROM drive.
+
+
+.. method:: CD player.close()
+
+ Frees the resources associated with the player object. After calling
+ :meth:`close`, the methods of the object should no longer be used.
+
+
+.. method:: CD player.eject()
+
+ Ejects the caddy from the CD-ROM drive.
+
+
+.. method:: CD player.getstatus()
+
+ Returns information pertaining to the current state of the CD-ROM drive. The
+ returned information is a tuple with the following values: *state*, *track*,
+ *rtime*, *atime*, *ttime*, *first*, *last*, *scsi_audio*, *cur_block*. *rtime*
+ is the time relative to the start of the current track; *atime* is the time
+ relative to the beginning of the disc; *ttime* is the total time on the disc.
+ For more information on the meaning of the values, see the man page
+ :manpage:`CDgetstatus(3dm)`. The value of *state* is one of the following:
+ :const:`ERROR`, :const:`NODISC`, :const:`READY`, :const:`PLAYING`,
+ :const:`PAUSED`, :const:`STILL`, or :const:`CDROM`.
+
+
+.. method:: CD player.gettrackinfo(track)
+
+ Returns information about the specified track. The returned information is a
+ tuple consisting of two elements, the start time of the track and the duration
+ of the track.
+
+
+.. method:: CD player.msftoblock(min, sec, frame)
+
+ Converts a minutes, seconds, frames triple representing a time in absolute time
+ code into the corresponding logical block number for the given CD-ROM drive.
+ You should use :func:`msftoframe` rather than :meth:`msftoblock` for comparing
+ times. The logical block number differs from the frame number by an offset
+ required by certain CD-ROM drives.
+
+
+.. method:: CD player.play(start, play)
+
+ Starts playback of an audio CD in the CD-ROM drive at the specified track. The
+ audio output appears on the CD-ROM drive's headphone and audio jacks (if
+ fitted). Play stops at the end of the disc. *start* is the number of the track
+ at which to start playing the CD; if *play* is 0, the CD will be set to an
+ initial paused state. The method :meth:`togglepause` can then be used to
+ commence play.
+
+
+.. method:: CD player.playabs(minutes, seconds, frames, play)
+
+ Like :meth:`play`, except that the start is given in minutes, seconds, and
+ frames instead of a track number.
+
+
+.. method:: CD player.playtrack(start, play)
+
+ Like :meth:`play`, except that playing stops at the end of the track.
+
+
+.. method:: CD player.playtrackabs(track, minutes, seconds, frames, play)
+
+ Like :meth:`play`, except that playing begins at the specified absolute time and
+ ends at the end of the specified track.
+
+
+.. method:: CD player.preventremoval()
+
+ Locks the eject button on the CD-ROM drive thus preventing the user from
+ arbitrarily ejecting the caddy.
+
+
+.. method:: CD player.readda(num_frames)
+
+ Reads the specified number of frames from an audio CD mounted in the CD-ROM
+ drive. The return value is a string representing the audio frames. This string
+ can be passed unaltered to the :meth:`parseframe` method of the parser object.
+
+
+.. method:: CD player.seek(minutes, seconds, frames)
+
+ Sets the pointer that indicates the starting point of the next read of digital
+ audio data from a CD-ROM. The pointer is set to an absolute time code location
+ specified in *minutes*, *seconds*, and *frames*. The return value is the
+ logical block number to which the pointer has been set.
+
+
+.. method:: CD player.seekblock(block)
+
+ Sets the pointer that indicates the starting point of the next read of digital
+ audio data from a CD-ROM. The pointer is set to the specified logical block
+ number. The return value is the logical block number to which the pointer has
+ been set.
+
+
+.. method:: CD player.seektrack(track)
+
+ Sets the pointer that indicates the starting point of the next read of digital
+ audio data from a CD-ROM. The pointer is set to the specified track. The
+ return value is the logical block number to which the pointer has been set.
+
+
+.. method:: CD player.stop()
+
+ Stops the current playing operation.
+
+
+.. method:: CD player.togglepause()
+
+ Pauses the CD if it is playing, and makes it play if it is paused.
+
+
+.. _cd-parser-objects:
+
+Parser Objects
+--------------
+
+Parser objects (returned by :func:`createparser`) have the following methods:
+
+
+.. method:: CD parser.addcallback(type, func, arg)
+
+ Adds a callback for the parser. The parser has callbacks for eight different
+ types of data in the digital audio data stream. Constants for these types are
+ defined at the :mod:`cd` module level (see above). The callback is called as
+ follows: ``func(arg, type, data)``, where *arg* is the user supplied argument,
+ *type* is the particular type of callback, and *data* is the data returned for
+ this *type* of callback. The type of the data depends on the *type* of callback
+ as follows:
+
+ +-------------+---------------------------------------------+
+ | Type | Value |
+ +=============+=============================================+
+ | ``audio`` | String which can be passed unmodified to |
+ | | :func:`al.writesamps`. |
+ +-------------+---------------------------------------------+
+ | ``pnum`` | Integer giving the program (track) number. |
+ +-------------+---------------------------------------------+
+ | ``index`` | Integer giving the index number. |
+ +-------------+---------------------------------------------+
+ | ``ptime`` | Tuple consisting of the program time in |
+ | | minutes, seconds, and frames. |
+ +-------------+---------------------------------------------+
+ | ``atime`` | Tuple consisting of the absolute time in |
+ | | minutes, seconds, and frames. |
+ +-------------+---------------------------------------------+
+ | ``catalog`` | String of 13 characters, giving the catalog |
+ | | number of the CD. |
+ +-------------+---------------------------------------------+
+ | ``ident`` | String of 12 characters, giving the ISRC |
+ | | identification number of the recording. |
+ | | The string consists of two characters |
+ | | country code, three characters owner code, |
+ | | two characters giving the year, and five |
+ | | characters giving a serial number. |
+ +-------------+---------------------------------------------+
+ | ``control`` | Integer giving the control bits from the CD |
+ | | subcode data |
+ +-------------+---------------------------------------------+
+
+
+.. method:: CD parser.deleteparser()
+
+ Deletes the parser and frees the memory it was using. The object should not be
+ used after this call. This call is done automatically when the last reference
+ to the object is removed.
+
+
+.. method:: CD parser.parseframe(frame)
+
+ Parses one or more frames of digital audio data from a CD such as returned by
+ :meth:`readda`. It determines which subcodes are present in the data. If these
+ subcodes have changed since the last frame, then :meth:`parseframe` executes a
+ callback of the appropriate type passing to it the subcode data found in the
+ frame. Unlike the C function, more than one frame of digital audio data can be
+ passed to this method.
+
+
+.. method:: CD parser.removecallback(type)
+
+ Removes the callback for the given *type*.
+
+
+.. method:: CD parser.resetparser()
+
+ Resets the fields of the parser used for tracking subcodes to an initial state.
+ :meth:`resetparser` should be called after the disc has been changed.
+