RIFF::File Class Reference

RIFF File. More...

`#include <RIFF.h>`

Inheritance diagram for RIFF::File:

## Public Types

typedef int | Handle
| OS dependent type serving as file handle / descriptor for OS dependent file I/O operations.

## Public Member Functions

| File (uint32_t FileType)
| Create new RIFF file.
| File (const String &path)
| Load existing RIFF file.
| File (const String &path, uint32_t FileType, endian_t Endian, layout_t layout, offset_size_t fileOffsetSize=offset_size_auto)
| Load existing RIFF-like file.
stream_mode_t | GetMode () const
| Returns the file I/O mode currently being available for the calling thread for this RIFF file (either ro, rw or closed).
bool | SetMode (stream_mode_t NewMode)
| Change file access mode.
void | SetByteOrder (endian_t Endian)
| Set the byte order to be used when saving.
String | GetFileName () const
void | SetFileName (const String &path)
Handle | FileHandle () const
| Returns the OS dependent file I/O read handle intended to be used by the calling thread.
bool | IsNew () const
| Returns `true` if this file has been created new from scratch and has not been stored to disk yet.
layout_t | GetLayout () const
file_offset_t | GetCurrentFileSize () const
| Returns the current size of this file (in bytes) as it is currently yet stored on disk.
file_offset_t | GetRequiredFileSize ()
| Returns the required size (in bytes) for this RIFF File to be saved to disk.
file_offset_t | GetRequiredFileSize (offset_size_t fileOffsetSize)
| Returns the rquired size (in bytes) for this RIFF file to be saved to disk, assuming the passed fileOffsestSize would be used for the Save() operation.
int | GetFileOffsetSize () const
| Returns the current size (in bytes) of file offsets stored in the headers of all chunks of this file.
int | GetRequiredFileOffsetSize ()
| Returns the required size (in bytes) of file offsets stored in the headers of all chunks of this file if the current RIFF tree would be saved to disk by calling Save().
bool | IsIOPerThread () const
| Whether file streams are independent for each thread.
void | SetIOPerThread (bool enable)
| Enable/disable file streams being independent for each thread.
size_t | totalDataChunkCount () const
| File's total amount of ordinary (data) chunks.
size_t | totalListChunkCount () const
| File's total amount of list chunks.
size_t | totalChunkCount () const
| File's total amount of data chunks and list chunks.
virtual void | Save (progress_t *pProgress=NULL)
| Save changes to same file.
virtual void | Save (const String &path, progress_t *pProgress=NULL)
| Save changes to another file.
String | GetListTypeString () const
| Returns string representation of the lists's id.
uint32_t | GetListType () const
| Returns unsigned integer representation of the list's ID.
Chunk * | GetSubChunkAt (size_t pos)
| Returns subchunk at supplied pos position within this chunk list.
Chunk * | GetSubChunk (uint32_t ChunkID)
| Returns subchunk with chunk ID ChunkID within this chunk list.
List * | GetSubListAt (size_t pos)
| Returns sublist chunk with list type ListType at supplied pos position among all subchunks of type ListType within this chunk list.
List * | GetSubList (uint32_t ListType)
| Returns sublist chunk with list type ListType within this chunk list.
Chunk * | GetFirstSubChunk ()
| Returns the first subchunk within the list (which may be an ordinary chunk as well as a list chunk).
Chunk * | GetNextSubChunk ()
| Returns the next subchunk within the list (which may be an ordinary chunk as well as a list chunk).
List * | GetFirstSubList ()
| Returns the first sublist within the list (that is a subchunk with chunk ID "LIST").
List * | GetNextSubList ()
| Returns the next sublist (that is a subchunk with chunk ID "LIST") within the list.
size_t | CountSubChunks ()
| Returns number of subchunks within the list (including list chunks).
size_t | CountSubChunks (uint32_t ChunkID)
| Returns number of subchunks within the list with chunk ID ChunkId.
size_t | CountSubLists ()
| Returns number of sublists within the list.
size_t | CountSubLists (uint32_t ListType)
| Returns number of sublists within the list with list type ListType.
Chunk * | AddSubChunk (uint32_t uiChunkID, file_offset_t ullBodySize)
| Creates a new sub chunk.
List * | AddSubList (uint32_t uiListType)
| Creates a new list sub chunk.
void | DeleteSubChunk (Chunk *pSubChunk)
| Removes a sub chunk.
void | MoveSubChunk (Chunk *pSrc, Chunk *pDst)
| Moves a sub chunk witin this list.
void | MoveSubChunk (Chunk *pSrc, List *pNewParent)
| Moves a sub chunk from this list to another list.
String | GetChunkIDString () const
| Returns the String representation of the chunk's ID (e.g.
uint32_t | GetChunkID () const
| Chunk ID in unsigned integer representation.
File * | GetFile () const
| Returns pointer to the chunk's File object.
List * | GetParent () const
| Returns pointer to the chunk's parent list chunk.
file_offset_t | GetSize () const
| Chunk size in bytes (without header, thus the chunk data body).
file_offset_t | GetNewSize () const
| New chunk size if it was modified with Resize(), otherwise value returned will be equal to GetSize().
file_offset_t | GetPos () const
| Current read/write position within the chunk data body (starting with 0).
file_offset_t | GetFilePos () const
| Current, actual offset in file of current chunk data body read/write position.
file_offset_t | SetPos (file_offset_t Where, stream_whence_t Whence=stream_start)
| Sets the position within the chunk body, thus within the data portion of the chunk (in bytes).
file_offset_t | RemainingBytes () const
| Returns the number of bytes left to read in the chunk body.
stream_state_t | GetState () const
| Returns the current state of the chunk object.
file_offset_t | Read (void *pData, file_offset_t WordCount, file_offset_t WordSize)
| Reads WordCount number of data words with given WordSize and copies it into a buffer pointed by pData.
file_offset_t | ReadInt8 (int8_t *pData, file_offset_t WordCount=1)
| Reads WordCount number of 8 Bit signed integer words and copies it into the buffer pointed by pData.
int8_t | ReadInt8 ()
| Reads one 8 Bit signed integer word and increments the position within the chunk.
file_offset_t | ReadUint8 (uint8_t *pData, file_offset_t WordCount=1)
| Reads WordCount number of 8 Bit unsigned integer words and copies it into the buffer pointed by pData.
uint8_t | ReadUint8 ()
| Reads one 8 Bit unsigned integer word and increments the position within the chunk.
file_offset_t | ReadInt16 (int16_t *pData, file_offset_t WordCount=1)
| Reads WordCount number of 16 Bit signed integer words and copies it into the buffer pointed by pData.
int16_t | ReadInt16 ()
| Reads one 16 Bit signed integer word and increments the position within the chunk.
file_offset_t | ReadUint16 (uint16_t *pData, file_offset_t WordCount=1)
| Reads WordCount number of 16 Bit unsigned integer words and copies it into the buffer pointed by pData.
uint16_t | ReadUint16 ()
| Reads one 16 Bit unsigned integer word and increments the position within the chunk.
file_offset_t | ReadInt32 (int32_t *pData, file_offset_t WordCount=1)
| Reads WordCount number of 32 Bit signed integer words and copies it into the buffer pointed by pData.
int32_t | ReadInt32 ()
| Reads one 32 Bit signed integer word and increments the position within the chunk.
file_offset_t | ReadUint32 (uint32_t *pData, file_offset_t WordCount=1)
| Reads WordCount number of 32 Bit unsigned integer words and copies it into the buffer pointed by pData.
uint32_t | ReadUint32 ()
| Reads one 32 Bit unsigned integer word and increments the position within the chunk.
void | ReadString (String &s, int size)
| Reads a null-padded string of size characters and copies it into the string s.
file_offset_t | Write (void *pData, file_offset_t WordCount, file_offset_t WordSize)
| Writes WordCount number of data words with given WordSize from the buffer pointed by pData.
file_offset_t | WriteInt8 (int8_t *pData, file_offset_t WordCount=1)
| Writes WordCount number of 8 Bit signed integer words from the buffer pointed by pData to the chunk's body, directly to the actual "physical" file.
file_offset_t | WriteUint8 (uint8_t *pData, file_offset_t WordCount=1)
| Writes WordCount number of 8 Bit unsigned integer words from the buffer pointed by pData to the chunk's body, directly to the actual "physical" file.
file_offset_t | WriteInt16 (int16_t *pData, file_offset_t WordCount=1)
| Writes WordCount number of 16 Bit signed integer words from the buffer pointed by pData to the chunk's body, directly to the actual "physical" file.
file_offset_t | WriteUint16 (uint16_t *pData, file_offset_t WordCount=1)
| Writes WordCount number of 16 Bit unsigned integer words from the buffer pointed by pData to the chunk's body, directly to the actual "physical" file.
file_offset_t | WriteInt32 (int32_t *pData, file_offset_t WordCount=1)
| Writes WordCount number of 32 Bit signed integer words from the buffer pointed by pData to the chunk's body, directly to the actual "physical" file.
file_offset_t | WriteUint32 (uint32_t *pData, file_offset_t WordCount=1)
| Writes WordCount number of 32 Bit unsigned integer words from the buffer pointed by pData to the chunk's body, directly to the actual "physical" file.
void * | LoadChunkData ()
| Load chunk body into RAM.
void | ReleaseChunkData ()
| Free loaded chunk body from RAM.
void | Resize (file_offset_t NewSize)
| Resize chunk.

