# PWAVFile Class Reference

A class representing a WAV audio file. More...

`#include <pwavfile.h>`

Inheritance diagram for PWAVFile:

List of all members.

## Construction

enum | WaveType { fmt_PCM = 1, fmt_MSADPCM = 2, fmt_ALaw = 6, fmt_uLaw = 7, fmt_VOXADPCM = 0x10, fmt_IMAADPCM = 0x11, fmt_GSM = 0x31, fmt_G728 = 0x41, fmt_G723 = 0x42, fmt_MSG7231 = 0x42, fmt_G726 = 0x64, fmt_G722 = 0x65, fmt_G729 = 0x83, fmt_VivoG7231 = 0x111, PCM_WavFile = fmt_PCM, G7231_WavFile = fmt_VivoG7231, fmt_NotKnown = 0x10000 }
| When a file is opened for writing, we can specify if this is a PCM wav file or a G.723.1 wav file. More...
| PWAVFile (unsigned format=fmt_PCM)
| Create a WAV file object but do not open it.
| PWAVFile (OpenMode mode, int opts=ModeDefault, unsigned format=fmt_PCM)
| Create a unique temporary file name, and open the file in the specified mode and using the specified options.
| PWAVFile (const PFilePath &name, OpenMode mode=ReadWrite, int opts=ModeDefault, unsigned format=fmt_PCM)
| Create a WAV file object with the specified name and open it in the specified mode and with the specified options.
| PWAVFile (const PString &format, const PFilePath &name, OpenMode mode=PFile::ReadWrite, int opts=PFile::ModeDefault)
| ~PWAVFile ()
| Close the file before destruction.

## Public Member Functions

PBoolean | RawRead (void *buf, PINDEX len)
PBoolean | RawWrite (const void *buf, PINDEX len)
PBoolean | FileRead (void *buf, PINDEX len)
PBoolean | FileWrite (const void *buf, PINDEX len)
off_t | RawGetPosition () const
PBoolean | RawSetPosition (off_t pos, FilePositionOrigin origin)
off_t | RawGetDataLength ()
void | SetLastReadCount (PINDEX v)
void | SetLastWriteCount (PINDEX v)
Overrides from class PFile
virtual PBoolean | Read (void *buf, PINDEX len)
| Call PFile::Read() to read in audio data and perform necessary processing such as byte-order swaping.
virtual PBoolean | Write (const void *buf, PINDEX len)
| Call PFile::Write() to write out audio data and perform necessary processing such as byte-order swaping.
virtual PBoolean | Open (OpenMode mode=ReadWrite, int opts=ModeDefault)
| Open the current file in the specified mode and with the specified options.
virtual PBoolean | Open (const PFilePath &name, OpenMode mode=ReadWrite, int opts=ModeDefault)
| Open the specified WAV file name in the specified mode and with the specified options.
virtual PBoolean | Close ()
| Close the file channel.
virtual PBoolean | SetPosition (off_t pos, FilePositionOrigin origin=Start)
| Set the current active position in the file for the next read or write operation.
virtual off_t | GetPosition () const
| Get the current active position in the file for the next read or write operation.
Member variable access
virtual PBoolean | SetFormat (unsigned fmt)
| Find out the format of the WAV file.
virtual PBoolean | SetFormat (const PString &format)
virtual unsigned | GetFormat () const
| Find out the format of the WAV file.
virtual PString | GetFormatAsString () const
virtual unsigned | GetChannels () const
| Find out the number of channels the WAV file has.
virtual void | SetChannels (unsigned v)
virtual unsigned | GetSampleRate () const
| Find out the sample rate of the WAV file in Hz.
virtual void | SetSampleRate (unsigned v)
virtual unsigned | GetSampleSize () const
| Find out how may bits there are per sample, eg 8 or 16.
virtual void | SetSampleSize (unsigned v)
virtual unsigned | GetBytesPerSecond () const
| Find out how may bytes there are per second.
virtual void | SetBytesPerSecond (unsigned v)
off_t | GetHeaderLength () const
| Find out the size of WAV header presented in the file.
virtual off_t | GetDataLength ()
| Find out how many bytes of audio data there are.
PBoolean | IsValid () const
| Determine if the WAV file is a valid wave file.
PString | GetFormatString () const
| Return a string that describes the WAV format.
void | SetAutoconvert ()
| Enable autoconversion between PCM-16 and the native format.

