07.02.21

Содержание

• Введение
• Доступ к интерфейсу
• Функции-члены интерфейса
  • DWORD iA4APrivateGetVersion()
  • недействительный iA4APrivateEnumerate()
  • void iA4APrivateEnumSetCallback(BOOL (void *), void * pCbData)
  • A4AError iA4APrivateGetDeviceProperty (A4ADeviceProperty DeviceProperty, long DeviceIndex, void *PropertyData, long DataSize)
  • A4AError iA4APrivateSetDeviceProperty (A4ADeviceProperty DeviceProperty, long DeviceIndex, void *PropertyData, long DataSize)
  • A4AError iA4APrivateGetInterfaceProperty (A4AInterfaceProperty InterfaceProperty, long DeviceIndex, long InterfaceIndex, void *PropertyData, long DataSize)
  • A4AError iA4APrivateSetInterfaceProperty(A4AInterfaceProperty InterfaceProperty, long DeviceIndex, long InterfaceIndex, void *PropertyData, long DataSize)
  • A4AError iA4APrivateGetPinProperty (A4APinProperty PinProperty, long DeviceIndex, long InterfaceIndex, long PinIndex, void *PropertyData, long DataSize)
  • A4AError iA4APrivateSetPinProperty (A4APinProperty PinProperty, long DeviceIndex, long InterfaceIndex, long PinIndex, void *PropertyData, long DataSize)
• коды ошибок
• Образец заявления
• Рекомендации

Введение

Драйвер ASIO4ALL предоставляет стандартный интерфейс ASIO для хост-приложения, посредством которого хост может управлять определенными аспектами поведения драйвера. Другие аспекты, такие как конфигурация устройства WDM, не охватываются средствами управления, достижимыми через стандартный интерфейс ASIO. Учитывая потребность в большем контроле — включая возможность для OEM предоставить собственную замену оригинальному графическому интерфейсу ASIO4ALL — был создан фирменный интерфейс для ядра движка ASIO4ALL.

Область действия данного определения интерфейса распространяется на все версии 2.x свободно распространяемого программного обеспечения ASIO4ALL, начиная с версии 2.9, а также на пользовательские сборки, для которых была указана поддержка этого интерфейса.

Доступ к интерфейсу

Поскольку доступ к ASIO в Windows осуществляется как к внутрипроцессному серверному объекту COM, очевидным выбором при проектировании было использование того же типа механизма и для фирменного интерфейса.

Саморегистрирующийся драйвер DLL, поддерживающий частный интерфейс ASIO4ALL, зарегистрирует последний вместе со стандартным интерфейсом ASIO в своей процедуре DLLRegisterServer. Разработчики приложений могут запросить любой существующий IASIO для IA4APRIVATE и, как только он будет обнаружен, использовать предоставленную функциональность.

Следовательно, создать экземпляр частного интерфейса ASIO4ALL так же просто, как:

CoCreateInstance(IID_IASIO,0,1,IID_IA4APRIVATE, (LPVOID*) &ifcInstance);

• см. код конструктора класса-обертки a4aInterface.cpp!

CLSID интерфейса (в CLSID.cpp) — {A26078C5-2840-4726-B427-E60FC8FEE403}.

Фактическое определение интерфейса, а также все связанные с ним объявления содержатся в ОБЩИЙ\iaa4aprv.h

Функции-члены интерфейса

DWORD iA4APrivateGetVersion()

Эта функция может быть вызвана в любое время и возвращает версию частного интерфейса в кодировке BCD 0xMMMMmmmm, где MMMM — это основной, а mmmm — дополнительный номер ревизии. 1.23 будет закодировано как 0x00010023.

недействительный iA4APrivateEnumerate()

Вызов этой функции заставит драйвер повторно запустить перечисление аудиоустройств. Вызывать ее безопасно только тогда, когда драйвер находится в состоянии ожидания («инициализирован» согласно спецификации ASIO). Эта функция обычно используется после установки обратного вызова, поскольку обратный вызов будет вызван сразу после перечисления, что позволит приложению взять на себя управление конфигурацией устройства WDM.

void iA4APrivateEnumSetCallback(BOOL (void *), void * pCbData)

