Root/
| Source at commit 1129 created 12 years 11 months ago. By meklort, Change options.o so that it reloads the system config as well. Also change it so that it uses that config for variables (NOTE: if the calue exists in chameleonConfig, it's used instead. | |
|---|---|
| 1 | /*␊ |
| 2 | * Copyright (c) 1998-2010 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 | #ifndef _IOKIT_IOAUDIOCONTROL_H␊ |
| 24 | #define _IOKIT_IOAUDIOCONTROL_H␊ |
| 25 | ␊ |
| 26 | #include <IOKit/IOService.h>␊ |
| 27 | #ifndef IOAUDIOFAMILY_SELF_BUILD␊ |
| 28 | #include <IOKit/audio/IOAudioEngine.h>␊ |
| 29 | #else␊ |
| 30 | #include "IOAudioEngine.h"␊ |
| 31 | #endif␊ |
| 32 | ␊ |
| 33 | class IOAudioPort;␊ |
| 34 | class OSDictionary;␊ |
| 35 | class OSSet;␊ |
| 36 | class IOAudioUserClient;␊ |
| 37 | class IOAudioControlUserClient;␊ |
| 38 | class IOWorkLoop;␊ |
| 39 | class IOCommandGate;␊ |
| 40 | ␊ |
| 41 | /*!␊ |
| 42 | * @class IOAudioControl␊ |
| 43 | * @abstract Represents any controllable attribute of an IOAudioDevice.␊ |
| 44 | * @discussion An IOAudioControl instance may belong to one IOAudioPort. Additionally, it may associated ␊ |
| 45 | * with an IOAudioEngine as a default control for that IOAudioEngine.␊ |
| 46 | *␊ |
| 47 | * When its value changes, it sends a notification to the CoreAudio.framework (HAL). It also makes a call␊ |
| 48 | * to the ValueChangeHandler.␊ |
| 49 | *␊ |
| 50 | * The base IOAudioControl class contains a type, a value and a channel ID representing the channel(s) which ␊ |
| 51 | * the control acts on. It may also contain a readable format for the name of the channel as well as a ␊ |
| 52 | * control ID that can be used to identify unique controls. Additionally it may contain a subType and a usage. ␊ |
| 53 | * Each type has its own set of possible subTypes. There currently four different control types defined: ␊ |
| 54 | * kIOAudioControlTypeLevel, kIOAudioControlTypeToggle, kIOAudioControlTypeSelector. ␊ |
| 55 | * Each one is represented by a subclass of IOAudioControl: IOAudioLevelControl, IOAudioToggleControl, ␊ |
| 56 | * IOAudioSelectorControl. The level control defines a range of allowed values and has ␊ |
| 57 | * a defined subtype of kIOAudioLevelControlSubTypeVolume used to define a volume control. The toggle control ␊ |
| 58 | * allows for a boolean value and has a defined subtype kIOAudioToggleControlSubTypeMute for a mute control. The ␊ |
| 59 | * selector control has a list of allowed selections with a value and description for each allowed selection and ␊ |
| 60 | * has the following sub types: kIOAudioSelectorControlSubTypeOutput for an output selector and ␊ |
| 61 | * kIOAudioSelectorControlSubTypeInput for an input selector. See the subclass documentation for a more ␊ |
| 62 | * complete description of each ␊ |
| 63 | * ␊ |
| 64 | * There are enums for default channel ID values and common channel names in IOAudioTypes.h. The channel ID ␊ |
| 65 | * values are prefixed with 'kIOAudioControlChannelID' and the common channel names are prefixed with␊ |
| 66 | * 'kIOAudioControlChannelName'. All of the attributes of the IOAudioControl are stored in the registry.␊ |
| 67 | * The key used for each attribute is defined in IOAudioTypes.h with the define matching the following␊ |
| 68 | * pattern: 'kIOAudioControl<attribute name>Key'. For example: kIOAudioControlChannelIDKey.␊ |
| 69 | *␊ |
| 70 | * In addition to the existing defined control types, drivers can define their own as well for other purposes.␊ |
| 71 | *␊ |
| 72 | * Changes to the IOAudioControl's value made by the CoreAudio.framework are done through the IORegistry. ␊ |
| 73 | * When the CoreAudio.framework initiates a value change, the control receives a setProperties() message. ␊ |
| 74 | * The setProperties() implementation looks for the property 'IOAudioControlValue' and if present, calls ␊ |
| 75 | * setValue() on the driver's IOWorkLoop with the new value. The setValue() function first checks to see ␊ |
| 76 | * if the new value is different. If so, it calls performValueChange() to call through to the driver␊ |
| 77 | * to make the change in the hardware. If that call succeeds the value is changed and the new value is set␊ |
| 78 | * in the registry. Additionally notifications are sent to all clients that have registered for them.␊ |
| 79 | */␊ |
| 80 | class IOAudioControl : public IOService␊ |
| 81 | {␊ |
| 82 | friend class IOAudioPort;␊ |
| 83 | friend class IOAudioDevice;␊ |
| 84 | friend class IOAudioEngine;␊ |
| 85 | ␊ |
| 86 | OSDeclareDefaultStructors(IOAudioControl)␊ |
| 87 | ␊ |
| 88 | public:␊ |
| 89 | ␊ |
| 90 | /*!␊ |
| 91 | * @typedef IntValueChangeHandler␊ |
| 92 | * @abstract Handler function used to make a notification when a value is to be changed.␊ |
| 93 | * @param target Reference supplied when the handler was registered.␊ |
| 94 | * @param audioControl The IOAudioControl that is changing.␊ |
| 95 | ␉ * @param oldValue The old value of the control.␊ |
| 96 | * @param newValue The new value the control is being changed to.␊ |
| 97 | ␉ * @result Must return kIOReturnSuccess when the hardware is successfully updated.␊ |
| 98 | */␊ |
| 99 | typedef IOReturn (*IntValueChangeHandler)(OSObject *target, IOAudioControl *audioControl, SInt32 oldValue, SInt32 newValue);␊ |
| 100 | typedef IOReturn (*DataValueChangeHandler)(OSObject *target, IOAudioControl *audioControl, const void *oldData, UInt32 oldDataSize, const void *newData, UInt32 newDataSize);␊ |
| 101 | typedef IOReturn (*ObjectValueChangeHandler)(OSObject *target, IOAudioControl *audioControl, OSObject *oldValue, OSObject *newValue);␊ |
| 102 | ␊ |
| 103 | protected:␊ |
| 104 | /*! @var workLoop ␊ |
| 105 | The IOWorkLoop for the audio driver - shared from the IOAudioDevice. ␊ |
| 106 | */␊ |
| 107 | IOWorkLoop ␉␉*workLoop;␊ |
| 108 | /*! @var commandGate ␊ |
| 109 | The IOCommandGate for this control - attached to the driver's IOWorkLoop.␊ |
| 110 | */␊ |
| 111 | IOCommandGate␉*commandGate;␊ |
| 112 | ␊ |
| 113 | /*! @var isStarted ␊ |
| 114 | Internal state keeping track of when the IOAudioControl has been started. ␊ |
| 115 | */␊ |
| 116 | bool␉␉isStarted;␊ |
| 117 | ␊ |
| 118 | /*! @var controlID ␊ |
| 119 | An optional identifier that can be used to identify the control. ␊ |
| 120 | */␊ |
| 121 | UInt32 ␉␉controlID;␊ |
| 122 | /*! @var channelID ␊ |
| 123 | The ID of the channel this control affects - may be kIOAudioControlChannelIDAll if it represents all channels.␊ |
| 124 | */␊ |
| 125 | UInt32␉␉channelID;␊ |
| 126 | ␊ |
| 127 | UInt32␉␉type;␊ |
| 128 | UInt32␉␉subType;␊ |
| 129 | UInt32␉␉usage;␊ |
| 130 | ␊ |
| 131 | OSObject␉*value;␊ |
| 132 | ␊ |
| 133 | typedef enum {␊ |
| 134 | kIntValueChangeHandler,␊ |
| 135 | kDataValueChangeHandler,␊ |
| 136 | kObjectValueChangeHandler␊ |
| 137 | } ValueChangeHandlerType;␊ |
| 138 | ␊ |
| 139 | ValueChangeHandlerType valueChangeHandlerType;␊ |
| 140 | ␊ |
| 141 | union {␊ |
| 142 | IntValueChangeHandler␉␉intHandler;␊ |
| 143 | DataValueChangeHandler␉␉dataHandler;␊ |
| 144 | ObjectValueChangeHandler␉objectHandler;␊ |
| 145 | } valueChangeHandler;␊ |
| 146 | ␊ |
| 147 | OSObject␉*valueChangeTarget;␊ |
| 148 | ␊ |
| 149 | /*! @var clients␊ |
| 150 | A list of user clients that have requested value change notifications. ␊ |
| 151 | */ ␊ |
| 152 | OSSet␉␉*userClients;␊ |
| 153 | ␊ |
| 154 | protected:␊ |
| 155 | struct ExpansionData {␊ |
| 156 | ␉␉IOAudioEngine *␉␉␉␉providerEngine;␊ |
| 157 | ␉␉OSArray *␉␉␉␉␉notificationQueue;␊ |
| 158 | ␉};␊ |
| 159 | ␊ |
| 160 | ExpansionData *reserved;␊ |
| 161 | ␊ |
| 162 | public:␊ |
| 163 | ␉// OSMetaClassDeclareReservedUsed(IOAudioControl, 0);␊ |
| 164 | ␉virtual void sendChangeNotification(UInt32 notificationType);␊ |
| 165 | ␊ |
| 166 | ␉// OSMetaClassDeclareReservedUsed(IOAudioControl, 1);␊ |
| 167 | /*!␊ |
| 168 | ␉ * @function setReadOnlyFlag␊ |
| 169 | * @abstract Call this function to say that a control is read only.␊ |
| 170 | ␉ * This call cannot be undone, so if a control is only temporarily unsetable,␊ |
| 171 | ␉ * do not use this call but instead return an error from the control handler.␊ |
| 172 | */␊ |
| 173 | ␉virtual void setReadOnlyFlag();␊ |
| 174 | ␊ |
| 175 | ␉// OSMetaClassDeclareReservedUsed(IOAudioControl, 2);␊ |
| 176 | ␉virtual void sendQueuedNotifications(void);␊ |
| 177 | ␊ |
| 178 | ␉// OSMetaClassDeclareReservedUsed(IOAudioControl, 3);␊ |
| 179 | /*!␊ |
| 180 | * @function createUserClient␊ |
| 181 | * @abstract Creates a new IOAudioControlUserClient instance.␊ |
| 182 | * @discussion This function is called by newUserClient() to create a new IOAudioControlUserClient instance. This function may be overridden by subclasses that need to add functionality␊ |
| 183 | * to the IOAudioControlUserClient. In that case, they must subclass IOAudioControlUserClient␊ |
| 184 | * and return a new, initialized instance of that subclass.␊ |
| 185 | ␉ * A derived class that requires overriding of createUserClient should override the version with the properties␊ |
| 186 | ␉ * parameter for Intel targets, and without the properties parameter for PPC targets. The #if __i386__ directive␊ |
| 187 | ␉ * can be used to select between the two behaviors.␊ |
| 188 | * @param task The task requesting the new user client.␊ |
| 189 | * @param securityID Optional security paramater passed in by the client - ignored.␊ |
| 190 | * @param type Optional user client type passed in by the client.␊ |
| 191 | * @param newUserClient The IOAudioControlUserClient * must be stored in this param on a successful␊ |
| 192 | * completion.␊ |
| 193 | * @param properties A dictionary of additional properties for the connection.␊ |
| 194 | * @result Returns kIOReturnSuccess on success.␊ |
| 195 | */␊ |
| 196 | virtual IOReturn createUserClient(task_t task, void *securityID, UInt32 type, IOAudioControlUserClient **newUserClient, OSDictionary *properties);␊ |
| 197 | ␊ |
| 198 | private:␊ |
| 199 | OSMetaClassDeclareReservedUsed(IOAudioControl, 0);␊ |
| 200 | OSMetaClassDeclareReservedUsed(IOAudioControl, 1);␊ |
| 201 | OSMetaClassDeclareReservedUsed(IOAudioControl, 2);␊ |
| 202 | OSMetaClassDeclareReservedUsed(IOAudioControl, 3);␊ |
| 203 | ␊ |
| 204 | OSMetaClassDeclareReservedUnused(IOAudioControl, 4);␊ |
| 205 | OSMetaClassDeclareReservedUnused(IOAudioControl, 5);␊ |
| 206 | OSMetaClassDeclareReservedUnused(IOAudioControl, 6);␊ |
| 207 | OSMetaClassDeclareReservedUnused(IOAudioControl, 7);␊ |
| 208 | OSMetaClassDeclareReservedUnused(IOAudioControl, 8);␊ |
| 209 | OSMetaClassDeclareReservedUnused(IOAudioControl, 9);␊ |
| 210 | OSMetaClassDeclareReservedUnused(IOAudioControl, 10);␊ |
| 211 | OSMetaClassDeclareReservedUnused(IOAudioControl, 11);␊ |
| 212 | OSMetaClassDeclareReservedUnused(IOAudioControl, 12);␊ |
| 213 | OSMetaClassDeclareReservedUnused(IOAudioControl, 13);␊ |
| 214 | OSMetaClassDeclareReservedUnused(IOAudioControl, 14);␊ |
| 215 | OSMetaClassDeclareReservedUnused(IOAudioControl, 15);␊ |
| 216 | OSMetaClassDeclareReservedUnused(IOAudioControl, 16);␊ |
| 217 | OSMetaClassDeclareReservedUnused(IOAudioControl, 17);␊ |
| 218 | OSMetaClassDeclareReservedUnused(IOAudioControl, 18);␊ |
| 219 | OSMetaClassDeclareReservedUnused(IOAudioControl, 19);␊ |
| 220 | OSMetaClassDeclareReservedUnused(IOAudioControl, 20);␊ |
| 221 | OSMetaClassDeclareReservedUnused(IOAudioControl, 21);␊ |
| 222 | OSMetaClassDeclareReservedUnused(IOAudioControl, 22);␊ |
| 223 | OSMetaClassDeclareReservedUnused(IOAudioControl, 23);␊ |
| 224 | ␊ |
| 225 | public:␊ |
| 226 | ␊ |
| 227 | /*!␊ |
| 228 | * @function withAttributes␊ |
| 229 | * @abstract Static function that allocates a new IOAudioControl with the given attributes.␊ |
| 230 | * @param type The type of the control. Common, known types are defined in IOAudioTypes.h. They currently␊ |
| 231 | * consist of kIOAudioControlTypeLevel, kIOAudioControlTypeToggle, kIOAudioControlTypeSelector.␊ |
| 232 | * @param channelID The ID of the channel(s) that the control acts on. Common IDs are located in IOAudioTypes.h.␊ |
| 233 | * @param channelName An optional name for the channel. Common names are located in IOAudioDefines.h. Any name not␊ |
| 234 | * defined in IOAudioDefines.h must be localized in order to be properly displayed in multiple languages.␊ |
| 235 | * @param cntrlID An optional ID for the control that can be used to uniquely identify controls␊ |
| 236 | * @param subType An optional subType specific to the given type␊ |
| 237 | * @param usage An optional value specifying how the control will be used. Currently defined usages are kIOAudioControlUsageInput, ␊ |
| 238 | * kIOAudioControlUsageOutput and kIOAudioControlUsagePassThru. This value is used when a control is set as a default control␊ |
| 239 | * on an IOAudioEngine.␊ |
| 240 | * @result Returns a newly allocated and initialized IOAudioControl.␊ |
| 241 | */␊ |
| 242 | static IOAudioControl *withAttributes(UInt32 type,␊ |
| 243 | OSObject *initialValue,␊ |
| 244 | UInt32 channelID,␊ |
| 245 | const char *channelName = 0,␊ |
| 246 | UInt32 cntrlID = 0,␊ |
| 247 | UInt32 subType = 0,␊ |
| 248 | UInt32 usage = 0);␊ |
| 249 | ␊ |
| 250 | /*!␊ |
| 251 | * @function init␊ |
| 252 | * @abstract Initializes a newly allocated IOAudioControl with the given attributes.␊ |
| 253 | * @param type The type of the control. Common, known types are defined in IOAudioTypes.h. They currently␊ |
| 254 | * consist of kIOAudioControlTypeLevel, kIOAudioControlTypeToggle, kIOAudioControlTypeSelector.␊ |
| 255 | * @param channelID The ID of the channel(s) that the control acts on. Common IDs are located in IOAudioTypes.h.␊ |
| 256 | * @param channelName An optional name for the channel. Common names are located in IOAudioDefines.h. Any name not␊ |
| 257 | * defined in IOAudioDefines.h must be localized in order to be properly displayed in multiple languages.␊ |
| 258 | * @param cntrlID An optional ID for the control that can be used to uniquely identify controls␊ |
| 259 | * @param subType An optional subType specific to the given type␊ |
| 260 | * @param usage An optional value specifying how the control will be used. Currently defined usages are kIOAudioControlUsageInput, ␊ |
| 261 | * kIOAudioControlUsageOutput and kIOAudioControlUsagePassThru. This value is used when a control is set as a default control␊ |
| 262 | * on an IOAudioEngine.␊ |
| 263 | * @param properties Standard property list passed to the init() function of any new IOService. This dictionary␊ |
| 264 | * gets stored in the registry entry for this instance.␊ |
| 265 | * @result Returns true on success.␊ |
| 266 | */␊ |
| 267 | virtual bool init(UInt32 type,␊ |
| 268 | OSObject *initialValue,␊ |
| 269 | UInt32 channelID,␊ |
| 270 | const char *channelName = 0,␊ |
| 271 | UInt32 cntrlID = 0,␊ |
| 272 | UInt32 subType = 0,␊ |
| 273 | UInt32 usage = 0,␊ |
| 274 | OSDictionary *properties = 0);␊ |
| 275 | ␊ |
| 276 | /*!␊ |
| 277 | * @function free␊ |
| 278 | * @abstract Frees all of the resources allocated by the IOAudioControl.␊ |
| 279 | * @discussion Do not call this directly. This is called automatically by the system when the instance's␊ |
| 280 | * refcount goes to 0. To decrement the refcount, call release() on the object.␊ |
| 281 | */␊ |
| 282 | virtual void free();␊ |
| 283 | ␊ |
| 284 | /*!␊ |
| 285 | * @function start␊ |
| 286 | * @abstract Starts a newly created IOAudioControl.␊ |
| 287 | * @discussion This is called automatically by IOAudioPort when addAudioControl() is called or by IOAudioEngine ␊ |
| 288 | * when addDefaultAudioControl() is called. It will only be called by the first call to either addAudioControl() or␊ |
| 289 | * addDefaultAudioControl().␊ |
| 290 | * @param provider The IOAudioPort or IOAudioEngine that owns this control.␊ |
| 291 | * @result Returns true on success.␊ |
| 292 | */␊ |
| 293 | virtual bool start(IOService *provider);␊ |
| 294 | ␊ |
| 295 | ␉virtual bool attachAndStart(IOService *provider);␊ |
| 296 | ␊ |
| 297 | /*!␊ |
| 298 | * @function getIsStarted␊ |
| 299 | * @abstract Returns true after start() has been called.␊ |
| 300 | * @discussion Used by IOAudioPort and IOAudioEngine to decide if the control needs to be started.␊ |
| 301 | */␊ |
| 302 | virtual bool getIsStarted();␊ |
| 303 | ␊ |
| 304 | /*!␊ |
| 305 | * @function stop␊ |
| 306 | * @abstract Stops the control when the provider is going away.␊ |
| 307 | * @param provider The IOAudioPort or IOAudioEngine that owns this control.␊ |
| 308 | */␊ |
| 309 | virtual void stop(IOService *provider);␊ |
| 310 | ␊ |
| 311 | /*!␊ |
| 312 | * @function getWorkLoop␊ |
| 313 | * @abstract Returns the IOWorkLoop for the whole audio driver.␊ |
| 314 | */␊ |
| 315 | virtual IOWorkLoop *getWorkLoop();␊ |
| 316 | ␊ |
| 317 | /*!␊ |
| 318 | * @function getCommandGate␊ |
| 319 | * @abstract Returns the IOCommandGate for this IOAudioControl.␊ |
| 320 | */␊ |
| 321 | virtual IOCommandGate *getCommandGate();␊ |
| 322 | ␊ |
| 323 | /*!␊ |
| 324 | * @function newUserClient␊ |
| 325 | * @abstract Creates a new user client object for this IOAudioControl instance.␊ |
| 326 | * @discussion This is called automatically by I/O Kit when a user process opens a connection to this␊ |
| 327 | * IOAudioControl. This is typically done when the user process needs to register for value change␊ |
| 328 | * notifications. This implementation allocates a new IOAudioControlUserClient object. There is no␊ |
| 329 | * need to call this directly.␊ |
| 330 | ␉ * A derived class that requires overriding of newUserClient should override the version with the properties␊ |
| 331 | ␉ * parameter for Intel targets, and without the properties parameter for PPC targets. The #if __i386__ directive␊ |
| 332 | ␉ * can be used to select between the two behaviors.␊ |
| 333 | * @param task The task requesting the new user client.␊ |
| 334 | * @param securityID Optional security paramater passed in by the client - ignored.␊ |
| 335 | * @param type Optional user client type passed in by the client - 0 for the default user client type.␊ |
| 336 | * @param handler The new IOUserClient * must be stored in this param on a successful completion.␊ |
| 337 | * @param properties A dictionary of additional properties for the connection.␊ |
| 338 | * @result Returns kIOReturnSuccess on success. May also result kIOReturnError or kIOReturnNoMemory.␊ |
| 339 | */␊ |
| 340 | virtual IOReturn newUserClient(task_t task, void *securityID, UInt32 type, IOUserClient **handler);␊ |
| 341 | virtual IOReturn newUserClient(task_t task, void *securityID, UInt32 type, OSDictionary *properties, IOUserClient **handler);␊ |
| 342 | ␊ |
| 343 | /*!␊ |
| 344 | * @function createUserClient␊ |
| 345 | * @abstract Creates a new IOAudioControlUserClient instance.␊ |
| 346 | * @discussion This function is called by newUserClient() to create a new IOAudioControlUserClient instance. This function may be overridden by subclasses that need to add functionality␊ |
| 347 | * to the IOAudioControlUserClient. In that case, they must subclass IOAudioControlUserClient␊ |
| 348 | * and return a new, initialized instance of that subclass.␊ |
| 349 | ␉ * A derived class that requires overriding of createUserClient should override the version with the properties␊ |
| 350 | ␉ * parameter for Intel targets, and without the properties parameter for PPC targets. The #if __i386__ directive␊ |
| 351 | ␉ * can be used to select between the two behaviors.␊ |
| 352 | * @param task The task requesting the new user client.␊ |
| 353 | * @param securityID Optional security paramater passed in by the client - ignored.␊ |
| 354 | * @param type Optional user client type passed in by the client.␊ |
| 355 | * @param newUserClient The IOAudioControlUserClient * must be stored in this param on a successful␊ |
| 356 | * completion.␊ |
| 357 | * @result Returns kIOReturnSuccess on success.␊ |
| 358 | */␊ |
| 359 | virtual IOReturn createUserClient(task_t task, void *securityID, UInt32 type, IOAudioControlUserClient **newUserClient);␊ |
| 360 | ␊ |
| 361 | /*!␊ |
| 362 | * @function clientClosed␊ |
| 363 | * @abstract Called automatically by the IOAudioControlUserClient when a user client closes its␊ |
| 364 | * connection to the control.␊ |
| 365 | * @param client The user client object that has disconnected.␊ |
| 366 | */␊ |
| 367 | virtual void clientClosed(IOAudioControlUserClient *client);␊ |
| 368 | ␊ |
| 369 | /*!␊ |
| 370 | * @function setProperties␊ |
| 371 | * @abstract Changes a property of this IOService. ␊ |
| 372 | * @discussion This is called when the user client changes a property of this ␊ |
| 373 | * IOAudioControl. In this case it is used to change the value. This function␊ |
| 374 | * looks for that property and then calls setValue() through the IOCommandGate and␊ |
| 375 | * setValueAction().␊ |
| 376 | * @param properties An OSDictionary containing the properties to change.␊ |
| 377 | * @result Returns kIOReturnSuccess on success.␊ |
| 378 | */␊ |
| 379 | virtual IOReturn setProperties(OSObject *properties);␊ |
| 380 | ␊ |
| 381 | virtual void setValueChangeHandler(IntValueChangeHandler intValueChangeHandler, OSObject *target);␊ |
| 382 | virtual void setValueChangeHandler(DataValueChangeHandler dataValueChangeHandler, OSObject *target);␊ |
| 383 | virtual void setValueChangeHandler(ObjectValueChangeHandler objectValueChangeHandler, OSObject *target);␊ |
| 384 | ␊ |
| 385 | virtual void setValueChangeTarget(OSObject *target);␊ |
| 386 | ␊ |
| 387 | /*!␊ |
| 388 | * @function flushValue␊ |
| 389 | * @abstract Forces the control to be flushed out to the hardware.␊ |
| 390 | * @discussion This function calls performValueChange() directly with the current value of the IOAudioControl.␊ |
| 391 | * @result Returns the result of performValueChange() - kIOReturnSuccess on success.␊ |
| 392 | */␊ |
| 393 | virtual IOReturn flushValue();␊ |
| 394 | ␊ |
| 395 | /*!␊ |
| 396 | * @function setValueAction␊ |
| 397 | * @abstract IOCommandGate Action which calls setValue() while holding the IOCommandGate.␊ |
| 398 | * @discussion This is needed to allow setValue() to be called on the IOWorkLoop.␊ |
| 399 | * @param owner The owner of the IOCommandGate (the IOAudioControl in this case).␊ |
| 400 | * @param arg1 The new value for the IOAudioControl.␊ |
| 401 | * @result Returns the result of setValue() - kIOReturnSuccess on success.␊ |
| 402 | */␊ |
| 403 | static IOReturn setValueAction(OSObject *owner, void *arg1, void *arg2, void *arg3, void *arg4);␊ |
| 404 | ␊ |
| 405 | ␉static IOReturn _setValueAction(OSObject *target, void *arg0, void *arg1, void *arg2, void *arg3);␉// <rdar://7529580>␊ |
| 406 | ␉␊ |
| 407 | /*!␊ |
| 408 | * @function setValue␊ |
| 409 | * @abstract Sets the value for this control.␊ |
| 410 | * @discussion When the control's value is changed, a call is made to performValueChange(). If that call␊ |
| 411 | * succeeds, the value is set and sendValueChangeNotification() is called to send a notification to the␊ |
| 412 | * user clients. This function must be called on the IOWorkLoop.␊ |
| 413 | * @param newValue The new value for this control.␊ |
| 414 | * @result Returns kIOReturnSuccess if the value is successfully set.␊ |
| 415 | */␊ |
| 416 | virtual IOReturn setValue(OSObject *newValue);␊ |
| 417 | ␊ |
| 418 | virtual IOReturn setValue(SInt32 intValue);␊ |
| 419 | ␊ |
| 420 | /*!␊ |
| 421 | * @function hardwareValueChanged␊ |
| 422 | * @abstract Updates the value for this control and sends out the value changed notification.␊ |
| 423 | * @discussion This is designed to be called by the driver when it detects that the hardware's value has␊ |
| 424 | * changed without driver intervention (e.g. when an external event causes the change). The difference between␊ |
| 425 | * hardwareValueChanged() and setValue() is that hardwareValueChanged() doesn't call performValueChange() which ␊ |
| 426 | * sends a message back to the driver to cause it to change the hardware with the new value. This function must␊ |
| 427 | * be called on the IOWorkLoop.␊ |
| 428 | * @param newValue The new value for this control.␊ |
| 429 | * @result Returns kIOReturnSuccess if the value is successfully updated.␊ |
| 430 | */␊ |
| 431 | virtual IOReturn hardwareValueChanged(OSObject *newValue);␊ |
| 432 | ␊ |
| 433 | /*!␊ |
| 434 | * @function getValue ␊ |
| 435 | * @abstract Returns the current value of the control.␊ |
| 436 | */␊ |
| 437 | virtual OSObject *getValue();␊ |
| 438 | virtual SInt32 getIntValue();␊ |
| 439 | virtual const void *getDataBytes();␊ |
| 440 | virtual UInt32 getDataLength();␊ |
| 441 | ␊ |
| 442 | /*!␊ |
| 443 | * @function getControlID ␊ |
| 444 | * @abstract Returns the control ID for the control.␊ |
| 445 | */␊ |
| 446 | virtual UInt32 getControlID();␊ |
| 447 | ␊ |
| 448 | /*!␊ |
| 449 | * @function getChannelID ␊ |
| 450 | * @abstract Returns the channel ID for the control.␊ |
| 451 | */␊ |
| 452 | virtual UInt32 getChannelID();␊ |
| 453 | ␊ |
| 454 | virtual UInt32 getType();␊ |
| 455 | virtual UInt32 getSubType();␊ |
| 456 | virtual UInt32 getUsage();␊ |
| 457 | ␊ |
| 458 | virtual void setCoreAudioPropertyID(UInt32 propertyID);␊ |
| 459 | ␊ |
| 460 | ␉void setWorkLoop(IOWorkLoop *wl);␊ |
| 461 | ␊ |
| 462 | protected:␊ |
| 463 | /*!␊ |
| 464 | * @function sendValueChangeNotification␊ |
| 465 | * @abstract Called when the value has changed for the control.␊ |
| 466 | * @discussion This function sends out the value change notification to the user clients.␊ |
| 467 | */␊ |
| 468 | virtual void sendValueChangeNotification();␊ |
| 469 | ␊ |
| 470 | /*!␊ |
| 471 | * @function setChannelName ␊ |
| 472 | * @abstract Called at init time to set the channel name for this IOAudioControl.␊ |
| 473 | */␊ |
| 474 | virtual void setChannelName(const char *channelName);␊ |
| 475 | ␊ |
| 476 | /*!␊ |
| 477 | * @function setChannelID ␊ |
| 478 | * @abstract Called at init time to set the channel ID for this IOAudioControl.␊ |
| 479 | */␊ |
| 480 | virtual void setChannelID(UInt32 newChannelID);␊ |
| 481 | virtual void setChannelNumber(SInt32 channelNumber);␊ |
| 482 | ␊ |
| 483 | /*!␊ |
| 484 | * @function setSubType ␊ |
| 485 | * @abstract Called at init time to set the control subType.␊ |
| 486 | */␊ |
| 487 | virtual void setType(UInt32 type);␊ |
| 488 | ␊ |
| 489 | /*!␊ |
| 490 | * @function setType ␊ |
| 491 | * @abstract Called at init time to set the control type.␊ |
| 492 | */␊ |
| 493 | virtual void setSubType(UInt32 subType);␊ |
| 494 | ␊ |
| 495 | /*!␊ |
| 496 | * @function setUsage ␊ |
| 497 | * @abstract Called at init time to set the control usage.␊ |
| 498 | */␊ |
| 499 | virtual void setUsage(UInt32 usage);␊ |
| 500 | ␊ |
| 501 | /*!␊ |
| 502 | * @function setControlID␊ |
| 503 | * @abstract Sets the controlID for this control.␊ |
| 504 | * @discussion The control ID is an optional attribute that can be used to track IOAudioControls. A typical␊ |
| 505 | * use is for the IOAudioDevice to assign a unique controlID to each control that it creates and then␊ |
| 506 | * do a switch statement on the id of the control when it gets an audioControlValueChanged() notification.␊ |
| 507 | * Typically the control ID is set when the object is created and doesn't need to be called again.␊ |
| 508 | * @param cntrlID The control ID for the control.␊ |
| 509 | */␊ |
| 510 | virtual void setControlID(UInt32 cntrlID);␊ |
| 511 | ␊ |
| 512 | /*!␊ |
| 513 | * @function validateValue␊ |
| 514 | * @abstract Called by setValue() to verify that the value is valid.␊ |
| 515 | * @param newValue The new value to be verified.␊ |
| 516 | * @result Returns kIOReturnSuccess if the value is valid.␊ |
| 517 | */␊ |
| 518 | virtual IOReturn validateValue(OSObject *newValue);␊ |
| 519 | ␊ |
| 520 | /*!␊ |
| 521 | * @function updateValue␊ |
| 522 | * @abstract Called by setValue() in order to update the value and the registry.␊ |
| 523 | * @discussion It also calls␊ |
| 524 | * sendValueChangedNotification() to send notifications to the user clients.␊ |
| 525 | * @param newValue The new value to b updated.␊ |
| 526 | * @result Returns kIOReturnSuccess if the value is successfully updated.␊ |
| 527 | */␊ |
| 528 | virtual IOReturn updateValue(OSObject *newValue);␊ |
| 529 | ␊ |
| 530 | virtual IOReturn _setValue(OSObject *newValue);␊ |
| 531 | ␊ |
| 532 | /*!␊ |
| 533 | * @function performValueChange␊ |
| 534 | * @abstract Called by setValue() to make the call to the valueChangeHandler␊ |
| 535 | * to update the hardware.␊ |
| 536 | * @result Returns the result of the handler call (or kIOReturnError on an error).␊ |
| 537 | */␊ |
| 538 | virtual IOReturn performValueChange(OSObject *newValue);␊ |
| 539 | ␊ |
| 540 | /*!␊ |
| 541 | * @function addUserClientAction␊ |
| 542 | * @abstract IOCommandGate Action which calls addUserClient() while holding the IOCommandGate.␊ |
| 543 | * @discussion This is needed to allow addUserClient() to be called on the IOWorkLoop.␊ |
| 544 | * @param owner The owner of the IOCommandGate (the IOAudioControl in this case).␊ |
| 545 | * @param arg1 The IOAudioControlUserClient to be added.␊ |
| 546 | * @result Returns the result of addUserClient() - kIOReturnSuccess on success.␊ |
| 547 | */␊ |
| 548 | static IOReturn addUserClientAction(OSObject *owner, void *arg1, void *arg2, void *arg3, void *arg4);␊ |
| 549 | ␊ |
| 550 | ␉static IOReturn _addUserClientAction(OSObject *target, void *arg0, void *arg1, void *arg2, void *arg3);␉// <rdar://7529580>␊ |
| 551 | ␊ |
| 552 | /*!␊ |
| 553 | * @function removeUserClientAction␊ |
| 554 | * @abstract IOCommandGate Action which calls removeUserClient() while holding the IOCommandGate.␊ |
| 555 | * @discussion This is needed to allow removeUserClient() to be called on the IOWorkLoop.␊ |
| 556 | * @param owner The owner of the IOCommandGate (the IOAudioControl in this case).␊ |
| 557 | * @param arg1 The IOAudioControlUserClient to be removed.␊ |
| 558 | * @result Returns the result of removeUserClient() - kIOReturnSuccess on success.␊ |
| 559 | */␊ |
| 560 | static IOReturn removeUserClientAction(OSObject *owner, void *arg1, void *arg2, void *arg3, void *arg4);␊ |
| 561 | ␊ |
| 562 | ␉static IOReturn _removeUserClientAction(OSObject *target, void *arg0, void *arg1, void *arg2, void *arg3);␉// <rdar://7529580>␊ |
| 563 | ␊ |
| 564 | /*!␊ |
| 565 | * @function detachUserClientsAction␊ |
| 566 | */␊ |
| 567 | static IOReturn detachUserClientsAction(OSObject *owner, void *arg1, void *arg2, void *arg3, void *arg4);␊ |
| 568 | ␊ |
| 569 | /*!␊ |
| 570 | * @function addUserClient␊ |
| 571 | * @abstract Called on the IOWorkLoop to add a new IOAudioControlUserClient.␊ |
| 572 | * @discussion There is no need to call this directly. It is called on the workLoop ␊ |
| 573 | * by newUserClient() through addUserClientAction().␊ |
| 574 | * @param newUserClient The IOAudioControlUserClientto be added.␊ |
| 575 | * @result Returns kIOReturnSuccess on success.␊ |
| 576 | */␊ |
| 577 | virtual IOReturn addUserClient(IOAudioControlUserClient *newUserClient);␊ |
| 578 | ␊ |
| 579 | /*!␊ |
| 580 | * @function removeUserClient␊ |
| 581 | * @abstract Called on the IOWorkLoop to remove an IOAudioControlUserClient.␊ |
| 582 | * @discussion This is called on the IOWorkLoop by clientClosed() through␊ |
| 583 | * removeUserClientAction() when the user client is going away. It should␊ |
| 584 | * not be called directly. ␊ |
| 585 | * @param userClient The IOAudioControlUserClient to be removed.␊ |
| 586 | * @result Returns kIOReturnSuccess on success.␊ |
| 587 | */␊ |
| 588 | virtual IOReturn removeUserClient(IOAudioControlUserClient *userClient);␊ |
| 589 | ␊ |
| 590 | virtual IOReturn detachUserClients();␊ |
| 591 | ␊ |
| 592 | };␊ |
| 593 | ␊ |
| 594 | #endif /* _IOKIT_IOAUDIOCONTROL_H */␊ |
| 595 | ␊ |
| 596 | |
