MmioInstallIoProc

LPMMIOPROC mmioInstallIOProc( FOURCC fccIOProc, LPMMIOPROC pIOProc, DWORD dwFlags );

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

Возвращает адрес установленной, удалённой или найденной процедуры ввода/вывода. При возникновении ошибки возвращает нулевое значение.

Аргументы

0. fccIOProc — четырёхбуквенный код, идентифицирующий установленную, удалённую или искомую процедуру ввода/вывода. Все символы данного кода должны располагаться в верхнем регистре.

1. pIOProc — указатель на устанавливаемую процедуру ввода/вывода. При удалении или поиске процедуры ввода/вывода этот аргумент должен иметь нулевое значение. Формат данной функции должен соответствовать формату функции MMIOProc.

2. dwFlags — флаги, определяющие действие, производимое над процедурой ввода/вывода. Определены следующие значения:

• MMIO_FINDPROC — поиск указанной процедуры ввода/вывода.

• MMIO_GLOBALPROC — флаг, модифицирующий действие флага MMIO_INSTALLPROC, и указывающий на то, что процедура ввода/вывода должна быть установлена для глобального использования. Состояние данного флага игнорируется при установке флагов MMIO_FINDPROC или MMIO_REMOVEPROC.

• MMIO_INSTALLPROC — указанная процедура ввода/вывода устанавливается.

• MMIO_REMOVEPROC — указанная процедура ввода/вывода удаляется.

Примечание

Функция mmioInstallIOProc устанавливает, удаляет или производит поиск процедуры ввода/вывода. Для идентификации установленной процедуры ввода/вывода используется её четырёхбуквенный идентификатор.

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

MmioOpen

HMMIO mmioOpen( LPSTR szFilename, LPMMIOINFO lpmmioinfo, DWORD dwOpenFlags );

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

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

• MMIOERR_ACCESSDENIED — файл защищён и не может быть открыт.

• MMIOERR_INVALIDFILE — используется по умолчанию для индикации ошибок, не имеющих своего отдельного идентификатора.

• MMIOERR_NETWORKERROR — нет реакции сети на попытку открыть удалённый файл.

• MMIOERR_PATHNOTFOUND — указан недопустимый директорий.

• MMIOERR_SHARINGVIOLATION — файл используется другим приложением в монопольном режиме.

• MMIOERR_TOOMANYOPENFILES — число одновременно открытых файлов превысило максимально допустимое значение. Система использовала все имеющиеся дескрипторы файлов.

Аргументы

0. szFilename — указатель на строку, содержащую имя открываемого файла. Если не определена процедура ввода/вывода для открытия файла, то режим открытия файла определяется его именем:

• Если имя файла не содержит знака плюс (+) оно рассматривается как имя стандартного файла (то есть тип файл отличен от HMMIO).

• Если имя файла имеет вид EXAMPLE.EXT+ABC, то предполагается, что расширение EXT идентифицирует установленную процедуру ввода/вывода, используемую для работы с данным файлом.

• Если данный аргумент имеет нулевое значение и отсутствует процедура ввода/вывода, то переменная adwInfo объекта структуры MMIOINFO будет рассматриваться как дескриптор стандартного (тип файл отличен от HMMIO) открытого файла.

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

При открытии образа файла в оперативной памяти аргумент szFilename имеет нулевое значение.

0. lpmmioinfo — указатель на объект структуры MMIOINFO, содержащий дополнительные аргументы функции mmioOpen. Если приложение не открывает образ файла в оперативной памяти, не определяет размер буфера при буферированном вводе/выводе или не определяет деинсталлированную процедуру ввода/вывода, используемую при открытии файла, этот аргумент должен иметь нулевое значение. Если данный аргумент имеет ненулевое значение, то все неиспользуемые переменные объекта структуры MMIOINFO должны иметь нулевое значение, включая зарезервированные переменные.