## Static Public Member Functions

static PWAVFile * | format (const PString &format)
static PWAVFile * | format (const PString &format, PFile::OpenMode mode, int opts=PFile::ModeDefault)

## Protected Member Functions

void | Construct ()
bool | SelectFormat (unsigned fmt)
bool | SelectFormat (const PString &format)
PBoolean | ProcessHeader ()
PBoolean | GenerateHeader ()
PBoolean | UpdateHeader ()

## Protected Attributes

PBYTEArray | wavHeaderData
PWAV::FMTChunk | wavFmtChunk
PBYTEArray | extendedHeader
bool | isValidWAV
unsigned int | origFmt
PWAVFileFormat * | formatHandler
PBoolean | autoConvert
PWAVFileConverter * | autoConverter
off_t | lenHeader
off_t | lenData
bool | header_needs_updating

## Detailed Description

A class representing a WAV audio file.

## Member Enumeration Documentation

enum PWAVFile::WaveType

When a file is opened for writing, we can specify if this is a PCM wav file or a G.723.1 wav file.

Enumerator:

  fmt_PCM | PCM, 8kHz, 16 bit, mono.
  fmt_MSADPCM | MS-ADPCM, 8kHz, mono.
  fmt_ALaw | A-Law 8kHz.
  fmt_uLaw | u-Law 8kHz
  fmt_VOXADPCM | OKI ADPCM.
  fmt_IMAADPCM | IMA-ADPCM, 8kHz mono.
  fmt_GSM | GSM.
  fmt_G728 | RFC2361.
  fmt_G723 | RFC2361.
  fmt_MSG7231 | Microsoft G.723.1.
  fmt_G726 | RFC2361.
  fmt_G722 | RFC2361.
  fmt_G729 | RFC2361.
  fmt_VivoG7231 | VivoActive G.723.1.
  PCM_WavFile |
  G7231_WavFile |
  fmt_NotKnown |

## Constructor & Destructor Documentation

PWAVFile::PWAVFile | ( | unsigned | format = `fmt_PCM` | ) |

Create a WAV file object but do not open it.

It does not initially have a valid file name. However, an attempt to open the file using the `PFile::Open()` function will generate a unique temporary file.

If a WAV file is being created, the type parameter can be used to create a PCM Wave file or a G.723.1 Wave file by using `WaveType` enum.

Parameters:

  format | Type of WAV File to create

PWAVFile::PWAVFile | ( | OpenMode | mode,
|  | int | opts = `ModeDefault`,
|  | unsigned | format = `fmt_PCM` |
| ) |  |  |

Create a unique temporary file name, and open the file in the specified mode and using the specified options.

Note that opening a new, unique, temporary file name in ReadOnly mode will always fail. This would only be usefull in a mode and options that will create the file.

If a WAV file is being created, the type parameter can be used to create a PCM Wave file or a G.723.1 Wave file by using `WaveType` enum.

The `PChannel::IsOpen()` function may be used after object construction to determine if the file was successfully opened.

Parameters:

  mode | Mode in which to open the file.
  opts | `OpenOptions` enum for open operation.
  format | Type of WAV File to create

PWAVFile::PWAVFile | ( | const PFilePath & | name,
|  | OpenMode | mode = `ReadWrite`,
|  | int | opts = `ModeDefault`,
|  | unsigned | format = `fmt_PCM` |
| ) |  |  |

Create a WAV file object with the specified name and open it in the specified mode and with the specified options.

If a WAV file is being created, the type parameter can be used to create a PCM Wave file or a G.723.1 Wave file by using `WaveType` enum.

The `PChannel::IsOpen()` function may be used after object construction to determine if the file was successfully opened.

Parameters:

  name | Name of file to open.
  mode | Mode in which to open the file.
  opts | `OpenOptions` enum for open operation.
  format | Type of WAV File to create

PWAVFile::PWAVFile | ( | const PString & | format,
|  | const PFilePath & | name,
|  | OpenMode | mode = `PFile::ReadWrite`,
|  | int | opts = `PFile::ModeDefault` |
| ) |  |  |

