1/* 2 * 3 * @APPLE_LICENSE_HEADER_START@ 4 * 5 * This file contains Original Code and/or Modifications of Original Code 6 * as defined in and that are subject to the Apple Public Source License 7 * Version 2.0 (the 'License'). You may not use this file except in 8 * compliance with the License. Please obtain a copy of the License at 9 * http://www.opensource.apple.com/apsl/ and read it before using this 10 * file. 11 * 12 * The 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, QUIET ENJOYMENT OR NON-INFRINGEMENT. 17 * Please see the License for the specific language governing rights and 18 * limitations under the License. 19 * 20 * @APPLE_LICENSE_HEADER_END@ 21 */ 22 23/*! 24 @header IOUPSPlugIn.h 25 26 IOUPSPlugIn.h is the header that defines the software used by ioupsd in user-space to communicate with 27 UPS devices. 28 <p> 29 <b>NOTE:</b> 30 Kernel extensions should have the following key/value pair in their personality in order to be 31 recognized by ioupsd: 32 <pre> 33 <key>UPSDevice</key> 34 <true/> 35 </pre> 36 </p> 37 <p> 38 To communicate with a UPS device, an instance of IOUPSPlugInInterface (a struct which is defined below) 39 is created. The methods of IOUPSPlugInInterface allow ioupsd to communicate with the device. 40 </p> 41 <p> 42 To obtain an IOUPSPlugInInterface for a UPS device, use the function IOCreatePlugInInterfaceForService() 43 defined in IOKit/IOCFPlugIn.h. (Note the "i" in "PlugIn" is 44 always upper-case.) Quick usage reference:<br> 45 <ul> 46 <li>'service' is a reference to the IOKit registry entry of the kernel object 47 (usually of type IOHIDDevice) representing the device 48 of interest. This reference can be obtained using the functions defined in 49 IOKit/IOKitLib.h.</li> 50 <li>'plugInType' should be CFUUIDGetUUIDBytes(kIOCFPlugInInterfaceID)</li> 51 <li>'interfaceType' should be CFUUIDGetUUIDBytes(kIOUPSPlugInTypeID) when using IOUPSPlugIn</li> 52 </ul> 53 The interface returned by IOCreatePlugInInterfaceForService() should be deallocated using 54 IODestroyPlugInInterface(). Do not call Release() on it. 55 </p> 56*/ 57 58#ifndef _IOKIT_PM_IOUPSPLUGIN_H 59#define _IOKIT_PM_IOUPSPLUGIN_H 60 61#include <CoreFoundation/CoreFoundation.h> 62#include <IOKit/IOCFPlugIn.h> 63 64 65/* 40A57A4E-26A0-11D8-9295-000A958A2C78 */ 66/*! 67 @define kIOUPSPlugInTypeID 68 @discussion Type ID for the IOUPSPlugInInterface. Corresponds to an 69 available UPS device. 70*/ 71#define kIOUPSPlugInTypeID CFUUIDGetConstantUUIDWithBytes(NULL, \ 72 0x40, 0xa5, 0x7a, 0x4e, 0x26, 0xa0, 0x11, 0xd8, \ 73 0x92, 0x95, 0x00, 0x0a, 0x95, 0x8a, 0x2c, 0x78) 74 75/* 63F8BFC4-26A0-11D8-88B4-000A958A2C78 */ 76/*! 77 @define kIOUPSPlugInInterfaceID 78 @discussion Interface ID for the IOUPSPlugInInterface. Corresponds to an 79 available UPS device. 80*/ 81#define kIOUPSPlugInInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 82 0x63, 0xf8, 0xbf, 0xc4, 0x26, 0xa0, 0x11, 0xd8, \ 83 0x88, 0xb4, 0x0, 0xa, 0x95, 0x8a, 0x2c, 0x78) 84 85/* E60E0799-9AA6-49DF-B55B-A5C94BA07A4A */ 86/*! 87 @define kIOUPSPlugInInterfaceID_v140 88 @discussion Interface ID for the IOUPSPlugInInterface. Corresponds to an 89 available UPS device. 90*/ 91#define kIOUPSPlugInInterfaceID_v140 CFUUIDGetConstantUUIDWithBytes(NULL, \ 92 0xe6, 0xe, 0x7, 0x99, 0x9a, 0xa6, 0x49, 0xdf, \ 93 0xb5, 0x5b, 0xa5, 0xc9, 0x4b, 0xa0, 0x7a, 0x4a) 94 95 96/*! 97 @typedef IOUPSEventCallbackFunction 98 @discussion Type and arguments of callout C function that is used when a 99 completion routine is called. This function pointer is set 100 via setEventCallback and is called when an event is available 101 from the UPS. 102 @param target void * pointer to your data, often a pointer to an object. 103 @param result Completion result of desired operation. 104 @param refcon void * pointer to more data. 105 @param sender Interface instance sending the completion routine. 106 @param event CFDictionaryRef containing event data. 107*/ 108typedef void (*IOUPSEventCallbackFunction) 109 (void * target, 110 IOReturn result, 111 void * refcon, 112 void * sender, 113 CFDictionaryRef event); 114 115#define IOUPSPLUGINBASE \ 116 IOReturn (*getProperties)( void * thisPointer, \ 117 CFDictionaryRef * properties); \ 118 IOReturn (*getCapabilities)(void * thisPointer, \ 119 CFSetRef * capabilities); \ 120 IOReturn (*getEvent)( void * thisPointer, \ 121 CFDictionaryRef * event); \ 122 IOReturn (*setEventCallback)(void * thisPointer, \ 123 IOUPSEventCallbackFunction callback, \ 124 void * callbackTarget, \ 125 void * callbackRefcon); \ 126 IOReturn (*sendCommand)( void * thisPointer, \ 127 CFDictionaryRef command) 128 129#define IOUPSPLUGIN_V140 \ 130 IOReturn (*createAsyncEventSource)(void * thisPointer, \ 131 CFTypeRef * source) 132 133 134typedef struct IOUPSPlugInInterface { 135 IUNKNOWN_C_GUTS; 136 IOUPSPLUGINBASE; 137} IOUPSPlugInInterface; 138 139typedef struct IOUPSPlugInInterface_v140 { 140 IUNKNOWN_C_GUTS; 141 IOUPSPLUGINBASE; 142 IOUPSPLUGIN_V140; 143} IOUPSPlugInInterface_v140; 144 145// 146// BEGIN READABLE STRUCTURE DEFINITIONS 147// 148// This portion of uncompiled code provides a more reader friendly representation of 149// the CFPlugin methods defined above. 150 151#if 0 152/*! 153 @interface IOUPSPlugInInterface 154 @discussion Represents and provides management functions for a UPS device. 155*/ 156 157typedef struct IOUPSPlugInInterface { 158 IUNKNOWN_C_GUTS; 159 160 /*! 161 @function getProperties 162 @abstract Used to obtain the properties of the UPS device such as the 163 name and transport. 164 @discussion Property keys are defined in IOPSKeys.h. This is not an 165 allocation method. Thus the caller does not release the 166 CFDictionary that is returned. 167 @param thisPointer The UPS Interface to use. 168 @param properties Pointer to a CFDictionaryRef that contains 169 the properties. 170 @result An IOReturn error code. 171 */ 172 IOReturn (*getProperties)( void * thisPointer, 173 CFDictionaryRef * properties); 174 175 /*! 176 @function getCapabilities 177 @abstract Used to obtain the capabilities of the UPS device. 178 @discussion Keys are defined in IOPSKeys.h and begin with kIOPS. This 179 is not an allocation method. Thus the caller does not 180 release the CFSet that is returned. 181 @param thisPointer The UPS Interface to use. 182 @param capabilities Pointer to a CFSetRef that contains the 183 capabilities. 184 @result An IOReturn error code. 185 */ 186 IOReturn (*getCapabilities)(void * thisPointer, 187 CFSetRef * capabilities); 188 189 /*! 190 @function getEvent 191 @abstract Used to poll the current state of the UPS. 192 @discussion Keys are defined in IOPSKeys.h and begin with kIOPS. This 193 is not an allocation method. Thus the caller does not 194 release the CFDictionary that is returned. 195 @param thisPointer The UPS Interface to use. 196 @param event Pointer to a CFDictionaryRef that contains 197 the current event state. 198 @result An IOReturn error code. 199 */ 200 IOReturn (*getEvent)( void * thisPointer, 201 CFDictionaryRef * event); 202 203 /*! 204 @function setEventCallback 205 @abstract Set the callback that should be called to handle an event 206 from the UPS. 207 @discussion The proivided callback method should be called whenever there 208 is a change of state in the UPS. This should be used in 209 conjunction with createAsyncEventSource. 210 @param thisPointer The UPS Interface to use. 211 @param callback A callback handler of type 212 IOUPSEventCallbackFunction. 213 @param callbackTarget The address to be targeted by this callback. 214 @param callbackRefcon A user specified reference value. This will 215 be passed to all callback functions. 216 @result An IOReturn error code. 217 */ 218 IOReturn (*setEventCallback)(void * thisPointer, 219 IOUPSEventCallbackFunction callback, 220 void * callbackTarget, 221 void * callbackRefcon); 222 223 /*! 224 @function sendCommand 225 @abstract Send a command to the UPS. 226 @discussion Command keys are defined in IOPSKeys.h and begin with 227 kIOPSCommand. An error should be returned if your device does 228 not know how to respond to a command. 229 @param thisPointer The UPS Interface to use. 230 @param command CFDictionaryRef that contains the command. 231 @result An IOReturn error code. 232 */ 233 IOReturn (*sendCommand)( void * thisPointer, 234 CFDictionaryRef command); 235 236 /*! 237 @function createAsyncEventSource 238 @abstract Used to create an async run loop event source of the plugin. 239 @discussion This is an allocation method. Thus the caller must 240 release the object that is returned. 241 @param thisPointer The UPS Interface to use. 242 @param source Pointer to a CFTypeRef. It is expected that this 243 point to either a CFRunLoopSourceRef, a 244 CFRunLoopTimerRef or a CFArray containing the 245 aforementioned types. 246 @result An IOReturn error code. 247 */ 248 IOReturn (*createAsyncEventSource)( void * thisPointer, 249 CFTypeRef * source); 250 251 252} IOUPSPlugInInterface; 253#endif 254 255// END READABLE STRUCTURE DEFINITIONS 256 257#endif /* !_IOKIT_PM_IOUPSPLUGIN_H */ 258