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