Parameters:

  format | Type of WAV File to create
  name | Name of file to open.
  mode | Mode in which to open the file.
  opts | `OpenOptions` enum for open operation.

PWAVFile::~PWAVFile | ( |  | ) |

Close the file before destruction.

## Member Function Documentation

virtual PBoolean PWAVFile::Close | ( |  | ) | `[virtual]`

Close the file channel.

If a WAV file has been written to, this will update the header to contain the correct size information.

Returns:
  true if close was OK.

Reimplemented from PFile.

void PWAVFile::Construct | ( |  | ) | `[protected]`

Reimplemented from PChannel.

PBoolean PWAVFile::FileRead | ( | void * | buf,
|  | PINDEX | len |
| ) |  |  |

PBoolean PWAVFile::FileWrite | ( | const void * | buf,
|  | PINDEX | len |
| ) |  |  |

static PWAVFile* PWAVFile::format | ( | const PString & | format,
|  | PFile::OpenMode | mode,
|  | int | opts = `PFile::ModeDefault` |
| ) |  |  | `[static]`

static PWAVFile* PWAVFile::format | ( | const PString & | format | ) | `[static]`

PBoolean PWAVFile::GenerateHeader | ( |  | ) | `[protected]`

virtual unsigned PWAVFile::GetBytesPerSecond | ( |  | ) | const`[virtual]`

Find out how may bytes there are per second.

virtual unsigned PWAVFile::GetChannels | ( |  | ) | const`[virtual]`

Find out the number of channels the WAV file has.

Typically this is 1 for mono and 2 for stereo.

virtual off_t PWAVFile::GetDataLength | ( |  | ) | `[virtual]`

Find out how many bytes of audio data there are.

virtual unsigned PWAVFile::GetFormat | ( |  | ) | const`[virtual]`

Find out the format of the WAV file.

Eg 0x01 for PCM, 0x42 or 0x111 for G.723.1.

virtual PString PWAVFile::GetFormatAsString | ( |  | ) | const`[virtual]`

PString PWAVFile::GetFormatString | ( |  | ) | const`[inline]`

Return a string that describes the WAV format.

off_t PWAVFile::GetHeaderLength | ( |  | ) | const

Find out the size of WAV header presented in the file.

virtual off_t PWAVFile::GetPosition | ( |  | ) | const`[virtual]`

Get the current active position in the file for the next read or write operation.

The WAV header is excluded from calculation the position.

Returns:
  current file position relative to the end of the WAV header.

Reimplemented from PFile.

virtual unsigned PWAVFile::GetSampleRate | ( |  | ) | const`[virtual]`

Find out the sample rate of the WAV file in Hz.

virtual unsigned PWAVFile::GetSampleSize | ( |  | ) | const`[virtual]`

Find out how may bits there are per sample, eg 8 or 16.

PBoolean PWAVFile::IsValid | ( |  | ) | const`[inline]`

Determine if the WAV file is a valid wave file.

Returns:
  true indicates that the WAV file is valid false indicates that the WAV file is invalid

virtual PBoolean PWAVFile::Open | ( | const PFilePath & | name,
|  | OpenMode | mode = `ReadWrite`,
|  | int | opts = `ModeDefault` |
| ) |  |  | `[virtual]`

Open the specified WAV file name in the specified mode and with the specified options.

If the file object already has an open file then it is closed. This reads (and validates) the header for existing files. For new files, it creates a new file (and header) using the type of WAV file specified in the class constructor.

Note: if `mode` is StandardInput, StandardOutput or StandardError, then the `name` parameter is ignored.

Returns:
  true if the file was successfully opened.

Parameters:

  name | Name of file to open.
  mode | Mode in which to open the file.
  opts | `OpenOptions` enum for open operation.

virtual PBoolean PWAVFile::Open | ( | OpenMode | mode = `ReadWrite`,
|  | int | opts = `ModeDefault` |
| ) |  |  | `[virtual]`

Open the current file in the specified mode and with the specified options.

If the file object already has an open file then it is closed.

If there has not been a filename attached to the file object (via `SetFilePath()`, the `name` parameter in the constructor or a previous open) then a new unique temporary filename is generated.

Returns:
  true if the file was successfully opened.

Parameters:

  mode | Mode in which to open the file.
  opts | Options for open operation.

PBoolean PWAVFile::ProcessHeader | ( |  | ) | `[protected]`