## Protected Types

typedef std::map< uint32_t, RIFF::Chunk * > | ChunkMap
typedef std::vector< Chunk * > | ChunkList
typedef std::set< Chunk * > | ChunkSet

## Protected Member Functions

Handle | FileWriteHandle () const
| Returns the OS dependent file I/O write handle intended to be used by the calling thread.
HandlePair | FileHandlePair () const
| Returns the OS dependent file I/O read and write handles intended to be used by the calling thread.
void | ReadHeader (file_offset_t filePos)
void | WriteHeader (file_offset_t filePos)
void | LoadSubChunks (progress_t *pProgress=NULL)
void | LoadSubChunksRecursively (progress_t *pProgress=NULL)
virtual file_offset_t | RequiredPhysicalSize (int fileOffsetSize)
| Returns the actual total size in bytes (including List chunk header and all subchunks) of this List Chunk if being stored to a file.
virtual file_offset_t | WriteChunk (file_offset_t ullWritePos, file_offset_t ullCurrentDataOffset, progress_t *pProgress=NULL)
| Write list chunk persistently e.g.
virtual void | __resetPos ()
| Sets List Chunk's read/write position to zero and causes all sub chunks to do the same.
void | DeleteChunkList ()
file_offset_t | ReadSceptical (void *pData, file_offset_t WordCount, file_offset_t WordSize)
| Just an internal wrapper for the main Read() method with additional Exception throwing on errors.

## Static Protected Member Functions

static String | convertToString (uint32_t word)

## Protected Attributes

RIFF::File::IO | io
String | Filename
bool | bEndianNative
bool | bIsNewFile
layout_t | Layout
| An ordinary RIFF file is always set to layout_standard.
offset_size_t | FileOffsetPreference
int | FileOffsetSize
| Size of file offsets (in bytes) when this file was opened (or saved the last time).
size_t | nDataChunkCount
size_t | nListChunkCount
uint32_t | ListType
ChunkList * | pSubChunks
ChunkMap * | pSubChunksMap
ChunkList::iterator | ChunksIterator
ChunkList::iterator | ListIterator
uint32_t | ChunkID
file_offset_t | ullCurrentChunkSize
file_offset_t | ullNewChunkSize
List * | pParent
File * | pFile
file_offset_t | ullStartPos
uint8_t * | pChunkData
file_offset_t | ullChunkDataSize
struct RIFF::Chunk::ChunkPos | chunkPos

## Detailed Description

RIFF File.

Handles arbitrary RIFF files and provides together with its base classes convenient methods to walk through, read and modify the file's RIFF tree.

Definition at line 314 of file RIFF.h.

## Member Typedef Documentation

## ChunkList

typedef std::vector<Chunk*> RIFF::List::ChunkList

protected inherited

Definition at line 287 of file RIFF.h.

## ChunkMap

typedef std::map<uint32_t, RIFF::Chunk*> RIFF::List::ChunkMap

protected inherited

Definition at line 286 of file RIFF.h.

## ChunkSet

typedef std::set<Chunk*> RIFF::List::ChunkSet

protected inherited

Definition at line 288 of file RIFF.h.

## Handle

typedef int RIFF::File::Handle

OS dependent type serving as file handle / descriptor for OS dependent file I/O operations.

Definition at line 321 of file RIFF.h.

## Constructor & Destructor Documentation

## File() [1/3]

RIFF::File::File | ( | uint32_t | FileType | ) |

Create new RIFF file.

Use this constructor if you want to create a new RIFF file completely "from scratch". Note: there must be no empty chunks or empty list chunks when trying to make the new RIFF file persistent with Save()!

Note: by default, the RIFF file will be saved in native endian format; that is, as a RIFF file on little-endian machines and as a RIFX file on big-endian. To change this behaviour, call SetByteOrder() before calling Save().

Parameters

  FileType | - four-byte identifier of the RIFF file type

See also
  AddSubChunk(), AddSubList(), SetByteOrder()

Definition at line 1833 of file RIFF.cpp.

References FileOffsetSize, Layout, RIFF::layout_standard, and RIFF::offset_size_auto.

## File() [2/3]

RIFF::File::File | ( | const String & | path | ) |

Load existing RIFF file.

Loads an existing RIFF file with all its chunks.

Parameters

  path | - path and file name of the RIFF file to open

Exceptions

  RIFF::Exception | if error occurred while trying to load the given RIFF file

Definition at line 1856 of file RIFF.cpp.

References FileOffsetSize, Layout, RIFF::layout_standard, and RIFF::offset_size_auto.

## File() [3/3]

RIFF::File::File | ( | const String & | path,
|  | uint32_t | FileType,
|  | endian_t | Endian,
|  | layout_t | layout,
|  | offset_size_t | fileOffsetSize = offset_size_auto )

Load existing RIFF-like file.

Loads an existing file, which is not a "real" RIFF file, but similar to an ordinary RIFF file.

A "real" RIFF file contains at top level a List chunk either with chunk ID "RIFF" or "RIFX". The simple constructor above expects this to be case, and if it finds the toplevel List chunk to have another chunk ID than one of those two expected ones, it would throw an Exception and would refuse to load the file accordingly.

Since there are however a lot of file formats which use the same simple principles of the RIFF format, with another toplevel List chunk ID though, you can use this alternative constructor here to be able to load and handle those files in the same way as you would do with "real" RIFF files.

Parameters

  path | - path and file name of the RIFF-alike file to be opened
  FileType | - expected toplevel List chunk ID (this is the very first chunk found in the file)
  Endian | - whether the file uses little endian or big endian layout
  layout | - general file structure type
  fileOffsetSize | - (optional) preference how to deal with large files

Exceptions

  RIFF::Exception | if error occurred while trying to load the given RIFF-alike file

Definition at line 1905 of file RIFF.cpp.

References FileOffsetSize, Layout, RIFF::offset_size_64bit, and SetByteOrder().

## ~File()

RIFF::File::~File | ( |  | ) |

virtual

Definition at line 2466 of file RIFF.cpp.

## Member Function Documentation

## __resetPos()

void RIFF::List::__resetPos | ( |  | ) |

protected virtual inherited

Sets List Chunk's read/write position to zero and causes all sub chunks to do the same.

Reimplemented from RIFF::Chunk.

Definition at line 1798 of file RIFF.cpp.

References RIFF::Chunk::__resetPos().

Referenced by RIFF::File::SetMode().

## AddSubChunk()

Chunk * RIFF::List::AddSubChunk | ( | uint32_t | uiChunkID,
|  | file_offset_t | ullBodySize )

inherited

