Updated documentation.
[erlang-mod_sse.git] / src / gen_sse_server.erl
1 %%%---------------------------------------------------------------------------
2 %%% @doc
3 %%%   Behaviour for a callback module to use with {@link mod_sse}.
4 %%%
5 %%%   == Expected callbacks ==
6 %%%
7 %%%   The callbacks are very similar to the ones from {@link gen_server},
8 %%%   except that `handle_*()' return one more element in tuples, which is
9 %%%   a list of events to send to the client (atom `nothing' in the place has
10 %%%   the same result as returning empty list).
11 %%%
12 %%%   <ul>
13 %%%     <li>
14 %%%       `init(RootURI :: uri(), URI :: uri(), Headers :: [http_header()],
15 %%%             Args :: term())'
16 %%%       <ul>
17 %%%         <li>{@type @{ok, term()@}}</li>
18 %%%         <li>{@type @{ok, term(), timeout()@}}</li>
19 %%%         <li>{@type @{ok, term(), hibernate@}}</li>
20 %%%         <li>{@type @{error, term()@}}</li>
21 %%%       </ul>
22 %%%     </li>
23 %%%     <li>
24 %%%       `terminate(Reason :: normal | shutdown | {shutdown, term()} | term(),
25 %%%                  State :: term())'
26 %%%       <ul>
27 %%%         <li>returned value is ignored</li>
28 %%%       </ul>
29 %%%     </li>
30 %%%     <li>
31 %%%       `handle_call(Request :: term(), From :: {pid(), Tag :: term()},
32 %%%                    State :: term())'
33 %%%       <ul>
34 %%%         <li>{@type @{reply, Reply :: term(), nothing | [event()], NewState :: term()@}}</li>
35 %%%         <li>{@type @{reply, Reply :: term(), nothing | [event()], NewState :: term(), timeout()@}}</li>
36 %%%         <li>{@type @{reply, Reply :: term(), nothing | [event()], NewState :: term(), hibernate@}}</li>
37 %%%         <li>{@type @{noreply, nothing | [event()], NewState :: term()@}}</li>
38 %%%         <li>{@type @{noreply, nothing | [event()], NewState :: term(), timeout()@}}</li>
39 %%%         <li>{@type @{noreply, nothing | [event()], NewState :: term(), hibernate@}}</li>
40 %%%         <li>{@type @{stop, Reason :: term(), Reply :: term(), nothing | [event()], NewState :: term()@}}</li>
41 %%%         <li>{@type @{stop, Reason :: term(), nothing | [event()], NewState :: term()@}}</li>
42 %%%       </ul>
43 %%%     </li>
44 %%%     <li>
45 %%%       `handle_cast(Request :: term(), State :: term())'
46 %%%       <ul>
47 %%%         <li>{@type @{noreply, nothing | [event()], NewState :: term()@}}</li>
48 %%%         <li>{@type @{noreply, nothing | [event()], NewState :: term(), timeout()@}}</li>
49 %%%         <li>{@type @{noreply, nothing | [event()], NewState :: term(), hibernate@}}</li>
50 %%%         <li>{@type @{stop, Reason :: term(), nothing | [event()], NewState :: term()@}}</li>
51 %%%       </ul>
52 %%%     </li>
53 %%%     <li>
54 %%%       `handle_info(Message :: term(), State :: term())'
55 %%%       <ul>
56 %%%         <li>{@type @{noreply, nothing | [event()], NewState :: term()@}}</li>
57 %%%         <li>{@type @{noreply, nothing | [event()], NewState :: term(), timeout()@}}</li>
58 %%%         <li>{@type @{noreply, nothing | [event()], NewState :: term(), hibernate@}}</li>
59 %%%         <li>{@type @{stop, Reason :: term(), nothing | [event()], NewState :: term()@}}</li>
60 %%%       </ul>
61 %%%     </li>
62 %%%     <li>
63 %%%       `code_change(OldVsn :: term() | {down, term()}, State :: term(),
64 %%%                    Extra :: term())'
65 %%%       <ul>
66 %%%         <li>{@type @{ok, NewState :: term()@}}</li>
67 %%%         <li>{@type @{error, term()@}}</li>
68 %%%       </ul>
69 %%%       <b>Note</b>: since I don't have much experience with Erlang
70 %%%       releases, this function most probably doesn't work correctly (this
71 %%%       is a working example of cargo cult programming).
72 %%%     </li>
73 %%%   </ul>
74 %%%
75 %%% @end
76 %%%---------------------------------------------------------------------------
77
78 -module(gen_sse_server).
79
80 -export_type([event/0, uri/0, http_header/0]).
81
82 %%%---------------------------------------------------------------------------
83
84 -type uri() :: string().
85 %% Path from the request (or module mountpoint).
86
87 -type event() :: iolist().
88 %% Event to be sent. This should be a bytestring ready to pass through
89 %% network, so `unicode:characters_to_binary/2' could be handy.
90
91 -type http_header() :: {term(), term()}.
92 %% Single HTTP request header.
93
94 %%%---------------------------------------------------------------------------
95
96 behaviour_info(callbacks) ->
97   [{init, 4}, {terminate, 2},
98     {handle_call, 3}, {handle_cast, 2}, {handle_info, 2},
99     {code_change, 3}];
100 behaviour_info(_Any) ->
101   undefined.
102
103 %%%---------------------------------------------------------------------------
104 %%% vim:ft=erlang:foldmethod=marker:nowrap