Устанавливает обратный вызов, который драйвер вызовет сразу после перечисления аудиоустройства. Аргумент pCbData является указателем на произвольные данные и будет передан функции обратного вызова. Обычно это указывает на данные экземпляра и т. д. Обратный вызов всегда вызывается после того, как драйвер завершил свое внутреннее (повторное) перечисление WDM-устройства. Используйте iA4APrivateEnumerate(), чтобы драйвер немедленно перезапустил перечисление!

Если функция обратного вызова возвращает TRUE, драйвер перезапустит перечисление еще раз. Таким образом, обычно вы хотите вернуть FALSE, чтобы избежать бесконечного зацикливания!

Только в контексте функции обратного вызова можно безопасно получить доступ к свойствам аудиоустройства/интерфейса/пина! Доступ к этим свойствам вне функции обратного вызова может привести к непредсказуемым результатам!

A4AError iA4APrivateGetDeviceProperty (A4ADeviceProperty DeviceProperty, long DeviceIndex, void *PropertyData, long DataSize)

Считывает свойство DeviceProperty перечисленного аудиоустройства DeviceIndex в предоставленное пользователем хранилище PropertyData размером DataSize.

Можно безопасно использовать только в контексте обратного вызова перечисления!

A4AError iA4APrivateSetDeviceProperty (A4ADeviceProperty DeviceProperty, long DeviceIndex, void *PropertyData, long DataSize)

Записывает свойство DeviceProperty перечисленного аудиоустройства DeviceIndex из предоставленного пользователем хранилища PropertyData размером DataSize.

Можно безопасно использовать только в контексте обратного вызова перечисления!

DevicePropertyможет быть одним из следующих:

A4AError iA4APrivateGetInterfaceProperty (A4AInterfaceProperty InterfaceProperty, long DeviceIndex, long InterfaceIndex, void *PropertyData, long DataSize)

Считывает свойство InterfaceProperty перечисленного интерфейса устройства InterfaceIndex перечисленного аудиоустройства DeviceIndex в предоставленное пользователем хранилище PropertyData размером DataSize.

Можно безопасно использовать только в контексте обратного вызова перечисления!

A4AError iA4APrivateSetInterfaceProperty(A4AInterfaceProperty InterfaceProperty, long DeviceIndex, long InterfaceIndex, void *PropertyData, long DataSize)

Записывает свойство InterfaceProperty перечисленного интерфейса устройства InterfaceIndex на перечисленном аудиоустройстве DeviceIndex из предоставленного пользователем хранилища PropertyData размером DataSize.

Можно безопасно использовать только в контексте обратного вызова перечисления!

ИнтерфейсСвойствоможет быть одним из следующих:

kA4A_Interface_dwFlags [DataSize=4]

Это битовое поле со следующими определениями битов:

A4A_FLAG_RTAUDIO	Указывает, что интерфейс — WaveRT.
A4A_FLAG_RUNNING	Указывает, что объект находится в состоянии «работает».
A4A_FLAG_ERROR	Неуказанный индикатор ошибки.
A4A_FLAG_ENABLED	Включено в текущей конфигурации.

kA4A_Interface_lpszName [DataSize=sizeof(void*)]

Строка имени интерфейса, полученная из реестра.

kA4A_Interface_pSPDIDD [DataSize=sizeof(void*)]

Указатель на структуру SP_DEVICE_INTERFACE_DETAIL_DATA для этого интерфейса устройства, см. определение структуры в Windows DDK!

kA4A_Interface_dwProperties [DataSize=4]

Физические характеристики интерфейса устройства. Может быть одним из следующих:

• A4A_IFPROPERTY_ADC
• A4A_IFPROPERTY_DAC
• A4A_IFPROPERTY_SPDIF

A4AError iA4APrivateGetPinProperty (A4APinProperty PinProperty, long DeviceIndex, long InterfaceIndex, long PinIndex, void *PropertyData, long DataSize)

Считывает свойство PinProperty аудиоконтакта PinIndex перечисленного интерфейса устройства InterfaceIndex перечисленного аудиоустройства DeviceIndex в предоставленное пользователем хранилище PropertyData размером DataSize.