Creates a new sub chunk.

Creates and adds a new sub chunk to this list chunk. Note that the chunk's body size given by ullBodySize must be greater than zero. You have to call File::Save() to make this change persistent to the actual file and before performing any data write operations on the new chunk!

Parameters

  uiChunkID | - chunk ID of the new chunk
  ullBodySize | - size of the new chunk's body, that is its actual data size (without header)

Exceptions

  RIFF::Exception | if ullBodySize equals zero

Definition at line 1485 of file RIFF.cpp.

References RIFF::Chunk::Resize().

Referenced by gig::File::AddInstrument(), gig::File::AddSample(), and gig::Instrument::UpdateChunks().

## AddSubList()

List * RIFF::List::AddSubList | ( | uint32_t | uiListType | ) |

inherited

Creates a new list sub chunk.

Creates and adds a new list sub chunk to this list chunk. Note that you have to add sub chunks / sub list chunks to the new created chunk before trying to make this change persisten to the actual file with File::Save()!

Parameters

  uiListType | - list ID of the new list chunk

Definition at line 1568 of file RIFF.cpp.

Referenced by DLS::File::__ensureMandatoryChunksExist(), gig::Region::AddDimension(), DLS::File::AddInstrument(), gig::File::AddInstrument(), DLS::File::AddSample(), gig::File::AddSample(), gig::Region::DeleteDimensionZone(), gig::DimensionRegion::DeleteSampleLoop(), gig::Region::SplitDimensionZone(), gig::File::UpdateChunks(), gig::Group::UpdateChunks(), gig::Instrument::UpdateChunks(), and gig::Region::UpdateChunks().

## convertToString()

String RIFF::Chunk::convertToString | ( | uint32_t | word | ) |

inline static protected inherited

Definition at line 245 of file RIFF.h.

## CountSubChunks() [1/2]

size_t RIFF::List::CountSubChunks | ( |  | ) |

inherited

Returns number of subchunks within the list (including list chunks).

Definition at line 1423 of file RIFF.cpp.

Referenced by CountSubLists(), and gig::File::UpdateChunks().

## CountSubChunks() [2/2]

size_t RIFF::List::CountSubChunks | ( | uint32_t | ChunkID | ) |

inherited

Returns number of subchunks within the list with chunk ID ChunkId.

Definition at line 1432 of file RIFF.cpp.

## CountSubLists() [1/2]

size_t RIFF::List::CountSubLists | ( |  | ) |

inherited

Returns number of sublists within the list.

Definition at line 1449 of file RIFF.cpp.

References CountSubChunks().

## CountSubLists() [2/2]

size_t RIFF::List::CountSubLists | ( | uint32_t | ListType | ) |

inherited

Returns number of sublists within the list with list type ListType.

Definition at line 1457 of file RIFF.cpp.

References GetListType().

## DeleteChunkList()

void RIFF::List::DeleteChunkList | ( |  | ) |

protected inherited

Definition at line 1230 of file RIFF.cpp.

## DeleteSubChunk()

void RIFF::List::DeleteSubChunk | ( | Chunk * | pSubChunk | ) |

inherited

Removes a sub chunk.

Removes the sub chunk given by pSubChunk from this list and frees it completely from RAM. The given chunk can either be a normal sub chunk or a list sub chunk. In case the given chunk is a list chunk, all its subchunks (if any) will be removed recursively as well. You should call File::Save() to make this change persistent at any time.

Parameters

  pSubChunk | - sub chunk or sub list chunk to be removed

Definition at line 1591 of file RIFF.cpp.

References RIFF::Chunk::GetChunkID().

Referenced by DLS::Instrument::DeleteChunks(), DLS::Region::DeleteChunks(), DLS::Sample::DeleteChunks(), gig::Region::DeleteDimension(), gig::ScriptGroup::DeleteScript(), gig::File::DeleteScriptGroup(), gig::Instrument::UpdateChunks(), and gig::Region::UpdateChunks().

## FileHandle()

File::Handle RIFF::File::FileHandle | ( |  | ) | const

Returns the OS dependent file I/O read handle intended to be used by the calling thread.

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 2046 of file RIFF.cpp.

References FileHandlePair().

Referenced by GetCurrentFileSize().

## FileHandlePair()

File::HandlePair RIFF::File::FileHandlePair | ( |  | ) | const

protected

Returns the OS dependent file I/O read and write handles intended to be used by the calling thread.

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 2025 of file RIFF.cpp.

Referenced by FileHandle(), FileWriteHandle(), GetMode(), and Save().

## FileWriteHandle()

File::Handle RIFF::File::FileWriteHandle | ( |  | ) | const

protected

Returns the OS dependent file I/O write handle intended to be used by the calling thread.

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 2056 of file RIFF.cpp.

References FileHandlePair().

Referenced by Save().

## GetChunkID()

uint32_t RIFF::Chunk::GetChunkID | ( |  | ) | const

inline inherited

Chunk ID in unsigned integer representation.

Definition at line 190 of file RIFF.h.

Referenced by DLS::Articulation::Articulation(), RIFF::List::DeleteSubChunk(), RIFF::List::GetSubListAt(), RIFF::List::MoveSubChunk(), and sf2::VerifySize().

## GetChunkIDString()

String RIFF::Chunk::GetChunkIDString | ( |  | ) | const

inherited

Returns the String representation of the chunk's ID (e.g.

"RIFF", "LIST").

Definition at line 312 of file RIFF.cpp.

## GetCurrentFileSize()

file_offset_t RIFF::File::GetCurrentFileSize | ( |  | ) | const

Returns the current size of this file (in bytes) as it is currently yet stored on disk.

If this file does not yet exist on disk (i.e. when this RIFF File has just been created from scratch and Save() has not been called yet) then this method returns 0.

Definition at line 2499 of file RIFF.cpp.

References FileHandle().

Referenced by GetRequiredFileOffsetSize(), and Save().

## GetFile()

File * RIFF::Chunk::GetFile | ( |  | ) | const

inline inherited

Returns pointer to the chunk's File object.

Definition at line 191 of file RIFF.h.

Referenced by DLS::Sample::Sample().

## GetFileName()

String RIFF::File::GetFileName | ( |  | ) | const

Definition at line 1989 of file RIFF.cpp.

## GetFileOffsetSize()

int RIFF::File::GetFileOffsetSize | ( |  | ) | const

Returns the current size (in bytes) of file offsets stored in the headers of all chunks of this file.

Most RIFF files are using 32 bit file offsets internally, which limits them to a maximum file size of less than 4 GB though. In contrast to the common standard, this RIFF File class implementation supports handling of RIFF files equal or larger than 4 GB. In such cases 64 bit file offsets have to be used in all headers of all RIFF Chunks when being stored to a physical file. libgig by default automatically selects the correct file offset size for you. You may however also force one particular file offset size by supplying the respective option to the RIFF::File constructor.

This method can be used to check which RIFF file offset size is currently being used for this RIFF File.

Returns
  current RIFF file offset size used (in bytes)

See also
  offset_size_t

Definition at line 2593 of file RIFF.cpp.

References FileOffsetSize.

Referenced by DLS::Sample::Sample().

## GetFilePos()

file_offset_t RIFF::Chunk::GetFilePos | ( |  | ) | const

inherited

Current, actual offset in file of current chunk data body read/write position.

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 348 of file RIFF.cpp.

References GetPos().

## GetFirstSubChunk()

Chunk * RIFF::List::GetFirstSubChunk | ( |  | ) |

inherited

Returns the first subchunk within the list (which may be an ordinary chunk as well as a list chunk).

You have to call this method before you can call GetNextSubChunk(). Recall it when you want to start from the beginning of the list again.

Returns
  pointer to the first subchunk within the list, NULL otherwise

Deprecated
  This method is not reentrant-safe, use GetSubChunkAt() instead.

Definition at line 1342 of file RIFF.cpp.

## GetFirstSubList()

List * RIFF::List::GetFirstSubList | ( |  | ) |

inherited

