iokit/IOKit/storage/IOCDMedia.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22
  23 /*!
  24  * @header IOCDMedia
  25  * @abstract
  26  * This header contains the IOCDMedia class definition.
  27  */
  28
  29 #ifndef _IOCDMEDIA_H
  30 #define _IOCDMEDIA_H
  31
  32 /*!
  33  * @defined kIOCDMediaClass
  34  * @abstract
  35  * kIOCDMediaClass is the name of the IOCDMedia class.
  36  * @discussion
  37  * kIOCDMediaClass is the name of the IOCDMedia class.
  38  */
  39
  40 #define kIOCDMediaClass "IOCDMedia"
  41
  42 /*!
  43  * @defined kIOCDMediaTOCKey
  44  * @abstract
  45  * kIOCDMediaTOCKey is a property of IOCDMedia objects.  It has an OSData value
  46  * and a CDTOC structure.
  47  * @discussion
  48  * The kIOCDMediaTOCKey property contains the CD's full table of contents,
  49  * formatted as a CDTOC structure.  The CDTOC structure is same as what is
  50  * returned by a READ TOC command, format 0x02, but with BCD numbers converted
  51  * to binary-encoded numbers, and the multi-byte fields converted to
  52  * host-endianess.
  53  */
  54
  55 #define kIOCDMediaTOCKey "TOC"
  56 #define kIOCDMediaTOC "TOC" ///d:deprecated
  57
  58 /*!
  59  * @defined kIOCDMediaTypeKey
  60  * @abstract
  61  * kIOCDMediaTypeKey is a property of IOCDMedia objects.  It has an OSString
  62  * value.
  63  * @discussion
  64  * The kIOCDMediaTypeKey property identifies the CD media type (CD-ROM, CD-R,
  65  * CD-RW, etc).  See the kIOCDMediaType contants for possible values.
  66  */
  67
  68 #define kIOCDMediaTypeKey "Type"
  69
  70 /*!
  71  * @defined kIOCDMediaTypeROM
  72  * The kIOCDMediaTypeKey constant for CD-ROM media (inclusive of the CD-I,
  73  * CD-ROM XA, and CD Audio standards, and mixed mode combinations thereof).
  74  */
  75
  76 #define kIOCDMediaTypeROM "CD-ROM"
  77
  78 /*!
  79  * @defined kIOCDMediaTypeR
  80  * The kIOCDMediaTypeKey constant for CD Recordable (CD-R) media.
  81  */
  82
  83 #define kIOCDMediaTypeR "CD-R"
  84
  85 /*!
  86  * @defined kIOCDMediaTypeRW
  87  * The kIOCDMediaTypeKey constant for CD ReWritable (CD-RW) media.
  88  */
  89
  90 #define kIOCDMediaTypeRW "CD-RW"
  91
  92 /*
  93  * Kernel
  94  */
  95
  96 #if defined(KERNEL) && defined(__cplusplus)
  97
  98 #include <IOKit/storage/IOCDBlockStorageDriver.h>
  99 #include <IOKit/storage/IOMedia.h>
 100
 101 /*!
 102  * @class IOCDMedia
 103  * @abstract
 104  * The IOCDMedia class is a random-access disk device abstraction for CDs.
 105  * @discussion
 106  * The IOCDMedia class is a random-access disk device abstraction for CDs. It
 107  * extends the IOMedia class by implementing special CD APIs, such as readCD,
 108  * and publishing the TOC as a property of the IOCDMedia object.
 109  */
 110
 111 class IOCDMedia : public IOMedia
 112 {
 113     OSDeclareDefaultStructors(IOCDMedia)
 114
 115 protected:
 116
 117     struct ExpansionData { /* */ };
 118     ExpansionData * _expansionData;
 119
 120 public:
 121
 122 ///m:2333367:workaround:commented:start
 123 //  using read;
 124 ///m:2333367:workaround:commented:stop
 125
 126     /*!
 127      * @function read
 128      * @discussion
 129      * Read data from the storage object at the specified byte offset into the
 130      * specified buffer, asynchronously.   When the read completes, the caller
 131      * will be notified via the specified completion action.
 132      *
 133      * The buffer will be retained for the duration of the read.
 134      * @param client
 135      * Client requesting the read.
 136      * @param byteStart
 137      * Starting byte offset for the data transfer.
 138      * @param buffer
 139      * Buffer for the data transfer.  The size of the buffer implies the size of
 140      * the data transfer.
 141      * @param completion
 142      * Completion routine to call once the data transfer is complete.
 143      */
 144
 145     virtual void read(IOService *          client,
 146                       UInt64               byteStart,
 147                       IOMemoryDescriptor * buffer,
 148                       IOStorageCompletion  completion);
 149
 150     /*!
 151      * @function readCD
 152      * @discussion
 153      * Read data from the CD media object at the specified byte offset into the
 154      * specified buffer, asynchronously.  Special areas of the CD sector can be
 155      * read via this method, such as the header and subchannel data.   When the
 156      * read completes, the caller will be notified via the specified completion
 157      * action.
 158      *
 159      * The buffer will be retained for the duration of the read.
 160      * @param client
 161      * Client requesting the read.
 162      * @param byteStart
 163      * Starting byte offset for the data transfer (see withAreas parameter).
 164      * @param buffer
 165      * Buffer for the data transfer.  The size of the buffer implies the size of
 166      * the data transfer.
 167      * @param sectorArea
 168      * Sector area(s) to read.  The sum of each area's size defines the "natural
 169      * block size" of the media for the call, which should be taken into account
 170      * when computing the address of byteStart.  See IOCDTypes.h.
 171      * @param sectorType
 172      * Sector type that is expected.  The data transfer is terminated as soon as
 173      * data is encountered that does not match the expected type.
 174      * @param completion
 175      * Completion routine to call once the data transfer is complete.
 176      */
 177
 178     virtual void readCD(IOService *          client,
 179                         UInt64               byteStart,
 180                         IOMemoryDescriptor * buffer,
 181                         CDSectorArea         sectorArea,
 182                         CDSectorType         sectorType,
 183                         IOStorageCompletion  completion);
 184
 185     /*!
 186      * @function readCD
 187      * @discussion
 188      * Read data from the CD media object at the specified byte offset into the
 189      * specified buffer, synchronously.   Special areas of the CD sector can be
 190      * read via this method, such as the header and subchannel data.   When the
 191      * read completes, this method will return to the caller.   The actual byte
 192      * count field is optional.
 193      * @param client
 194      * Client requesting the read.
 195      * @param byteStart
 196      * Starting byte offset for the data transfer.
 197      * @param buffer
 198      * Buffer for the data transfer.  The size of the buffer implies the size of
 199      * the data transfer.
 200      * @param sectorArea
 201      * Sector area(s) to read.  The sum of each area's size defines the "natural
 202      * block size" of the media for the call, which should be taken into account
 203      * when computing the address of byteStart.  See IOCDTypes.h.
 204      * @param sectorType
 205      * Sector type that is expected.  The data transfer is terminated as soon as
 206      * data is encountered that does not match the expected type.
 207      * @param actualByteCount
 208      * Returns the actual number of bytes transferred in the data transfer.
 209      * @result
 210      * Returns the status of the data transfer.
 211      */
 212
 213     virtual IOReturn readCD(IOService *          client,
 214                             UInt64               byteStart,
 215                             IOMemoryDescriptor * buffer,
 216                             CDSectorArea         sectorArea,
 217                             CDSectorType         sectorType,
 218                             UInt64 *             actualByteCount = 0);
 219
 220     /*!
 221      * @function readISRC
 222      * @abstract
 223      * Read the International Standard Recording Code for the specified track.
 224      * @param track
 225      * The track number from which to read the ISRC.
 226      * @param isrc
 227      * The buffer for the ISRC data.  Buffer contents will be zero-terminated.
 228      */
 229
 230     virtual IOReturn readISRC(UInt8 track, CDISRC isrc);
 231
 232     /*!
 233      * @function readMCN
 234      * @abstract
 235      * Read the Media Catalog Number (also known as the Universal Product Code).
 236      * @param mcn
 237      * The buffer for the MCN data.  Buffer contents will be zero-terminated.
 238      */
 239
 240     virtual IOReturn readMCN(CDMCN mcn);
 241
 242     /*
 243      * @function getTOC
 244      * @discussion
 245      * Get the full Table Of Contents.
 246      *
 247      * All CDTOC fields passed across I/O Kit APIs are guaranteed to be
 248      * binary-encoded numbers (not BCD) and converted to host-endianess.
 249      * @result
 250      * Returns a pointer to the TOC buffer (do not deallocate).
 251      */
 252
 253     virtual CDTOC * getTOC();
 254
 255     /*
 256      * Obtain this object's provider.  We override the superclass's method to
 257      * return a more specific subclass of IOService -- IOCDBlockStorageDriver.
 258      * This method serves simply as a convenience to subclass developers.
 259      */
 260
 261     virtual IOCDBlockStorageDriver * getProvider() const;
 262
 263     OSMetaClassDeclareReservedUnused(IOCDMedia,  0);
 264     OSMetaClassDeclareReservedUnused(IOCDMedia,  1);
 265     OSMetaClassDeclareReservedUnused(IOCDMedia,  2);
 266     OSMetaClassDeclareReservedUnused(IOCDMedia,  3);
 267     OSMetaClassDeclareReservedUnused(IOCDMedia,  4);
 268     OSMetaClassDeclareReservedUnused(IOCDMedia,  5);
 269     OSMetaClassDeclareReservedUnused(IOCDMedia,  6);
 270     OSMetaClassDeclareReservedUnused(IOCDMedia,  7);
 271     OSMetaClassDeclareReservedUnused(IOCDMedia,  8);
 272     OSMetaClassDeclareReservedUnused(IOCDMedia,  9);
 273     OSMetaClassDeclareReservedUnused(IOCDMedia, 10);
 274     OSMetaClassDeclareReservedUnused(IOCDMedia, 11);
 275     OSMetaClassDeclareReservedUnused(IOCDMedia, 12);
 276     OSMetaClassDeclareReservedUnused(IOCDMedia, 13);
 277     OSMetaClassDeclareReservedUnused(IOCDMedia, 14);
 278     OSMetaClassDeclareReservedUnused(IOCDMedia, 15);
 279 };
 280
 281 #endif /* defined(KERNEL) && defined(__cplusplus) */
 282
 283 #endif /* !_IOCDMEDIA_H */