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