MPD: InputStream Class Reference

MPD 0.20.15

Public Types | Public Member Functions | Static Public Member Functions | Data Fields | Protected Attributes | Static Protected Attributes
InputStream Class Referenceabstract

`#include <InputStream.hxx>`

Inheritance diagram for InputStream:
[legend]
Collaboration diagram for InputStream:
[legend]

## Public Types
typedef ::offset_type | offset_type

## Public Member Functions
| InputStream (const char *_uri, Mutex &_mutex, Cond &_cond)
virtual | ~InputStream ()
| Close the input stream and free resources. More...
const char * | GetURI () const
| The absolute URI which was used to open this stream. More...
void | Lock ()
void | Unlock ()
virtual void | Check ()
| Check for errors that may have occurred in the I/O thread. More...
virtual void | Update ()
| Update the public attributes. More...
void | SetReady ()
bool | IsReady () const
| Return whether the stream is ready for reading and whether the other attributes in this struct are valid. More...
void | WaitReady ()
void | LockWaitReady ()
| Wrapper for WaitReady() which locks and unlocks the mutex; the caller must not be holding it already. More...
gcc_pure bool | HasMimeType () const noexcept
gcc_pure const char * | GetMimeType () const noexcept
void | ClearMimeType () noexcept
gcc_nonnull_all void | SetMimeType (const char *_mime)
void | SetMimeType (std::string &&_mime)
gcc_pure bool | KnownSize () const noexcept
gcc_pure offset_type | GetSize () const noexcept
void | AddOffset (offset_type delta) noexcept
gcc_pure offset_type | GetOffset () const noexcept
gcc_pure offset_type | GetRest () const noexcept
gcc_pure bool | IsSeekable () const noexcept
gcc_pure bool | CheapSeeking () const noexcept
| Determines whether seeking is cheap. More...
virtual void | Seek (offset_type offset)
| Seeks to the specified position in the stream. More...
void | LockSeek (offset_type offset)
| Wrapper for Seek() which locks and unlocks the mutex; the caller must not be holding it already. More...
void | Rewind ()
| Rewind to the beginning of the stream. More...
void | LockRewind ()
void | Skip (offset_type _offset)
| Skip input bytes. More...
void | LockSkip (offset_type _offset)
virtual gcc_pure bool | IsEOF () noexcept=0
| Returns true if the stream has reached end-of-file. More...
gcc_pure bool | LockIsEOF () noexcept
| Wrapper for IsEOF() which locks and unlocks the mutex; the caller must not be holding it already. More...
virtual gcc_malloc Tag * | ReadTag ()
| Reads the tag from the stream. More...
gcc_malloc Tag * | LockReadTag ()
| Wrapper for ReadTag() which locks and unlocks the mutex; the caller must not be holding it already. More...
virtual gcc_pure bool | IsAvailable () noexcept
| Returns true if the next read operation will not block: either data is available, or end-of-stream has been reached, or an error has occurred. More...
virtual gcc_nonnull_all size_t | Read (void *ptr, size_t size)=0
| Reads data from the stream into the caller-supplied buffer. More...
gcc_nonnull_all size_t | LockRead (void *ptr, size_t size)
| Wrapper for Read() which locks and unlocks the mutex; the caller must not be holding it already. More...
gcc_nonnull_all void | ReadFull (void *ptr, size_t size)
| Reads the whole data from the stream into the caller-supplied buffer. More...
gcc_nonnull_all void | LockReadFull (void *ptr, size_t size)
| Wrapper for ReadFull() which locks and unlocks the mutex; the caller must not be holding it already. More...

## Static Public Member Functions
static gcc_nonnull_all InputStreamPtr | Open (const char *uri, Mutex &mutex, Cond &cond)
| Opens a new input stream. More...
static gcc_nonnull_all InputStreamPtr | OpenReady (const char *uri, Mutex &mutex, Cond &cond)
| Just like Open(), but waits for the stream to become ready. More...

## Data Fields
Mutex & | mutex
| A mutex that protects the mutable attributes of this object and its implementation. More...
Cond & | cond
| A cond that gets signalled when the state of this object changes from the I/O thread. More...

## Protected Attributes
bool | ready
| indicates whether the stream is ready for reading and whether the other attributes in this struct are valid More...
bool | seekable
| if true, then the stream is fully seekable More...
offset_type | size
| the size of the resource, or UNKNOWN_SIZE if unknown More...
offset_type | offset
| the current offset within the stream More...

## Static Protected Attributes
static constexpr offset_type | UNKNOWN_SIZE = -1

## Detailed Description

Definition at line 36 of file InputStream.hxx.

## Member Typedef Documentation

## ◆ offset_type

typedef ::offset_type InputStream::offset_type

Definition at line 38 of file InputStream.hxx.

## Constructor & Destructor Documentation

## ◆ InputStream()

InputStream::InputStream | ( | const char * | _uri,
|  | Mutex & | _mutex,
|  | Cond & | _cond
| ) |  |
| inline

Definition at line 98 of file InputStream.hxx.

## ◆ ~InputStream()

virtual InputStream::~InputStream | ( |  | ) |
| virtual

