Техническое примечание TN2223

Отъезжая осуждаемый HAL APIs

Это Техническое примечание обсуждает переход к более новому AudioDevice и AudioObject APIs, доступный начиная с выпуска Mac OS X 10.5.

Введение
Регистрационные изменения IOProc
Примеры
Изменения средства доступа свойства
Примеры
Ссылка
История версии документа

Введение

AudioHardware.h заголовочный файл содержит APIs, используемый для работы с аудио HAL. Аудио HAL обеспечивает абстракцию, посредством которой приложения могут получить доступ к аудио аппаратным средствам. Существует ряд HAL APIs, который был осужден начиная с выпуска Mac OS X 10.5 и больше не должен использоваться.

Существует два типа осуждаемого APIs. Первый тип AudioDeviceIOProc регистрационные вызовы, они включают AudioDeviceAddIOProc и AudioDeviceRemoveIOProc. Второй тип является средствами доступа свойства такой как AudioHardwareGetProperty, AudioDeviceSetProperty и связанный APIs.

Переход к более новому APIs является прямым и рекомендован для всех приложений в настоящее время с помощью более старого осуждаемого APIs.

Назад к началу.

Регистрационные изменения IOProc

AudioDeviceIOProc регистрационное изменение представляет AudioDeviceIOProcID введите и повторно отображается AudioDeviceAddIOProc и AudioDeviceRemoveIOProc к AudioDeviceCreateIOProcID и AudioDeviceDestroyIOProcID соответственно.

AudioDeviceIOProcID представляет и IOProc и клиентские данные, который идет с ним. После того, как создаваемый, AudioDeviceIOProcID может использоваться везде, можно было бы использовать регулярный IOProc. Цель для AudioDeviceIOProcID должен позволить клиенту регистрировать тот же указатель функции как IOProc с устройством многократно (как долго, как пользовательский указатель клиентских данных отличается каждый раз).

При использовании их новая регистрация APIs Вы передаете AudioDeviceIOProcID возвращенный из AudioDeviceCreateIOProcID к AudioDeviceStart и AudioDeviceStop вместо самого IOProc.

Примеры

  Осуждаемое перечисление 1 - AudioDeviceIOProc Регистрация.

OSStatus MyIOProc(AudioDeviceID           inDevice,
                  const AudioTimeStamp*   inNow,
                  const AudioBufferList*  inInputData,
                  const AudioTimeStamp*   inInputTime,
                  AudioBufferList*        outOutputData,
                  const AudioTimeStamp*   inOutputTime,
                  void*                   inClientData)
{
    // your IOProc here
    ...
}

// Deprecated
void DeprecatedFakePlay(AudioObjectID inDevice, void* inClientData)
{
    //  register the IOProc
    OSStatus theError = AudioDeviceAddIOProc(inDevice, MyIOProc, inClientData);
    // handle errors

    //  start IO
    theError = AudioDeviceStart(inDevice, MyIOProc);

    ...

    //  stop IO
    theError = AudioDeviceStop(inDevice, MyIOProc);

    //  unregister the IOProc
    theError = AudioDeviceRemoveIOProc(inDevice, MyIOProc);
}

  Новое перечисление 2 - AudioDeviceIOProc Регистрация.

OSStatus MyIOProc(AudioDeviceID           inDevice,
                  const AudioTimeStamp*   inNow,
                  const AudioBufferList*  inInputData,
                  const AudioTimeStamp*   inInputTime,
                  AudioBufferList*        outOutputData,
                  const AudioTimeStamp*   inOutputTime,
                  void*                   inClientData)
{
    // your IOProc here
    ...
}

// New Mac OS X 10.5+
void NewFakePlay(AudioObjectID inDevice, void* inClientData)
{
    //  register the IOProc
    AudioDeviceIOProcID theIOProcID = NULL;

    OSStatus theError = AudioDeviceCreateIOProcID(inDevice, MyIOProc, inClientData, &theIOProcID);
    // handle errors
    // ensure theIOProcID != NULL

    //  start IO
    theError = AudioDeviceStart(inDevice, theIOProcID);

    ...

    //  stop IO
    theError = AudioDeviceStop(inDevice, theIOProcID);

    //  unregister the IOProc
    theError = AudioDeviceDestroyIOProcID(inDevice, theIOProcID);
}
Назад к началу.

Изменения средства доступа свойства

Изменения Средства доступа Свойства немного отличаются, но могут быть подведены итог как это - Все отдельные функции доступа свойства класса были заменены столь же именованный AudioObject- снабженная префиксом функция.

Таблица ниже иллюстрирует основное отображение, где 'XXX' на более старое имя API может быть заменен 'Аппаратными средствами', 'Устройством' или 'Потоком':

Таблица 1  

Осуждаемый API

Новый API

AudioXXXGetPropertyInfo