Returns the first sublist within the list (that is a subchunk with chunk ID "LIST").

You have to call this method before you can call GetNextSubList(). Recall it when you want to start from the beginning of the list again.

Returns
  pointer to the first sublist within the list, NULL otherwise

Deprecated
  This method is not reentrant-safe, use GetSubListAt() instead.

Definition at line 1381 of file RIFF.cpp.

## GetLayout()

layout_t RIFF::File::GetLayout | ( |  | ) | const

Definition at line 2070 of file RIFF.cpp.

## GetListType()

uint32_t RIFF::List::GetListType | ( |  | ) | const

inline inherited

Returns unsigned integer representation of the list's ID.

Definition at line 266 of file RIFF.h.

Referenced by CountSubLists(), and GetSubList().

## GetListTypeString()

String RIFF::List::GetListTypeString | ( |  | ) | const

inherited

Returns string representation of the lists's id.

Definition at line 1810 of file RIFF.cpp.

## GetMode()

stream_mode_t RIFF::File::GetMode | ( |  | ) | const

Returns the file I/O mode currently being available for the calling thread for this RIFF file (either ro, rw or closed).

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 2066 of file RIFF.cpp.

References FileHandlePair().

## GetNewSize()

file_offset_t RIFF::Chunk::GetNewSize | ( |  | ) | const

inline inherited

New chunk size if it was modified with Resize(), otherwise value returned will be equal to GetSize().

Definition at line 194 of file RIFF.h.

Referenced by gig::File::RebuildSampleChecksumTable(), gig::DimensionRegion::UpdateChunks(), and gig::File::VerifySampleChecksumTable().

## GetNextSubChunk()

Chunk * RIFF::List::GetNextSubChunk | ( |  | ) |

inherited

Returns the next subchunk within the list (which may be an ordinary chunk as well as a list chunk).

You have to call GetFirstSubChunk() before you can use this method!

Returns
  pointer to the next subchunk within the list or NULL if end of list is reached

Deprecated
  This method is not reentrant-safe, use GetSubChunkAt() instead.

Definition at line 1361 of file RIFF.cpp.

## GetNextSubList()

List * RIFF::List::GetNextSubList | ( |  | ) |

inherited

Returns the next sublist (that is a subchunk with chunk ID "LIST") within the list.

You have to call GetFirstSubList() before you can use this method!

Returns
  pointer to the next sublist within the list, NULL if end of list is reached

Deprecated
  This method is not reentrant-safe, use GetSubListAt() instead.

Definition at line 1405 of file RIFF.cpp.

## GetParent()

List * RIFF::Chunk::GetParent | ( |  | ) | const

inline inherited

Returns pointer to the chunk's parent list chunk.

Definition at line 192 of file RIFF.h.

Referenced by DLS::Instrument::DeleteChunks(), DLS::Region::DeleteChunks(), DLS::Sample::DeleteChunks(), gig::ScriptGroup::DeleteScript(), and gig::File::DeleteScriptGroup().

## GetPos()

file_offset_t RIFF::Chunk::GetPos | ( |  | ) | const

inherited

Current read/write position within the chunk data body (starting with 0).

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 335 of file RIFF.cpp.

Referenced by DLS::Sample::CopyAssign(), GetFilePos(), Korg::KSFSample::GetPos(), GetState(), Read(), RemainingBytes(), and Write().

## GetRequiredFileOffsetSize()

int RIFF::File::GetRequiredFileOffsetSize | ( |  | ) |

Returns the required size (in bytes) of file offsets stored in the headers of all chunks of this file if the current RIFF tree would be saved to disk by calling Save().

See GetFileOffsetSize() for mor details about RIFF file offsets.

Returns
  RIFF file offset size required (in bytes) if being saved

See also
  offset_size_t

Definition at line 2607 of file RIFF.cpp.

References GetCurrentFileSize().

## GetRequiredFileSize() [1/2]

file_offset_t RIFF::File::GetRequiredFileSize | ( |  | ) |

Returns the required size (in bytes) for this RIFF File to be saved to disk.

The precise size of the final file on disk depends on the RIFF file offset size actually used internally in all headers of the RIFF chunks. By default libgig handles the required file offset size automatically for you; that means it is using 32 bit offsets for files smaller than 4 GB and 64 bit offsets for files equal or larger than 4 GB. You may however also override this default behavior by passing the respective option to the RIFF File constructor to force one particular offset size. In the latter case this method will return the file size for the requested forced file offset size that will be used when calling Save() later on.

You may also use the overridden method below to get the file size for an arbitrary other file offset size instead.

See also
  offset_size_t
  GetFileOffsetSize()

Definition at line 2529 of file RIFF.cpp.

References GetRequiredFileSize().

Referenced by GetRequiredFileSize(), GetRequiredFileSize(), Save(), Save(), and DLS::File::UpdateChunks().

## GetRequiredFileSize() [2/2]

file_offset_t RIFF::File::GetRequiredFileSize | ( | offset_size_t | fileOffsetSize | ) |

Returns the rquired size (in bytes) for this RIFF file to be saved to disk, assuming the passed fileOffsestSize would be used for the Save() operation.

This overridden method essentialy behaves like the above method, with the difference that you must provide a specific RIFF fileOffsetSize for calculating the theoretical final file size.

See also
  GetFileOffsetSize()

Definition at line 2544 of file RIFF.cpp.

References FileOffsetSize, GetRequiredFileSize(), RIFF::offset_size_32bit, RIFF::offset_size_64bit, RIFF::offset_size_auto, and RIFF::List::RequiredPhysicalSize().

## GetSize()

file_offset_t RIFF::Chunk::GetSize | ( |  | ) | const

inline inherited

Chunk size in bytes (without header, thus the chunk data body).

Definition at line 193 of file RIFF.h.

Referenced by DLS::File::File(), LoadChunkData(), DLS::Region::UpdateChunks(), DLS::Sampler::UpdateChunks(), gig::File::UpdateChunks(), gig::Instrument::UpdateChunks(), and sf2::VerifySize().

## GetState()

stream_state_t RIFF::Chunk::GetState | ( |  | ) | const

inherited

Returns the current state of the chunk object.

Following values are possible:

- RIFF::stream_ready : chunk data can be read (this is the usual case)
- RIFF::stream_closed : the data stream was closed somehow, no more reading possible
- RIFF::stream_end_reached : already reached the end of the chunk data, no more reading possible without SetPos()

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 434 of file RIFF.cpp.

References GetPos().

## GetSubChunk()

Chunk * RIFF::List::GetSubChunk | ( | uint32_t | ChunkID | ) |

inherited

Returns subchunk with chunk ID ChunkID within this chunk list.

Use this method if you expect only one subchunk of that type in the list. It there are more than one, it's undetermined which one of them will be returned! If there are no subchunks with that desired chunk ID, NULL will be returned.

Parameters

  ChunkID | - chunk ID of the sought subchunk

Returns
  pointer to the subchunk or NULL if there is none of that ID

Definition at line 1273 of file RIFF.cpp.

Referenced by DLS::Resource::Resource(), DLS::Sample::Sample(), gig::Sample::Sample(), DLS::File::UpdateChunks(), gig::File::UpdateChunks(), gig::Group::UpdateChunks(), and gig::Instrument::UpdateChunks().

## GetSubChunkAt()

Chunk * RIFF::List::GetSubChunkAt | ( | size_t | pos | ) |

inherited

Returns subchunk at supplied pos position within this chunk list.

If supplied pos is out of bounds then `NULL` is returned. The returned subchunk can either by an ordinary data chunk or a list chunk.

Parameters

  pos | - position of sought subchunk within this list

Returns
  pointer to the subchunk or NULL if supplied position is not within the valid range of this list

Definition at line 1256 of file RIFF.cpp.

Referenced by gig::File::UpdateChunks(), and gig::Group::UpdateChunks().

## GetSubList()

List * RIFF::List::GetSubList | ( | uint32_t | ListType | ) |

inherited

Returns sublist chunk with list type ListType within this chunk list.

