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

Статья
08/24/2023

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

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

Синтаксис

HMMIO mmioOpenW(
  LPWSTR     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	Открывает файл только для записи.

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

None

Remarks

Если 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. Открытые файлы не закрываются автоматически при выходе из приложения.

Примечание

Заголовок mmiscapi.h определяет mmioOpen как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

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

Share via