Функция mmioOpen (mmiscapi.h)

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

Примечание Эта функция является устаревшей. Приложения должны вызывать CreateFile для создания или открытия файлов.

 

Синтаксис

HMMIO mmioOpen(
  LPSTR      pszFileName,
  LPMMIOINFO pmmioinfo,
  DWORD      fdwOpen
);

Параметры

pszFileName

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

• Если имя файла не содержит знак "плюс" (+), предполагается, что это имя стандартного файла (то есть файла, тип которого не является HMMIO).
• Если имя файла имеет форму EXAMPLE. EXT+ABC. Предполагается, что расширение EXT определяет установленную процедуру ввода-вывода, которая вызывается для выполнения операций ввода-вывода в файле. Дополнительные сведения см. в разделе mmioInstallIOProc.
• Если имя файла равно NULL и процедура ввода-вывода не указана, то член adwInfo структуры MMIOINFO считается стандартным (не HMMIO) дескриптором файла открытого в данный момент.

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

При открытии файла памяти задайте для параметра szFilename значениеNULL.

pmmioinfo

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

fdwOpen

Флаги для операции открытия. Флаги 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 не должно иметь значение NULL. Возвращаемое значение равно TRUE (приведение к HMMIO), если файл был успешно удален, или FALSE в противном случае. Не вызывайте функцию mmioClose для удаленного файла. Если этот флаг указан, все остальные флаги, открывающие файлы, игнорируются.
MMIO_DENYNONE	Открывает файл, не запрещая другим процессам доступ на чтение или запись к файлу. Если файл был открыт в режиме совместимости любым другим процессом, mmioOpen завершается ошибкой .
MMIO_DENYREAD	Открывает файл и запрещает другим процессам доступ на чтение к файлу. Если файл был открыт в режиме совместимости или для чтения любым другим процессом, mmioOpen завершается ошибкой .
MMIO_DENYWRITE	Открывает файл и запрещает другим процессам доступ на запись в файл. Если файл был открыт в режиме совместимости или для записи любым другим процессом, mmioOpen завершается ошибкой .
MMIO_EXCLUSIVE	Открывает файл и запрещает другим процессам доступ на чтение и запись к файлу. Если файл был открыт в любом другом режиме для чтения или записи, даже текущим процессом, mmioOpen завершается ошибкой .
MMIO_EXIST	Определяет, существует ли указанный файл, и создает полное имя файла по пути, указанному в szFilename. Возвращаемое значение равно TRUE (приведение к HMMIO), если квалификация была успешной и файл существует, или FALSE в противном случае. Файл не открывается, и функция не возвращает допустимый дескриптор файла ввода-вывода мультимедийного файла, поэтому не пытайтесь закрыть файл. Примечание Вместо этого приложения должны вызывать GetFileAttributes или GetFileAttributesEx .
MMIO_GETTEMP	Создает имя временного файла, при необходимости используя параметры, передаваемые в szFilename. Например, можно указать "C:F", чтобы создать временный файл, размещенный на диске C, начиная с буквы "F". Полученное имя файла копируется в буфер, на который указывает szFilename. Буфер должен быть достаточно большим и содержать не менее 128 символов. Если имя временного файла было создано успешно, возвращаемое значение будет MMSYSERR_NOERROR (приведение к HMMIO). В противном случае возвращаемое значение будет MMIOERR_FILENOTFOUND в противном случае. Файл не открывается, и функция не возвращает допустимый дескриптор файла ввода-вывода мультимедийного файла, поэтому не пытайтесь закрыть файл. Этот флаг переопределяет все остальные флаги. Примечание Вместо этого приложения должны вызывать GetTempFileName .
MMIO_PARSE	Создает полное имя файла из пути, указанного в szFilename. Полное имя копируется в буфер, на который указывает szFilename. Буфер должен быть достаточно большим и содержать не менее 128 символов. Если функция выполняется успешно, возвращается значение TRUE (приведение к HMMIO). В противном случае возвращается значение FALSE. Файл не открывается, и функция не возвращает допустимый дескриптор файла ввода-вывода мультимедийного файла, поэтому не пытайтесь закрыть файл. Если этот флаг указан, все флаги, открывающие файлы, игнорируются. Примечание Вместо этого приложения должны вызывать GetFullPathName .
MMIO_READ	Открывает файл только для чтения. Это значение по умолчанию, если MMIO_WRITE и MMIO_READWRITE не указаны.
MMIO_READWRITE	Открывает файл для чтения и записи.
MMIO_WRITE	Открывает файл только для записи.

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

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

Код возврата	Описание
MMIOERR_ACCESSDENIED	Файл защищен и не может быть открыт.
MMIOERR_INVALIDFILE	Произошло еще одно условие сбоя. Это ошибка по умолчанию при сбое при открытии файла.
MMIOERR_NETWORKERROR	Сеть не отвечает на запрос на открытие удаленного файла.
MMIOERR_PATHNOTFOUND	Указана неверная спецификация каталога.
MMIOERR_SHARINGVIOLATION	Файл используется другим приложением и недоступен.
MMIOERR_TOOMANYOPENFILES	Количество одновременно открытых файлов находится на максимальном уровне. В системе истекли доступные дескрипторы файлов.

Комментарии

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

• Чтобы запросить открытие файла с помощью установленной процедуры ввода-вывода, задайте для параметра fccIOProc четырехзначный код процедуры ввода-вывода, а для параметра pIOProc — значение NULL.
• Чтобы запросить открытие файла с помощью удаленной процедуры ввода-вывода, задайте для параметра IOProc значение , указывающее на процедуру ввода-вывода, и задайте для параметра fccIOProcзначение NULL.
• Чтобы запросить, чтобы mmioOpen определила, какую процедуру ввода-вывода следует использовать для открытия файла на основе имени файла, содержащегося в szFilename, присвойте fccIOProc и pIOProcзначение NULL. Это поведение по умолчанию, если структура MMIOINFO не указана.
• Чтобы открыть файл памяти с помощью внутреннего выделенного и управляемого буфера, задайте для параметра pchBufferзначение NULL, 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 — значение NULL, а adwInfo — стандартный дескриптор файла. Смещения в файле будут относительно начала файла и не связаны с позицией в стандартном файле во время вызова mmioOpen ; Начальное смещение ввода-вывода мультимедийного файла будет таким же, как смещение в стандартном файле при вызове mmioOpen . Чтобы закрыть дескриптор мультимедийного файла ввода-вывода, не закрывая стандартный дескриптор файла, передайте флаг MMIO_FHOPEN в mmioClose.

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	mmiscapi.h (включая Mmiscapi.h, Windows.h)
Библиотека	Winmm.lib
DLL	Winmm.dll