[apple/xnu.git] / iokit / IOKit / storage / IOCDMedia.h

/*
 * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * The contents of this file constitute Original Code as defined in and
 * are subject to the Apple Public Source License Version 1.1 (the
 * "License").  You may not use this file except in compliance with the
 * License.  Please obtain a copy of the License at
 * http://www.apple.com/publicsource and read it before using this file.
 * 
 * This Original Code and all software distributed under the License are
 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
 * License for the specific language governing rights and limitations
 * under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */

/*!
 * @header IOCDMedia
 * @abstract
 * This header contains the IOCDMedia class definition.
 */

#ifndef _IOCDMEDIA_H
#define _IOCDMEDIA_H

/*!
 * @defined kIOCDMediaClass
 * @abstract
 * kIOCDMediaClass is the name of the IOCDMedia class.
 * @discussion
 * kIOCDMediaClass is the name of the IOCDMedia class.
 */

#define kIOCDMediaClass "IOCDMedia"

/*!
 * @defined kIOCDMediaTOCKey
 * @abstract
 * kIOCDMediaTOCKey is a property of IOCDMedia objects.  It has an OSData value
 * and a CDTOC structure.
 * @discussion
 * The kIOCDMediaTOCKey property contains the CD's full table of contents,
 * formatted as a CDTOC structure.  The CDTOC structure is same as what is
 * returned by a READ TOC command, format 0x02, but with BCD numbers converted
 * to binary-encoded numbers, and the multi-byte fields converted to
 * host-endianess.
 */

#define kIOCDMediaTOCKey "TOC"
#define kIOCDMediaTOC "TOC" ///d:deprecated

/*!
 * @defined kIOCDMediaTypeKey
 * @abstract
 * kIOCDMediaTypeKey is a property of IOCDMedia objects.  It has an OSString
 * value.
 * @discussion
 * The kIOCDMediaTypeKey property identifies the CD media type (CD-ROM, CD-R,
 * CD-RW, etc).  See the kIOCDMediaType contants for possible values.
 */

#define kIOCDMediaTypeKey "Type"

/*!
 * @defined kIOCDMediaTypeROM
 * The kIOCDMediaTypeKey constant for CD-ROM media (inclusive of the CD-I,
 * CD-ROM XA, and CD Audio standards, and mixed mode combinations thereof).
 */

#define kIOCDMediaTypeROM "CD-ROM"

/*!
 * @defined kIOCDMediaTypeR
 * The kIOCDMediaTypeKey constant for CD Recordable (CD-R) media.
 */

#define kIOCDMediaTypeR "CD-R"

/*!
 * @defined kIOCDMediaTypeRW
 * The kIOCDMediaTypeKey constant for CD ReWritable (CD-RW) media.
 */

#define kIOCDMediaTypeRW "CD-RW"

/*
 * Kernel
 */

#if defined(KERNEL) && defined(__cplusplus)

#include <IOKit/storage/IOCDBlockStorageDriver.h>
#include <IOKit/storage/IOMedia.h>

/*!
 * @class IOCDMedia
 * @abstract
 * The IOCDMedia class is a random-access disk device abstraction for CDs.
 * @discussion
 * The IOCDMedia class is a random-access disk device abstraction for CDs. It
 * extends the IOMedia class by implementing special CD APIs, such as readCD,
 * and publishing the TOC as a property of the IOCDMedia object.
 */

class IOCDMedia : public IOMedia
{
    OSDeclareDefaultStructors(IOCDMedia)

protected:

    struct ExpansionData { /* */ };
    ExpansionData * _expansionData;

public:

///m:2333367:workaround:commented:start
//  using read;
///m:2333367:workaround:commented:stop

    /*!
     * @function read
     * @discussion
     * Read data from the storage object at the specified byte offset into the
     * specified buffer, asynchronously.   When the read completes, the caller
     * will be notified via the specified completion action.
     *
     * The buffer will be retained for the duration of the read.
     * @param client
     * Client requesting the read.
     * @param byteStart
     * Starting byte offset for the data transfer.
     * @param buffer
     * Buffer for the data transfer.  The size of the buffer implies the size of
     * the data transfer.
     * @param completion
     * Completion routine to call once the data transfer is complete.
     */

    virtual void read(IOService *          client,
                      UInt64               byteStart,
                      IOMemoryDescriptor * buffer,
                      IOStorageCompletion  completion);