1. dwOpenFlags — флаги, определяющие режим открытия файла. Флаги MMIO_READ, MMIO_WRITE и MMIO_READWRITE являются взаимоисключающими (может быть установлен только один из них). Флаги MMIO_COMPAT, MMIO_EXCLUSIVE, MMIO_DENYWRITE, MMIO_DENYREAD и MMIO_DENYNONE могут использоваться совместно. Определены следующие значения:

• MMIO_ALLOCBUF — открывает файл для буферированного ввода/вывода. Для задания размера буфера, отличного от используемого по умолчанию размера 8 КБ (MMIO_DEFAULTBUFFER), следует занести новый размер в переменную cchBuffer объекта структуры MMIOINFO. Если переменная cchBuffer имеет нулевое значение, то используется размер буфера, заданный по умолчанию. При использовании пользовательского буфера ввода/вывода этот флаг не устанавливается.

• MMIO_COMPAT — файл открывается в режиме совместимости, позволяющем любому процессу на данном компьютере открывать данный файл неограниченное число раз. Если этот файл уже был открыт в любом другом режиме совместимости, вызов функции mmioOpen завершается с ошибкой.

• MMIO_CREATE — создаёт новый файл. Если файл уже существует, он урезается до нулевой длины. Для образа файла в оперативной памяти установка этого флага означает, что изначально его начало и конец совпадают.

• MMIO_DELETE — уничтожает файл. Если данный флаг установлен, то аргумент szFilename не может иметь нулевое значение. В случае успешного удаления файла возвращается значение TRUE (ссылка на HMMIO). В противном случае возвращается значение FALSE. Для уничтоженного файла не вызывается функция mmioClose. Если установлен данный флаг, то значения всех других флагов открытия файла игнорируются.

• MMIO_DENYNONE — открывает файл, запрещая для любого другого процесса доступ к этому файлу по чтению или записи. Если этот файл был открыт другим процессом в режиме разрешения доступа по чтению или записи, то вызов функции mmioOpen завершается с ошибкой.

• MMIO_DENYREAD — открывает файл, запрещая для любого другого процесса доступ к этому файлу по чтению. Если этот файл был открыт другим процессом в режиме совместимости или с разрешением доступа по чтению, то вызов функции mmioOpen завершается с ошибкой.

• MMIO_DENYWRITE — открывает файл, запрещая для любого другого процесса доступ к этому файлу по записи. Если этот файл был открыт другим процессом в режиме совместимости или с разрешением доступа по записи, то вызов функции mmioOpen завершается с ошибкой.

• MMIO_EXCLUSIVE — открывает файл, запрещая для любого другого процесса доступ к этому файлу по чтению или записи. Если этот файл был открыт любым процессом, даже данным, в режиме разрешения доступа по чтению или записи, то вызов функции mmioOpen завершается с ошибкой.

• MMIO_EXIST — определяет, существует ли указанный файл и создаёт полный путь к файлу из имени файла, указанного в аргументе szFilename. Полученный путь записывается в аргумент szFilename. В случае успешного построения полного пути к файлу возвращается значение TRUE (ссылка на HMMIO). В противном случае возвращается значение FALSE. Файл при этом не открывается и функция не возвращает дескриптор мультимедийного файла, поэтому его не нужно закрывать.

• MMIO_GETTEMP — создаёт временное имя файла, используя информацию, переданную в аргументе szFilename. Например, при передаче в данном аргументе строки "C:F" временный файл создаётся на диске C, а его имя начинается с буквы "F". Полученное имя файла записывается в аргумент szFilename. В случае успешного создания имени временного файла возвращается значение MMSYSERR_NOERROR (ссылка на HMMIO). В противном случае возвращается значение MMIOERR_FILENOTFOUND. Файл при этом не открывается и функция не возвращает дескриптор мультимедийного файла, поэтому его не нужно закрывать. Этот флаг отменяет действие всех остальных флагов.

• MMIO_PARSE — создаёт полный путь к файлу из имени файла, указанного в аргументе szFilename. Полученный путь записывается в аргумент szFilename. В случае успешного построения полного пути к файлу возвращается значение TRUE (ссылка на HMMIO). В противном случае возвращается значение FALSE. Файл при этом не открывается и функция не возвращает дескриптор мультимедийного файла, поэтому его не нужно закрывать. При установке данного флага установки всех флагов открытия файла игнорируются.

