mirror of
https://github.com/ninenines/cowboy.git
synced 2025-07-15 04:30:25 +00:00
101 lines
2.4 KiB
Text
101 lines
2.4 KiB
Text
= cowboy_req:stream_events(3)
|
|
|
|
== Name
|
|
|
|
cowboy_req:stream_events - Stream events
|
|
|
|
== Description
|
|
|
|
[source,erlang]
|
|
----
|
|
stream_events(Events, IsFin, Req :: cowboy_req:req()) -> ok
|
|
|
|
Events :: Event | [Event]
|
|
IsFin :: fin | nofin
|
|
|
|
Event :: #{
|
|
comment => iodata(),
|
|
data => iodata(),
|
|
event => iodata() | atom(),
|
|
id => iodata(),
|
|
retry => non_neg_integer()
|
|
}
|
|
----
|
|
|
|
Stream events.
|
|
|
|
This function should only be used for `text/event-stream`
|
|
responses when using server-sent events. Cowboy will
|
|
automatically encode the given events to their text
|
|
representation.
|
|
|
|
This function may be called as many times as needed after
|
|
initiating a response using the
|
|
link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)]
|
|
function.
|
|
|
|
The second argument indicates if this call is the final
|
|
call. Use the `nofin` value until you know no more data
|
|
will be sent. The final call should use `fin` (possibly
|
|
with an empty data value) or be a call to the
|
|
link:man:cowboy_req:stream_trailers(3)[cowboy_req:stream_trailers(3)]
|
|
function.
|
|
|
|
Note that not using `fin` for the final call is not an
|
|
error; Cowboy will take care of it when the request
|
|
handler terminates if needed. Depending on the resource
|
|
it may however be more efficient to do it as early as
|
|
possible.
|
|
|
|
You do not need to handle HEAD requests specifically as
|
|
Cowboy will ensure no data is sent when you call this function.
|
|
|
|
== Arguments
|
|
|
|
Events::
|
|
|
|
Events to be sent. All fields are optional.
|
|
|
|
IsFin::
|
|
|
|
A flag indicating whether this is the final piece of data
|
|
to be sent.
|
|
|
|
Req::
|
|
|
|
The Req object.
|
|
|
|
== Return value
|
|
|
|
The atom `ok` is always returned. It can be safely ignored.
|
|
|
|
== Changelog
|
|
|
|
* *2.5*: Function introduced.
|
|
|
|
== Examples
|
|
|
|
.Stream events
|
|
[source,erlang]
|
|
----
|
|
Req = cowboy_req:stream_reply(200, #{
|
|
<<"content-type">> => <<"text/event-stream">>
|
|
}, Req0),
|
|
cowboy_req:stream_events(#{
|
|
id => <<"comment-123">>,
|
|
event => <<"add_comment">>,
|
|
data => <<"Hello,\n\nI noticed something wrong in ...">>
|
|
}, nofin, Req),
|
|
timer:sleep(1000),
|
|
cowboy_req:stream_events(#{
|
|
event => <<"debug">>,
|
|
data => io_lib:format("An error occurred: ~p~n", [Error])
|
|
}, fin, Req).
|
|
----
|
|
|
|
== See also
|
|
|
|
link:man:cowboy_req(3)[cowboy_req(3)],
|
|
link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)],
|
|
link:man:cowboy_req:stream_body(3)[cowboy_req:stream_body(3)],
|
|
link:man:cowboy_req:stream_trailers(3)[cowboy_req:stream_trailers(3)]
|