Use this method if you expect only one sublist chunk of that type in the list. If there are more than one, it's undetermined which one of them will be returned! If there are no sublists with that desired list type, NULL will be returned.

Parameters

  ListType | - list type of the sought sublist

Returns
  pointer to the sublist or NULL if there is none of that type

Definition at line 1314 of file RIFF.cpp.

References GetListType().

Referenced by DLS::File::__ensureMandatoryChunksExist(), gig::Region::AddDimension(), DLS::File::AddInstrument(), gig::File::AddInstrument(), DLS::File::AddSample(), gig::File::AddSample(), gig::Region::DeleteDimension(), gig::Region::DeleteDimensionZone(), DLS::Info::Info(), gig::Instrument::MoveTo(), gig::Region::SplitDimensionZone(), DLS::Info::UpdateChunks(), gig::File::UpdateChunks(), gig::Group::UpdateChunks(), gig::Instrument::UpdateChunks(), and gig::Region::UpdateChunks().

## GetSubListAt()

List * RIFF::List::GetSubListAt | ( | size_t | pos | ) |

inherited

Returns sublist chunk with list type ListType at supplied pos position among all subchunks of type ListType within this chunk list.

If supplied pos is out of bounds then `NULL` is returned.

Parameters

  pos | - position of sought sublist within this list

Returns
  pointer to the sublist or NULL if if supplied position is not within valid range

Definition at line 1291 of file RIFF.cpp.

References RIFF::Chunk::GetChunkID().

## IsIOPerThread()

bool RIFF::File::IsIOPerThread | ( |  | ) | const

Whether file streams are independent for each thread.

All file I/O operations like reading from a RIFF chunk body (e.g. by calling Chunk::Read(), Chunk::ReadInt8()), writing to a RIFF chunk body (e.g. by calling Chunk::Write(), Chunk::WriteInt8()) or saving the current RIFF tree structure to some file (e.g. by calling Save()) operate on a file I/O stream state, i.e. there is a "current" file read/write position and reading/writing by a certain amount of bytes automatically advances that "current" file position.

By default there is only one stream state for a RIFF::File object, which is not an issue as long as only one thread is using the RIFF::File object at a time (which might also be the case in a collaborative / coroutine multi-threaded scenario).

If however a RIFF::File object is read/written simultaniously by multiple threads this can lead to undefined behaviour as the individual threads would concurrently alter the file stream position. For such a concurrent multithreaded file I/O scenario `SetIOPerThread(true)` might be enabled which causes each thread to automatically use its own file stream state.

Returns
  true if each thread has its own file stream state (default: false)

See also
  SetIOPerThread()

Definition at line 2637 of file RIFF.cpp.

## IsNew()

bool RIFF::File::IsNew | ( |  | ) | const

Returns `true` if this file has been created new from scratch and has not been stored to disk yet.

Definition at line 2477 of file RIFF.cpp.

## LoadChunkData()

void * RIFF::Chunk::LoadChunkData | ( |  | ) |

inherited

Load chunk body into RAM.

Loads the whole chunk body into memory. You can modify the data in RAM and save the data by calling File::Save() afterwards.

Caution: the buffer pointer will be invalidated once File::Save() was called. You have to call LoadChunkData() again to get a new, valid pointer whenever File::Save() was called.

You can call LoadChunkData() again if you previously scheduled to enlarge this chunk with a Resize() call. In that case the buffer will be enlarged to the new, scheduled chunk size and you can already place the new chunk data to the buffer and finally call File::Save() to enlarge the chunk physically and write the new data in one rush. This approach is definitely recommended if you have to enlarge and write new data to a lot of chunks.

Returns
  a pointer to the data in RAM on success, NULL otherwise

Exceptions

  Exception | if data buffer could not be enlarged

See also
  ReleaseChunkData()
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 984 of file RIFF.cpp.

References GetSize().

Referenced by gig::File::RebuildSampleChecksumTable(), gig::File::Save(), DLS::File::UpdateChunks(), DLS::Instrument::UpdateChunks(), DLS::Region::UpdateChunks(), DLS::Sample::UpdateChunks(), DLS::Sampler::UpdateChunks(), gig::DimensionRegion::UpdateChunks(), gig::File::UpdateChunks(), gig::Instrument::UpdateChunks(), gig::Region::UpdateChunks(), gig::File::VerifySampleChecksumTable(), and WriteChunk().

## LoadSubChunks()

void RIFF::List::LoadSubChunks | ( | progress_t * | pProgress = NULL | ) |

protected inherited

Definition at line 1689 of file RIFF.cpp.

## LoadSubChunksRecursively()

void RIFF::List::LoadSubChunksRecursively | ( | progress_t * | pProgress = NULL | ) |

protected inherited

Definition at line 1735 of file RIFF.cpp.

## MoveSubChunk() [1/2]

void RIFF::List::MoveSubChunk | ( | Chunk * | pSrc,
|  | Chunk * | pDst )

inherited

Moves a sub chunk witin this list.

Moves a sub chunk from one position in this list to another position in the same list. The pSrc chunk is placed before the pDst chunk.

Parameters

  pSrc | - sub chunk to be moved
  pDst | - the position to move to. pSrc will be placed before pDst. If pDst is 0, pSrc will be placed last in list.

Definition at line 1511 of file RIFF.cpp.

Referenced by gig::Region::AddDimension(), gig::Instrument::MoveTo(), gig::File::UpdateChunks(), and gig::Group::UpdateChunks().

## MoveSubChunk() [2/2]

void RIFF::List::MoveSubChunk | ( | Chunk * | pSrc,
|  | List * | pNewParent )

inherited

Moves a sub chunk from this list to another list.

Moves a sub chunk from this list list to the end of another list.

Parameters

  pSrc | - sub chunk to be moved
  pDst | - destination list where the chunk shall be moved to

Definition at line 1532 of file RIFF.cpp.

References RIFF::Chunk::GetChunkID().

## Read()

file_offset_t RIFF::Chunk::Read | ( | void * | pData,
|  | file_offset_t | WordCount,
|  | file_offset_t | WordSize )

inherited

Reads WordCount number of data words with given WordSize and copies it into a buffer pointed by pData.

The buffer has to be allocated and be sure to provide the correct WordSize, as this will be important and taken into account for eventual endian correction (swapping of bytes due to different native byte order of a system). The position within the chunk will automatically be incremented.

Parameters

  pData | destination buffer
  WordCount | number of data words to read
  WordSize | size of each data word to read

Returns
  number of successfully read data words or 0 if end of file reached or error occurred

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 465 of file RIFF.cpp.

References GetPos(), and SetPos().

Referenced by DLS::Articulation::Articulation(), DLS::File::File(), DLS::Instrument::Instrument(), Korg::KSFSample::Read(), ReadSceptical(), DLS::Resource::Resource(), and DLS::File::UpdateChunks().

## ReadHeader()

void RIFF::List::ReadHeader | ( | file_offset_t | filePos | ) |

protected inherited

Definition at line 1635 of file RIFF.cpp.

## ReadInt16() [1/2]

int16_t RIFF::Chunk::ReadInt16 | ( |  | ) |

inherited

Reads one 16 Bit signed integer word and increments the position within the chunk.

Endian correction will automatically be done if needed.

Returns
  read integer word

Exceptions

  RIFF::Exception | if an error occurred

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 899 of file RIFF.cpp.

References ReadSceptical().

## ReadInt16() [2/2]

file_offset_t RIFF::Chunk::ReadInt16 | ( | int16_t * | pData,
|  | file_offset_t | WordCount = 1 )

inherited

Reads WordCount number of 16 Bit signed integer words and copies it into the buffer pointed by pData.

The buffer has to be allocated. Endian correction will automatically be done if needed. The position within the chunk will automatically be incremented.

Parameters

  pData | destination buffer
  WordCount | number of 16 Bit signed integers to read

Returns
  number of read integers

Exceptions

  RIFF::Exception | if an error occurred or less than WordCount integers could be read!

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 695 of file RIFF.cpp.

References ReadSceptical().

