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