• MMIO_READ — открывает файл в режиме только для чтения. Этот флаг устанавливается по умолчанию, если не установлены флаги MMIO_WRITE и MMIO_READWRITE.

• MMIO_READWRITE — открывает файл в режиме доступа для чтения и записи.

• MMIO_WRITE — открывает файл в режиме только для записи.

Примечание

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

Если в аргументе lpmmioinfo содержится ссылка на объект структуры MMIOINFO, то установка переменных данной структуры должна производиться в соответствии с приведёнными ниже правилами:

• Все неиспользуемые переменные, включая зарезервированные, должны иметь нулевое значение.

• Для указания того, что открытие файла должно производиться инсталлированной процедурой ввода/вывода, занесите в переменную fccIOProc четырёхбуквенный код процедуры вввода/вывода, а переменной pIOProc присвойте нулевое значение.

• Для указания того, что открытие файла должно производиться неинсталлированной процедурой ввода/вывода, занесите в переменную pIOProc указатель на процедуру ввода/вывода, а переменной fccIOProc присвойте нулевое значение.

• Для указания того, что функция mmioOpen должна самостоятельно найти процедуру ввода/вывода, используемую для открытия файла, основываясь на содержимом аргумента szFilename, присвойте переменным fccIOProc и pIOProc нулевое значение. Это способ нахождения процедуры открытия файла используется по умолчанию при отсутствии ссылки на объекта структуры MMIOINFO.

• Для открытия образа файла в оперативной памяти с использованием внутреннего буфера присвойте нулевое значение переменной pchBuffer, переменной fccIOProc присвойте значение FOURCC_MEM, в переменную cchBuffer занесите исходный размер буфера, а в переменную adwInfo — шаг расширения буфера. В случае необходимости размер буфера будет увеличиваться шагами, определяемыми переменной adwInfo. Установите флаг MMIO_CREATE в аргументе dwOpenFlags для указания того, что конец файла изначально расположен в начале буфера.

• Для открытия образа файла в оперативной памяти с использованием буфера приложения занесите в переменную pchBuffer указатель на используемый буфер, переменной fccIOProc присвойте значение FOURCC_MEM, в переменную cchBuffer занесите исходный размер буфера, а в переменную adwInfo — шаг расширения буфера. Переменная adwInfo может иметь ненулевое значение только в том случае, если указатель, записанный в переменную pchBuffer получен с использованием функция GlobalAlloc и GlobalLock. В этом случае для увеличения размера буфера используется функция GlobalReAlloc. Другими словами, если переменная pchBuffer указывает на локальный или глобальный массив или блок памяти в локальной куче, переменная adwInfo должна иметь нулевое значение. Установите флаг MMIO_CREATE в аргументе dwOpenFlags для указания того, что конец файла изначально расположен в начале буфера. В противном случае весь блок памяти будет рассматриваться как доступный для чтения.

• Для использования стандартного дескриптора уже открытого файла (то есть тип дескриптора не HMMIO) в служебных программах работы с файлами мультимедиа присвойте переменной fccIOProc значение FOURCC_DOS, занесите в переменную pchBuffer нулевое значение, а в переменную adwInfo — стандартный дескриптор файла. Смещение в файле должно измеряться от его начала и не зависеть от текущей позиции в стандартном файле в момент вызова функции mmioOpen. При этом текущая позиция в файле мультимедиа при его создании соответствует текущей позиции в стандартном файле в момент вызова функции mmioOpen. Для закрытия мультимедийного дескриптора ввода/вывода без закрытия стандартного дескриптора файла, вызовите функцию mmioClose с флагом MMIO_FHOPEN.

Для закрытия файлов, отврытых с использованием функции mmioOpen используется функция mmioClose. Открытые файлы не закрываются автоматически при закрытии приложения.

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