## ReadInt32() [1/2]

int32_t RIFF::Chunk::ReadInt32 | ( |  | ) |

inherited

Reads one 32 Bit signed integer word and increments the position within the chunk.

Endian correction will automatically be done if needed.

Returns
  read integer word

Exceptions

  RIFF::Exception | if an error occurred

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 935 of file RIFF.cpp.

References ReadSceptical().

## ReadInt32() [2/2]

file_offset_t RIFF::Chunk::ReadInt32 | ( | int32_t * | pData,
|  | file_offset_t | WordCount = 1 )

inherited

Reads WordCount number of 32 Bit signed integer words and copies it into the buffer pointed by pData.

The buffer has to be allocated. Endian correction will automatically be done if needed. The position within the chunk will automatically be incremented.

Parameters

  pData | destination buffer
  WordCount | number of 32 Bit signed integers to read

Returns
  number of read integers

Exceptions

  RIFF::Exception | if an error occurred or less than WordCount integers could be read!

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 773 of file RIFF.cpp.

References ReadSceptical().

Referenced by gig::Sample::Sample().

## ReadInt8() [1/2]

int8_t RIFF::Chunk::ReadInt8 | ( |  | ) |

inherited

Reads one 8 Bit signed integer word and increments the position within the chunk.

Returns
  read integer word

Exceptions

  RIFF::Exception | if an error occurred

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 864 of file RIFF.cpp.

References ReadSceptical().

## ReadInt8() [2/2]

file_offset_t RIFF::Chunk::ReadInt8 | ( | int8_t * | pData,
|  | file_offset_t | WordCount = 1 )

inherited

Reads WordCount number of 8 Bit signed integer words and copies it into the buffer pointed by pData.

The buffer has to be allocated. The position within the chunk will automatically be incremented.

Parameters

  pData | destination buffer
  WordCount | number of 8 Bit signed integers to read

Returns
  number of read integers

Exceptions

  RIFF::Exception | if an error occurred or less than WordCount integers could be read!

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 617 of file RIFF.cpp.

References ReadSceptical().

## ReadSceptical()

file_offset_t RIFF::Chunk::ReadSceptical | ( | void * | pData,
|  | file_offset_t | WordCount,
|  | file_offset_t | WordSize )

protected inherited

Just an internal wrapper for the main Read() method with additional Exception throwing on errors.

Definition at line 599 of file RIFF.cpp.

References Read().

Referenced by ReadInt16(), ReadInt16(), ReadInt32(), ReadInt32(), ReadInt8(), ReadInt8(), ReadString(), ReadUint16(), ReadUint16(), ReadUint32(), ReadUint32(), ReadUint8(), and ReadUint8().

## ReadString()

void RIFF::Chunk::ReadString | ( | String & | s,
|  | int | size )

inherited

Reads a null-padded string of size characters and copies it into the string s.

The position within the chunk will automatically be incremented.

Parameters

  s | destination string
  size | number of characters to read

Exceptions

  RIFF::Exception | if an error occurred or less than size characters could be read!

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 830 of file RIFF.cpp.

References ReadSceptical().

## ReadUint16() [1/2]

uint16_t RIFF::Chunk::ReadUint16 | ( |  | ) |

inherited

Reads one 16 Bit unsigned integer word and increments the position within the chunk.

Endian correction will automatically be done if needed.

Returns
  read integer word

Exceptions

  RIFF::Exception | if an error occurred

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 917 of file RIFF.cpp.

References ReadSceptical().

## ReadUint16() [2/2]

file_offset_t RIFF::Chunk::ReadUint16 | ( | uint16_t * | pData,
|  | file_offset_t | WordCount = 1 )

inherited

Reads WordCount number of 16 Bit unsigned integer words and copies it into the buffer pointed by pData.

The buffer has to be allocated. Endian correction will automatically be done if needed. The position within the chunk will automatically be incremented.

Parameters

  pData | destination buffer
  WordCount | number of 8 Bit unsigned integers to read

Returns
  number of read integers

Exceptions

  RIFF::Exception | if an error occurred or less than WordCount integers could be read!

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 734 of file RIFF.cpp.

References ReadSceptical().

## ReadUint32() [1/2]

uint32_t RIFF::Chunk::ReadUint32 | ( |  | ) |

inherited

Reads one 32 Bit unsigned integer word and increments the position within the chunk.

Endian correction will automatically be done if needed.

Returns
  read integer word

Exceptions

  RIFF::Exception | if an error occurred

See also
  File::IsIOPerThread() for multi-threaded streamings

Definition at line 953 of file RIFF.cpp.

References ReadSceptical().

## ReadUint32() [2/2]

file_offset_t RIFF::Chunk::ReadUint32 | ( | uint32_t * | pData,
|  | file_offset_t | WordCount = 1 )

inherited

Reads WordCount number of 32 Bit unsigned integer words and copies it into the buffer pointed by pData.

The buffer has to be allocated. Endian correction will automatically be done if needed. The position within the chunk will automatically be incremented.

Parameters

  pData | destination buffer
  WordCount | number of 32 Bit unsigned integers to read

Returns
  number of read integers

Exceptions

  RIFF::Exception | if an error occurred or less than WordCount integers could be read!

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 812 of file RIFF.cpp.

References ReadSceptical().

Referenced by DLS::Articulation::Articulation(), DLS::File::File(), and DLS::Instrument::Instrument().

## ReadUint8() [1/2]

uint8_t RIFF::Chunk::ReadUint8 | ( |  | ) |

inherited

Reads one 8 Bit unsigned integer word and increments the position within the chunk.

Returns
  read integer word

Exceptions

  RIFF::Exception | if an error occurred

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 881 of file RIFF.cpp.

References ReadSceptical().

## ReadUint8() [2/2]

file_offset_t RIFF::Chunk::ReadUint8 | ( | uint8_t * | pData,
|  | file_offset_t | WordCount = 1 )

inherited

Reads WordCount number of 8 Bit unsigned integer words and copies it into the buffer pointed by pData.

The buffer has to be allocated. The position within the chunk will automatically be incremented.

Parameters

  pData | destination buffer
  WordCount | number of 8 Bit unsigned integers to read

Returns
  number of read integers

Exceptions

  RIFF::Exception | if an error occurred or less than WordCount integers could be read!

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 656 of file RIFF.cpp.

References ReadSceptical().

## ReleaseChunkData()

void RIFF::Chunk::ReleaseChunkData | ( |  | ) |

inherited

Free loaded chunk body from RAM.

Frees loaded chunk body data from memory (RAM). You should call File::Save() before calling this method if you modified the data to make the changes persistent.

Definition at line 1033 of file RIFF.cpp.

## RemainingBytes()

file_offset_t RIFF::Chunk::RemainingBytes | ( |  | ) | const

inherited

Returns the number of bytes left to read in the chunk body.

When reading data from the chunk using the Read*() Methods, the position within the chunk data (that is the chunk body) will be incremented by the number of read bytes and RemainingBytes() returns how much data is left to read from the current position to the end of the chunk data.

Returns
  number of bytes left to read

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 400 of file RIFF.cpp.

References GetPos().

## RequiredPhysicalSize()

file_offset_t RIFF::List::RequiredPhysicalSize | ( | int | fileOffsetSize | ) |

protected virtual inherited

Returns the actual total size in bytes (including List chunk header and all subchunks) of this List Chunk if being stored to a file.

Parameters

  fileOffsetSize | - RIFF file offset size (in bytes) assumed when being saved to a file

Reimplemented from RIFF::Chunk.

Definition at line 1625 of file RIFF.cpp.

Referenced by RIFF::File::GetRequiredFileSize().

## Resize()

void RIFF::Chunk::Resize | ( | file_offset_t | NewSize | ) |

inherited

Resize chunk.

Resizes this chunk's body, that is the actual size of data possible to be written to this chunk. This call will return immediately and just schedule the resize operation. You should call File::Save() to actually perform the resize operation(s) "physically" to the file. As this can take a while on large files, it is recommended to call Resize() first on all chunks which have to be resized and finally to call File::Save() to perform all those resize operations in one rush.

