ranch_transport
===============

The `ranch_transport` behaviour defines the interface used
by Ranch transports.

Types
-----

### sendfile_opts() = [{chunk_size, non_neg_integer()}]

> Options used by the sendfile function and callbacks.
>
> Allows configuring the chunk size, in bytes. Defaults to 8191 bytes.

Callbacks
---------

### accept(LSocket, Timeout)
	-> {ok, CSocket} | {error, closed | timeout | atom()}

> Types:
>  *  LSocket = CSocket = any()
>  *  Timeout = timeout()
>
> Accept a connection on the given listening socket.
>
> The `accept_ack` callback will be used to initialize the socket
> after accepting the connection. This is most useful when the
> transport is not raw TCP, like with SSL for example.

### accept_ack(CSocket, Timeout) -> ok

> Types:
>  *  CSocket = any()
>  *  Timeout = timeout()
>
> Perform post-accept initialization of the connection.
>
> This function will be called by connection processes
> before performing any socket operation. It allows
> transports that require extra initialization to perform
> their task and make the socket ready to use.

### close(CSocket) -> ok

> Types:
>  *  CSocket = any()
>
> Close the given socket.

### controlling_process(CSocket, Pid)
	-> ok | {error, closed | not_owner | atom()}

> Types:
>  *  CSocket = any()
>  *  Pid = pid()
>
> Change the controlling process for the given socket.
>
> The controlling process is the process that is allowed to
> perform operations on the socket, and that will receive
> messages from the socket when active mode is used. When
> the controlling process dies, the socket is closed.

### listen(TransOpts) -> {ok, LSocket} | {error, atom()}

> Types:
>  *  TransOpts = any()
>  *  LSocket = any()
>
> Listen for connections on the given port.
>
> The port is given as part of the transport options under
> the key `port`. Any other option is transport dependent.
>
> The socket returned by this call can then be used to
> accept connections. It is not possible to send or receive
> data from the listening socket.

### messages() -> {OK, Closed, Error}

> Types:
>  *  OK = Closed = Error = atom()
>
> Return the atoms used to identify messages sent in active mode.

### name() -> Name

> Types:
>  *  Name = atom()
>
> Return the name of the transport.

### peername(CSocket) -> {ok, {IP, Port}} | {error, atom()}

> Types:
>  *  CSocket = any()
>  *  IP = inet:ip_address()
>  *  Port = inet:port_number()
>
> Return the IP and port of the remote endpoint.

### recv(CSocket, Length, Timeout)
	-> {ok, Packet} | {error, closed | timeout | atom()}

> Types:
>  *  CSocket = any()
>  *  Length = non_neg_integer()
>  *  Timeout = timeout()
>  *  Packet = iodata() | any()
>
> Receive data from the given socket when in passive mode.
>
> Trying to receive data from a socket that is in active mode
> will return an error.
>
> A length of 0 will return any data available on the socket.
>
> While it is possible to use the timeout value `infinity`,
> this is highly discouraged as this could cause your process
> to get stuck waiting for data that will never come. This may
> happen when a socket becomes half-open due to a crash of the
> remote endpoint. Wi-Fi going down is another common culprit
> of this issue.

### send(CSocket, Packet) -> ok | {error, atom()}

> Types:
>  *  CSocket = any()
>  *  Packet = iodata()
>
> Send data to the given socket.

### sendfile(CSocket, File)
	-> sendfile(CSocket, File, 0, 0, [])
### sendfile(CSocket, File, Offset, Bytes)
	-> sendfile(CSocket, File, Offset, Bytes, [])
### sendfile(CSocket, File, Offset, Bytes, SfOpts)
	-> {ok, SentBytes} | {error, atom()}

> Types:
>  *  CSocket = any()
>  *  File = file:filename_all() | file:fd()
>  *  Offset = non_neg_integer()
>  *  Bytes = SentBytes = non_neg_integer()
>  *  SfOpts = sendfile_opts()
>
> Send data from a file to the given socket.
>
> The file may be sent full or in parts, and may be specified
> by its filename or by an already open file descriptor.
>
> Transports that manipulate TCP directly may use the
> `file:sendfile/{2,4,5}` function, which calls the sendfile
> syscall where applicable (on Linux, for example). Other
> transports can use the `sendfile/6` function exported from
> this module.

### setopts(CSocket, TransOpts) -> ok | {error, atom()}

> Types:
>  *  CSocket = any()
>  *  TransOpts = any()
>
> Change transport options for the given socket.
>
> This is mainly useful for switching to active or passive mode.

### shutdown(CSocket, How) -> ok | {error, atom()}

> Types:
>  *  CSocket = any()
>  *  How = read | write | read_write
>
> Immediately close the socket in one or two directions.

### sockname(CSocket) -> {ok, {IP, Port}} | {error, atom()}

> Types:
>  *  CSocket = any()
>  *  IP = inet:ip_address()
>  *  Port = inet:port_number()
>
> Return the IP and port of the local endpoint.

Exports
-------

### sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts)
	-> {ok, SentBytes} | {error, atom()}

> Types:
>  *  Transport = module()
>  *  CSocket = any()
>  *  File = file:filename_all() | file:fd()
>  *  Offset = non_neg_integer()
>  *  Bytes = SentBytes = non_neg_integer()
>  *  SfOpts = sendfile_opts()
>
> Send data from a file to the given socket.
>
> This function emulates the function `file:sendfile/{2,4,5}`
> and may be used when transports are not manipulating TCP
> directly.