mmioOpen 函数 (mmiscapi.h)

  • 项目

mmioOpen 函数打开未缓冲或缓冲 I/O 的文件;创建文件;删除文件;或 检查文件是否存在。 该文件可以是标准文件、内存文件或自定义存储系统的元素。 mmioOpen 返回的句柄不是标准文件句柄;请勿将其用于除多媒体文件 I/O 函数以外的任何文件 I/O 函数。

注意 此函数已弃用。 应用程序应调用 CreateFile 来创建或打开文件。
 

语法

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

参数

pszFileName

指向包含文件名的缓冲区的指针。 如果未指定 I/O 过程来打开文件，则文件名将确定文件的打开方式，如下所示：

  • 如果文件名不包含加号 (+) ，则假定它是标准文件的名称 (即类型不是 HMMIO) 的文件。
  • 如果文件名的格式为 EXAMPLE。EXT+ABC，假定扩展 EXT 标识已安装的 I/O 过程，该过程被调用以对文件执行 I/O。 有关详细信息，请参阅 mmioInstallIOProc。
  • 如果文件名为 NULL 且未提供 I/O 过程，则假定 MMIOINFO 结构的 adwInfo 成员是当前打开的文件的标准 (非 HMMIO) 文件句柄。
文件名不应超过 128 个字符，包括终止 NULL 字符。

打开内存文件时，将 szFilename 设置为 NULL。

pmmioinfo

指向 MMIOINFO 结构的指针，该结构包含 mmioOpen 使用的额外参数。 除非打开内存文件、指定缓冲 I/O 的缓冲区大小，或指定卸载的 I/O 过程以打开文件，否则此参数应为 NULL。 如果此参数不为 NULL，则它引用的 MMIOINFO 结构的所有未使用成员都必须设置为零，包括保留成员。

fdwOpen

打开操作的标志。 MMIO_READ标志、MMIO_WRITE标志和MMIO_READWRITE标志互斥 ， 只应指定一个标志。 MMIO_COMPAT、MMIO_EXCLUSIVE、MMIO_DENYWRITE、MMIO_DENYREAD和MMIO_DENYNONE标志是文件共享标志。 定义了以下值。

值 含义
MMIO_ALLOCBUF 打开缓冲 I/O 的文件。 若要分配大于或小于默认缓冲区大小 (8K（定义为 MMIO_DEFAULTBUFFER) ）的缓冲区，请将 MMIOINFO 结构的 cchBuffer 成员设置为所需的缓冲区大小。 如果 cchBuffer 为零，则使用默认缓冲区大小。 如果提供自己的 I/O 缓冲区，则不应使用此标志。
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 。 文件未打开，并且函数不返回有效的多媒体文件 I/O 文件句柄，因此请不要尝试关闭该文件。
注意 应用程序应改为调用 GetFileAttributes 或 GetFileAttributesEx 。
 
MMIO_GETTEMP 创建一个临时文件名，可以选择使用 szFilename 中传递的参数。例如，可以指定“C：F”以创建驻留在驱动器 C 上的临时文件，以字母“F”开头。 生成的文件名将复制到 szFilename 指向的缓冲区。 缓冲区必须足够大才能容纳至少 128 个字符。

如果成功创建临时文件名，则返回值 MMSYSERR_NOERROR (强制转换为 HMMIO) 。 否则，返回值 MMIOERR_FILENOTFOUND 。 文件未打开，并且函数不返回有效的多媒体文件 I/O 文件句柄，因此请不要尝试关闭该文件。 此标志替代所有其他标志。

注意 应用程序应改为调用 GetTempFileName 。
 
MMIO_PARSE 从 szFilename 中指定的路径创建完全限定的文件名。 完全限定的名称将复制到 szFilename 指向的缓冲区。 缓冲区必须足够大才能容纳至少 128 个字符。

如果函数成功，则 (强制转换为 HMMIO) 返回值为 TRUE。 否则，返回值为 FALSE。 文件未打开，并且函数不返回有效的多媒体文件 I/O 文件句柄，因此请不要尝试关闭该文件。 如果指定了此标志，则会忽略打开文件的所有标志。

注意 应用程序应改为调用 GetFullPathName 。
 
