1/* 2 * Copyright (c) 1998-2014 Apple Computer, Inc. All rights reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23/* 24 * HISTORY 25 * 26 */ 27 28/* 29 * IOKit user library 30 */ 31 32#ifndef _IOKIT_IOKITLIB_H 33#define _IOKIT_IOKITLIB_H 34 35#ifdef KERNEL 36#error This file is not for kernel use 37#endif 38 39#include <sys/cdefs.h> 40#include <sys/types.h> 41 42#include <mach/mach_types.h> 43#include <mach/mach_init.h> 44 45#include <CoreFoundation/CFBase.h> 46#include <CoreFoundation/CFDictionary.h> 47#include <CoreFoundation/CFRunLoop.h> 48 49#include <IOKit/IOTypes.h> 50#include <IOKit/IOKitKeys.h> 51 52#include <IOKit/OSMessageNotification.h> 53 54#include <AvailabilityMacros.h> 55 56#include <dispatch/dispatch.h> 57 58__BEGIN_DECLS 59 60/*! @header IOKitLib 61IOKitLib implements non-kernel task access to common IOKit object types - IORegistryEntry, IOService, IOIterator etc. These functions are generic - families may provide API that is more specific.<br> 62IOKitLib represents IOKit objects outside the kernel with the types io_object_t, io_registry_entry_t, io_service_t, & io_connect_t. Function names usually begin with the type of object they are compatible with - eg. IOObjectRelease can be used with any io_object_t. Inside the kernel, the c++ class hierarchy allows the subclasses of each object type to receive the same requests from user level clients, for example in the kernel, IOService is a subclass of IORegistryEntry, which means any of the IORegistryEntryXXX functions in IOKitLib may be used with io_service_t's as well as io_registry_t's. There are functions available to introspect the class of the kernel object which any io_object_t et al. represents. 63IOKit objects returned by all functions should be released with IOObjectRelease. 64*/ 65/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 66 67typedef struct IONotificationPort * IONotificationPortRef; 68 69 70/*! @typedef IOServiceMatchingCallback 71 @abstract Callback function to be notified of IOService publication. 72 @param refcon The refcon passed when the notification was installed. 73 @param iterator The notification iterator which now has new objects. 74*/ 75typedef void 76(*IOServiceMatchingCallback)( 77 void * refcon, 78 io_iterator_t iterator ); 79 80/*! @typedef IOServiceInterestCallback 81 @abstract Callback function to be notified of changes in state of an IOService. 82 @param refcon The refcon passed when the notification was installed. 83 @param service The IOService whose state has changed. 84 @param messageType A messageType enum, defined by IOKit/IOMessage.h or by the IOService's family. 85 @param messageArgument An argument for the message, dependent on the messageType. If the message data is larger than sizeof(void*), then messageArgument contains a pointer to the message data; otherwise, messageArgument contains the message data. 86*/ 87 88typedef void 89(*IOServiceInterestCallback)( 90 void * refcon, 91 io_service_t service, 92 uint32_t messageType, 93 void * messageArgument ); 94 95/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 96 97/*! @const kIOMasterPortDefault 98 @abstract The default mach port used to initiate communication with IOKit. 99 @discussion When specifying a master port to IOKit functions, the NULL argument indicates "use the default". This is a synonym for NULL, if you'd rather use a named constant. 100*/ 101 102extern 103const mach_port_t kIOMasterPortDefault; 104 105/*! @function IOMasterPort 106 @abstract Returns the mach port used to initiate communication with IOKit. 107 @discussion Functions that don't specify an existing object require the IOKit master port to be passed. This function obtains that port. 108 @param bootstrapPort Pass MACH_PORT_NULL for the default. 109 @param masterPort The master port is returned. 110 @result A kern_return_t error code. */ 111 112kern_return_t 113IOMasterPort( mach_port_t bootstrapPort, 114 mach_port_t * masterPort ); 115 116 117/*! @function IONotificationPortCreate 118 @abstract Creates and returns a notification object for receiving IOKit notifications of new devices or state changes. 119 @discussion Creates the notification object to receive notifications from IOKit of new device arrivals or state changes. The notification object can be supply a CFRunLoopSource, or mach_port_t to be used to listen for events. 120 @param masterPort The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port. 121 @result A reference to the notification object. */ 122 123IONotificationPortRef 124IONotificationPortCreate( 125 mach_port_t masterPort ); 126 127/*! @function IONotificationPortDestroy 128 @abstract Destroys a notification object created with IONotificationPortCreate. 129 Also destroys any mach_port's or CFRunLoopSources obatined from 130 <code>@link IONotificationPortGetRunLoopSource @/link</code> 131 or <code>@link IONotificationPortGetMachPort @/link</code> 132 @param notify A reference to the notification object. */ 133 134void 135IONotificationPortDestroy( 136 IONotificationPortRef notify ); 137 138/*! @function IONotificationPortGetRunLoopSource 139 @abstract Returns a CFRunLoopSource to be used to listen for notifications. 140 @discussion A notification object may deliver notifications to a CFRunLoop 141 by adding the run loop source returned by this function to the run loop. 142 143 The caller should not release this CFRunLoopSource. Just call 144 <code>@link IONotificationPortDestroy @/link</code> to dispose of the 145 IONotificationPortRef and the CFRunLoopSource when done. 146 @param notify The notification object. 147 @result A CFRunLoopSourceRef for the notification object. */ 148 149CFRunLoopSourceRef 150IONotificationPortGetRunLoopSource( 151 IONotificationPortRef notify ); 152 153/*! @function IONotificationPortGetMachPort 154 @abstract Returns a mach_port to be used to listen for notifications. 155 @discussion A notification object may deliver notifications to a mach messaging client 156 if they listen for messages on the port obtained from this function. 157 Callbacks associated with the notifications may be delivered by calling 158 IODispatchCalloutFromMessage with messages received. 159 160 The caller should not release this mach_port_t. Just call 161 <code>@link IONotificationPortDestroy @/link</code> to dispose of the 162 mach_port_t and IONotificationPortRef when done. 163 @param notify The notification object. 164 @result A mach_port for the notification object. */ 165 166mach_port_t 167IONotificationPortGetMachPort( 168 IONotificationPortRef notify ); 169 170/*! @function IONotificationPortSetDispatchQueue 171 @abstract Sets a dispatch queue to be used to listen for notifications. 172 @discussion A notification object may deliver notifications to a dispatch client. 173 @param notify The notification object. 174 @param queue A dispatch queue. */ 175 176void 177IONotificationPortSetDispatchQueue( 178 IONotificationPortRef notify, dispatch_queue_t queue ) 179__OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_4_3); 180 181/*! @function IODispatchCalloutFromMessage 182 @abstract Dispatches callback notifications from a mach message. 183 @discussion A notification object may deliver notifications to a mach messaging client, 184 which should call this function to generate the callbacks associated with the notifications arriving on the port. 185 @param unused Not used, set to zero. 186 @param msg A pointer to the message received. 187 @param reference Pass the IONotificationPortRef for the object. */ 188 189void 190IODispatchCalloutFromMessage( 191 void *unused, 192 mach_msg_header_t *msg, 193 void *reference ); 194 195/*! @function IOCreateReceivePort 196 @abstract Creates and returns a mach port suitable for receiving IOKit messages of the specified type. 197 @discussion In the future IOKit may use specialized messages and ports 198 instead of the standard ports created by mach_port_allocate(). Use this 199 function instead of mach_port_allocate() to ensure compatibility with future 200 revisions of IOKit. 201 @param msgType Type of message to be sent to this port 202 (kOSNotificationMessageID or kOSAsyncCompleteMessageID) 203 @param recvPort The created port is returned. 204 @result A kern_return_t error code. */ 205 206kern_return_t 207IOCreateReceivePort( uint32_t msgType, mach_port_t * recvPort ); 208 209/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 210 211/* 212 * IOObject 213 */ 214 215/*! @function IOObjectRelease 216 @abstract Releases an object handle previously returned by IOKitLib. 217 @discussion All objects returned by IOKitLib should be released with this function when access to them is no longer needed. Using the object after it has been released may or may not return an error, depending on how many references the task has to the same object in the kernel. 218 @param object The IOKit object to release. 219 @result A kern_return_t error code. */ 220 221kern_return_t 222IOObjectRelease( 223 io_object_t object ); 224 225/*! @function IOObjectRetain 226 @abstract Retains an object handle previously returned by IOKitLib. 227 @discussion Gives the caller an additional reference to an existing object handle previously returned by IOKitLib. 228 @param object The IOKit object to retain. 229 @result A kern_return_t error code. */ 230 231kern_return_t 232IOObjectRetain( 233 io_object_t object ); 234 235/*! @function IOObjectGetClass 236 @abstract Return the class name of an IOKit object. 237 @discussion This function uses the OSMetaClass system in the kernel to derive the name of the class the object is an instance of. 238 @param object The IOKit object. 239 @param className Caller allocated buffer to receive the name string. 240 @result A kern_return_t error code. */ 241 242kern_return_t 243IOObjectGetClass( 244 io_object_t object, 245 io_name_t className ); 246 247/*! @function IOObjectCopyClass 248 @abstract Return the class name of an IOKit object. 249 @discussion This function does the same thing as IOObjectGetClass, but returns the result as a CFStringRef. 250 @param object The IOKit object. 251 @result The resulting CFStringRef. This should be released by the caller. If a valid object is not passed in, then NULL is returned.*/ 252 253CFStringRef 254IOObjectCopyClass(io_object_t object) 255AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; 256 257/*! @function IOObjectCopySuperclassForClass 258 @abstract Return the superclass name of the given class. 259 @discussion This function uses the OSMetaClass system in the kernel to derive the name of the superclass of the class. 260 @param classname The name of the class as a CFString. 261 @result The resulting CFStringRef. This should be released by the caller. If there is no superclass, or a valid class name is not passed in, then NULL is returned.*/ 262 263CFStringRef 264IOObjectCopySuperclassForClass(CFStringRef classname) 265AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; 266 267/*! @function IOObjectCopyBundleIdentifierForClass 268 @abstract Return the bundle identifier of the given class. 269 @discussion This function uses the OSMetaClass system in the kernel to derive the name of the kmod, which is the same as the bundle identifier. 270 @param classname The name of the class as a CFString. 271 @result The resulting CFStringRef. This should be released by the caller. If a valid class name is not passed in, then NULL is returned.*/ 272 273CFStringRef 274IOObjectCopyBundleIdentifierForClass(CFStringRef classname) 275AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; 276 277/*! @function IOObjectConformsTo 278 @abstract Performs an OSDynamicCast operation on an IOKit object. 279 @discussion This function uses the OSMetaClass system in the kernel to determine if the object will dynamic cast to a class, specified as a C-string. In other words, if the object is of that class or a subclass. 280 @param object An IOKit object. 281 @param className The name of the class, as a C-string. 282 @result If the object handle is valid, and represents an object in the kernel that dynamic casts to the class true is returned, otherwise false. */ 283 284boolean_t 285IOObjectConformsTo( 286 io_object_t object, 287 const io_name_t className ); 288 289/*! @function IOObjectIsEqualTo 290 @abstract Checks two object handles to see if they represent the same kernel object. 291 @discussion If two object handles are returned by IOKitLib functions, this function will compare them to see if they represent the same kernel object. 292 @param object An IOKit object. 293 @param anObject Another IOKit object. 294 @result If both object handles are valid, and represent the same object in the kernel true is returned, otherwise false. */ 295 296boolean_t 297IOObjectIsEqualTo( 298 io_object_t object, 299 io_object_t anObject ); 300 301/*! @function IOObjectGetKernelRetainCount 302 @abstract Returns kernel retain count of an IOKit object. 303 @discussion This function may be used in diagnostics to determine the current retain count of the kernel object at the kernel level. 304 @param object An IOKit object. 305 @result If the object handle is valid, the kernel objects retain count is returned, otherwise zero is returned. */ 306 307uint32_t 308IOObjectGetKernelRetainCount( 309 io_object_t object ) 310AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER; 311 312/*! @function IOObjectGetUserRetainCount 313 @abstract Returns the retain count for the current process of an IOKit object. 314 @discussion This function may be used in diagnostics to determine the current retain count for the calling process of the kernel object. 315 @param object An IOKit object. 316 @result If the object handle is valid, the objects user retain count is returned, otherwise zero is returned. */ 317 318uint32_t 319IOObjectGetUserRetainCount( 320 io_object_t object ) 321AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER; 322 323/*! @function IOObjectGetRetainCount 324 @abstract Returns kernel retain count of an IOKit object. Identical to IOObjectGetKernelRetainCount() but available prior to Mac OS 10.6. 325 @discussion This function may be used in diagnostics to determine the current retain count of the kernel object at the kernel level. 326 @param object An IOKit object. 327 @result If the object handle is valid, the kernel objects retain count is returned, otherwise zero is returned. */ 328 329uint32_t 330IOObjectGetRetainCount( 331 io_object_t object ); 332 333 334/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 335 336/* 337 * IOIterator, subclass of IOObject 338 */ 339 340/*! @function IOIteratorNext 341 @abstract Returns the next object in an iteration. 342 @discussion This function returns the next object in an iteration, or zero if no more remain or the iterator is invalid. 343 @param iterator An IOKit iterator handle. 344 @result If the iterator handle is valid, the next element in the iteration is returned, otherwise zero is returned. The element should be released by the caller when it is finished. */ 345 346io_object_t 347IOIteratorNext( 348 io_iterator_t iterator ); 349 350/*! @function IOIteratorReset 351 @abstract Resets an iteration back to the beginning. 352 @discussion If an iterator is invalid, or if the caller wants to start over, IOIteratorReset will set the iteration back to the beginning. 353 @param iterator An IOKit iterator handle. */ 354 355void 356IOIteratorReset( 357 io_iterator_t iterator ); 358 359/*! @function IOIteratorIsValid 360 @abstract Checks an iterator is still valid. 361 @discussion Some iterators will be made invalid if changes are made to the structure they are iterating over. This function checks the iterator is still valid and should be called when IOIteratorNext returns zero. An invalid iterator can be reset and the iteration restarted. 362 @param iterator An IOKit iterator handle. 363 @result True if the iterator handle is valid, otherwise false is returned. */ 364 365boolean_t 366IOIteratorIsValid( 367 io_iterator_t iterator ); 368 369/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 370 371/* 372 * IOService, subclass of IORegistryEntry 373 */ 374 375/*! 376 @function IOServiceGetMatchingService 377 @abstract Look up a registered IOService object that matches a matching dictionary. 378 @discussion This is the preferred method of finding IOService objects currently registered by IOKit (that is, objects that have had their registerService() methods invoked). To find IOService objects that aren't yet registered, use an iterator as created by IORegistryEntryCreateIterator(). IOServiceAddMatchingNotification can also supply this information and install a notification of new IOServices. The matching information used in the matching dictionary may vary depending on the class of service being looked up. 379 @param masterPort The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port. 380 @param matching A CF dictionary containing matching information, of which one reference is always consumed by this function (Note prior to the Tiger release there was a small chance that the dictionary might not be released if there was an error attempting to serialize the dictionary). IOKitLib can construct matching dictionaries for common criteria with helper functions such as IOServiceMatching, IOServiceNameMatching, IOBSDNameMatching. 381 @result The first service matched is returned on success. The service must be released by the caller. 382 */ 383 384io_service_t 385IOServiceGetMatchingService( 386 mach_port_t masterPort, 387 CFDictionaryRef matching ); 388 389/*! @function IOServiceGetMatchingServices 390 @abstract Look up registered IOService objects that match a matching dictionary. 391 @discussion This is the preferred method of finding IOService objects currently registered by IOKit (that is, objects that have had their registerService() methods invoked). To find IOService objects that aren't yet registered, use an iterator as created by IORegistryEntryCreateIterator(). IOServiceAddMatchingNotification can also supply this information and install a notification of new IOServices. The matching information used in the matching dictionary may vary depending on the class of service being looked up. 392 @param masterPort The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port. 393 @param matching A CF dictionary containing matching information, of which one reference is always consumed by this function (Note prior to the Tiger release there was a small chance that the dictionary might not be released if there was an error attempting to serialize the dictionary). IOKitLib can construct matching dictionaries for common criteria with helper functions such as IOServiceMatching, IOServiceNameMatching, IOBSDNameMatching. 394 @param existing An iterator handle is returned on success, and should be released by the caller when the iteration is finished. 395 @result A kern_return_t error code. */ 396 397kern_return_t 398IOServiceGetMatchingServices( 399 mach_port_t masterPort, 400 CFDictionaryRef matching, 401 io_iterator_t * existing ); 402 403 404kern_return_t 405IOServiceAddNotification( 406 mach_port_t masterPort, 407 const io_name_t notificationType, 408 CFDictionaryRef matching, 409 mach_port_t wakePort, 410 uintptr_t reference, 411 io_iterator_t * notification ) DEPRECATED_ATTRIBUTE; 412 413/*! @function IOServiceAddMatchingNotification 414 @abstract Look up registered IOService objects that match a matching dictionary, and install a notification request of new IOServices that match. 415 @discussion This is the preferred method of finding IOService objects that may arrive at any time. The type of notification specifies the state change the caller is interested in, on IOService's that match the match dictionary. Notification types are identified by name, and are defined in IOKitKeys.h. The matching information used in the matching dictionary may vary depending on the class of service being looked up. 416 @param notifyPort A IONotificationPortRef object that controls how messages will be sent when the armed notification is fired. When the notification is delivered, the io_iterator_t representing the notification should be iterated through to pick up all outstanding objects. When the iteration is finished the notification is rearmed. See IONotificationPortCreate. 417 @param notificationType A notification type from IOKitKeys.h 418<br> kIOPublishNotification Delivered when an IOService is registered. 419<br> kIOFirstPublishNotification Delivered when an IOService is registered, but only once per IOService instance. Some IOService's may be reregistered when their state is changed. 420<br> kIOMatchedNotification Delivered when an IOService has had all matching drivers in the kernel probed and started. 421<br> kIOFirstMatchNotification Delivered when an IOService has had all matching drivers in the kernel probed and started, but only once per IOService instance. Some IOService's may be reregistered when their state is changed. 422<br> kIOTerminatedNotification Delivered after an IOService has been terminated. 423 @param matching A CF dictionary containing matching information, of which one reference is always consumed by this function (Note prior to the Tiger release there was a small chance that the dictionary might not be released if there was an error attempting to serialize the dictionary). IOKitLib can construct matching dictionaries for common criteria with helper functions such as IOServiceMatching, IOServiceNameMatching, IOBSDNameMatching. 424 @param callback A callback function called when the notification fires. 425 @param refCon A reference constant for the callbacks use. 426 @param notification An iterator handle is returned on success, and should be released by the caller when the notification is to be destroyed. The notification is armed when the iterator is emptied by calls to IOIteratorNext - when no more objects are returned, the notification is armed. Note the notification is not armed when first created. 427 @result A kern_return_t error code. */ 428 429kern_return_t 430IOServiceAddMatchingNotification( 431 IONotificationPortRef notifyPort, 432 const io_name_t notificationType, 433 CFDictionaryRef matching, 434 IOServiceMatchingCallback callback, 435 void * refCon, 436 io_iterator_t * notification ); 437 438/*! @function IOServiceAddInterestNotification 439 @abstract Register for notification of state changes in an IOService. 440 @discussion IOService objects deliver notifications of their state changes to their clients via the IOService::messageClients API, and to other interested parties including callers of this function. Message types are defined IOKit/IOMessage.h. 441 @param notifyPort A IONotificationPortRef object that controls how messages will be sent when the notification is fired. See IONotificationPortCreate. 442 @param interestType A notification type from IOKitKeys.h 443<br> kIOGeneralInterest General state changes delivered via the IOService::messageClients API. 444<br> kIOBusyInterest Delivered when the IOService changes its busy state to or from zero. The message argument contains the new busy state causing the notification. 445 @param callback A callback function called when the notification fires, with messageType and messageArgument for the state change. 446 @param refCon A reference constant for the callbacks use. 447 @param notification An object handle is returned on success, and should be released by the caller when the notification is to be destroyed. 448 @result A kern_return_t error code. */ 449 450kern_return_t 451IOServiceAddInterestNotification( 452 IONotificationPortRef notifyPort, 453 io_service_t service, 454 const io_name_t interestType, 455 IOServiceInterestCallback callback, 456 void * refCon, 457 io_object_t * notification ); 458 459/*! @function IOServiceMatchPropertyTable 460 @abstract Match an IOService objects with matching dictionary. 461 @discussion This function calls the matching method of an IOService object and returns the boolean result. 462 @param service The IOService object to match. 463 @param matching A CF dictionary containing matching information. IOKitLib can construct matching dictionaries for common criteria with helper functions such as IOServiceMatching, IOServiceNameMatching, IOBSDNameMatching. 464 @param matches The boolean result is returned. 465 @result A kern_return_t error code. */ 466 467kern_return_t 468IOServiceMatchPropertyTable( 469 io_service_t service, 470 CFDictionaryRef matching, 471 boolean_t * matches ); 472 473/*! @function IOServiceGetBusyState 474 @abstract Returns the busyState of an IOService. 475 @discussion Many activities in IOService are asynchronous. When registration, matching, or termination is in progress on an IOService, its busyState is increased by one. Change in busyState to or from zero also changes the IOService's provider's busyState by one, which means that an IOService is marked busy when any of the above activities is ocurring on it or any of its clients. 476 @param service The IOService whose busyState to return. 477 @param busyState The busyState count is returned. 478 @result A kern_return_t error code. */ 479 480kern_return_t 481IOServiceGetBusyState( 482 io_service_t service, 483 uint32_t * busyState ); 484 485/*! @function IOServiceWaitQuiet 486 @abstract Wait for an IOService's busyState to be zero. 487 @discussion Blocks the caller until an IOService is non busy, see IOServiceGetBusyState. 488 @param service The IOService wait on. 489 @param waitTime Specifies a maximum time to wait. 490 @result Returns an error code if mach synchronization primitives fail, kIOReturnTimeout, or kIOReturnSuccess. */ 491 492kern_return_t 493IOServiceWaitQuiet( 494 io_service_t service, 495 mach_timespec_t * waitTime ); 496 497/*! @function IOKitGetBusyState 498 @abstract Returns the busyState of all IOServices. 499 @discussion Many activities in IOService are asynchronous. When registration, matching, or termination is in progress on an IOService, its busyState is increased by one. Change in busyState to or from zero also changes the IOService's provider's busyState by one, which means that an IOService is marked busy when any of the above activities is ocurring on it or any of its clients. IOKitGetBusyState returns the busy state of the root of the service plane which reflects the busy state of all IOServices. 500 @param masterPort The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port. 501 @param busyState The busyState count is returned. 502 @result A kern_return_t error code. */ 503 504kern_return_t 505IOKitGetBusyState( 506 mach_port_t masterPort, 507 uint32_t * busyState ); 508 509/*! @function IOKitWaitQuiet 510 @abstract Wait for a all IOServices' busyState to be zero. 511 @discussion Blocks the caller until all IOServices are non busy, see IOKitGetBusyState. 512 @param masterPort The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port. 513 @param waitTime Specifies a maximum time to wait. 514 @result Returns an error code if mach synchronization primitives fail, kIOReturnTimeout, or kIOReturnSuccess. */ 515 516kern_return_t 517IOKitWaitQuiet( 518 mach_port_t masterPort, 519 mach_timespec_t * waitTime ); 520 521/*! @function IOServiceOpen 522 @abstract A request to create a connection to an IOService. 523 @discussion A non kernel client may request a connection be opened via the IOServiceOpen() library function, which will call IOService::newUserClient in the kernel. The rules & capabilities of user level clients are family dependent, the default IOService implementation returns kIOReturnUnsupported. 524 @param service The IOService object to open a connection to, usually obtained via the IOServiceGetMatchingServices or IOServiceAddNotification APIs. 525 @param owningTask The mach task requesting the connection. 526 @param type A constant specifying the type of connection to be created, interpreted only by the IOService's family. 527 @param connect An io_connect_t handle is returned on success, to be used with the IOConnectXXX APIs. It should be destroyed with IOServiceClose(). 528 @result A return code generated by IOService::newUserClient. */ 529 530kern_return_t 531IOServiceOpen( 532 io_service_t service, 533 task_port_t owningTask, 534 uint32_t type, 535 io_connect_t * connect ); 536 537/*! @function IOServiceRequestProbe 538 @abstract A request to rescan a bus for device changes. 539 @discussion A non kernel client may request a bus or controller rescan for added or removed devices, if the bus family does automatically notice such changes. For example, SCSI bus controllers do not notice device changes. The implementation of this routine is family dependent, and the default IOService implementation returns kIOReturnUnsupported. 540 @param service The IOService object to request a rescan, usually obtained via the IOServiceGetMatchingServices or IOServiceAddNotification APIs. 541 @param options An options mask, interpreted only by the IOService's family. 542 @result A return code generated by IOService::requestProbe. */ 543 544kern_return_t 545IOServiceRequestProbe( 546 io_service_t service, 547 uint32_t options ); 548 549// options for IOServiceAuthorize() 550enum { 551 kIOServiceInteractionAllowed = 0x00000001 552}; 553 554/*! @function IOServiceAuthorize 555 @abstract Authorize access to an IOService. 556 @discussion Determine whether this application is authorized to invoke IOServiceOpen() for a given IOService, either by confirming that it has been previously authorized by the user, or by soliciting the console user. 557 @param service The IOService object to be authorized, usually obtained via the IOServiceGetMatchingServices or IOServiceAddNotification APIs. 558 @param options kIOServiceInteractionAllowed may be set to permit user interaction, if required. 559 @result kIOReturnSuccess if the IOService is authorized, kIOReturnNotPermitted if the IOService is not authorized. */ 560 561kern_return_t 562IOServiceAuthorize( 563 io_service_t service, 564 uint32_t options ); 565 566int 567IOServiceOpenAsFileDescriptor( 568 io_service_t service, 569 int oflag ); 570 571/* * * * * * * * * * * * * * *ff * * * * * * * * * * * * * * * * * * * * * * */ 572 573/* 574 * IOService connection 575 */ 576 577/*! @function IOServiceClose 578 @abstract Close a connection to an IOService and destroy the connect handle. 579 @discussion A connection created with the IOServiceOpen should be closed when the connection is no longer to be used with IOServiceClose. 580 @param connect The connect handle created by IOServiceOpen. It will be destroyed by this function, and should not be released with IOObjectRelease. 581 @result A kern_return_t error code. */ 582 583kern_return_t 584IOServiceClose( 585 io_connect_t connect ); 586 587/*! @function IOConnectAddRef 588 @abstract Adds a reference to the connect handle. 589 @discussion Adds a reference to the connect handle. 590 @param connect The connect handle created by IOServiceOpen. 591 @result A kern_return_t error code. */ 592 593kern_return_t 594IOConnectAddRef( 595 io_connect_t connect ); 596 597/*! @function IOConnectRelease 598 @abstract Remove a reference to the connect handle. 599 @discussion Removes a reference to the connect handle. If the last reference is removed an implicit IOServiceClose is performed. 600 @param connect The connect handle created by IOServiceOpen. 601 @result A kern_return_t error code. */ 602 603kern_return_t 604IOConnectRelease( 605 io_connect_t connect ); 606 607/*! @function IOConnectGetService 608 @abstract Returns the IOService a connect handle was opened on. 609 @discussion Finds the service object a connection was opened on. 610 @param connect The connect handle created by IOServiceOpen. 611 @param service On succes, the service handle the connection was opened on, which should be released with IOObjectRelease. 612 @result A kern_return_t error code. */ 613 614kern_return_t 615IOConnectGetService( 616 io_connect_t connect, 617 io_service_t * service ); 618 619/*! @function IOConnectSetNotificationPort 620 @abstract Set a port to receive family specific notifications. 621 @discussion This is a generic method to pass a mach port send right to be be used by family specific notifications. 622 @param connect The connect handle created by IOServiceOpen. 623 @param type The type of notification requested, not interpreted by IOKit and family defined. 624 @param port The port to which to send notifications. 625 @param reference Some families may support passing a reference parameter for the callers use with the notification. 626 @result A kern_return_t error code. */ 627 628kern_return_t 629IOConnectSetNotificationPort( 630 io_connect_t connect, 631 uint32_t type, 632 mach_port_t port, 633 uintptr_t reference ); 634 635/*! @function IOConnectMapMemory 636 @abstract Map hardware or shared memory into the caller's task. 637 @discussion This is a generic method to create a mapping in the callers task. The family will interpret the type parameter to determine what sort of mapping is being requested. Cache modes and placed mappings may be requested by the caller. 638 @param connect The connect handle created by IOServiceOpen. 639 @param memoryType What is being requested to be mapped, not interpreted by IOKit and family defined. The family may support physical hardware or shared memory mappings. 640 @param intoTask The task port for the task in which to create the mapping. This may be different to the task which the opened the connection. 641 @param atAddress An in/out parameter - if the kIOMapAnywhere option is not set, the caller should pass the address where it requests the mapping be created, otherwise nothing need to set on input. The address of the mapping created is passed back on sucess. 642 @param ofSize The size of the mapping created is passed back on success. 643 @result A kern_return_t error code. */ 644 645#if !__LP64__ || defined(IOCONNECT_MAPMEMORY_10_6) 646 647kern_return_t 648IOConnectMapMemory( 649 io_connect_t connect, 650 uint32_t memoryType, 651 task_port_t intoTask, 652 vm_address_t *atAddress, 653 vm_size_t *ofSize, 654 IOOptionBits options ); 655 656#else 657 658kern_return_t 659IOConnectMapMemory( 660 io_connect_t connect, 661 uint32_t memoryType, 662 task_port_t intoTask, 663 mach_vm_address_t *atAddress, 664 mach_vm_size_t *ofSize, 665 IOOptionBits options ); 666 667#endif /* !__LP64__ || defined(IOCONNECT_MAPMEMORY_10_6) */ 668 669 670/*! @function IOConnectMapMemory64 671 @abstract Map hardware or shared memory into the caller's task. 672 @discussion This is a generic method to create a mapping in the callers task. The family will interpret the type parameter to determine what sort of mapping is being requested. Cache modes and placed mappings may be requested by the caller. 673 @param connect The connect handle created by IOServiceOpen. 674 @param memoryType What is being requested to be mapped, not interpreted by IOKit and family defined. The family may support physical hardware or shared memory mappings. 675 @param intoTask The task port for the task in which to create the mapping. This may be different to the task which the opened the connection. 676 @param atAddress An in/out parameter - if the kIOMapAnywhere option is not set, the caller should pass the address where it requests the mapping be created, otherwise nothing need to set on input. The address of the mapping created is passed back on sucess. 677 @param ofSize The size of the mapping created is passed back on success. 678 @result A kern_return_t error code. */ 679 680kern_return_t IOConnectMapMemory64( 681 io_connect_t connect, 682 uint32_t memoryType, 683 task_port_t intoTask, 684 mach_vm_address_t *atAddress, 685 mach_vm_size_t *ofSize, 686 IOOptionBits options ); 687 688/*! @function IOConnectUnmapMemory 689 @abstract Remove a mapping made with IOConnectMapMemory. 690 @discussion This is a generic method to remove a mapping in the callers task. 691 @param connect The connect handle created by IOServiceOpen. 692 @param memoryType The memory type originally requested in IOConnectMapMemory. 693 @param fromTask The task port for the task in which to remove the mapping. This may be different to the task which the opened the connection. 694 @param atAddress The address of the mapping to be removed. 695 @result A kern_return_t error code. */ 696 697#if !__LP64__ || defined(IOCONNECT_MAPMEMORY_10_6) 698 699kern_return_t 700IOConnectUnmapMemory( 701 io_connect_t connect, 702 uint32_t memoryType, 703 task_port_t fromTask, 704 vm_address_t atAddress ); 705 706#else 707 708kern_return_t 709IOConnectUnmapMemory( 710 io_connect_t connect, 711 uint32_t memoryType, 712 task_port_t fromTask, 713 mach_vm_address_t atAddress ); 714 715 716#endif /* !__LP64__ || defined(IOCONNECT_MAPMEMORY_10_6) */ 717 718/*! @function IOConnectUnmapMemory64 719 @abstract Remove a mapping made with IOConnectMapMemory64. 720 @discussion This is a generic method to remove a mapping in the callers task. 721 @param connect The connect handle created by IOServiceOpen. 722 @param memoryType The memory type originally requested in IOConnectMapMemory. 723 @param fromTask The task port for the task in which to remove the mapping. This may be different to the task which the opened the connection. 724 @param atAddress The address of the mapping to be removed. 725 @result A kern_return_t error code. */ 726 727kern_return_t IOConnectUnmapMemory64( 728 io_connect_t connect, 729 uint32_t memoryType, 730 task_port_t fromTask, 731 mach_vm_address_t atAddress ); 732 733 734/*! @function IOConnectSetCFProperties 735 @abstract Set CF container based properties on a connection. 736 @discussion This is a generic method to pass a CF container of properties to the connection. The properties are interpreted by the family and commonly represent configuration settings, but may be interpreted as anything. 737 @param connect The connect handle created by IOServiceOpen. 738 @param properties A CF container - commonly a CFDictionary but this is not enforced. The container should consist of objects which are understood by IOKit - these are currently : CFDictionary, CFArray, CFSet, CFString, CFData, CFNumber, CFBoolean, and are passed in the kernel as the corresponding OSDictionary etc. objects. 739 @result A kern_return_t error code returned by the family. */ 740 741kern_return_t 742IOConnectSetCFProperties( 743 io_connect_t connect, 744 CFTypeRef properties ); 745 746/*! @function IOConnectSetCFProperty 747 @abstract Set a CF container based property on a connection. 748 @discussion This is a generic method to pass a CF property to the connection. The property is interpreted by the family and commonly represent configuration settings, but may be interpreted as anything. 749 @param connect The connect handle created by IOServiceOpen. 750 @param propertyName The name of the property as a CFString. 751 @param property A CF container - should consist of objects which are understood by IOKit - these are currently : CFDictionary, CFArray, CFSet, CFString, CFData, CFNumber, CFBoolean, and are passed in the kernel as the corresponding OSDictionary etc. objects. 752 @result A kern_return_t error code returned by the object. */ 753 754kern_return_t 755IOConnectSetCFProperty( 756 io_connect_t connect, 757 CFStringRef propertyName, 758 CFTypeRef property ); 759 760/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 761 762// Combined LP64 & ILP32 Extended IOUserClient::externalMethod 763 764kern_return_t 765IOConnectCallMethod( 766 mach_port_t connection, // In 767 uint32_t selector, // In 768 const uint64_t *input, // In 769 uint32_t inputCnt, // In 770 const void *inputStruct, // In 771 size_t inputStructCnt, // In 772 uint64_t *output, // Out 773 uint32_t *outputCnt, // In/Out 774 void *outputStruct, // Out 775 size_t *outputStructCnt) // In/Out 776AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 777 778kern_return_t 779IOConnectCallAsyncMethod( 780 mach_port_t connection, // In 781 uint32_t selector, // In 782 mach_port_t wake_port, // In 783 uint64_t *reference, // In 784 uint32_t referenceCnt, // In 785 const uint64_t *input, // In 786 uint32_t inputCnt, // In 787 const void *inputStruct, // In 788 size_t inputStructCnt, // In 789 uint64_t *output, // Out 790 uint32_t *outputCnt, // In/Out 791 void *outputStruct, // Out 792 size_t *outputStructCnt) // In/Out 793AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 794 795kern_return_t 796IOConnectCallStructMethod( 797 mach_port_t connection, // In 798 uint32_t selector, // In 799 const void *inputStruct, // In 800 size_t inputStructCnt, // In 801 void *outputStruct, // Out 802 size_t *outputStructCnt) // In/Out 803AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 804 805kern_return_t 806IOConnectCallAsyncStructMethod( 807 mach_port_t connection, // In 808 uint32_t selector, // In 809 mach_port_t wake_port, // In 810 uint64_t *reference, // In 811 uint32_t referenceCnt, // In 812 const void *inputStruct, // In 813 size_t inputStructCnt, // In 814 void *outputStruct, // Out 815 size_t *outputStructCnt) // In/Out 816AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 817 818kern_return_t 819IOConnectCallScalarMethod( 820 mach_port_t connection, // In 821 uint32_t selector, // In 822 const uint64_t *input, // In 823 uint32_t inputCnt, // In 824 uint64_t *output, // Out 825 uint32_t *outputCnt) // In/Out 826AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 827 828kern_return_t 829IOConnectCallAsyncScalarMethod( 830 mach_port_t connection, // In 831 uint32_t selector, // In 832 mach_port_t wake_port, // In 833 uint64_t *reference, // In 834 uint32_t referenceCnt, // In 835 const uint64_t *input, // In 836 uint32_t inputCnt, // In 837 uint64_t *output, // Out 838 uint32_t *outputCnt) // In/Out 839AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 840 841/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 842 843kern_return_t 844IOConnectTrap0(io_connect_t connect, 845 uint32_t index ); 846 847kern_return_t 848IOConnectTrap1(io_connect_t connect, 849 uint32_t index, 850 uintptr_t p1 ); 851 852kern_return_t 853IOConnectTrap2(io_connect_t connect, 854 uint32_t index, 855 uintptr_t p1, 856 uintptr_t p2); 857 858kern_return_t 859IOConnectTrap3(io_connect_t connect, 860 uint32_t index, 861 uintptr_t p1, 862 uintptr_t p2, 863 uintptr_t p3); 864 865kern_return_t 866IOConnectTrap4(io_connect_t connect, 867 uint32_t index, 868 uintptr_t p1, 869 uintptr_t p2, 870 uintptr_t p3, 871 uintptr_t p4); 872 873kern_return_t 874IOConnectTrap5(io_connect_t connect, 875 uint32_t index, 876 uintptr_t p1, 877 uintptr_t p2, 878 uintptr_t p3, 879 uintptr_t p4, 880 uintptr_t p5); 881 882kern_return_t 883IOConnectTrap6(io_connect_t connect, 884 uint32_t index, 885 uintptr_t p1, 886 uintptr_t p2, 887 uintptr_t p3, 888 uintptr_t p4, 889 uintptr_t p5, 890 uintptr_t p6); 891 892/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 893 894/*! @function IOConnectAddClient 895 @abstract Inform a connection of a second connection. 896 @discussion This is a generic method to inform a family connection of a second connection, and is rarely used. 897 @param connect The connect handle created by IOServiceOpen. 898 @param client Another connect handle created by IOServiceOpen. 899 @result A kern_return_t error code returned by the family. */ 900 901kern_return_t 902IOConnectAddClient( 903 io_connect_t connect, 904 io_connect_t client ); 905 906/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 907 908/* 909 * IORegistry accessors 910 */ 911 912/*! @function IORegistryGetRootEntry 913 @abstract Return a handle to the registry root. 914 @discussion This method provides an accessor to the root of the registry for the machine. The root may be passed to a registry iterator when iterating a plane, and contains properties that describe the available planes, and diagnostic information for IOKit. 915 @param masterPort The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port. 916 @result A handle to the IORegistryEntry root instance, to be released with IOObjectRelease by the caller, or MACH_PORT_NULL on failure. */ 917 918io_registry_entry_t 919IORegistryGetRootEntry( 920 mach_port_t masterPort ); 921 922/*! @function IORegistryEntryFromPath 923 @abstract Looks up a registry entry by path. 924 @discussion This function parses paths to lookup registry entries. The path should begin with '<plane name>:' If there are characters remaining unparsed after an entry has been looked up, this is considered an invalid lookup. Paths are further documented in IORegistryEntry.h 925 @param masterPort The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port. 926 @param path A C-string path. 927 @result A handle to the IORegistryEntry witch was found with the path, to be released with IOObjectRelease by the caller, or MACH_PORT_NULL on failure. */ 928 929io_registry_entry_t 930IORegistryEntryFromPath( 931 mach_port_t masterPort, 932 const io_string_t path ); 933 934// options for IORegistryCreateIterator(), IORegistryEntryCreateIterator, IORegistryEntrySearchCFProperty() 935enum { 936 kIORegistryIterateRecursively = 0x00000001, 937 kIORegistryIterateParents = 0x00000002 938}; 939 940/*! @function IORegistryCreateIterator 941 @abstract Create an iterator rooted at the registry root. 942 @discussion This method creates an IORegistryIterator in the kernel that is set up with options to iterate children of the registry root entry, and to recurse automatically into entries as they are returned, or only when instructed with calls to IORegistryIteratorEnterEntry. The iterator object keeps track of entries that have been recursed into previously to avoid loops. 943 @param masterPort The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port. 944 @param plane The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane. 945 @param options kIORegistryIterateRecursively may be set to recurse automatically into each entry as it is returned from IOIteratorNext calls on the registry iterator. 946 @param iterator A created iterator handle, to be released by the caller when it has finished with it. 947 @result A kern_return_t error code. */ 948 949kern_return_t 950IORegistryCreateIterator( 951 mach_port_t masterPort, 952 const io_name_t plane, 953 IOOptionBits options, 954 io_iterator_t * iterator ); 955 956/*! @function IORegistryEntryCreateIterator 957 @abstract Create an iterator rooted at a given registry entry. 958 @discussion This method creates an IORegistryIterator in the kernel that is set up with options to iterate children or parents of a root entry, and to recurse automatically into entries as they are returned, or only when instructed with calls to IORegistryIteratorEnterEntry. The iterator object keeps track of entries that have been recursed into previously to avoid loops. 959 @param entry The root entry to begin the iteration at. 960 @param plane The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane. 961 @param options kIORegistryIterateRecursively may be set to recurse automatically into each entry as it is returned from IOIteratorNext calls on the registry iterator. kIORegistryIterateParents may be set to iterate the parents of each entry, by default the children are iterated. 962 @param iterator A created iterator handle, to be released by the caller when it has finished with it. 963 @result A kern_return_t error code. */ 964 965kern_return_t 966IORegistryEntryCreateIterator( 967 io_registry_entry_t entry, 968 const io_name_t plane, 969 IOOptionBits options, 970 io_iterator_t * iterator ); 971 972/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 973 974/* 975 * IORegistryIterator, subclass of IOIterator 976 */ 977 978/*! @function IORegistryIteratorEnterEntry 979 @abstract Recurse into the current entry in the registry iteration. 980 @discussion This method makes the current entry, ie. the last entry returned by IOIteratorNext, the root in a new level of recursion. 981 @result A kern_return_t error code. */ 982 983kern_return_t 984IORegistryIteratorEnterEntry( 985 io_iterator_t iterator ); 986 987/*! @function IORegistryIteratorExitEntry 988 @abstract Exits a level of recursion, restoring the current entry. 989 @discussion This method undoes an IORegistryIteratorEnterEntry, restoring the current entry. If there are no more levels of recursion to exit false is returned, otherwise true is returned. 990 @result kIOReturnSuccess if a level of recursion was undone, kIOReturnNoDevice if no recursive levels are left in the iteration. */ 991 992kern_return_t 993IORegistryIteratorExitEntry( 994 io_iterator_t iterator ); 995 996/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 997 998/* 999 * IORegistryEntry, subclass of IOObject 1000 */ 1001 1002/*! @function IORegistryEntryGetName 1003 @abstract Returns a C-string name assigned to a registry entry. 1004 @discussion Registry entries can be named in a particular plane, or globally. This function returns the entry's global name. The global name defaults to the entry's meta class name if it has not been named. 1005 @param entry The registry entry handle whose name to look up. 1006 @param name The caller's buffer to receive the name. 1007 @result A kern_return_t error code. */ 1008 1009kern_return_t 1010IORegistryEntryGetName( 1011 io_registry_entry_t entry, 1012 io_name_t name ); 1013 1014/*! @function IORegistryEntryGetNameInPlane 1015 @abstract Returns a C-string name assigned to a registry entry, in a specified plane. 1016 @discussion Registry entries can be named in a particular plane, or globally. This function returns the entry's name in the specified plane or global name if it has not been named in that plane. The global name defaults to the entry's meta class name if it has not been named. 1017 @param entry The registry entry handle whose name to look up. 1018 @param plane The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane. 1019 @param name The caller's buffer to receive the name. 1020 @result A kern_return_t error code. */ 1021 1022kern_return_t 1023IORegistryEntryGetNameInPlane( 1024 io_registry_entry_t entry, 1025 const io_name_t plane, 1026 io_name_t name ); 1027 1028/*! @function IORegistryEntryGetLocationInPlane 1029 @abstract Returns a C-string location assigned to a registry entry, in a specified plane. 1030 @discussion Registry entries can given a location string in a particular plane, or globally. If the entry has had a location set in the specified plane that location string will be returned, otherwise the global location string is returned. If no global location string has been set, an error is returned. 1031 @param entry The registry entry handle whose name to look up. 1032 @param plane The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane. 1033 @param location The caller's buffer to receive the location string. 1034 @result A kern_return_t error code. */ 1035 1036kern_return_t 1037IORegistryEntryGetLocationInPlane( 1038 io_registry_entry_t entry, 1039 const io_name_t plane, 1040 io_name_t location ); 1041 1042/*! @function IORegistryEntryGetPath 1043 @abstract Create a path for a registry entry. 1044 @discussion The path for a registry entry is copied to the caller's buffer. The path describes the entry's attachment in a particular plane, which must be specified. The path begins with the plane name followed by a colon, and then followed by '/' separated path components for each of the entries between the root and the registry entry. An alias may also exist for the entry, and will be returned if available. 1045 @param entry The registry entry handle whose path to look up. 1046 @param plane The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane. 1047 @param path A char buffer allocated by the caller. 1048 @result IORegistryEntryGetPath will fail if the entry is not attached in the plane, or if the buffer is not large enough to contain the path. */ 1049 1050kern_return_t 1051IORegistryEntryGetPath( 1052 io_registry_entry_t entry, 1053 const io_name_t plane, 1054 io_string_t path ); 1055 1056/*! @function IORegistryEntryGetRegistryEntryID 1057 @abstract Returns an ID for the registry entry that is global to all tasks. 1058 @discussion The entry ID returned by IORegistryEntryGetRegistryEntryID can be used to identify a registry entry across all tasks. A registry entry may be looked up by its entryID by creating a matching dictionary with IORegistryEntryIDMatching() to be used with the IOKit matching functions. The ID is valid only until the machine reboots. 1059 @param entry The registry entry handle whose ID to look up. 1060 @param entryID The resulting ID. 1061 @result A kern_return_t error code. */ 1062 1063kern_return_t 1064IORegistryEntryGetRegistryEntryID( 1065 io_registry_entry_t entry, 1066 uint64_t * entryID ); 1067 1068/*! @function IORegistryEntryCreateCFProperties 1069 @abstract Create a CF dictionary representation of a registry entry's property table. 1070 @discussion This function creates an instantaneous snapshot of a registry entry's property table, creating a CFDictionary analogue in the caller's task. Not every object available in the kernel is represented as a CF container; currently OSDictionary, OSArray, OSSet, OSSymbol, OSString, OSData, OSNumber, OSBoolean are created as their CF counterparts. 1071 @param entry The registry entry handle whose property table to copy. 1072 @param properties A CFDictionary is created and returned the caller on success. The caller should release with CFRelease. 1073 @param allocator The CF allocator to use when creating the CF containers. 1074 @param options No options are currently defined. 1075 @result A kern_return_t error code. */ 1076 1077kern_return_t 1078IORegistryEntryCreateCFProperties( 1079 io_registry_entry_t entry, 1080 CFMutableDictionaryRef * properties, 1081 CFAllocatorRef allocator, 1082 IOOptionBits options ); 1083 1084/*! @function IORegistryEntryCreateCFProperty 1085 @abstract Create a CF representation of a registry entry's property. 1086 @discussion This function creates an instantaneous snapshot of a registry entry property, creating a CF container analogue in the caller's task. Not every object available in the kernel is represented as a CF container; currently OSDictionary, OSArray, OSSet, OSSymbol, OSString, OSData, OSNumber, OSBoolean are created as their CF counterparts. 1087 @param entry The registry entry handle whose property to copy. 1088 @param key A CFString specifying the property name. 1089 @param allocator The CF allocator to use when creating the CF container. 1090 @param options No options are currently defined. 1091 @result A CF container is created and returned the caller on success. The caller should release with CFRelease. */ 1092 1093CFTypeRef 1094IORegistryEntryCreateCFProperty( 1095 io_registry_entry_t entry, 1096 CFStringRef key, 1097 CFAllocatorRef allocator, 1098 IOOptionBits options ); 1099 1100/*! @function IORegistryEntrySearchCFProperty 1101 @abstract Create a CF representation of a registry entry's property. 1102 @discussion This function creates an instantaneous snapshot of a registry entry property, creating a CF container analogue in the caller's task. Not every object available in the kernel is represented as a CF container; currently OSDictionary, OSArray, OSSet, OSSymbol, OSString, OSData, OSNumber, OSBoolean are created as their CF counterparts. 1103This function will search for a property, starting first with specified registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the same semantics as IORegistryEntryCreateCFProperty. The iteration keeps track of entries that have been recursed into previously to avoid loops. 1104 @param entry The registry entry at which to start the search. 1105 @param plane The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane. 1106 @param key A CFString specifying the property name. 1107 @param allocator The CF allocator to use when creating the CF container. 1108 @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard IORegistryEntryCreateCFProperty() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children. 1109 @result A CF container is created and returned the caller on success. The caller should release with CFRelease. */ 1110 1111CFTypeRef 1112IORegistryEntrySearchCFProperty( 1113 io_registry_entry_t entry, 1114 const io_name_t plane, 1115 CFStringRef key, 1116 CFAllocatorRef allocator, 1117 IOOptionBits options ) CF_RETURNS_RETAINED; 1118 1119/* @function IORegistryEntryGetProperty - deprecated, 1120 use IORegistryEntryCreateCFProperty */ 1121 1122kern_return_t 1123IORegistryEntryGetProperty( 1124 io_registry_entry_t entry, 1125 const io_name_t propertyName, 1126 io_struct_inband_t buffer, 1127 uint32_t * size ); 1128 1129/*! @function IORegistryEntrySetCFProperties 1130 @abstract Set CF container based properties in a registry entry. 1131 @discussion This is a generic method to pass a CF container of properties to an object in the registry. Setting properties in a registry entry is not generally supported, it is more common to support IOConnectSetCFProperties for connection based property setting. The properties are interpreted by the object. 1132 @param entry The registry entry whose properties to set. 1133 @param properties A CF container - commonly a CFDictionary but this is not enforced. The container should consist of objects which are understood by IOKit - these are currently : CFDictionary, CFArray, CFSet, CFString, CFData, CFNumber, CFBoolean, and are passed in the kernel as the corresponding OSDictionary etc. objects. 1134 @result A kern_return_t error code returned by the object. */ 1135 1136kern_return_t 1137IORegistryEntrySetCFProperties( 1138 io_registry_entry_t entry, 1139 CFTypeRef properties ); 1140 1141/*! @function IORegistryEntrySetCFProperty 1142 @abstract Set a CF container based property in a registry entry. 1143 @discussion This is a generic method to pass a CF container as a property to an object in the registry. Setting properties in a registry entry is not generally supported, it is more common to support IOConnectSetCFProperty for connection based property setting. The property is interpreted by the object. 1144 @param entry The registry entry whose property to set. 1145 @param propertyName The name of the property as a CFString. 1146 @param property A CF container - should consist of objects which are understood by IOKit - these are currently : CFDictionary, CFArray, CFSet, CFString, CFData, CFNumber, CFBoolean, and are passed in the kernel as the corresponding OSDictionary etc. objects. 1147 @result A kern_return_t error code returned by the object. */ 1148 1149kern_return_t 1150IORegistryEntrySetCFProperty( 1151 io_registry_entry_t entry, 1152 CFStringRef propertyName, 1153 CFTypeRef property ); 1154 1155/*! @function IORegistryEntryGetChildIterator 1156 @abstract Returns an iterator over an registry entry's child entries in a plane. 1157 @discussion This method creates an iterator which will return each of a registry entry's child entries in a specified plane. 1158 @param entry The registry entry whose children to iterate over. 1159 @param plane The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane. 1160 @param iterator The created iterator over the children of the entry, on success. The iterator must be released when the iteration is finished. 1161 @result A kern_return_t error code. */ 1162 1163kern_return_t 1164IORegistryEntryGetChildIterator( 1165 io_registry_entry_t entry, 1166 const io_name_t plane, 1167 io_iterator_t * iterator ); 1168 1169/*! @function IORegistryEntryGetChildEntry 1170 @abstract Returns the first child of a registry entry in a plane. 1171 @discussion This function will return the child which first attached to a registry entry in a plane. 1172 @param entry The registry entry whose child to look up. 1173 @param plane The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane. 1174 @param child The first child of the registry entry, on success. The child must be released by the caller. 1175 @result A kern_return_t error code. */ 1176 1177kern_return_t 1178IORegistryEntryGetChildEntry( 1179 io_registry_entry_t entry, 1180 const io_name_t plane, 1181 io_registry_entry_t * child ); 1182 1183/*! @function IORegistryEntryGetParentIterator 1184 @abstract Returns an iterator over an registry entry's parent entries in a plane. 1185 @discussion This method creates an iterator which will return each of a registry entry's parent entries in a specified plane. 1186 @param entry The registry entry whose parents to iterate over. 1187 @param plane The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane. 1188 @param iterator The created iterator over the parents of the entry, on success. The iterator must be released when the iteration is finished. 1189 @result A kern_return_t error. */ 1190 1191kern_return_t 1192IORegistryEntryGetParentIterator( 1193 io_registry_entry_t entry, 1194 const io_name_t plane, 1195 io_iterator_t * iterator ); 1196 1197/*! @function IORegistryEntryGetParentEntry 1198 @abstract Returns the first parent of a registry entry in a plane. 1199 @discussion This function will return the parent to which the registry entry was first attached in a plane. 1200 @param entry The registry entry whose parent to look up. 1201 @param plane The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane. 1202 @param parent The first parent of the registry entry, on success. The parent must be released by the caller. 1203 @result A kern_return_t error code. */ 1204 1205kern_return_t 1206IORegistryEntryGetParentEntry( 1207 io_registry_entry_t entry, 1208 const io_name_t plane, 1209 io_registry_entry_t * parent ); 1210 1211/*! @function IORegistryEntryInPlane 1212 @abstract Determines if the registry entry is attached in a plane. 1213 @discussion This method determines if the entry is attached in a plane to any other entry. 1214 @param entry The registry entry. 1215 @param plane The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane. 1216 @result If the entry has a parent in the plane, true is returned, otherwise false is returned. */ 1217 1218boolean_t 1219IORegistryEntryInPlane( 1220 io_registry_entry_t entry, 1221 const io_name_t plane ); 1222 1223/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 1224 1225/* 1226 * Matching dictionary creation helpers 1227 */ 1228 1229/*! @function IOServiceMatching 1230 @abstract Create a matching dictionary that specifies an IOService class match. 1231 @discussion A very common matching criteria for IOService is based on its class. IOServiceMatching will create a matching dictionary that specifies any IOService of a class, or its subclasses. The class is specified by C-string name. 1232 @param name The class name, as a const C-string. Class matching is successful on IOService's of this class or any subclass. 1233 @result The matching dictionary created, is returned on success, or zero on failure. The dictionary is commonly passed to IOServiceGetMatchingServices or IOServiceAddNotification which will consume a reference, otherwise it should be released with CFRelease by the caller. */ 1234 1235CFMutableDictionaryRef 1236IOServiceMatching( 1237 const char * name ); 1238 1239/*! @function IOServiceNameMatching 1240 @abstract Create a matching dictionary that specifies an IOService name match. 1241 @discussion A common matching criteria for IOService is based on its name. IOServiceNameMatching will create a matching dictionary that specifies an IOService with a given name. Some IOServices created from the device tree will perform name matching on the standard compatible, name, model properties. 1242 @param name The IOService name, as a const C-string. 1243 @result The matching dictionary created, is returned on success, or zero on failure. The dictionary is commonly passed to IOServiceGetMatchingServices or IOServiceAddNotification which will consume a reference, otherwise it should be released with CFRelease by the caller. */ 1244 1245CFMutableDictionaryRef 1246IOServiceNameMatching( 1247 const char * name ); 1248 1249/*! @function IOBSDNameMatching 1250 @abstract Create a matching dictionary that specifies an IOService match based on BSD device name. 1251 @discussion IOServices that represent BSD devices have an associated BSD name. This function creates a matching dictionary that will match IOService's with a given BSD name. 1252 @param masterPort The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port. 1253 @param options No options are currently defined. 1254 @param bsdName The BSD name, as a const char *. 1255 @result The matching dictionary created, is returned on success, or zero on failure. The dictionary is commonly passed to IOServiceGetMatchingServices or IOServiceAddNotification which will consume a reference, otherwise it should be released with CFRelease by the caller. */ 1256 1257CFMutableDictionaryRef 1258IOBSDNameMatching( 1259 mach_port_t masterPort, 1260 uint32_t options, 1261 const char * bsdName ); 1262 1263CFMutableDictionaryRef 1264IOOpenFirmwarePathMatching( 1265 mach_port_t masterPort, 1266 uint32_t options, 1267 const char * path ) DEPRECATED_ATTRIBUTE; 1268 1269/*! @function IORegistryEntryIDMatching 1270 @abstract Create a matching dictionary that specifies an IOService match based on a registry entry ID. 1271 @discussion This function creates a matching dictionary that will match a registered, active IOService found with the given registry entry ID. The entry ID for a registry entry is returned by IORegistryEntryGetRegistryEntryID(). 1272 @param entryID The registry entry ID to be found. 1273 @result The matching dictionary created, is returned on success, or zero on failure. The dictionary is commonly passed to IOServiceGetMatchingServices or IOServiceAddNotification which will consume a reference, otherwise it should be released with CFRelease by the caller. */ 1274 1275CFMutableDictionaryRef 1276IORegistryEntryIDMatching( 1277 uint64_t entryID ); 1278 1279/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 1280 1281kern_return_t 1282IOServiceOFPathToBSDName(mach_port_t masterPort, 1283 const io_name_t openFirmwarePath, 1284 io_name_t bsdName) DEPRECATED_ATTRIBUTE; 1285 1286/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 1287 1288/*! @typedef IOAsyncCallback0 1289 @abstract standard callback function for asynchronous I/O requests with 1290 no extra arguments beyond a refcon and result code. 1291 @param refcon The refcon passed into the original I/O request 1292 @param result The result of the I/O operation 1293*/ 1294typedef void (*IOAsyncCallback0)(void *refcon, IOReturn result); 1295 1296/*! @typedef IOAsyncCallback1 1297 @abstract standard callback function for asynchronous I/O requests with 1298 one extra argument beyond a refcon and result code. 1299 This is often a count of the number of bytes transferred 1300 @param refcon The refcon passed into the original I/O request 1301 @param result The result of the I/O operation 1302 @param arg0 Extra argument 1303*/ 1304typedef void (*IOAsyncCallback1)(void *refcon, IOReturn result, void *arg0); 1305 1306/*! @typedef IOAsyncCallback2 1307 @abstract standard callback function for asynchronous I/O requests with 1308 two extra arguments beyond a refcon and result code. 1309 @param refcon The refcon passed into the original I/O request 1310 @param result The result of the I/O operation 1311 @param arg0 Extra argument 1312 @param arg1 Extra argument 1313*/ 1314typedef void (*IOAsyncCallback2)(void *refcon, IOReturn result, void *arg0, void *arg1); 1315 1316/*! @typedef IOAsyncCallback 1317 @abstract standard callback function for asynchronous I/O requests with 1318 lots of extra arguments beyond a refcon and result code. 1319 @param refcon The refcon passed into the original I/O request 1320 @param result The result of the I/O operation 1321 @param args Array of extra arguments 1322 @param numArgs Number of extra arguments 1323*/ 1324typedef void (*IOAsyncCallback)(void *refcon, IOReturn result, void **args, 1325 uint32_t numArgs); 1326 1327 1328/* Internal use */ 1329 1330kern_return_t 1331OSGetNotificationFromMessage( 1332 mach_msg_header_t * msg, 1333 uint32_t index, 1334 uint32_t * type, 1335 uintptr_t * reference, 1336 void ** content, 1337 vm_size_t * size ); 1338 1339/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 1340 1341/* Internal use */ 1342 1343kern_return_t 1344IOCatalogueSendData( 1345 mach_port_t masterPort, 1346 uint32_t flag, 1347 const char *buffer, 1348 uint32_t size ); 1349 1350kern_return_t 1351IOCatalogueTerminate( 1352 mach_port_t masterPort, 1353 uint32_t flag, 1354 io_name_t description ); 1355 1356kern_return_t 1357IOCatalogueGetData( 1358 mach_port_t masterPort, 1359 uint32_t flag, 1360 char **buffer, 1361 uint32_t *size ); 1362 1363kern_return_t 1364IOCatalogueModuleLoaded( 1365 mach_port_t masterPort, 1366 io_name_t name ); 1367 1368/* Use IOCatalogueSendData(), with kIOCatalogResetDrivers, to replace catalogue 1369 * rather than emptying it. Doing so keeps instance counts down by uniquing 1370 * existing personalities. 1371 */ 1372kern_return_t 1373IOCatalogueReset( 1374 mach_port_t masterPort, 1375 uint32_t flag ); 1376 1377/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 1378 1379// obsolete API 1380 1381#if !defined(__LP64__) 1382 1383// for Power Mgt 1384 1385typedef struct IOObject IOObject; 1386 1387// for MacOS.app 1388 1389kern_return_t 1390IORegistryDisposeEnumerator( 1391 io_enumerator_t enumerator ) DEPRECATED_ATTRIBUTE; 1392 1393kern_return_t 1394IOMapMemory( 1395 io_connect_t connect, 1396 uint32_t memoryType, 1397 task_port_t intoTask, 1398 vm_address_t * atAddress, 1399 vm_size_t * ofSize, 1400 uint32_t flags ) DEPRECATED_ATTRIBUTE; 1401 1402// for CGS 1403 1404kern_return_t 1405IOCompatibiltyNumber( 1406 mach_port_t connect, 1407 uint32_t * objectNumber ) DEPRECATED_ATTRIBUTE; 1408 1409// Traditional IOUserClient transport routines 1410kern_return_t 1411IOConnectMethodScalarIScalarO( 1412 io_connect_t connect, 1413 uint32_t index, 1414 IOItemCount scalarInputCount, 1415 IOItemCount scalarOutputCount, 1416 ... ) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5; 1417 1418kern_return_t 1419IOConnectMethodScalarIStructureO( 1420 io_connect_t connect, 1421 uint32_t index, 1422 IOItemCount scalarInputCount, 1423 IOByteCount * structureSize, 1424 ... ) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5; 1425 1426kern_return_t 1427IOConnectMethodScalarIStructureI( 1428 io_connect_t connect, 1429 uint32_t index, 1430 IOItemCount scalarInputCount, 1431 IOByteCount structureSize, 1432 ... ) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5; 1433 1434kern_return_t 1435IOConnectMethodStructureIStructureO( 1436 io_connect_t connect, 1437 uint32_t index, 1438 IOItemCount structureInputSize, 1439 IOByteCount * structureOutputSize, 1440 void * inputStructure, 1441 void * ouputStructure ) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5; 1442 1443// Compatability with earlier Mig interface routines 1444#if IOCONNECT_NO_32B_METHODS 1445 1446kern_return_t 1447io_connect_map_memory( 1448 io_connect_t connect, 1449 uint32_t memoryType, 1450 task_port_t intoTask, 1451 vm_address_t *atAddress, 1452 vm_size_t *ofSize, 1453 IOOptionBits options) DEPRECATED_ATTRIBUTE; 1454 1455kern_return_t 1456io_connect_unmap_memory( 1457 io_connect_t connect, 1458 uint32_t memoryType, 1459 task_port_t fromTask, 1460 vm_address_t atAddress) DEPRECATED_ATTRIBUTE; 1461 1462kern_return_t 1463io_connect_method_scalarI_scalarO( 1464 mach_port_t connection, 1465 int selector, 1466 io_scalar_inband_t input, 1467 mach_msg_type_number_t inputCnt, 1468 io_scalar_inband_t output, 1469 mach_msg_type_number_t *outputCnt) DEPRECATED_ATTRIBUTE; 1470 1471kern_return_t 1472io_connect_method_scalarI_structureO( 1473 mach_port_t connection, 1474 int selector, 1475 io_scalar_inband_t input, 1476 mach_msg_type_number_t inputCnt, 1477 io_struct_inband_t output, 1478 mach_msg_type_number_t *outputCnt) DEPRECATED_ATTRIBUTE; 1479 1480kern_return_t 1481io_connect_method_scalarI_structureI( 1482 mach_port_t connection, 1483 int selector, 1484 io_scalar_inband_t input, 1485 mach_msg_type_number_t inputCnt, 1486 io_struct_inband_t inputStruct, 1487 mach_msg_type_number_t inputStructCnt) DEPRECATED_ATTRIBUTE; 1488 1489kern_return_t 1490io_connect_method_structureI_structureO( 1491 mach_port_t connection, 1492 int selector, 1493 io_struct_inband_t input, 1494 mach_msg_type_number_t inputCnt, 1495 io_struct_inband_t output, 1496 mach_msg_type_number_t *outputCnt) DEPRECATED_ATTRIBUTE; 1497 1498kern_return_t 1499io_async_method_scalarI_scalarO( 1500 mach_port_t connection, 1501 mach_port_t wake_port, 1502 io_async_ref_t reference, 1503 mach_msg_type_number_t referenceCnt, 1504 int selector, 1505 io_scalar_inband_t input, 1506 mach_msg_type_number_t inputCnt, 1507 io_scalar_inband_t output, 1508 mach_msg_type_number_t *outputCnt) DEPRECATED_ATTRIBUTE; 1509 1510kern_return_t 1511io_async_method_scalarI_structureO( 1512 mach_port_t connection, 1513 mach_port_t wake_port, 1514 io_async_ref_t reference, 1515 mach_msg_type_number_t referenceCnt, 1516 int selector, 1517 io_scalar_inband_t input, 1518 mach_msg_type_number_t inputCnt, 1519 io_struct_inband_t output, 1520 mach_msg_type_number_t *outputCnt) DEPRECATED_ATTRIBUTE; 1521 1522kern_return_t 1523io_async_method_scalarI_structureI( 1524 mach_port_t connection, 1525 mach_port_t wake_port, 1526 io_async_ref_t reference, 1527 mach_msg_type_number_t referenceCnt, 1528 int selector, 1529 io_scalar_inband_t input, 1530 mach_msg_type_number_t inputCnt, 1531 io_struct_inband_t inputStruct, 1532 mach_msg_type_number_t inputStructCnt) DEPRECATED_ATTRIBUTE; 1533 1534kern_return_t 1535io_async_method_structureI_structureO( 1536 mach_port_t connection, 1537 mach_port_t wake_port, 1538 io_async_ref_t reference, 1539 mach_msg_type_number_t referenceCnt, 1540 int selector, 1541 io_struct_inband_t input, 1542 mach_msg_type_number_t inputCnt, 1543 io_struct_inband_t output, 1544 mach_msg_type_number_t *outputCnt) DEPRECATED_ATTRIBUTE; 1545#endif // IOCONNECT_NO_32B_METHODS 1546 1547#endif /* defined(__LP64__) */ 1548 1549__END_DECLS 1550 1551#endif /* ! _IOKIT_IOKITLIB_H */ 1552