# StreamWriter

<a id="streamwriter"></a>

# StreamWriter

```cpp
#include <icy/packetio.h>

class StreamWriter
```

[Defined in src/base/include/icy/packetio.h:108](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L108)

> **Inherits:** [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor)

Packet stream writer class.

This class can be connected to a [`PacketStream`](https://auscaster.com/icey/docs/api-reference/icy-PacketStream.md#packetstream) to write output to any class that derives from `std::ostream`. It's most regularly used for writing output files.

## List of all members

| Name | Kind | Owner |
|------|------|-------|
| [`emitter`](#emitter-2) | `variable` | Declared here |
| [`StreamWriter`](#streamwriter-1) | `function` | Declared here |
| [`~StreamWriter`](#streamwriter-2) | `function` | Declared here |
| [`process`](#process-9) | `function` | Declared here |
| [`stream`](#stream-4) | `function` | Declared here |
| [`onStreamStateChange`](#onstreamstatechange-3) | `function` | Declared here |
| [`stream`](#stream-5) | `function` | Declared here |
| [`_ostream`](#_ostream) | `variable` | Declared here |
| [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor-1) | `function` | Inherited from [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor) |
| [`process`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#process-1) | `function` | Inherited from [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor) |
| [`accepts`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#accepts-1) | `function` | Inherited from [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor) |
| [`operator<<`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#operator-69) | `function` | Inherited from [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor) |
| [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-1) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`~PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-2) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-1) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-2) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-3) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-4) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-5) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`getEmitter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#getemitter) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`retention`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#retention-1) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`onStreamStateChange`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#onstreamstatechange-1) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`_emitter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#_emitter) | `variable` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-3) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#operator-72) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-4) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#operator-73) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |

## Inherited from [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor)

| Kind | Name | Description |
|------|------|-------------|
| `function` | [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor-1) `inline` |  |
| `function` | [`process`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#process-1) `virtual` | This method performs processing on the given packet and emits the result. |
| `function` | [`accepts`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#accepts-1) `virtual` `inline` | This method ensures compatibility with the given packet type. Return false to reject the packet. |
| `function` | [`operator<<`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#operator-69) `virtual` `inline` | [Stream](https://auscaster.com/icey/docs/api-reference/icy-Stream.md#stream) operator alias for [process()](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#process-1) |

## Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter)

| Kind | Name | Description |
|------|------|-------------|
| `function` | [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-1)  | Construct the adapter, binding it to the given packet signal. |
| `function` | [`~PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-2) `virtual` `inline` |  |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-1) `virtual` | Emit a mutable raw buffer as a packet. |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-2) `virtual` | Emit a read-only raw buffer as a packet (data is copied internally). |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-3) `virtual` | Emit a string as a packet (data is copied internally). |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-4) `virtual` | Emit a flag-only packet carrying no payload data. |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-5) `virtual` | Emit an existing packet directly onto the outgoing signal. |
| `function` | [`getEmitter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#getemitter)  | Returns a reference to the outgoing packet signal. |
| `function` | [`retention`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#retention-1) `virtual` `const` | Returns how this adapter treats incoming packet lifetime. Most adapters are synchronous and therefore only borrow the packet for the current call chain. Queue-style adapters override this to advertise that they clone before deferred use. Callers may treat the first adapter reporting Cloned or Retained as the explicit ownership boundary in the stream graph. |
| `function` | [`onStreamStateChange`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#onstreamstatechange-1) `virtual` `inline` | Called by the [PacketStream](https://auscaster.com/icey/docs/api-reference/icy-PacketStream.md#packetstream) to notify when the internal [Stream](https://auscaster.com/icey/docs/api-reference/icy-Stream.md#stream) state changes. On receiving the Stopped state, it is the responsibility of the adapter to have ceased all outgoing packet transmission, especially in multi-thread scenarios. |
| `variable` | [`_emitter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#_emitter)  |  |
| `function` | [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-3)  | NonCopyable and NonMovable. |
| `function` | [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#operator-72)  | Deleted assignment operator. |
| `function` | [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-4)  | Deleted constructor. |
| `function` | [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#operator-73)  | Deleted assignment operator. |

## Public Attributes

| Return | Name | Description |
|--------|------|-------------|
| [`PacketSignal`](https://auscaster.com/icey/docs/api-reference/base.md#packetsignal) | [`emitter`](#emitter-2)  |  |

---

<a id="emitter-2"></a>

### emitter

```cpp
PacketSignal emitter
```

Type: [`PacketSignal`](https://auscaster.com/icey/docs/api-reference/base.md#packetsignal)

[Defined in src/base/include/icy/packetio.h:188](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L188)

## Public Methods

| Return | Name | Description |
|--------|------|-------------|
|  | [`StreamWriter`](#streamwriter-1) `inline` |  |
|  | [`~StreamWriter`](#streamwriter-2) `virtual` `inline` | Closes any open `std::ofstream` and deletes the owned stream. |
| `void` | [`process`](#process-9) `virtual` `inline` `override` | Serializes the packet via `write()`, flushes it to the output stream, then forwards the packet to the next processor. |
| `StreamT &` | [`stream`](#stream-4) `inline` | Returns the internal output stream cast to `StreamT`. |
| `void` | [`onStreamStateChange`](#onstreamstatechange-3) `virtual` `inline` `override` | Closes the output file on `Closed` or [`Error`](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error) stream state transitions. |
| `std::ostream &` | [`stream`](#stream-5) `inline` |  |

---

<a id="streamwriter-1"></a>

### StreamWriter

`inline`

```cpp
inline StreamWriter(std::ostream * stream)
```

[Defined in src/base/include/icy/packetio.h:112](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L112)

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `stream` | `std::ostream *` | Output stream to write to; takes ownership. |

---

<a id="streamwriter-2"></a>

### ~StreamWriter

`virtual` `inline`

```cpp
virtual inline ~StreamWriter()
```

[Defined in src/base/include/icy/packetio.h:119](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L119)

Closes any open `std::ofstream` and deletes the owned stream.

---

<a id="process-9"></a>

### process

`virtual` `inline` `override`

```cpp
virtual inline void process(IPacket & packet) override
```

[Defined in src/base/include/icy/packetio.h:132](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L132)

Serializes the packet via `write()`, flushes it to the output stream, then forwards the packet to the next processor.

#### Reimplements

- [`PacketProcessor::process`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#process-1)

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `packet` | [`IPacket`](https://auscaster.com/icey/docs/api-reference/icy-IPacket.md#ipacket) & | Incoming packet to process. |

---

<a id="stream-4"></a>

### stream

`inline`

```cpp
template<class StreamT> inline StreamT & stream()
```

[Defined in src/base/include/icy/packetio.h:148](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L148)

Returns the internal output stream cast to `StreamT`. 
#### Returns
Reference to the cast stream.

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::runtime_error` | if the cast fails. |

---

<a id="onstreamstatechange-3"></a>

### onStreamStateChange

`virtual` `inline` `override`

```cpp
virtual inline void onStreamStateChange(const PacketStreamState & state) override
```

[Defined in src/base/include/icy/packetio.h:159](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L159)

Closes the output file on `Closed` or [`Error`](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error) stream state transitions.

#### Reimplements

- [`PacketStreamAdapter::onStreamStateChange`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#onstreamstatechange-1)

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `state` | const [`PacketStreamState`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamState.md#packetstreamstate) & | New stream state. |

---

<a id="stream-5"></a>

### stream

`inline`

```cpp
inline std::ostream & stream()
```

[Defined in src/base/include/icy/packetio.h:181](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L181)

#### Returns
Reference to the underlying output stream.

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::runtime_error` | if the stream pointer is null. |

## Protected Attributes

| Return | Name | Description |
|--------|------|-------------|
| `std::ostream *` | [`_ostream`](#_ostream)  |  |

---

<a id="_ostream"></a>

### _ostream

```cpp
std::ostream * _ostream
```

[Defined in src/base/include/icy/packetio.h:191](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L191)