diff options
Diffstat (limited to 'manual/ranch_transport.md')
| -rw-r--r-- | manual/ranch_transport.md | 197 |
1 files changed, 197 insertions, 0 deletions
diff --git a/manual/ranch_transport.md b/manual/ranch_transport.md new file mode 100644 index 0000000..7eb350d --- /dev/null +++ b/manual/ranch_transport.md @@ -0,0 +1,197 @@ +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() | tuple()} + +> 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. + +### 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. |