Compaq Multimedia Services
for OpenVMS Alpha
Programmer's Guide
Previous Contents Index

mmioCreateChunk

 Name mmioCreateChunk --- Create a new chunk Syntax 


#include <mme/mme_api.h> 
 
MMRESULT APIENTRY mmioCreateChunk(HMMIO hmmio, 
                                  LPMMCKINFO lpck, 
                                  UINT uFlags);
Arguments HMMIO hmmio
Specifies the file handle for an open RIFF file.

LPMMCKINFO lpck
Specifies a pointer to an MMCKINFO data structure that was previously filled by the mmioDescend or the mmioCreateChunk function.

UINT uFlags
Specifies option flags for creating the new chunk.

Description

The mmioCreateChunk function creates a new chunk in a RIFF file. The mmioCreateChunk function cannot insert a chunk into the middle of a file. If a chunk is created anywhere but at the end of a file, the mmioCreateChunk function overwrites existing information in the file.
Extensions None.

Return Values

1
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:
Error Code Description
MMIOERR_CANNOTWRITE The contents of the buffer could not be written to disk.
MMIOERR_CANNOTSEEK There was an error while seeking to the end.
See Also mmioAscend , mmioDescend , mmioFOURCC , mmioStringToFOURCC

mmioDescend

 Name mmioDescend --- Descend into a RIFF file chunk beginning at the current file position or search for a specified chunk Syntax 


#include <mme/mme_api.h> 
 
MMRESULT APIENTRY mmioDescend(HMMIO hmmio, 
                              LPMMCKINFO lpck, 
                              LPMMCKINFO lpckParent, 
                              UINT uFlags);
Arguments HMMIO hmmio
Specifies the file handle to an open RIFF file.

LPMMCKINFO lpck
Specifies a pointer to an MMCKINFO data structure to be filled by the mmioDescend function. See Section 6.2.1 for more information about the MMCKINFO data structure.

LPMMCKINFO lpckParent
Specifies a pointer to an optional MMCKINFO data structure that identifies the parent of the chunk being searched. A parent of a chunk is the enclosing chunk; only RIFF and LIST chunks can be parents.

If the lpckParent argument is not NULL, then the mmioDescend function assumes that the MMCKINFO data structure it references was filled when the mmioDescend function was called to descend into the parent chunk. In this case, the mmioDescend function searches only for a chunk within the parent chunk. Set the lpckParent argument to NULL if no parent is being specified. See Section 6.2.1 for more information about the MMCKINFO data structure.

UINT uFlags
Specifies search options for a chunk. If no flags are specified, mmioDescend descends into the chunk at the current file position. The following flags are defined:

MMIO_FINDCHUNK
Searches for a chunk with the specified chunk ID.

MMIO_FINDRIFF
Searches for a chunk with chunk ID RIFF and with the specified form type.

MMIO_FINDLIST
Searches for a chunk with chunk ID LIST and with the specified form type.

Description

The mmioDescend function descends into a RIFF file chunk beginning at the current file position or searches for a specified chunk. When using the mmioDescend function to search for a chunk, position the file at the beginning of the chunk before calling the mmioDescend function. The search begins at the current file position and continues to the end of the file. If a parent chunk is specified, the file position should be within the parent chunk before calling the mmioDescend function. The search begins at the current file position and continues to the end of the parent chunk.

If the mmioDescend function is unsuccessful in searching for a chunk, the current file position is undefined. If the mmioDescend function is successful, the current file position is changed. If the chunk is a RIFF or LIST chunk, the new file position is immediately after the form or list type (12 bytes from the beginning of the chunk). For other chunks, the new file position is at the start of the data portion of the chunk (8 bytes from the beginning of the chunk).

Extensions None.

Return Values

1
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns the following error code:
Error Code Description
MMIOERR_CHUNKNOTFOUND The end of the file or the end of the parent chunk was reached before the chunk was found.
See Also mmioAscend , mmioCreateChunk , mmioFOURCC mmioStringToFOURCC

mmioFlush

 Name mmioFlush --- Flush pending output to a file Syntax 


#include <mme/mme_api.h> 
 
MMRESULT APIENTRY mmioFlush(HMMIO hmmio, 
                            UINT uFlags);
Arguments HMMIO hmmio
Specifies the file handle of the file to flush.

UINT uFlags
Not used, set to zero (0).

Description