Caution: You cannot directly write to enlarged chunks before calling File::Save() as this might exceed the current chunk's body boundary!

Parameters

  NewSize | - new chunk body size in bytes (must be greater than zero)

Exceptions

  RIFF::Exception | if NewSize is less than 1 or unrealistic large

See also
  File::Save()

Definition at line 1058 of file RIFF.cpp.

Referenced by RIFF::List::AddSubChunk(), gig::File::RebuildSampleChecksumTable(), DLS::File::UpdateChunks(), DLS::Sampler::UpdateChunks(), gig::DimensionRegion::UpdateChunks(), gig::File::UpdateChunks(), and gig::Instrument::UpdateChunks().

## Save() [1/2]

void RIFF::File::Save | ( | const String & | path,
|  | progress_t * | pProgress = NULL )

virtual

Save changes to another file.

Make all changes of all chunks persistent by writing them to another file. Caution: this method is optimized for writing to another file, do not use it to save the changes to the same file! Use File::Save() in that case instead! Ignoring this might result in a corrupted file, especially in case chunks were resized!

After calling this method, this File object will be associated with the new file (given by path) afterwards.

Parameters

  path | - path and file name where everything should be written to
  pProgress | - optional: callback function for progress notification

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 2346 of file RIFF.cpp.

References RIFF::progress_t::__private, FileOffsetSize, FileWriteHandle(), GetRequiredFileSize(), Layout, RIFF::layout_flat, SetMode(), and RIFF::List::WriteChunk().

## Save() [2/2]

void RIFF::File::Save | ( | progress_t * | pProgress = NULL | ) |

virtual

Save changes to same file.

Make all changes of all chunks persistent by writing them to the actual (same) file.

Parameters

  pProgress | - optional: callback function for progress notification

Exceptions

  RIFF::Exception | if there is an empty chunk or empty list chunk or any kind of IO error occurred

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 2209 of file RIFF.cpp.

References RIFF::progress_t::__private, FileHandlePair(), FileOffsetSize, GetCurrentFileSize(), GetRequiredFileSize(), Layout, RIFF::layout_flat, SetMode(), and RIFF::List::WriteChunk().

## SetByteOrder()

void RIFF::File::SetByteOrder | ( | endian_t | Endian | ) |

Set the byte order to be used when saving.

Set the byte order to be used in the file. A value of endian_little will create a RIFF file, endian_big a RIFX file and endian_native will create a RIFF file on little-endian machines and RIFX on big-endian machines.

Parameters

  Endian | - endianess to use when file is saved.

Definition at line 2191 of file RIFF.cpp.

Referenced by File().

## SetFileName()

void RIFF::File::SetFileName | ( | const String & | path | ) |

Definition at line 1993 of file RIFF.cpp.

## SetIOPerThread()

void RIFF::File::SetIOPerThread | ( | bool | enable | ) |

Enable/disable file streams being independent for each thread.

By enabling this feature (default off) each thread will automatically use its own file I/O stream state for allowing simultanious multi-threaded file read/write operations.

NOTE: After having enabled this feature, the individual threads must at least once check GetState() and if their file I/O stream is yet closed they must call SetMode() (i.e. once) respectively to open their own file handles before being able to use any of the Read() or Write() methods.

Parameters

  enable | - `true:` one independent stream state per thread, `false:` only one stream in total shared by all threads

See also
  IsIOPerThread() for more details about this feature

Definition at line 2666 of file RIFF.cpp.

## SetMode()

bool RIFF::File::SetMode | ( | stream_mode_t | NewMode | ) |

Change file access mode.

Changes files access mode either to read-only mode or to read/write mode.

Parameters

  NewMode | - new file access mode

Returns
  true if mode was changed, false if current mode already equals new mode

Exceptions

  RIFF::Exception | if file could not be opened in requested file access mode or if passed access mode is unknown

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 2086 of file RIFF.cpp.

References RIFF::List::__resetPos().

Referenced by Save(), and Save().

## SetPos()

file_offset_t RIFF::Chunk::SetPos | ( | file_offset_t | Where,
|  | stream_whence_t | Whence = stream_start )

inherited

Sets the position within the chunk body, thus within the data portion of the chunk (in bytes).

Caution: the position will be reset to zero whenever File::Save() was called.

Parameters

  Where | - position offset (in bytes)
  Whence | - optional: defines to what Where relates to, if omitted Where relates to beginning of the chunk data

See also
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 365 of file RIFF.cpp.

Referenced by DLS::Articulation::Articulation(), DLS::Sample::CopyAssign(), DLS::File::File(), DLS::Instrument::Instrument(), Read(), DLS::Resource::Resource(), gig::Sample::Sample(), Korg::KSFSample::SetPos(), gig::File::SetSampleChecksum(), and Write().

## totalChunkCount()

size_t RIFF::File::totalChunkCount | ( |  | ) | const

File's total amount of data chunks and list chunks.

The returned value is equivalent to:

totalDataChunkCount() + totalListChunkCount()
RIFF::File::totalDataChunkCount
size_t totalDataChunkCount() const
File's total amount of ordinary (data) chunks.
Definition RIFF.cpp:2696
RIFF::File::totalListChunkCount
size_t totalListChunkCount() const
File's total amount of list chunks.
Definition RIFF.cpp:2708

Caution: This method only returns the amount of chunks known so far (i.e. chunks either already loaded, or added via API). For performance reasons, chunks are loaded only on demand. So if this is an already existing RIFF file and you need to know the true total amount of chunks, then make sure to call LoadSubChunksRecursively() before.

Definition at line 2724 of file RIFF.cpp.

## totalDataChunkCount()

size_t RIFF::File::totalDataChunkCount | ( |  | ) | const

File's total amount of ordinary (data) chunks.

Caution: This method only returns the amount of chunks known so far (i.e. chunks either already loaded, or added via API). For performance reasons, chunks are loaded only on demand. So if this is an already existing RIFF file and you need to know the true total amount of chunks, then make sure to call LoadSubChunksRecursively() before.

Definition at line 2696 of file RIFF.cpp.

## totalListChunkCount()

size_t RIFF::File::totalListChunkCount | ( |  | ) | const

File's total amount of list chunks.

Caution: This method only returns the amount of chunks known so far (i.e. chunks either already loaded, or added via API). For performance reasons, chunks are loaded only on demand. So if this is an already existing RIFF file and you need to know the true total amount of chunks, then make sure to call LoadSubChunksRecursively() before.

Definition at line 2708 of file RIFF.cpp.

## Write()

file_offset_t RIFF::Chunk::Write | ( | void * | pData,
|  | file_offset_t | WordCount,
|  | file_offset_t | WordSize )

inherited

Writes WordCount number of data words with given WordSize from the buffer pointed by pData.

Be sure to provide the correct WordSize, as this will be important and taken into account for eventual endian correction (swapping of bytes due to different native byte order of a system). The position within the chunk will automatically be incremented.

Parameters

  pData | source buffer (containing the data)
  WordCount | number of data words to write
  WordSize | size of each data word to write

Returns
  number of successfully written data words

Exceptions

  RIFF::Exception | if write operation would exceed current chunk size or any IO error occurred

See also
  Resize()
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 541 of file RIFF.cpp.

References GetPos(), and SetPos().

Referenced by WriteInt16(), WriteInt32(), WriteInt8(), WriteUint16(), WriteUint32(), and WriteUint8().

## WriteChunk()

file_offset_t RIFF::List::WriteChunk | ( | file_offset_t | ullWritePos,
|  | file_offset_t | ullCurrentDataOffset,
|  | progress_t * | pProgress = NULL )

protected virtual inherited

Write list chunk persistently e.g.

to disk.

Stores the list chunk persistently to its actual "physical" file. All subchunks (including sub list chunks) will be stored recursively as well.

Parameters

  ullWritePos | - position within the "physical" file where this list chunk should be written to
  ullCurrentDataOffset | - offset of current (old) data within the file
  pProgress | - optional: callback function for progress notification