Можно безопасно использовать только в контексте обратного вызова перечисления!

A4AError iA4APrivateSetPinProperty (A4APinProperty PinProperty, long DeviceIndex, long InterfaceIndex, long PinIndex, void *PropertyData, long DataSize)

Записывает свойство PinProperty аудиоконтакта PinIndex в перечисленном интерфейсе устройства InterfaceIndex в перечисленном аудиоустройстве DeviceIndex из предоставленного пользователем хранилища PropertyData размером DataSize.

Можно безопасно использовать только в контексте обратного вызова перечисления!

PinPropertyможет быть одним из следующих:

kA4A_Pin_dwFlags [DataSize=4]

Это битовое поле со следующими определениями битов:

A4A_FLAG_AVAILABLE	Остался как минимум один возможный экземпляр.
A4A_FLAG_RUNNING	Указывает, что объект находится в состоянии «работает».
A4A_FLAG_ERROR	Неуказанный индикатор ошибки.
A4A_FLAG_ENABLED	Включено в текущей конфигурации.

kA4A_Pin_dwDataFlow [DataSize=4]

Возможные значения:

• KSPIN_DATAFLOW_IN (для «выходного контакта»)
• KSPIN_DATAFLOW_OUT (для «входного контакта»)

 – определения см. в Windows DDK!

kA4A_Pin_dwMaxChannels [DataSize=4]

Максимальное количество каналов PCM.

kA4A_Pin_dwMaxBits [DataSize=4]

Максимальная битовая глубина звука.

kA4A_Pin_dwMinSR [Размер данных=4]

Минимальная частота дискретизации (Гц).

kA4A_Pin_dwMaxSR [Размер данных=4]

Максимальная частота дискретизации (Гц).

коды ошибок

Функции, возвращающие тип A4AError, вернут одно из следующих значений:

A4A_PRIVATE_NOERROR

Операция завершилась успешно.

A4A_PRIVATE_ERR_ENUM_REENTRY

Была сделана попытка повторно ввести перечисление устройств, пока перечисление устройств уже выполняется. Наиболее вероятной причиной является обратный вызов, установленный с помощью iA4APrivateEnumSetCallback(), пытающийся вызвать iA4APrivateEnumerate(). iA4APrivateEnumerate() никогда не должен использоваться внутри обратного вызова!

A4A_PRIVATE_ERR_DRIVER_NOT_IDLE

Была сделана попытка доступа к данным перечисления, пока драйвер ASIO не находится в состоянии ожидания. Остановите всю обработку звука и только потом вызывайте iA4APrivateEnumerate()!

A4A_PRIVATE_ERR_NO_SUCH_OBJECT

Объект (устройство, интерфейс, пин) с указанным индексом не существует. Вы можете законно столкнуться с этой ошибкой при перечислении объектов. Если этот код возвращается внутри цикла перечисления, это будет показателем того, что достигнут конец списка устройств/интерфейсов/пинов.

A4A_PRIVATE_ERR_ILLEGAL_ARGUMENT

Интерфейсу был передан аргумент, выходящий за пределы того, что он может обработать. Возможные причины включают идентификаторы свойств вне диапазона, указатель NULL на данные свойства или аргумент размера данных, слишком малый для запрошенного свойства.

 Образец заявления

Предоставляется пример проекта приложения MSVC++, демонстрирующий использование API, описанного в этом документе, для управления конфигурацией устройства WDM из контекста вашего приложения.

Рекомендации

1. ASIO-SDK, Steinberg Media Technologies GmbH
2. Набор драйверов для Windows, Microsoft, Корпорация
3. Win32 Software Development Kit, Microsoft, Корпорация
4. Руководство по эксплуатации ASIO4ALL, Михаэль Типпах

Авторские права © 2003-2021, Михаэль Типпах

Если не согласовано иное, не предоставляется никаких гарантий относительно точности информации, представленной в настоящем документе, а также относительно будущих изменений интерфейсов и определений, описанных в настоящем документе.

Все используемые здесь товарные знаки являются полностью признанной собственностью их соответствующих владельцев и используются исключительно в целях идентификации продукта.