Close the input stream and free resources.

The caller must not lock the mutex.

## Member Function Documentation

## ◆ AddOffset()

void InputStream::AddOffset | ( | offset_type | delta | ) |
| inlinenoexcept

Definition at line 232 of file InputStream.hxx.

## ◆ CheapSeeking()

gcc_pure bool InputStream::CheapSeeking | ( |  | ) | const
| noexcept

Determines whether seeking is cheap.

This is true for local files.

## ◆ Check()

virtual void InputStream::Check | ( |  | ) |
| virtual

Check for errors that may have occurred in the I/O thread.

Throws std::runtime_error on error.

Reimplemented in ThreadInputStream, AsyncInputStream, and ProxyInputStream.

## ◆ ClearMimeType()

void InputStream::ClearMimeType | ( |  | ) |
| inlinenoexcept

Definition at line 200 of file InputStream.hxx.

## ◆ GetMimeType()

gcc_pure const char* InputStream::GetMimeType | ( |  | ) | const
| inlinenoexcept

Definition at line 194 of file InputStream.hxx.

## ◆ GetOffset()

gcc_pure offset_type InputStream::GetOffset | ( |  | ) | const
| inlinenoexcept

Definition at line 239 of file InputStream.hxx.

## ◆ GetRest()

gcc_pure offset_type InputStream::GetRest | ( |  | ) | const
| inlinenoexcept

Definition at line 246 of file InputStream.hxx.

## ◆ GetSize()

gcc_pure offset_type InputStream::GetSize | ( |  | ) | const
| inlinenoexcept

Definition at line 225 of file InputStream.hxx.

## ◆ GetURI()

const char* InputStream::GetURI | ( |  | ) | const
| inline

The absolute URI which was used to open this stream.

No lock necessary for this method.

Definition at line 142 of file InputStream.hxx.

## ◆ HasMimeType()

gcc_pure bool InputStream::HasMimeType | ( |  | ) | const
| inlinenoexcept

Definition at line 187 of file InputStream.hxx.

## ◆ IsAvailable()

virtual gcc_pure bool InputStream::IsAvailable | ( |  | ) |
| virtualnoexcept

Returns true if the next read operation will not block: either data is available, or end-of-stream has been reached, or an error has occurred.

The caller must lock the mutex.

Reimplemented in AsyncInputStream, ThreadInputStream, and ProxyInputStream.

## ◆ IsEOF()

virtual gcc_pure bool InputStream::IsEOF | ( |  | ) |
| pure virtualnoexcept

Returns true if the stream has reached end-of-file.

The caller must lock the mutex.

Implemented in ThreadInputStream, AsyncInputStream, and ProxyInputStream.

## ◆ IsReady()

bool InputStream::IsReady | ( |  | ) | const
| inline

Return whether the stream is ready for reading and whether the other attributes in this struct are valid.

The caller must lock the mutex.

Definition at line 174 of file InputStream.hxx.

## ◆ IsSeekable()

gcc_pure bool InputStream::IsSeekable | ( |  | ) | const
| inlinenoexcept

Definition at line 254 of file InputStream.hxx.

## ◆ KnownSize()

gcc_pure bool InputStream::KnownSize | ( |  | ) | const
| inlinenoexcept

Definition at line 218 of file InputStream.hxx.

## ◆ Lock()

void InputStream::Lock | ( |  | ) |
| inline

Definition at line 146 of file InputStream.hxx.

## ◆ LockIsEOF()

gcc_pure bool InputStream::LockIsEOF | ( |  | ) |
| noexcept

Wrapper for IsEOF() which locks and unlocks the mutex; the caller must not be holding it already.

## ◆ LockRead()

gcc_nonnull_all size_t InputStream::LockRead | ( | void * | ptr,
|  | size_t | size
| ) |  |

Wrapper for Read() which locks and unlocks the mutex; the caller must not be holding it already.

Throws std::runtime_error on error.

## ◆ LockReadFull()

gcc_nonnull_all void InputStream::LockReadFull | ( | void * | ptr,
|  | size_t | size
| ) |  |

Wrapper for ReadFull() which locks and unlocks the mutex; the caller must not be holding it already.

Throws std::runtime_error on error.

## ◆ LockReadTag()

gcc_malloc Tag* InputStream::LockReadTag | ( |  | ) |

Wrapper for ReadTag() which locks and unlocks the mutex; the caller must not be holding it already.

## ◆ LockRewind()

void InputStream::LockRewind | ( |  | ) |
| inline

Definition at line 292 of file InputStream.hxx.

## ◆ LockSeek()

void InputStream::LockSeek | ( | offset_type | offset | ) |

Wrapper for Seek() which locks and unlocks the mutex; the caller must not be holding it already.

## ◆ LockSkip()

void InputStream::LockSkip | ( | offset_type | _offset | ) |

## ◆ LockWaitReady()

void InputStream::LockWaitReady | ( |  | ) |

Wrapper for WaitReady() which locks and unlocks the mutex; the caller must not be holding it already.

## ◆ Open()

static gcc_nonnull_all InputStreamPtr InputStream::Open | ( | const char * | uri,
|  | Mutex & | mutex,
|  | Cond & | cond
| ) |  |
| static