    /*!
     * @function readCD
     * @discussion
     * Read data from the CD media object at the specified byte offset into the
     * specified buffer, asynchronously.  Special areas of the CD sector can be
     * read via this method, such as the header and subchannel data.   When the
     * read completes, the caller will be notified via the specified completion
     * action.
     *
     * The buffer will be retained for the duration of the read.
     * @param client
     * Client requesting the read.
     * @param byteStart
     * Starting byte offset for the data transfer (see withAreas parameter).
     * @param buffer
     * Buffer for the data transfer.  The size of the buffer implies the size of
     * the data transfer.
     * @param sectorArea
     * Sector area(s) to read.  The sum of each area's size defines the "natural
     * block size" of the media for the call, which should be taken into account
     * when computing the address of byteStart.  See IOCDTypes.h.
     * @param sectorType
     * Sector type that is expected.  The data transfer is terminated as soon as
     * data is encountered that does not match the expected type.
     * @param completion
     * Completion routine to call once the data transfer is complete.
     */

    virtual void readCD(IOService *          client,
                        UInt64               byteStart,
                        IOMemoryDescriptor * buffer,
                        CDSectorArea         sectorArea,
                        CDSectorType         sectorType,
                        IOStorageCompletion  completion);

    /*!
     * @function readCD
     * @discussion
     * Read data from the CD media object at the specified byte offset into the
     * specified buffer, synchronously.   Special areas of the CD sector can be
     * read via this method, such as the header and subchannel data.   When the
     * read completes, this method will return to the caller.   The actual byte
     * count field is optional.
     * @param client
     * Client requesting the read.
     * @param byteStart
     * Starting byte offset for the data transfer.
     * @param buffer
     * Buffer for the data transfer.  The size of the buffer implies the size of
     * the data transfer.
     * @param sectorArea
     * Sector area(s) to read.  The sum of each area's size defines the "natural
     * block size" of the media for the call, which should be taken into account
     * when computing the address of byteStart.  See IOCDTypes.h.
     * @param sectorType
     * Sector type that is expected.  The data transfer is terminated as soon as
     * data is encountered that does not match the expected type.
     * @param actualByteCount
     * Returns the actual number of bytes transferred in the data transfer.
     * @result
     * Returns the status of the data transfer.
     */

    virtual IOReturn readCD(IOService *          client,
                            UInt64               byteStart,
                            IOMemoryDescriptor * buffer,
                            CDSectorArea         sectorArea,
                            CDSectorType         sectorType,
                            UInt64 *             actualByteCount = 0);

    /*!
     * @function readISRC
     * @abstract
     * Read the International Standard Recording Code for the specified track.
     * @param track
     * The track number from which to read the ISRC.
     * @param isrc
     * The buffer for the ISRC data.  Buffer contents will be zero-terminated.
     */

    virtual IOReturn readISRC(UInt8 track, CDISRC isrc);
    
    /*!
     * @function readMCN
     * @abstract
     * Read the Media Catalog Number (also known as the Universal Product Code).
     * @param mcn
     * The buffer for the MCN data.  Buffer contents will be zero-terminated.
     */

    virtual IOReturn readMCN(CDMCN mcn);

    /*
     * @function getTOC
     * @discussion
     * Get the full Table Of Contents.
     *
     * All CDTOC fields passed across I/O Kit APIs are guaranteed to be
     * binary-encoded numbers (not BCD) and converted to host-endianess.
     * @result
     * Returns a pointer to the TOC buffer (do not deallocate).
     */
     
    virtual CDTOC * getTOC();

    /*
     * Obtain this object's provider.  We override the superclass's method to
     * return a more specific subclass of IOService -- IOCDBlockStorageDriver.  
     * This method serves simply as a convenience to subclass developers.
     */

    virtual IOCDBlockStorageDriver * getProvider() const;

    OSMetaClassDeclareReservedUnused(IOCDMedia,  0);
    OSMetaClassDeclareReservedUnused(IOCDMedia,  1);
    OSMetaClassDeclareReservedUnused(IOCDMedia,  2);
    OSMetaClassDeclareReservedUnused(IOCDMedia,  3);
    OSMetaClassDeclareReservedUnused(IOCDMedia,  4);
    OSMetaClassDeclareReservedUnused(IOCDMedia,  5);
    OSMetaClassDeclareReservedUnused(IOCDMedia,  6);
    OSMetaClassDeclareReservedUnused(IOCDMedia,  7);
    OSMetaClassDeclareReservedUnused(IOCDMedia,  8);
    OSMetaClassDeclareReservedUnused(IOCDMedia,  9);
    OSMetaClassDeclareReservedUnused(IOCDMedia, 10);
    OSMetaClassDeclareReservedUnused(IOCDMedia, 11);
    OSMetaClassDeclareReservedUnused(IOCDMedia, 12);
    OSMetaClassDeclareReservedUnused(IOCDMedia, 13);
    OSMetaClassDeclareReservedUnused(IOCDMedia, 14);
    OSMetaClassDeclareReservedUnused(IOCDMedia, 15);
};

#endif /* defined(KERNEL) && defined(__cplusplus) */

#endif /* !_IOCDMEDIA_H */
Commit	Line	Data
1c79356b A	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 */