The mmioFlush function flushes any pending output to the hmmio file.
Extensions None.

Return Values

1
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns the following error code:
Error Code Description
MMIOERR_CANNOTWRITE The contents of the buffer could not be written to disk.
See Also mmioOpen , mmioRead , mmioSeek , mmioWrite

mmioFOURCC

 Name mmioFOURCC --- Convert four characters into a four-character code Syntax 


#include <mme/mme_api.h> 
 
FOURCC mmioFOURCC(CHAR ch0, 
                  CHAR ch1, 
                  CHAR ch2, 
                  CHAR ch3)
Arguments CHAR ch0, ch1, ch2, ch3
Characters to be converted into a four-character code.

Description

The mmioFOURCC macro converts four characters into a four-character code. All characters must be specified because the macro does not pad any missing characters as the mmioStringToFOURCC function does.
Extensions None.

Return Values

1
Returns a four-character code created from the given four characters.

See Also mmioAscend , mmioCreateChunk , mmioDescend , mmioStringToFOURCC

mmioOpen

 Name mmioOpen --- Open a file for unbuffered or buffered I/O Syntax 


#include <mme/mme_api.h> 
 
HMMIO APIENTRY mmioOpen(LPSTR szFileName, 
                        LPMMIOINFO lpmmioinfo, 
                        DWORD dwOpenFlags);
Arguments LPSTR szFileName
Specifies a pointer to a string containing the file name of the file to open.

The file name should not be longer than 128 bytes, including the terminating NULL. The length of the path string cannot exceed PATH_MAX nor can a component exceed NAME_MAX.

LPMMIOINFO lpmmioinfo
This flag is not used; set it to NULL.

DWORD dwOpenFlags
Specifies options for opening the file. The following flags are defined:

MMIO_READ
Opens the file for reading only. This is the default flag if MMIO_WRITE and MMIO_READWRITE are not specified.

MMIO_WRITE
Opens the file for writing only. Do not read from a file opened in this mode.

MMIO_READWRITE
Opens the file for both reading and writing.

MMIO_CREATE
Creates a new file. If the file already exists, it is truncated to zero length. For memory files, MMIO_CREATE indicates that the end of the file is initially at the start of the buffer.

MMIO_DELETE
Deletes a file. If this flag is specified, the szFileName argument should not be NULL. The return value will be TRUE (cast to HMMIO) if the file was deleted successfully, and FALSE otherwise. Do not call the mmioClose function for a file that has been deleted. If this flag is specified, all other flags are ignored.

Description

The mmioOpen function opens a file for unbuffered or buffered I/O.
Extensions None.

Return Values

1
Returns a file handle to the opened file. This handle is not an OpenVMS file handle; do not use it with any file I/O functions other than multimedia file I/O (mmio) functions. If the file cannot be opened, the return value is NULL. If the lpmmioinfo argument is not NULL, then the wError field of the MMIOINFO data structure contains error information returned by the I/O procedure.

See Also mmioClose , mmioRead , mmioSeek , mmioWrite

mmioRead

 Name mmioRead --- Read a specified number of bytes from a file Syntax 


#include <mme/mme_api.h> 
 
MMRESULT APIENTRY mmioRead(HMMIO hmmio, 
                           HPSTR pch, 
                           LONG cch);
Arguments HMMIO hmmio
Specifies the file handle to the file to be read.

HPSTR pch
Specifies a pointer to a buffer containing the data read from the file.

LONG cch
Specifies the number of bytes to read from the file.

Description

The mmioRead function reads a specified number of bytes from a file opened with the mmioOpen function.
Extensions None.

Return Values

1
Returns the value of the number of bytes actually read. If the end of the file has been reached and no more bytes can be read, the return value is 0. If there is an error reading from the file, the return value is --1.

See Also mmioClose , mmioOpen , mmioSeek , mmioWrite

mmioRename

 Name mmioRename --- Rename a file Syntax 


#include <mme/mme_api.h> 
 
MMRESULT APIENTRY mmioRename(LPCSTR szFileName, 
                             LPCSTR szNewFileName, 
                             LPMMIOINFO lpmmioinfo, 
                             DWORD dwRenameFlags);
Arguments LPCSTR szFileName
Specifies a pointer to a string containing the file name of the file to be renamed.

LPCSTR szNewFileName
Specifies a pointer to a string containing the new file name.

LPMMIOINFO lpmmioinfo
This flag is not used; set it to NULL.

