The RIFF read/write object provides methods to access, read, write, and parse files in the RIFF format.
To learn more about the UMSRiffReadWrite object, see:
For introductory information, see Formatted File Access Objects.
A RIFF file is composed of chunks. Each chunk has at least three parts. The first part is an ID string identifying the type of chunk. The second part is an integer giving the size of the data. The third part is the data followed by a pad byte if the size of the data is an odd number.
The ID is a 4-byte string of ASCII characters identifying the type of chunk. When this value is represented as an unsigned integer, it is called a FOURCC value.
The size is a 4-byte unsigned integer least-significant byte (LSB) first. The specified size does not include the four bytes of the ID, the four bytes of the size, or the pad byte.
The data part of the chunk, shown in the illustration, can be any size from 0 to 4,294,967,294 bytes. If the size is an odd number, a pad byte is added to round the real size to an even number. The size value does not include this pad byte.
Every RIFF file has at least one as the top-level chunk. The first four bytes of a LIST chunk's data specify the LIST's type. The rest of the data is used to hold zero or more chunks. These chunks are considered to be inside the LIST chunk and are called subchunks. The subchunks can also be LIST chunks containing other subchunks.
The list type, shown in the illustration, is a 4-byte string of ASCII characters. When the list type is represented as an unsigned integer, it is called a FOURCC value just like the chunk ID.
To avoid name collision, integer values are defined in enumerated lists. The set of valid values from an enumerated list can vary with the application. The enumerated lists that are defined for the UMSRiffReadWrite class are listed below. The valid return values for each of the UMSRiffReadWrite methods are listed after the method's description on the following pages.
enum ReturnCode {
Success,
Failure,
InvalidListOrRiff,
InvalidCreatePosition,
NoChunk,
NoSubChunk,
NotAtChunkStart,
FileNotOpen,
StorageAllocationFailure,
ReadFailure,
WriteFailure,
ReadOnly,
WriteOnly,
InvalidArgument,
EndOfListChunk,
FIOFailure,
BadInternalState,
FilePermissions
};
The object uses the unistd.h file definition for the following:
Use the ascend function to indicate completion of reading or modifying the current chunk. This function moves the file pointer to the byte position after the end of the chunk, and sets the current chunk to the parent of the chunk from which you are ascending. If create_chunk was used to enter the chunk, this function also updates the chunk header to the real size of the data written.
Success Failure NoChunk FileNotOpen
This function flushes buffers and closes the file. Upon destruction, a UMSRiffReadWrite object automatically calls the close function if needed.
Success Failure FileNotOpen
This function creates a new chunk at the current file position. If the current file position is at the end of the file, the new chunk is appended; otherwise, the new chunk is inserted at that position. If the file system does not contain enough space for the temporary files, this method returns an error. The current file position after this call is the start of the data part of the newly created chunk.
Success Failure InvalidCreatePosition ReadOnly FileNotOpen WriteFailure InvalidListOrRiff StorageAllocationFailure InvalidArgument
This function uses a temporary file.
Success Failure NoChunk FileNotOpen
This function descends into a RIFF chunk. If type is 0, it descends into the chunk at the current file position. If type is nonzero, it searches for a chunk of that type starting at the current file position and ending with either having found the chunk or having reached the end of the current RIFF or LIST chunk. If type is RIFF or LIST and riff_or_list_type is nonzero, it searches for a RIFF or LIST chunk with the type riff_or_list_type. The current file position must be the start of a chunk at the time this function is called.
Success Failure NoSubChunk NoChunk InvalidListOrRiff NotAtChunkStart FileNotOpen WriteOnly EndOfListChunk ReadFailure StorageAllocationFailure
When writing to a file, flush flushes all buffers and updates chunk sizes (if needed) to match what has been written.
Success Failure FileNotOpen WriteFailure
On success, the end address of the RIFF chunk is returned. A 0 value is returned if not successful.
The end of data position for the current RIFF chunk.
On success, the data position of the RIFF chunk is returned. A 0 value is returned if not successful.
The start of data position for the current RIFF chunk.
On success, the ID of the RIFF chunk is returned. A 0 value is returned if not successful. This ID is a 4-byte unsigned integer that identifies the type of a chunk. For example a common value for the ID is 0x5453494c, which identifies a LIST chunk.
Use the string_to_FOURCC and FOURCC_to_string methods to convert to and from strings, such as LIST, and FOURCC chunk IDs, such as 0x5453494c.
The riff_fourcc representation of the current chunk ID.
On success, the ID string is returned at the location pointed to by s. This method is similar to the get_current_ID method but returns a string instead of a FOURCC value.
| in string s | This is a pointer to the returned ID string. This is always four characters plus a null. Your application must provide this space. |
The return value is either the pointer to the string s or null indicating that function was not successful.
On success, the ID (type) of the current RIFF or LIST chunk is returned. A 0 value is returned if the function is not successful or if the current chunk is not a RIFF or LIST chunk. This ID is a 4-byte unsigned integer that identifies the type of LIST chunk. For example, a common value for the list type is 0x4f464e49, which identifies the chunk as an INFO list chunk. Use the string_to_FOURCC and FOURCC_to_string methods to convert to and from stings, such as INFO, and FOURCC values, such as 0x4f464e49.
The FOURCC list type of the current RIFF chunk.
On success, the list type string is returned to the location pointed to by the s parameter. This method is similar to the get_current_list_type method.
| in string s | This is a pointer to the returned list type string. This is always four characters plus a null. Your application must provide this space. |
The return value is either the pointer to the string (same as ListType) or null if the function is not successful.
On success, the start of the RIFF chunk is returned. A 0 value is returned if the function is not successful.
The start position for the current RIFF chunk or 0 if the function is not successful.
On success, the size of the RIFF chunk in bytes is returned. A 0 value is returned if the function is not successful.
The size in bytes of the current RIFF chunk or 0 if the function is not successful.
This is similar to the lseek libc function call but should only be used to seek within the data part of the current chunk. Also, if the current chunk is a RIFF or LIST chunk, then lseek should only be used to seek to the start of a sub-chunk. Any other destination for the seek has undefined results.
The return value is the new absolute position in the file. A return value of -1 indicates an error.
This is similar to the read libc function call, but it only operates within the data part of the current RIFF chunk. The logical position within the RIFF chunk is modified accordingly.
| in void *buf | This is a pointer to a buffer that holds the data to be read. It must be at least nbytes in size. |
| in long nbyte | This is the number of bytes of data to be read. |
The return value is the actual number of bytes read. A return value of -1 indicates an error; a return value of 0 indicates that the end of the RIFF data chunk or end of the file has been reached.
Similar to the write libc function call. It only operates within the data part of the current RIFF chunk. If data is written past the end of the current chunk, then the chunk is extended. The operation of this method is affected by the set_insert and set_overwrite methods.
| in void *buf | A pointer to the data to be written. |
| in long nbyte | The number of bytes of data to be written. |
The return value is the number of bytes written. A return value of -1 indicates an error.
This function opens a RIFF file for reading or writing.
| in string path | The path name of the RIFF file to be opened. |
| in long oflag | The bitwise-OR of the flags from the fcntl.h file used the same way they are used for the libc open function. |
| in long filemode | When building a new file, the filemode parameter specifies the new file's permissions modes. This value is ignored if the file already exists. |
Success Failure FilePermissions
After your application calls the set_insert function, data written to a chunk is inserted at the current file location. This is the default. For example, when N bytes are written to a chunk, everything from the current file location to the end of the file is moved N bytes and the new data is inserted in the gap. This mode increases the size of the chunk by N bytes. This method does not affect the operation of the create_chunk method.
Success Failure FileNotOpen WriteFailure
After your application calls the set_overwrite function, data written to a chunk overwrites the data at the current file location. For example, when N bytes are written to a chunk, the next N bytes of data in the file are overwritten by the new data.
However, if there are only N2 bytes left in the chunk, where N2 is less than N, N2 bytes are overwritten, and (N-N2) bytes is inserted. This increases the size of the chunk by (N-N2) bytes.
This method does not affect the operation of the create_chunk method.
Success Failure FileNotOpen WriteFailure
Use the set_tmp function to specify the directory in which the UMSRiffReadWrite object should write temporary files. If this function is not called, the /tmp directory is used by default.
| in string *dpath | Name of the directory to be used for temporary files. This value can be null. If it is null, the /tmp directory is used. |
Success Failure InvalidArgument FileNotOpen StorageAllocationFailure
This function checks the status of the UMSRiffReadWrite object. If the object has not opened a file, this method returns FileNotOpen. If the file has been corrupted in some way, this method returns Failure. This method enables your code to check the status of a UMSRiffReadWrite object to see if the object is usable.
Success Failure FileNotOpen
Converts a string name into a FOURCC for use with chunk headers and RIFF or LIST types. If the string is longer than four characters, it is truncated to the first (leftmost) four. If the string is shorter than four characters, it is padded with spaces to four. If the length is 0 or if s is a null pointer, a 0 value is returned.
| in string s | The string to be converted to a FOURCC. |
The return value is the FOURCC value. A 0 value indicates an error.
This is similar to the write libc function call. It only operates within the data part of the current RIFF chunk. If data is written past the end of the current chunk, the chunk is extended. The operation of this method is affected by the set_insert and set_overwrite methods.
| void * buf | This is a pointer to the data to be written. |
| size_t nbyte | This is the number of bytes of data to be written. |
The return value is the number of bytes written. A return value of -1 indicates an error.
This converts a FOURCC value into a string. The string representation of the value v is returned at location s. The string is always four bytes long with one null terminator byte. The string includes any spaces needed to pad the type to four bytes when it was created.
| in unsigned long v | This is the FOURCC value to be converted to a string. |
| in string s | This is a pointer to the memory location to return the string representation of the value v. |
If successful a pointer to the string location is returned. A null pointer is returned on failure.
For introductory information, see Formatted File Access Objects.