Opens a new input stream.

You may not access it until the "ready" flag is set.

Throws std::runtime_error on error.

Parameters

  mutex | a mutex that is used to protect this object; must be locked before calling any of the public methods
  cond | a cond that gets signalled when the state of this object changes; may be nullptr if the caller doesn't want to get notifications

Returns
  an InputStream object on success

## ◆ OpenReady()

static gcc_nonnull_all InputStreamPtr InputStream::OpenReady | ( | const char * | uri,
|  | Mutex & | mutex,
|  | Cond & | cond
| ) |  |
| static

Just like Open(), but waits for the stream to become ready.

It is a wrapper for Open(), WaitReady() and Check().

## ◆ Read()

virtual gcc_nonnull_all size_t InputStream::Read | ( | void * | ptr,
|  | size_t | size
| ) |  |
| pure virtual

Reads data from the stream into the caller-supplied buffer.

Returns 0 on error or eof (check with IsEOF()).

The caller must lock the mutex.

Throws std::runtime_error on error.

Parameters

  ptr | the buffer to read into
  size | the maximum number of bytes to read

Returns
  the number of bytes read

Implemented in AsyncInputStream, ThreadInputStream, IcyInputStream, and ProxyInputStream.

## ◆ ReadFull()

gcc_nonnull_all void InputStream::ReadFull | ( | void * | ptr,
|  | size_t | size
| ) |  |

Reads the whole data from the stream into the caller-supplied buffer.

The caller must lock the mutex.

Throws std::runtime_error on error.

Parameters

  ptr | the buffer to read into
  size | the number of bytes to read

Returns
  true if the whole data was read, false otherwise.

## ◆ ReadTag()

virtual gcc_malloc Tag* InputStream::ReadTag | ( |  | ) |
| virtual

Reads the tag from the stream.

The caller must lock the mutex.

Returns
  a tag object which must be freed by the caller, or nullptr if the tag has not changed since the last call

Reimplemented in AsyncInputStream, IcyInputStream, and ProxyInputStream.

## ◆ Rewind()

void InputStream::Rewind | ( |  | ) |
| inline

Rewind to the beginning of the stream.

This is a wrapper for Seek(0, error).

Definition at line 288 of file InputStream.hxx.

## ◆ Seek()

virtual void InputStream::Seek | ( | offset_type | offset | ) |
| virtual

Seeks to the specified position in the stream.

This will most likely fail if the "seekable" flag is false.

The caller must lock the mutex.

Throws std::runtime_error on error.

Parameters

  offset | the relative offset

Reimplemented in AsyncInputStream, and ProxyInputStream.

## ◆ SetMimeType() [1/2]

gcc_nonnull_all void InputStream::SetMimeType | ( | const char * | _mime | ) |
| inline

Definition at line 205 of file InputStream.hxx.

## ◆ SetMimeType() [2/2]

void InputStream::SetMimeType | ( | std::string && | _mime | ) |
| inline

Definition at line 211 of file InputStream.hxx.

## ◆ SetReady()

void InputStream::SetReady | ( |  | ) |

## ◆ Skip()

void InputStream::Skip | ( | offset_type | _offset | ) |
| inline

Skip input bytes.

Definition at line 299 of file InputStream.hxx.

## ◆ Unlock()

void InputStream::Unlock | ( |  | ) |
| inline

Definition at line 150 of file InputStream.hxx.

## ◆ Update()

virtual void InputStream::Update | ( |  | ) |
| virtual

Update the public attributes.

Call before accessing attributes such as "ready" or "offset".

Reimplemented in IcyInputStream, and ProxyInputStream.

## ◆ WaitReady()

void InputStream::WaitReady | ( |  | ) |

## Field Documentation

## ◆ cond

Cond& InputStream::cond

A cond that gets signalled when the state of this object changes from the I/O thread.

The client of this object may wait on it. Optional, may be nullptr.

This object is allocated by the client, and the client is responsible for freeing it.

Definition at line 65 of file InputStream.hxx.

## ◆ mutex

Mutex& InputStream::mutex

A mutex that protects the mutable attributes of this object and its implementation.

It must be locked before calling any of the public methods.

This object is allocated by the client, and the client is responsible for freeing it.

Definition at line 55 of file InputStream.hxx.

## ◆ offset

offset_type InputStream::offset
| protected

the current offset within the stream

Definition at line 89 of file InputStream.hxx.

## ◆ ready

bool InputStream::ready
| protected

indicates whether the stream is ready for reading and whether the other attributes in this struct are valid

Definition at line 72 of file InputStream.hxx.

## ◆ seekable

bool InputStream::seekable
| protected

if true, then the stream is fully seekable

Definition at line 77 of file InputStream.hxx.

## ◆ size

offset_type InputStream::size
| protected

the size of the resource, or UNKNOWN_SIZE if unknown

Definition at line 84 of file InputStream.hxx.

## ◆ UNKNOWN_SIZE

constexpr offset_type InputStream::UNKNOWN_SIZE = -1
| staticprotected

Definition at line 79 of file InputStream.hxx.

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

- input/InputStream.hxx