pszFileName (PSZ) - input

      The name of the file to open. If the fccIOProc field of MMIOINFO is NULL, mmioOpen looks at the pszFileName parameter to figure out what kind of file to open, as follows:

      • If the pszFileName parameter does not contain a plus (+), the name is assumed to be that of a DOS file, which is opened using the file system file open process.

      • If the file name is of the form ABC.EXT+ELEMENTNAME, the extension EXT is assumed to identify an installed I/O procedure that is called to perform I/O on the file (see mmioInstallIOProc). If the extension is BND, the system-provided BND I/O procedure processes the open. Note also that ELEMENTNAME could be of the form ABC.EXT followed by a plus sign (+). Parsing of the file name is done from right to left, so the first I/O procedure called belongs to the rightmost extension name that is followed by the +. The I/O procedure must be already installed and be able to further parse the file name, if required. The trailing separator character is stripped off by mmioOpen, and is not passed to the I/O procedure.

      • If the pszFileName parameter is NULL, then the aulInfo field of MMIOINFO contains the DOS file handle, and I/O is performed on that file handle. The MMIO offset is the same as the DOS offset when mmioOpen is called.

      • The pszFileName parameter cannot be longer than 260 bytes, including the terminating NULL, for a fully-qualified path name, or 256 bytes for an individual component name, including the terminating NULL.

      pmmioinfo (PMMIOINFO) - input

        A pointer to a caller-provided MMIOINFO structure containing extra parameters used by mmioOpen. Only certain values of the MMIOINFO structure may be used as input to the mmioOpen function. These fields are fccIOProc, pIOProc, cchBuffer, pchBuffer, aulInfo, and ulTranslate. fccIOProc and pIOProc are used if you wish to identify the I/O procedure to be used, rather than allowing MMIO to determine the appropriate I/O procedure. cchBuffer and pchBuffer are used for buffered access. aulInfo can contain a media type which restricts the open to I/O procedures of that type. ulTranslate is used to specify whether or not translation of header and data is performed.

        The pmmioinfo parameter can be NULL if the default values of the fields of MMIOINFO are sufficient. All unused fields must be set to 0, including reserved fields. (The easiest way to do this is to fill the structure with NULL bytes before setting the desired fields.) See the MMIOINFO data structure for more information. mmioOpen will modify the ulErrorRet field of MMIOINFO if an error is encountered.

      ulOpenFlags (ULONG) - input

        Contains one or more of the following flags:

        Note: The MMIO_READ, MMIO_WRITE, and MMIO_READWRITE flags are mutually exclusive.

        MMIO_READ

          Opens the file for reading only. This is the default behavior if MMIO_WRITE and MMIO_READWRITE are not specified. However, the flag is not automatically set in the default case.
        MMIO_WRITE
          Opens the file for writing. You should not read from a file opened in this way.
        MMIO_READWRITE
          Opens the file for both reading and writing.

          Note: To save a wave file, you must open the file with the MMIO_READWRITE flag. After the data is written, the I/O procedure will need to descend back into the wave chunk-a process that requires read support.

        MMIO_BUFSHARED
          Requests that if MMIO services allocates the I/O buffer, it does so from shared memory.
        MMIO_VERTBAR
          Requests that the vertical bar symbol (|) rather than the plus sign (+) be used as a file separator.
        MMIO_EXCLUSIVE
          Opens the file with exclusive mode, denying other processes both read and write access to the file. mmioOpen fails if the file has been opened in any other mode for read or write access, even by the current process.
        MMIO_DENYWRITE
          Opens the file and denies other processes write access. mmioOpen fails if the file has been opened in compatibility or for write access by any other process.
        MMIO_DENYREAD
          Opens the file and denies other processes read access. mmioOpen fails if the file has been opened in compatibility or for read access by any other process.
        MMIO_DENYNONE
          Opens the file and denies other processes read access. mmioOpen fails if the file has been opened in compatibility or for read access by any other process. This is the default if no share mode flags are defined.
        MMIO_CREATE
          Directs mmioOpen to create a new file. If the file already exists, it is truncated to 0 length. For a memory file, MMIO_CREATE indicates the end of the file is initially at the start of the buffer.
        MMIO_DELETE
          Directs mmioOpen to delete the file. The pszFileName parameter should not be NULL. The return value will be TRUE (sent to hmmio) if the file was deleted successfully, FALSE otherwise. Do not call mmioClose if MMIO_DELETE has been specified. All other flags are ignored if MMIO_DELETE is specified.
        MMIO_ALLOCBUF
          Directs mmioOpen to allocate an I/O buffer. If the cchBuffer field of MMIOINFO is 0, then a default buffer size (specified by the constant MMIO_DEFAULTBUFFER) is used. If the caller provides an I/O buffer, then MMIO_ALLOCBUF should not be specified.
        MMIO_APPEND
          Directs mmioOpen to allow appending to the end of the file. This will cause the logical file pointer to be positioned at the end of file when the open process completes. The open fails if both MMIO_CREATE and MMIO_APPEND are set. In the case of a BND element, this flag allows the element to expand past its existing fixed boundary by deleting the existing element and rewriting it at the end of a compound-file resource group (CGRP).
        MMIO_NOIDENTIFY
          Directs mmioOpen to directly open the file without attempting to automatically identify the file. An automatic identify is the default for this function.

        hmmio (HMMIO) - returns

          A handle is returned to use with further calls to MMIO functions to perform I/O. This handle is not a file system handle. Do not use this with such operations as OS/2 file system read, or write.

          NULL is returned if the file cannot be opened. See the exception for the preceding ulOpenFlags parameter flag MMIO_DELETE. If the pmmioinfo parameter is not NULL, the ulErrorRet field of its MMIOINFO structure will contain extended error information returned by the I/O procedure. If delete fails, ulErrorRet contains MMIOERR_DELETE_FAILED. The error return can also be queried by calling the mmioGetLastError function. See Return Codes for a description of MMIO Manager error codes.

        [Back] [Next]