![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IOStorage.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / XNU / iokit / IOKit / storage|
Return to IOStorage.h CVS log | Up to [Apple XNU] / XNU / iokit / IOKit / storage |
1.1 root 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 IOStorage
25: * @abstract
26: * This header contains the IOStorage class definition.
27: */
28:
29: #ifndef _IOSTORAGE_H
30: #define _IOSTORAGE_H
31:
32: /*!
33: * @enum IOStorageAccess
34: * @discussion
35: * The IOStorageAccess enumeration describes the possible access levels for open
36: * requests.
37: * @constant kAccessNone
38: * No access is requested; should not be passed to open().
39: * @constant kAccessReader
40: * Read-only access is requested.
41: * @constant kAccessReaderWriter
42: * Read and write access is requested.
43: */
44:
45: enum IOStorageAccess
46: {
47: kAccessNone = 0, kAccessReader = 1, kAccessReaderWriter = 3
48: };
49:
50: /*!
51: * @defined kIOStorageCategory
52: * @abstract
53: * kIOStorageCategory is a value for IOService's kIOMatchCategoryKey property.
54: * @discussion
55: * The kIOStorageCategory value is the standard value for the IOService property
56: * kIOMatchCategoryKey ("IOMatchCategory") for all storage drivers. All storage
57: * objects that expect to drive new content (that is, produce new media objects)
58: * are expected to compete within the kIOStorageCategory namespace.
59: *
60: * See the IOService documentation for more information on match categories.
61: */
62:
63: #define kIOStorageCategory "IOStorage" /* (as IOMatchCategory) */
64:
65: /*
66: * Kernel
67: */
68:
69: #if defined(KERNEL) && defined(__cplusplus)
70:
71: #include <IOKit/assert.h>
72: #include <IOKit/IOMemoryDescriptor.h>
73: #include <IOKit/IOService.h>
74:
75: /*!
76: * @typedef IOStorageCompletionAction
77: * @discussion
78: * The IOStorageCompletionAction declaration describes the C (or C++) completion
79: * routine that is called once an asynchronous storage operation completes.
80: * @param target
81: * Opaque client-supplied pointer (or an instance pointer for a C++ callback).
82: * @param parameter
83: * Opaque client-supplied pointer.
84: * @param status
85: * Status of the data transfer.
86: * @param actualByteCount
87: * Actual number of bytes transferred in the data transfer.
88: */
89:
90: typedef void (*IOStorageCompletionAction)(void * target,
91: void * parameter,
92: IOReturn status,
93: UInt64 actualByteCount);
94:
95: /*!
96: * @struct IOStorageCompletion
97: * @discussion
98: * The IOStorageCompletion structure describes the C (or C++) completion routine
99: * that is called once an asynchronous storage operation completes. The values
100: * passed for the target and parameter fields will be passed to the routine when
101: * it is called.
102: * @field target
103: * Opaque client-supplied pointer (or an instance pointer for a C++ callback).
104: * @field action
105: * Completion routine to call on completion of the data transfer.
106: * @field parameter
107: * Opaque client-supplied pointer.
108: */
109:
110: struct IOStorageCompletion
111: {
112: void * target;
113: IOStorageCompletionAction action;
114: void * parameter;
115: };
116:
117: /*!
118: * @class IOStorage
119: * @abstract
120: * The IOStorage class is the common base class for mass storage objects.
121: * @discussion
122: * The IOStorage class is the common base class for mass storage objects. It is
123: * an abstract class that defines the open/close/read/write APIs that need to be
124: * implemented in a given subclass. Synchronous versions of the read/write APIs
125: * are provided here -- they are coded in such a way as to wrap the asynchronous
126: * versions implmeneted in the subclass.
127: */
128:
129: class IOStorage : public IOService
130: {
131: OSDeclareAbstractStructors(IOStorage);
132:
133: protected:
134:
135: /*!
136: * @function complete
137: * @discussion
138: * Invokes the specified completion action of the read/write request. If
139: * the completion action is unspecified, no action is taken. This method
140: * serves simply as a convenience to storage subclass developers.
141: * @param completion
142: * Completion information for the data transfer.
143: * @param status
144: * Status of the data transfer.
145: * @param actualByteCount
146: * Actual number of bytes transferred in the data transfer.
147: */
148:
149: inline void complete(IOStorageCompletion completion,
150: IOReturn status,
151: UInt64 actualByteCount = 0);
152:
153: /*!
154: * @function handleOpen
155: * @discussion
156: * The handleOpen method grants or denies permission to access this object
157: * to an interested client. The argument is an IOStorageAccess value that
158: * specifies the level of access desired -- reader or reader-writer.
159: *
160: * This method can be invoked to upgrade or downgrade the access level for
161: * an existing client as well. The previous access level will prevail for
162: * upgrades that fail, of course. A downgrade should never fail. If the
163: * new access level should be the same as the old for a given client, this
164: * method will do nothing and return success. In all cases, one, singular
165: * close-per-client is expected for all opens-per-client received.
166: * @param client
167: * Client requesting the open.
168: * @param options
169: * Options for the open. Set to zero.
170: * @param access
171: * Access level for the open. Set to kAccessReader or kAccessReaderWriter.
172: * @result
173: * Returns true if the open was successful, false otherwise.
174: */
175:
176: virtual bool handleOpen(IOService * client,
177: IOOptionBits options,
178: void * access) = 0;
179:
180: /*!
181: * @function handleIsOpen
182: * @discussion
183: * The handleIsOpen method determines whether the specified client, or any
184: * client if none is specificed, presently has an open on this object.
185: * @param client
186: * Client to check the open state of. Set to zero to check the open state
187: * of all clients.
188: * @result
189: * Returns true if the client was (or clients were) open, false otherwise.
190: */
191:
192: virtual bool handleIsOpen(const IOService * client) const = 0;
193:
194: /*!
195: * @function handleClose
196: * @discussion
197: * The handleClose method closes the client's access to this object.
198: * @param client
199: * Client requesting the close.
200: * @param options
201: * Options for the close. Set to zero.
202: */
203:
204: virtual void handleClose(IOService * client, IOOptionBits options) = 0;
205:
206: public:
207:
208: /*!
209: * @function open
210: * @discussion
211: * Ask the storage object for permission to access its contents; the method
212: * is equivalent to IOService::open(), but with the correct parameter types.
213: *
214: * This method may also be invoked to upgrade or downgrade the access of an
215: * existing open (if it fails, the existing open prevails).
216: * @param client
217: * Client requesting the open.
218: * @param options
219: * Options for the open. Set to zero.
220: * @param access
221: * Access level for the open. Set to kAccessReader or kAccessReaderWriter.
222: * @result
223: * Returns true if the open was successful, false otherwise.
224: */
225:
226: inline bool open(IOService * client,
227: IOOptionBits options,
228: IOStorageAccess access);
229:
230: /*!
231: * @function read
232: * @discussion
233: * Read data from the storage object at the specified byte offset into the
234: * specified buffer, asynchronously. When the read completes, the caller
235: * will be notified via the specified completion action.
236: *
237: * The buffer will be retained for the duration of the read.
238: * @param client
239: * Client requesting the read.
240: * @param byteStart
241: * Starting byte offset for the data transfer.
242: * @param buffer
243: * Buffer for the data transfer. The size of the buffer implies the size of
244: * the data transfer.
245: * @param completion
246: * Completion routine to call once the data transfer is complete.
247: */
248:
249: virtual void read(IOService * client,
250: UInt64 byteStart,
251: IOMemoryDescriptor * buffer,
252: IOStorageCompletion completion) = 0;
253:
254: /*!
255: * @function write
256: * @discussion
257: * Write data into the storage object at the specified byte offset from the
258: * specified buffer, asynchronously. When the write completes, the caller
259: * will be notified via the specified completion action.
260: *
261: * The buffer will be retained for the duration of the write.
262: * @param client
263: * Client requesting the write.
264: * @param byteStart
265: * Starting byte offset for the data transfer.
266: * @param buffer
267: * Buffer for the data transfer. The size of the buffer implies the size of
268: * the data transfer.
269: * @param completion
270: * Completion routine to call once the data transfer is complete.
271: */
272:
273: virtual void write(IOService * client,
274: UInt64 byteStart,
275: IOMemoryDescriptor * buffer,
276: IOStorageCompletion completion) = 0;
277:
278: /*!
279: * @function read
280: * @discussion
281: * Read data from the storage object at the specified byte offset into the
282: * specified buffer, synchronously. When the read completes, this method
283: * will return to the caller. The actual byte count field is optional.
284: * @param client
285: * Client requesting the read.
286: * @param byteStart
287: * Starting byte offset for the data transfer.
288: * @param buffer
289: * Buffer for the data transfer. The size of the buffer implies the size of
290: * the data transfer.
291: * @param actualByteCount
292: * Returns the actual number of bytes transferred in the data transfer.
293: * @result
294: * Returns the status of the data transfer.
295: */
296:
297: virtual IOReturn read(IOService * client,
298: UInt64 byteStart,
299: IOMemoryDescriptor * buffer,
300: UInt64 * actualByteCount = 0);
301:
302: /*!
303: * @function write
304: * @discussion
305: * Write data into the storage object at the specified byte offset from the
306: * specified buffer, synchronously. When the write completes, this method
307: * will return to the caller. The actual byte count field is optional.
308: * @param client
309: * Client requesting the write.
310: * @param byteStart
311: * Starting byte offset for the data transfer.
312: * @param buffer
313: * Buffer for the data transfer. The size of the buffer implies the size of
314: * the data transfer.
315: * @param actualByteCount
316: * Returns the actual number of bytes transferred in the data transfer.
317: * @result
318: * Returns the status of the data transfer.
319: */
320:
321: virtual IOReturn write(IOService * client,
322: UInt64 byteStart,
323: IOMemoryDescriptor * buffer,
324: UInt64 * actualByteCount = 0);
325: };
326:
327: /*
328: * Inline Functions
329: */
330:
331: inline void IOStorage::complete(IOStorageCompletion completion,
332: IOReturn status,
333: UInt64 actualByteCount)
334: {
335: /*
336: * Invokes the specified completion action of the read/write request. If
337: * the completion action is unspecified, no action is taken. This method
338: * serves simply as a convenience to storage subclass developers.
339: */
340:
341: if (completion.action) (*completion.action)(completion.target,
342: completion.parameter,
343: status,
344: actualByteCount);
345: }
346:
347: inline bool IOStorage::open(IOService * client,
348: IOOptionBits options,
349: IOStorageAccess access)
350: {
351: /*
352: * Ask the storage object for permission to access its contents; the method
353: * is equivalent to IOService::open(), but with the correct parameter types.
354: */
355:
356: return IOService::open(client, options, (void *) access);
357: }
358:
359: #endif /* defined(KERNEL) && defined(__cplusplus) */
360:
361: #endif /* !_IOSTORAGE_H */
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.