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