Returns
  new write position in the "physical" file, that is ullWritePos incremented by this list chunk's new size (including its header size of course)

Reimplemented from RIFF::Chunk.

Definition at line 1768 of file RIFF.cpp.

References RIFF::progress_t::__private.

Referenced by RIFF::File::Save(), and RIFF::File::Save().

## WriteHeader()

void RIFF::List::WriteHeader | ( | file_offset_t | filePos | ) |

protected inherited

Definition at line 1666 of file RIFF.cpp.

## WriteInt16()

file_offset_t RIFF::Chunk::WriteInt16 | ( | int16_t * | pData,
|  | file_offset_t | WordCount = 1 )

inherited

Writes WordCount number of 16 Bit signed integer words from the buffer pointed by pData to the chunk's body, directly to the actual "physical" file.

The position within the chunk will automatically be incremented. Note: you cannot write beyond the boundaries of the chunk, to append data to the chunk call Resize() before.

Parameters

  pData | source buffer (containing the data)
  WordCount | number of 16 Bit signed integers to write

Returns
  number of written integers

Exceptions

  RIFF::Exception | if an IO error occurred

See also
  Resize()
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 717 of file RIFF.cpp.

References Write().

## WriteInt32()

file_offset_t RIFF::Chunk::WriteInt32 | ( | int32_t * | pData,
|  | file_offset_t | WordCount = 1 )

inherited

Writes WordCount number of 32 Bit signed integer words from the buffer pointed by pData to the chunk's body, directly to the actual "physical" file.

The position within the chunk will automatically be incremented. Note: you cannot write beyond the boundaries of the chunk, to append data to the chunk call Resize() before.

Parameters

  pData | source buffer (containing the data)
  WordCount | number of 32 Bit signed integers to write

Returns
  number of written integers

Exceptions

  RIFF::Exception | if an IO error occurred

See also
  Resize()
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 795 of file RIFF.cpp.

References Write().

## WriteInt8()

file_offset_t RIFF::Chunk::WriteInt8 | ( | int8_t * | pData,
|  | file_offset_t | WordCount = 1 )

inherited

Writes WordCount number of 8 Bit signed integer words from the buffer pointed by pData to the chunk's body, directly to the actual "physical" file.

The position within the chunk will automatically be incremented. Note: you cannot write beyond the boundaries of the chunk, to append data to the chunk call Resize() before.

Parameters

  pData | source buffer (containing the data)
  WordCount | number of 8 Bit signed integers to write

Returns
  number of written integers

Exceptions

  RIFF::Exception | if an IO error occurred

See also
  Resize()
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 639 of file RIFF.cpp.

References Write().

## WriteUint16()

file_offset_t RIFF::Chunk::WriteUint16 | ( | uint16_t * | pData,
|  | file_offset_t | WordCount = 1 )

inherited

Writes WordCount number of 16 Bit unsigned integer words from the buffer pointed by pData to the chunk's body, directly to the actual "physical" file.

The position within the chunk will automatically be incremented. Note: you cannot write beyond the boundaries of the chunk, to append data to the chunk call Resize() before.

Parameters

  pData | source buffer (containing the data)
  WordCount | number of 16 Bit unsigned integers to write

Returns
  number of written integers

Exceptions

  RIFF::Exception | if an IO error occurred

See also
  Resize()
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 756 of file RIFF.cpp.

References Write().

## WriteUint32()

file_offset_t RIFF::Chunk::WriteUint32 | ( | uint32_t * | pData,
|  | file_offset_t | WordCount = 1 )

inherited

Writes WordCount number of 32 Bit unsigned integer words from the buffer pointed by pData to the chunk's body, directly to the actual "physical" file.

The position within the chunk will automatically be incremented. Note: you cannot write beyond the boundaries of the chunk, to append data to the chunk call Resize() before.

Parameters

  pData | source buffer (containing the data)
  WordCount | number of 32 Bit unsigned integers to write

Returns
  number of written integers

Exceptions

  RIFF::Exception | if an IO error occurred

See also
  Resize()
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 852 of file RIFF.cpp.

References Write().

Referenced by gig::File::SetSampleChecksum().

## WriteUint8()

file_offset_t RIFF::Chunk::WriteUint8 | ( | uint8_t * | pData,
|  | file_offset_t | WordCount = 1 )

inherited

Writes WordCount number of 8 Bit unsigned integer words from the buffer pointed by pData to the chunk's body, directly to the actual "physical" file.

The position within the chunk will automatically be incremented. Note: you cannot write beyond the boundaries of the chunk, to append data to the chunk call Resize() before.

Parameters

  pData | source buffer (containing the data)
  WordCount | number of 8 Bit unsigned integers to write

Returns
  number of written integers

Exceptions

  RIFF::Exception | if an IO error occurred

See also
  Resize()
  File::IsIOPerThread() for multi-threaded streaming

Definition at line 678 of file RIFF.cpp.

References Write().

## Member Data Documentation

## bEndianNative

bool RIFF::File::bEndianNative

protected

Definition at line 365 of file RIFF.h.

## bIsNewFile

bool RIFF::File::bIsNewFile

protected

Definition at line 366 of file RIFF.h.

## ChunkID

uint32_t RIFF::Chunk::ChunkID

protected inherited

Definition at line 226 of file RIFF.h.

## ChunksIterator

ChunkList::iterator RIFF::List::ChunksIterator

protected inherited

Definition at line 293 of file RIFF.h.

## Filename

String RIFF::File::Filename

protected

Definition at line 364 of file RIFF.h.

## FileOffsetPreference

offset_size_t RIFF::File::FileOffsetPreference

protected

Definition at line 368 of file RIFF.h.

## FileOffsetSize

int RIFF::File::FileOffsetSize

protected

Size of file offsets (in bytes) when this file was opened (or saved the last time).

Definition at line 369 of file RIFF.h.

Referenced by File(), File(), File(), GetFileOffsetSize(), GetRequiredFileSize(), Save(), and Save().

## Layout

layout_t RIFF::File::Layout

protected

An ordinary RIFF file is always set to layout_standard.

Definition at line 367 of file RIFF.h.

Referenced by File(), File(), File(), Save(), and Save().

## ListIterator

ChunkList::iterator RIFF::List::ListIterator

protected inherited

Definition at line 294 of file RIFF.h.

## ListType

uint32_t RIFF::List::ListType

protected inherited

Definition at line 290 of file RIFF.h.

## nDataChunkCount

size_t RIFF::File::nDataChunkCount

protected

Definition at line 370 of file RIFF.h.

## nListChunkCount

size_t RIFF::File::nListChunkCount

protected

Definition at line 371 of file RIFF.h.

## pChunkData

uint8_t* RIFF::Chunk::pChunkData

protected inherited

Definition at line 232 of file RIFF.h.

## pFile

File* RIFF::Chunk::pFile

protected inherited

Definition at line 230 of file RIFF.h.

## pParent

List* RIFF::Chunk::pParent

protected inherited

Definition at line 229 of file RIFF.h.

## pSubChunks

ChunkList* RIFF::List::pSubChunks

protected inherited

Definition at line 291 of file RIFF.h.

## pSubChunksMap

ChunkMap* RIFF::List::pSubChunksMap

protected inherited

Definition at line 292 of file RIFF.h.

## ullChunkDataSize

file_offset_t RIFF::Chunk::ullChunkDataSize

protected inherited

Definition at line 233 of file RIFF.h.

## ullCurrentChunkSize

file_offset_t RIFF::Chunk::ullCurrentChunkSize

protected inherited

Definition at line 227 of file RIFF.h.

## ullNewChunkSize

file_offset_t RIFF::Chunk::ullNewChunkSize

protected inherited

Definition at line 228 of file RIFF.h.

## ullStartPos

file_offset_t RIFF::Chunk::ullStartPos

protected inherited

Definition at line 231 of file RIFF.h.

The documentation for this class was generated from the following files:

- RIFF.h
- RIFF.cpp