Root/
Source at commit 2920 created 5 years 9 months ago. By ifabio, typo | |
---|---|
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 |