DWORD dwRenameFlags
Must be set to zero.

Description

The mmioRename function renames a file.
Extensions None.

Return Values

1
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:
Error Code Description
MMIOERR_CANNOTWRITE The contents of the buffer could not be written to disk.
MMIOERR_FILENOTFOUND The file was not found.
See Also None.

mmioSeek

 Name mmioSeek --- Change the current file position in a file Syntax 


#include <mme/mme_api.h> 
 
MMRESULT APIENTRY mmioSeek(HMMIO hmmio, 
                           LONG lOffset, 
                           LONG iOrigin);
Arguments HMMIO hmmio
Specifies the file handle to the file within which to seek.

LONG lOffset
Specifies an offset for changing the current position in the file.

LONG iOrigin
Specifies how the offset given by the lOffset argument is interpreted. The following flags are defined:

SEEK_SET
Seeks to lOffset bytes from the beginning of the file.

SEEK_CUR
Seeks to lOffset bytes from the current file position.

SEEK_END
Seeks to lOffset bytes from the end of the file.

Description

The mmioSeek function changes the current file position in a file opened with the mmioOpen function. The current file position is the location in the file where data is read or written.

If seeking to an invalid location in a file, such as past the end of the file, the mmioSeek function might not return an error but subsequent I/O operations can fail. To locate the end of a file, call the mmioSeek function with the lOffset argument set to zero and the iOrigin argument set to SEEK_END.

Extensions None.

Return Values

1
Returns a new position specified in bytes, relative to the beginning of the file. If an error occurs, the return value is --1.

See Also mmioClose , mmioOpen

mmioStringToFOURCC

 Name mmioStringToFOURCC --- Convert a null-terminated string into a four-character code Syntax 


#include <mme/mme_api.h> 
 
FOURCC APIENTRY mmioStringToFOURCC(LPCSTR sz, 
                                   UINT uFlags);
Arguments LPCSTR sz
Specifies a pointer to a null-terminated string.

UINT uFlags
Specifies options for the conversion. The following flags are defined:

MMIO_TOUPPER
Converts all characters to uppercase.

NULL
Does not convert characters to uppercase.

Description

The mmioStringToFOURCC function converts a null-terminated string into a four-character code. The mmioStringToFOURCC function does not check to see if the sz argument follows conventions regarding legal characters to use in a four-character code. The string is copied to a four-character code and is either padded to the right with blanks or truncated to four characters, as required.
Extensions None.

Return Values

1
Returns the four-character code created from the given string.

See Also mmioAscend , mmioCreateChunk , mmioDescend , mmioFOURCC

mmioWrite

 Name mmioWrite --- Write a specified number of bytes to a file Syntax 


#include <mme/mme_api.h> 
 
MMRESULT APIENTRY mmioWrite(HMMIO hmmio, 
                            HPSTR pch, 
                            LONG cch);
Arguments HMMIO hmmio
Specifies the file handle to the file.

HPSTR pch
Specifies a pointer to the buffer to be written to the file.

LONG cch
Specifies the number of bytes to write to the file.

Description

The mmioWrite function writes a specified number of bytes to a file opened with the mmioOpen function. The current file position is incremented by the number of bytes written.
Extensions None.

Return Values

1
Returns the number of bytes actually written. If there is an error writing to the file, the return value is --1.

See Also mmioClose , mmioOpen , mmioRead

6.7 Multimedia File I/O Return Values

This section presents the multimedia file I/O return values or error codes. Table 6-2 lists the codes that can be returned by one or more of the file I/O functions.

Table 6-2 Multimedia File I/O Error Codes
Error Code Description
MMIOERR_CANNOTCLOSE Cannot close file.
MMIOERR_CANNOTOPEN Cannot open file.
MMIOERR_CANNOTEXPAND Cannot expand file.
MMIOERR_CANNOTREAD Cannot read file.
MMIOERR_CANNOTSEEK An error occurred while seeking to the end of the file.
MMIOERR_CANNOTWRITE The contents of the buffer could not be written to disk.
MMIOERR_CHUNKNOTFOUND The end of the file or the end of the parent chunk was reached before the chunk was found.
MMIOERR_FILENOTFOUND The file was not found.
MMIOERR_OUTOFMEMORY Out of memory.
MMIOERR_UNBUFFERED File is unbuffered.

Previous Next Contents Index