AcmDriverPriority

MMRESULT acmDriverPriority( HACMDRIVERID hadid, DWORD dwPriority, DWORD fdwPriority );

Возвращаемое значение

В случае успешного завершения возвращает нулевое значение. В противном случае возвращает одно из следующих значений:

• MMSYSERR_ALLOCATED — отложенный запрет на посылку сообщений принадлежит другой задаче.

• MMSYSERR_INVALFLAG — при вызове данной функции установлен, по крайней мере, один недопустимый флаг.

• MMSYSERR_INVALHANDLE — использован недопустимый дескриптор.

• MMSYSERR_INVALPARAM — при вызове данной функции, по крайней мере, один из её аргументов имеет недопустимое значение.

• MMSYSERR_NOMEM — система не в состоянии разместить в памяти требуемые ресурсы.

• MMSYSERR_NOTSUPPORTED — требуемая операция не может быть выполнена указанным драйвером. Например, локальные драйверы и драйверы извещения не могут обладать приоритетом (но могут быть сделаны доступными или недоступными). Если приложение указывает ненулевое значение аргумента dwPriority для локального драйвера и драйвера извещения, функция возвращает данное значение.

Аргументы

0. hadid — дескриптор идентификатора установленного драйвера ACM. Если установлены флаги ACM_DRIVERPRIORITYF_BEGIN или ACM_DRIVERPRIORITYF_END, этот аргумент должен иметь нулевое значение.

1. dwPriority — новое значение приоритета идентификатора глобального драйвера ACM. Нулевое значение данного аргумента означает, что приоритет идентификатора драйвера остаётся без изменений. Значение 1 данного аргумента означает, что указанный драйвер имеет наивысший приоритет при поиске. Значение -1 данного аргумента означает, что указанный драйвер имеет самый низкий приоритет при поиске. Приоритеты используются только для глобальных драйверов.

2. fdwPriority — флаги установки приоритетов драйверов ACM. Определены следующие значения:

• ACM_DRIVERPRIORITYF_BEGIN — посылка сообщения об изменении должна быть отложена. Приложение должно восстановить право на посылку сообщений как можно скорее, установив флаг ACM_DRIVERPRIORITYF_END. Если этот флаг установлен, то не может быть установлен ни один другой флаг, а аргументы hadid и dwPriority должны иметь нулевое значение.

• ACM_DRIVERPRIORITYF_DISABLE — если драйвер ACM в настоящее время доступен, его следует сделать недоступным. Данный флаг не оказывает никакого влияния на недоступный драйвер.

• ACM_DRIVERPRIORITYF_ENABLE — если драйвер ACM в настоящее время недоступен, его следует сделать доступным. Данный флаг не оказывает никакого влияния на доступный драйвер.

• ACM_DRIVERPRIORITYF_END — задача, в которой вызывается данная функция, хочет восстановить своё право на посылку сообщений об изменении. Приложение должно вызывать функцию acmDriverPriority с установленным флагом ACM_DRIVERPRIORITYF_END для каждого успешно завершившегося вызова данной функции с флагом ACM_DRIVERPRIORITYF_BEGIN. Если этот флаг установлен, то не может быть установлен ни один другой флаг, а аргументы hadid и dwPriority должны иметь нулевое значение.

Примечание

• Функция acmDriverPriority используется для изменения приоритета и состояния драйвера ACM.

• Все идентификаторы драйверов могут быть сделаны доступными или недоступными, включая глобальные и локальные драйверы, а также драйверы сообщений. Если необходимо сделать доступными, недоступными или изменить приоритет нескольких глобальных драйверов, приложение должно отложить посылку сообщения с использованием флага ACM_DRIVERPRIORITYF_BEGIN. После вызова данной функции с флагом ACM_DRIVERPRIORITYF_END будет послано одно сообщение обо всех изменениях в драйверах. Приложение может использовать функцию acmMetrics с индексом метрики ACM_METRIC_DRIVER_PRIORITY, для получения текущего значения приоритета глобального драйвера. При составлении списка драйверов с использованием функции acmDriverEnum драйверы всегда вносятся в него по убыванию приоритета.

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

Описание данной функции содержится в файле заголовка msacm.h. При работе с данной функцией следует включить в проект библиотеку msacm32.lib.