off_t PWAVFile::RawGetDataLength | ( |  | ) |

off_t PWAVFile::RawGetPosition | ( |  | ) | const

PBoolean PWAVFile::RawRead | ( | void * | buf,
|  | PINDEX | len |
| ) |  |  |

PBoolean PWAVFile::RawSetPosition | ( | off_t | pos,
|  | FilePositionOrigin | origin |
| ) |  |  |

PBoolean PWAVFile::RawWrite | ( | const void * | buf,
|  | PINDEX | len |
| ) |  |  |

virtual PBoolean PWAVFile::Read | ( | void * | buf,
|  | PINDEX | len |
| ) |  |  | `[virtual]`

Call PFile::Read() to read in audio data and perform necessary processing such as byte-order swaping.

Returns:
  true indicates that at least one character was read from the channel. false means no bytes were read due to timeout or some other I/O error.

Parameters:

  buf | Pointer to a block of memory to receive the read bytes.
  len | Maximum number of bytes to read into the buffer.

Reimplemented from PFile.

bool PWAVFile::SelectFormat | ( | const PString & | format | ) | `[protected]`

bool PWAVFile::SelectFormat | ( | unsigned | fmt | ) | `[protected]`

void PWAVFile::SetAutoconvert | ( |  | ) |

Enable autoconversion between PCM-16 and the native format.

virtual void PWAVFile::SetBytesPerSecond | ( | unsigned | v | ) | `[virtual]`

virtual void PWAVFile::SetChannels | ( | unsigned | v | ) | `[virtual]`

virtual PBoolean PWAVFile::SetFormat | ( | const PString & | format | ) | `[virtual]`

virtual PBoolean PWAVFile::SetFormat | ( | unsigned | fmt | ) | `[virtual]`

Find out the format of the WAV file.

Eg 0x01 for PCM, 0x42 or 0x111 for G.723.1.

void PWAVFile::SetLastReadCount | ( | PINDEX | v | ) | `[inline]`

void PWAVFile::SetLastWriteCount | ( | PINDEX | v | ) | `[inline]`

virtual PBoolean PWAVFile::SetPosition | ( | off_t | pos,
|  | FilePositionOrigin | origin = `Start` |
| ) |  |  | `[virtual]`

Set the current active position in the file for the next read or write operation.

The `pos` variable is a signed number which is added to the specified origin. For `origin` == PFile::Start only positive values for `pos` are meaningful. For `origin` == PFile::End only negative values for `pos` are meaningful.

Note that for a WAV file, the origin of the file is right after the header. That is, the WAV header is not included when perform SetPosition().

Returns:
  true if the new file position was set.

Parameters:

  pos | New position to set.
  origin | Origin for position change.

virtual void PWAVFile::SetSampleRate | ( | unsigned | v | ) | `[virtual]`

virtual void PWAVFile::SetSampleSize | ( | unsigned | v | ) | `[virtual]`

PBoolean PWAVFile::UpdateHeader | ( |  | ) | `[protected]`

virtual PBoolean PWAVFile::Write | ( | const void * | buf,
|  | PINDEX | len |
| ) |  |  | `[virtual]`

Call PFile::Write() to write out audio data and perform necessary processing such as byte-order swaping.

Returns:
  true indicates that at least one character was written to the channel. false means no bytes were written due to timeout or some other I/O error.

Parameters:

  buf | Pointer to a block of memory to receive the write bytes.
  len | Maximum number of bytes to write to the channel.

Reimplemented from PFile.

## Member Data Documentation

PBoolean PWAVFile::autoConvert `[protected]`

PWAVFileConverter* PWAVFile::autoConverter `[protected]`

PBYTEArray PWAVFile::extendedHeader `[protected]`

PWAVFileFormat* PWAVFile::formatHandler `[protected]`

bool PWAVFile::header_needs_updating `[protected]`

bool PWAVFile::isValidWAV `[protected]`

off_t PWAVFile::lenData `[protected]`

off_t PWAVFile::lenHeader `[protected]`

unsigned int PWAVFile::origFmt `[protected]`

PWAV::FMTChunk PWAVFile::wavFmtChunk `[protected]`

PBYTEArray PWAVFile::wavHeaderData `[protected]`

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

- pwavfile.h