AudioObjectHasProperty, AudioObjectIsPropertySettable, AudioObjectGetPropertyDataSize

AudioXXXGetProperty

AudioObjectGetPropertyData

AudioXXXSetProperty

AudioObjectSetPropertyData

AudioXXXAddPropertyListener

AudioObjectAddPropertyListener

AudioXXXRemovePropertyListener

AudioObjectRemovePropertyListener

Основное отличие между осуждаемым и новым API является использованием AudioObjectPropertyAddress структура.

struct  AudioObjectPropertyAddress
{
    AudioObjectPropertySelector mSelector;
    AudioObjectPropertyScope    mScope;
    AudioObjectPropertyElement  mElement;
};
typedef struct AudioObjectPropertyAddress   AudioObjectPropertyAddress;

AudioObjectPropertyAddress структура используется с новым APIs для инкапсуляции различающей информации для определенного свойства; селекторный ID (mSelector), объем (mScope) и элемент (mElement). HAL использует объем условий и элемент таким же образом, который делает AudioUnit API.

Большинство объектов имеет только один объем и один элемент, например Системный объект, Потоковый объект и Объект управления имеют только один объем, kAudioObjectPropertyScopeGlobal и один элемент, kAudioObjectPropertyElementMaster.

Объекты устройства отличаются и могут иметь три других объема около kAudioObjectPropertyScopeGlobal. Это kAudioDevicePropertyScopeInput, kAudioDevicePropertyScopeOutput, и kAudioDevicePropertyScopePlayThrough.

Для Объекта Устройства, элемент (mElement) из AudioObjectPropertyAddress структура относится к номеру канала на устройстве.

Примеры

  Осуждаемое перечисление 3 - Получение Устройства ввода данных по умолчанию.

AudioDeviceID DeprecatedGetDefaultInputDevice()
{
    AudioDeviceID theAnswer = 0;
    UInt32 theSize = sizeof(AudioDeviceID);
    OSStatus theError = AudioHardwareGetProperty(kAudioHardwarePropertyDefaultInputDevice,
                                                 &theSize,
                                                 &theAnswer);

    // handle errors

    return theAnswer;
}

  Новое перечисление 4 - Получение устройства ввода данных по умолчанию.

AudioDeviceID NewGetDefaultInputDevice()
{
    AudioDeviceID theAnswer = 0;
    UInt32 theSize = sizeof(AudioDeviceID);
    AudioObjectPropertyAddress theAddress = { kAudioHardwarePropertyDefaultInputDevice,
                                              kAudioObjectPropertyScopeGlobal,
                                              kAudioObjectPropertyElementMaster };

    OSStatus theError = AudioObjectGetPropertyData(kAudioObjectSystemObject,
                                                   &theAddress,
                                                   0,
                                                   NULL,
                                                   &theSize,
                                                   &theAnswer);
    // handle errors

    return theAnswer;
}

  Осуждаемое перечисление 5 - Получение текущего скаляра объема.

Float32 DeprecatedGetVolumeScalar(AudioDeviceID inDevice, bool inIsInput, UInt32 inChannel)
{
    Float32 theAnswer = 0;
    UInt32 theSize = sizeof(Float32);
    OSStatus theError = AudioDeviceGetProperty(inDevice,
                                               inChannel,
                                               inIsInput,
                                               kAudioDevicePropertyVolumeScalar,
                                               &theSize,
                                               &theAnswer);
    // handle errors

    return theAnswer;
}

  Новое перечисление 6 - Получение текущего скаляра объема.

Float32 NewGetVolumeScalar(AudioDeviceID inDevice, bool inIsInput, UInt32 inChannel)
{
    Float32 theAnswer = 0;
    UInt32 theSize = sizeof(Float32);
    AudioObjectPropertyScope theScope = inIsInput ? kAudioDevicePropertyScopeInput :
                                                    kAudioDevicePropertyScopeOutput
    AudioObjectPropertyAddress theAddress = { kAudioDevicePropertyVolumeScalar,
                                              theScope,
                                              inChannel };

    OSStatus theError = AudioObjectGetPropertyData(inDevice,
                                                   &theAddress,
                                                   0,
                                                   NULL,
                                                   &theSize,
                                                   &theAnswer);
    // handle errors

    return theAnswer;
}

Отметьте использование kAudioObjectSystemObject при замене старого APIs. kAudioObjectSystemObject AudioObjectID это всегда относится к тому и только экземпляру Объекта Аудиосистемы.

Назад к началу.

Ссылка

Посмотрите CoreAudio/AudioHardware.h для получения дальнейшей информации.

Назад к началу.

История версии документа


ДатаПримечания
14.04.2010

Передовая статья

08.04.2010

Передовая статья

09.01.2010

Новый документ, обсуждающий переход к более новому AudioDevice и AudioObject APIs, доступному на Mac OS X 10.5 +