MMIO_READ 打开文件以供只读。 如果未指定MMIO_WRITE和MMIO_READWRITE，则这是默认值。
MMIO_READWRITE 打开文件进行读取和写入。
MMIO_WRITE 打开文件以仅只写。

返回值

返回打开的文件的句柄。 如果无法打开该文件，则返回值为 NULL。 如果 lpmmioinfo 不为 NULL，则 MMIOINFO 结构的 wErrorRet 成员将包含以下错误值之一。

返回代码 说明
MMIOERR_ACCESSDENIED
 该文件受保护，无法打开。
MMIOERR_INVALIDFILE
 发生了另一个失败情况。 这是打开文件失败的默认错误。
MMIOERR_NETWORKERROR
 网络未响应打开远程文件的请求。
MMIOERR_PATHNOTFOUND
 目录规范不正确。
MMIOERR_SHARINGVIOLATION
 该文件正由另一个应用程序使用，并且不可用。
MMIOERR_TOOMANYOPENFILES
 同时打开的文件数处于最大级别。 系统已用完可用的文件句柄。

注解

如果 lpmmioinfo 指向 MMIOINFO 结构，请初始化结构的成员，如下所示。 所有未使用的成员都必须设置为零，包括保留成员。

  • 若要请求使用已安装的 I/O 过程打开文件，请将 fccIOProc 设置为 I/O 过程的四个字符代码，并将 pIOProc 设置为 NULL。
  • 若要请求使用卸载的 I/O 过程打开文件，请将 IOProc 设置为指向 I/O 过程，并将 fccIOProc 设置为 NULL。
  • 若要请求 mmioOpen 根据 szFilename 中包含的文件名确定用于打开文件的 I/O 过程，请将 fccIOProc 和 pIOProc 设置为 NULL。 如果未指定 MMIOINFO 结构，则这是默认行为。
  • 若要使用内部分配和管理的缓冲区打开内存文件，请将 pchBuffer 设置为 NULL， 将 fccIOProc 设置为 FOURCC_MEM， 将 cchBuffer 设置为缓冲区的初始大小，将 adwInfo 设置为缓冲区的增量扩展大小。 如有必要，此内存文件将自动以 adwInfo 中指定的字节数为增量进行扩展。 指定 dwOpenFlags 参数的 MMIO_CREATE 标志，以将文件末尾最初设置为缓冲区的开头。
  • 若要使用应用程序提供的缓冲区打开内存文件，请将 pchBuffer 设置为指向内存缓冲区， 将 fccIOProc 设置为FOURCC_MEM， 将 cchBuffer 设置为缓冲区的大小，将 adwInfo 设置为缓冲区的增量扩展大小。 仅当 pchBuffer 是通过调用 GlobalAlloc 和 GlobalLock 函数获取的指针时，adwInfo 中的扩展大小应为非零;在这种情况下，将调用 GlobalReAlloc 函数来扩展缓冲区。 换句话说，如果 pchBuffer 指向本地或全局数组或本地堆中的内存块， adwInfo 必须为零。 指定 dwOpenFlags 参数的 MMIO_CREATE 标志，以将文件末尾最初设置为缓冲区的开头。 否则，整个内存块被视为可读。
  • 若要使用当前打开的标准文件句柄 (即没有 HMMIO 类型的文件句柄) 多媒体文件 I/O 服务，请将 fccIOProc 设置为 FOURCC_DOS， 将 pchBuffer 设置为 NULL，将 adwInfo 设置为标准文件句柄。 文件中的偏移量将相对于文件的开头，与调用 mmioOpen 时标准文件中的位置无关;调用 mmioOpen 时，初始多媒体文件 I/O 偏移量将与标准文件中的偏移量相同。 若要在不关闭标准文件句柄的情况下关闭多媒体文件 I/O 文件句柄，请将 MMIO_FHOPEN 标志传递给 mmioClose。
必须调用 mmioClose 才能关闭使用 mmioOpen 打开的文件。 应用程序退出时，打开的文件不会自动关闭。

要求

要求 值
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 mmiscapi.h (包括 Mmiscapi.h、Windows.h)
Library Winmm.lib
DLL Winmm.dll