= cowboy_stream:data(3)

== Name

cowboy_stream:data - Handle data for a stream

== Description

[source,erlang]
----
data(StreamID, IsFin, Data, State) -> {Commands, State}

StreamID :: cowboy_stream:stream_id()
IsFin    :: cowboy_stream:fin()
Data     :: binary()
Commands :: cowboy_stream:commands()
State    - opaque
----

Handle data for a stream.

This function should be called by all stream handlers. It will
propagate data to the next configured stream handler. Handlers
do not have to propagate data that has been fully handled.

== Arguments

StreamID::

The stream ID.

IsFin::

Whether this is the end of the request body.

Data::

The data received.

Commands::

The commands to be executed.

State::

The state for the next stream handler.

== Return value

A list of commands and an opaque state is returned.

The list of commands returned should be included in the
commands returned from the current stream handler. It
can be modified if necessary.

The state should be stored in the current stream
handler's state and passed to `cowboy_stream` when
necessary. The state should be treated as opaque.

== Changelog

* *2.0*: Function introduced.

== Examples

.Propagate data to the next stream handler
[source,erlang]
----
data(StreamID, IsFin, Data, State=#state{next=Next0}) ->
    MyCommands = my_commands(),
    {Commands, Next} = cowboy_stream:data(StreamID, IsFin, Data, Next0),
    {MyCommands ++ Commands, #state{next=Next}}.
----

== See also

link:man:cowboy_stream(3)[cowboy_stream(3)],
link:man:cowboy_stream:init(3)[cowboy_stream:init(3)],
link:man:cowboy_stream:info(3)[cowboy_stream:info(3)],
link:man:cowboy_stream:terminate(3)[cowboy_stream:terminate(3)],
link:man:cowboy_stream:early_error(3)[cowboy_stream:early_error(3)]