diff options
Diffstat (limited to 'src/cowboy_ssl_transport.erl')
| -rw-r--r-- | src/cowboy_ssl_transport.erl | 57 |
1 files changed, 54 insertions, 3 deletions
diff --git a/src/cowboy_ssl_transport.erl b/src/cowboy_ssl_transport.erl index 8e569ec..098d409 100644 --- a/src/cowboy_ssl_transport.erl +++ b/src/cowboy_ssl_transport.erl @@ -12,18 +12,50 @@ %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +%% @doc SSL transport API. +%% +%% Wrapper around <em>ssl</em> implementing the Cowboy transport API. +%% +%% This transport requires the <em>crypto</em>, <em>public_key</em> +%% and <em>ssl</em> applications to be started. If they aren't started, +%% it will try to start them itself before opening a port to listen. +%% Applications aren't stopped when the listening socket is closed, though. +%% +%% @see ssl -module(cowboy_ssl_transport). -export([name/0, messages/0, listen/1, accept/2, recv/3, send/2, setopts/2, - controlling_process/2, peername/1, close/1]). %% API. - -%% API. + controlling_process/2, peername/1, close/1]). +%% @doc Name of this transport API, <em>ssl</em>. -spec name() -> ssl. name() -> ssl. +%% @doc Atoms used in the process messages sent by this API. +%% +%% They identify incoming data, closed connection and errors when receiving +%% data in active mode. -spec messages() -> {ssl, ssl_closed, ssl_error}. messages() -> {ssl, ssl_closed, ssl_error}. +%% @doc Setup a socket to listen on the given port on the local host. +%% +%% The available options are: +%% <dl> +%% <dt>port</dt><dd>Mandatory. TCP port number to open.</dd> +%% <dt>backlog</dt><dd>Maximum length of the pending connections queue. +%% Defaults to 1024.</dd> +%% <dt>ip</dt><dd>Interface to listen on. Listen on all interfaces +%% by default.</dd> +%% <dt>certfile</dt><dd>Mandatory. Path to a file containing the user's +%% certificate.</dd> +%% <dt>keyfile</dt><dd>Mandatory. Path to the file containing the user's +%% private PEM encoded key.</dd> +%% <dt>password</dt><dd>Mandatory. String containing the user's password. +%% All private keyfiles must be password protected currently.</dd> +%% </dl> +%% +%% @see ssl:listen/2 +%% @todo The password option shouldn't be mandatory. -spec listen([{port, inet:ip_port()} | {certfile, string()} | {keyfile, string()} | {password, string()} | {ip, inet:ip_address()}]) @@ -45,6 +77,13 @@ listen(Opts) -> end, ssl:listen(Port, ListenOpts). +%% @doc Accept an incoming connection on a listen socket. +%% +%% Note that this function does both the transport accept and +%% the SSL handshake. +%% +%% @see ssl:transport_accept/2 +%% @see ssl:ssl_accept/2 -spec accept(ssl:sslsocket(), timeout()) -> {ok, ssl:sslsocket()} | {error, closed | timeout | atom()}. accept(LSocket, Timeout) -> @@ -55,29 +94,41 @@ accept(LSocket, Timeout) -> {error, Reason} end. +%% @doc Receive a packet from a socket in passive mode. +%% @see ssl:recv/3 -spec recv(ssl:sslsocket(), non_neg_integer(), timeout()) -> {ok, any()} | {error, closed | atom()}. recv(Socket, Length, Timeout) -> ssl:recv(Socket, Length, Timeout). +%% @doc Send a packet on a socket. +%% @see ssl:send/2 -spec send(ssl:sslsocket(), iolist()) -> ok | {error, atom()}. send(Socket, Packet) -> ssl:send(Socket, Packet). +%% @doc Set one or more options for a socket. +%% @see ssl:setopts/2 -spec setopts(ssl:sslsocket(), list()) -> ok | {error, atom()}. setopts(Socket, Opts) -> ssl:setopts(Socket, Opts). +%% @doc Assign a new controlling process <em>Pid</em> to <em>Socket</em>. +%% @see ssl:controlling_process/2 -spec controlling_process(ssl:sslsocket(), pid()) -> ok | {error, closed | not_owner | atom()}. controlling_process(Socket, Pid) -> ssl:controlling_process(Socket, Pid). +%% @doc Return the address and port for the other end of a connection. +%% @see ssl:peername/1 -spec peername(ssl:sslsocket()) -> {ok, {inet:ip_address(), inet:ip_port()}} | {error, atom()}. peername(Socket) -> ssl:peername(Socket). +%% @doc Close a TCP socket. +%% @see ssl:close/1 -spec close(ssl:sslsocket()) -> ok. close(Socket) -> ssl:close(Socket). |