1/*
2 * Copyright (c) 1998-2014 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_IOAUDIOPORT_H
24#define _IOKIT_IOAUDIOPORT_H
25
26#include <IOKit/IOService.h>
27#include <AvailabilityMacros.h>
28
29class IOAudioDevice;
30class IOAudioControl;
31class OSDictionary;
32
33/*!
34 * @class IOAudioPort
35 * @abstract Represents a logical or physical port or functional unit in an audio device.
36 * @discussion An IOAudioPort represents an element in the signal chain in the audio device.  It may contain
37 *  one or more controls (represented by IOAudioControl) by which different attributes of the port may be
38 *  represented and adjusted.
39 *
40 *  IOAudioPort objects are connected up in the IORegistry in the IOAudioPlane to represent the signal chain of
41 *  the device.  They may be connected to other IOAudioPorts as well as IOAudioEngines to indicate they either
42 *  feed into or are fed by one of the audio engines (i.e. they provide input to or take output from the computer).
43 */
44class IOAudioPort : public IOService
45{
46    friend class IOAudioDevice;
47
48    OSDeclareDefaultStructors(IOAudioPort)
49
50public:
51    /* @var audioDevice The IOAudioDevice that this IOAudioPort belongs to. */
52    IOAudioDevice *	audioDevice;
53    /* @var audioControls A set containg all of the IOAudioControl instances that belong to the port. */
54    OSSet *		audioControls;
55    bool		isRegistered;
56
57protected:
58    struct ExpansionData { };
59
60    ExpansionData *reserved;
61
62private:
63    OSMetaClassDeclareReservedUnused(IOAudioPort, 0);
64    OSMetaClassDeclareReservedUnused(IOAudioPort, 1);
65    OSMetaClassDeclareReservedUnused(IOAudioPort, 2);
66    OSMetaClassDeclareReservedUnused(IOAudioPort, 3);
67    OSMetaClassDeclareReservedUnused(IOAudioPort, 4);
68    OSMetaClassDeclareReservedUnused(IOAudioPort, 5);
69    OSMetaClassDeclareReservedUnused(IOAudioPort, 6);
70    OSMetaClassDeclareReservedUnused(IOAudioPort, 7);
71    OSMetaClassDeclareReservedUnused(IOAudioPort, 8);
72    OSMetaClassDeclareReservedUnused(IOAudioPort, 9);
73    OSMetaClassDeclareReservedUnused(IOAudioPort, 10);
74    OSMetaClassDeclareReservedUnused(IOAudioPort, 11);
75    OSMetaClassDeclareReservedUnused(IOAudioPort, 12);
76    OSMetaClassDeclareReservedUnused(IOAudioPort, 13);
77    OSMetaClassDeclareReservedUnused(IOAudioPort, 14);
78    OSMetaClassDeclareReservedUnused(IOAudioPort, 15);
79    OSMetaClassDeclareReservedUnused(IOAudioPort, 16);
80    OSMetaClassDeclareReservedUnused(IOAudioPort, 17);
81    OSMetaClassDeclareReservedUnused(IOAudioPort, 18);
82    OSMetaClassDeclareReservedUnused(IOAudioPort, 19);
83    OSMetaClassDeclareReservedUnused(IOAudioPort, 20);
84    OSMetaClassDeclareReservedUnused(IOAudioPort, 21);
85    OSMetaClassDeclareReservedUnused(IOAudioPort, 22);
86    OSMetaClassDeclareReservedUnused(IOAudioPort, 23);
87    OSMetaClassDeclareReservedUnused(IOAudioPort, 24);
88    OSMetaClassDeclareReservedUnused(IOAudioPort, 25);
89    OSMetaClassDeclareReservedUnused(IOAudioPort, 26);
90    OSMetaClassDeclareReservedUnused(IOAudioPort, 27);
91    OSMetaClassDeclareReservedUnused(IOAudioPort, 28);
92    OSMetaClassDeclareReservedUnused(IOAudioPort, 29);
93    OSMetaClassDeclareReservedUnused(IOAudioPort, 30);
94    OSMetaClassDeclareReservedUnused(IOAudioPort, 31);
95
96public:
97    /*!
98     * @function withAttributes
99     * @abstract Allocates a new IOAudioPort instance with the given attributes
100     * @discussion This static method allocates a new IOAudioPort and calls initWithAttributes() on it with
101     *  the parameters passed in to it.
102     * @param portType A readable string representing the type of port.  Common port types are defined in
103     *  IOAudioTypes.h and are prefixed with 'kIOAudioPortType'.  Please provide feedback if there are
104     *  other common port types that should be included.
105     * @param portName A readable string representing the name of the port.  For example: 'Internal Speaker',
106     *  'Line Out'.  This field is optional, but useful for providing information to the application/user.
107     * @param subType Developer defined readable string representing a subtype for the port. (optional)
108     * @param properties Standard property list passed to the init of any new IOService.  This dictionary
109     *  gets stored in the registry for this instance. (optional)
110     * @result Returns the newly allocated and initialized IOAudioPort instance.
111     */
112    static IOAudioPort *withAttributes(UInt32 portType, const char *portName = 0, UInt32 subType = 0, OSDictionary *properties = 0) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10;
113
114    /*!
115     * @function initWithAttributes
116     * @abstract Initializes a newly allocated IOAudioPort instance with the given attributes
117     * @discussion The properties parameter is passed on the superclass' init().  The portType, subType
118     *  and properties parameters are optional, however portType is recommended.
119     * @param portType A readable string representing the type of port.  Common port types are defined in
120     *  IOAudioTypes.h and are prefixed with 'kIOAudioPortType'.  Please provide feedback if there are
121     *  other common port types that should be included.
122     * @param portName A readable string representing the name of the port.  For example: 'Internal Speaker',
123     *  'Line Out'.  This field is optional, but useful for providing information to the application/user.
124     * @param subType Developer defined readable string representing a subtype for the port. (optional)
125     * @param properties Standard property list passed to the init of any new IOService.  This dictionary
126     *  gets stored in the registry for this instance. (optional)
127     * @result Returns true on success.
128     */
129    virtual bool initWithAttributes(UInt32 portType, const char *portName = 0, UInt32 subType = 0, OSDictionary *properties = 0) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10;
130
131    /*!
132     * @function free
133     * @abstract Frees all of the resources allocated by the IOAudioPort.
134     * @discussion Do not call this directly.  This is called automatically by the system when the instance's
135     *  refcount goes to 0.  To decrement the refcount, call release() on the object.
136     */
137    virtual void free() AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10;
138
139    /*!
140     * @function start
141     * @abstract Called to start a newly created IOAudioPort.
142     * @discussion This is called automatically by IOAudioDevice when attachAudioPort() is called.
143     * @param provider The IOAudioDevice that owns this port
144     * @result Returns true on success
145     */
146    virtual bool start(IOService *provider) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10;
147
148    /*!
149     * @function stop
150     * @abstract Called when the IOAudioDevice is stopping when it is no longer available.
151     * @discussion This method calls deactivateAudioControls() to shut down all of the controls associated with
152     *  this port.
153     * @param provider The IOAudioDevice that owns this port
154     */
155    virtual void stop(IOService *provider) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10;
156
157    virtual void registerService(IOOptionBits options = 0) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10;
158
159    virtual IOAudioDevice *getAudioDevice() AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10;
160
161    /*!
162     * @function addAudioControl
163     * @abstract Adds a newly created IOAudioControl instance to the port.
164     * @discussion This method is responsible for starting the new IOAudioControl and adding it to the internal
165     *  audioControls array.
166     * @param control A newly created IOAudioControl instance that should belong to this port.
167     * @result Returns true on successfully staring the IOAudioControl.
168     */
169    virtual IOReturn addAudioControl(IOAudioControl *control) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10;
170
171    /*!
172     * @function deactivateAudioControls
173     * @abstract Called to shut down all of the audio controls for this port.
174     * @discussion This will stop all of the audio controls and release them so that the instances may be
175     *  freed.  This is called from the free() method.
176     */
177    virtual void deactivateAudioControls() AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10;
178
179protected:
180    virtual void setType(UInt32 portType) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10;
181    virtual void setSubType(UInt32 subType) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10;
182    virtual void setName(const char *name) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10;
183};
184
185#endif /* _IOKIT_IOAUDIOPORT_H */
186