|
|
@@ -2,60 +2,90 @@
|
|
|
|
|
|
== Name
|
|
|
|
|
|
-ranch_transport - behaviour for transport modules
|
|
|
+ranch_transport - Transport modules
|
|
|
|
|
|
== Description
|
|
|
|
|
|
-The `ranch_transport` behaviour defines the interface used
|
|
|
+The module `ranch_transport` defines the interface used
|
|
|
by Ranch transports.
|
|
|
|
|
|
-== Types
|
|
|
+== Callbacks
|
|
|
|
|
|
-=== sendfile_opts() = [{chunk_size, non_neg_integer()}]
|
|
|
+Ranch transports implement the following interface:
|
|
|
|
|
|
-Options used by the sendfile function and callbacks.
|
|
|
+=== accept
|
|
|
|
|
|
-Allows configuring the chunk size, in bytes. Defaults to 8191 bytes.
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+accept(LSocket :: socket(), Timeout :: timeout())
|
|
|
+ -> {ok, Socket :: socket()}
|
|
|
+ | {error, closed | timeout | atom()}
|
|
|
+----
|
|
|
|
|
|
-== Callbacks
|
|
|
+Use the listening socket returned by `listen/1`
|
|
|
+to accept a new connection. The timeout is specified
|
|
|
+in milliseconds.
|
|
|
+
|
|
|
+=== close
|
|
|
|
|
|
-=== accept(LSocket, Timeout) -> {ok, CSocket} | {error, closed | timeout | atom()}
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+close(Socket :: socket()) -> ok
|
|
|
+----
|
|
|
|
|
|
-LSocket = CSocket = any():: Listening socket.
|
|
|
-Timeout = timeout():: Accept timeout.
|
|
|
+Close the socket.
|
|
|
|
|
|
-Accept a connection on the given listening socket.
|
|
|
+=== controlling_process
|
|
|
|
|
|
-The `handshake` 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.
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+controlling_process(Socket :: socket(), Pid :: pid())
|
|
|
+ -> ok | {error, closed | not_owner | atom()}
|
|
|
+----
|
|
|
|
|
|
-=== close(Socket) -> ok
|
|
|
+Assign a new controlling process to the socket. The
|
|
|
+controlling process is the process that is linked to
|
|
|
+and receives messages from the socket.
|
|
|
|
|
|
-Socket = any():: Socket opened with listen/1 or accept/2.
|
|
|
+=== getopts
|
|
|
|
|
|
-Close the given socket.
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+getopts(Socket :: socket(), SockOpts :: [atom()])
|
|
|
+ -> {ok, any()} | {error, atom()}
|
|
|
+----
|
|
|
|
|
|
-=== controlling_process(Socket, Pid) -> ok | {error, closed | not_owner | atom()}
|
|
|
+Get one or more options for the socket.
|
|
|
|
|
|
-Socket = any():: Socket opened with listen/1 or accept/2.
|
|
|
-Pid = pid():: Pid of the new owner of the socket.
|
|
|
+=== getstat
|
|
|
|
|
|
-Change the controlling process for the given socket.
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+getstat(Socket :: socket())
|
|
|
+ -> {ok, SockStatValues :: any()} | {error, atom()}
|
|
|
+----
|
|
|
|
|
|
-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.
|
|
|
+Get all statistics for the socket.
|
|
|
|
|
|
-=== handshake(CSocket0, Options, Timeout) -> {ok, CSocket1}
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+getstat(Socket :: socket(), SockStats :: [atom()])
|
|
|
+ -> {ok, SockStatValues :: any()} | {error, atom()}
|
|
|
+----
|
|
|
|
|
|
-CSocket0 = any():: Uninitialized socket for this connection.
|
|
|
-Options = any():: Options for initialization.
|
|
|
-Timeout = timeout():: Handshake timeout.
|
|
|
-CSocket1 = any():: Initialized socket for this connection.
|
|
|
+Get one or more statistic options for the socket.
|
|
|
|
|
|
-Perform any necessary handshake for this transport.
|
|
|
+=== handshake
|
|
|
+
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+handshake(Socket0 :: socket(),
|
|
|
+ SockOpts :: any(),
|
|
|
+ Timeout :: timeout())
|
|
|
+ -> {ok, Socket}
|
|
|
+----
|
|
|
+
|
|
|
+Perform the transport-level handshake.
|
|
|
|
|
|
This function will be called by connection processes
|
|
|
before performing any socket operation. It allows
|
|
|
@@ -67,158 +97,198 @@ from a transport to another depending on the capabilities
|
|
|
of the transports. For example a `ranch_tcp` socket may
|
|
|
be upgraded to a `ranch_ssl` one using this function.
|
|
|
|
|
|
-=== listen(TransOpts) -> {ok, LSocket} | {error, atom()}
|
|
|
-
|
|
|
-TransOpts = any():: Transport options.
|
|
|
-LSocket = any():: Listening socket.
|
|
|
+=== listen
|
|
|
|
|
|
-Listen for connections on the given port.
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+listen(SockOpts :: any())
|
|
|
+ -> {ok, LSocket :: socket()} | {error, atom()}
|
|
|
+----
|
|
|
|
|
|
-The port is given as part of the transport options under
|
|
|
-the key `port`. Any other option is transport dependent.
|
|
|
+Create a socket that listens on the given port.
|
|
|
|
|
|
-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.
|
|
|
+The port may not be specified or may be set to 0, which
|
|
|
+means a random available port number will be chosen.
|
|
|
|
|
|
-=== messages() -> {OK, Closed, Error}
|
|
|
+=== messages
|
|
|
|
|
|
-OK = Closed = Error = atom():: Tuple names.
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+messages()
|
|
|
+ -> {OK :: atom(),
|
|
|
+ Closed :: atom(),
|
|
|
+ Error :: atom()}
|
|
|
+----
|
|
|
|
|
|
-Return the atoms used to identify messages sent in active mode.
|
|
|
+Return the tuple keys for the messages sent by the socket.
|
|
|
|
|
|
-=== name() -> Name
|
|
|
+=== name
|
|
|
|
|
|
-Name = atom():: Transport module name.
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+name() -> Name :: atom()
|
|
|
+----
|
|
|
|
|
|
Return the name of the transport.
|
|
|
|
|
|
-=== peername(CSocket) -> {ok, {IP, Port}} | {error, atom()}
|
|
|
+=== peername
|
|
|
|
|
|
-CSocket = any():: Socket for this connection.
|
|
|
-IP = inet:ip_address():: IP of the remote endpoint.
|
|
|
-Port = inet:port_number():: Port of the remote endpoint.
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+peername(Socket :: socket())
|
|
|
+ -> {ok, {inet:ip_address(), inet:port_number()}}
|
|
|
+ | {error, atom()}.
|
|
|
+----
|
|
|
|
|
|
-Return the IP and port of the remote endpoint.
|
|
|
+Return the address and port number for the other end of
|
|
|
+the connection.
|
|
|
|
|
|
-=== recv(CSocket, Length, Timeout) -> {ok, Packet} | {error, closed | timeout | atom()}
|
|
|
+=== recv
|
|
|
|
|
|
-CSocket = any():: Socket for this connection.
|
|
|
-Length = non_neg_integer():: Requested length.
|
|
|
-Timeout = timeout():: Receive timeout.
|
|
|
-Packet = iodata() | any():: Data received.
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+recv(Socket :: socket(),
|
|
|
+ Length :: non_neg_integer(),
|
|
|
+ Timeout :: timeout())
|
|
|
+ -> {ok, Packet :: any()}
|
|
|
+ | {error, closed | timeout | atom()}
|
|
|
+----
|
|
|
|
|
|
-Receive data from the given socket when in passive mode.
|
|
|
+Receive a packet from the socket in passive mode.
|
|
|
|
|
|
-Trying to receive data from a socket that is in active mode
|
|
|
-will return an error.
|
|
|
+Attempting 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.
|
|
|
+A length of 0 will return the data available on
|
|
|
+the socket as soon as possible, regardless of length.
|
|
|
|
|
|
While it is possible to use the timeout value `infinity`,
|
|
|
-this is highly discouraged as this could cause your process
|
|
|
+it is highly discouraged as it 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.
|
|
|
+remote endpoint. Wi-Fi going down is another common culprit.
|
|
|
|
|
|
-=== send(CSocket, Packet) -> ok | {error, atom()}
|
|
|
+=== secure
|
|
|
|
|
|
-CSocket = any():: Socket for this connection.
|
|
|
-Packet = iodata():: Data to be sent.
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+secure() -> boolean()
|
|
|
+----
|
|
|
|
|
|
-Send data to the given socket.
|
|
|
+Return whether the transport can be used for secure connections.
|
|
|
|
|
|
-=== sendfile(CSocket, File) -> sendfile(CSocket, File, 0, 0, [])
|
|
|
+=== send
|
|
|
|
|
|
-Alias of `ranch_transport:sendfile/5`.
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+send(Socket :: socket(), Packet :: iodata())
|
|
|
+ -> ok | {error, atom()}
|
|
|
+----
|
|
|
|
|
|
-=== sendfile(CSocket, File, Offset, Bytes) -> sendfile(CSocket, File, Offset, Bytes, [])
|
|
|
+Send a packet on the socket.
|
|
|
|
|
|
-Alias of `ranch_transport:sendfile/5`.
|
|
|
+=== sendfile
|
|
|
|
|
|
-=== sendfile(CSocket, File, Offset, Bytes, SfOpts) -> {ok, SentBytes} | {error, atom()}
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+sendfile(Socket, File)
|
|
|
+ -> sendfile(Socket, File, 0, 0, [])
|
|
|
|
|
|
-CSocket = any():: Socket for this connection.
|
|
|
-File = file:filename_all() | file:fd():: Filename or file descriptor for the file to be sent.
|
|
|
-Offset = non_neg_integer():: Begin sending at this position in the file.
|
|
|
-Bytes = non_neg_integer():: Send this many bytes.
|
|
|
-SentBytes = non_neg_integer():: This many bytes were sent.
|
|
|
-SfOpts = sendfile_opts():: Sendfile options.
|
|
|
+sendfile(Socket, File, Offset, Bytes)
|
|
|
+ -> sendfile(Socket, File, Offset, Bytes, [])
|
|
|
|
|
|
-Send data from a file to the given socket.
|
|
|
+sendfile(Socket :: socket(),
|
|
|
+ File :: file:name_all() | file:fd(),
|
|
|
+ Offset :: non_neg_integer(),
|
|
|
+ Bytes :: non_neg_integer(),
|
|
|
+ Opts :: sendfile_opts())
|
|
|
+ -> {ok, SentBytes :: non_neg_integer()} | {error, atom()}
|
|
|
+----
|
|
|
+
|
|
|
+Send a file on the 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
|
|
|
+`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, SockOpts) -> ok | {error, atom()}
|
|
|
+=== setopts
|
|
|
+
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+setopts(Socket :: socket(), SockOpts :: any())
|
|
|
+ -> ok | {error, atom()}
|
|
|
+----
|
|
|
+
|
|
|
+Set one or more options for the socket.
|
|
|
|
|
|
-CSocket = any():: Socket for this connection.
|
|
|
-SockOpts = any():: Socket options.
|
|
|
+=== shutdown
|
|
|
|
|
|
-Change options for the given socket.
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+shutdown(Socket :: socket(),
|
|
|
+ How :: read | write | read_write)
|
|
|
+ -> ok | {error, atom()}
|
|
|
+----
|
|
|
|
|
|
-This is mainly useful for switching to active or passive mode
|
|
|
-or to set protocol-specific options.
|
|
|
+Close the socket for reading and/or writing.
|
|
|
|
|
|
-=== getopts(CSocket, SockOpts) -> {ok, SockOptValues} | {error, atom()}
|
|
|
+=== sockname
|
|
|
|
|
|
-CSocket = any():: Socket for this connection.
|
|
|
-SockOpts = [atom()]:: Socket option names.
|
|
|
-SockOptValues = list():: Socket options.
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+sockname(Socket :: socket())
|
|
|
+ -> {ok, {inet:ip_address(), inet:port_number()}}
|
|
|
+ | {error, atom()}.
|
|
|
+----
|
|
|
|
|
|
-Get options for the given socket.
|
|
|
+Return the address and port number for the local end
|
|
|
+of the connection.
|
|
|
|
|
|
-=== getstat(CSocket) -> {ok, SockStatValues} | {error, atom()}
|
|
|
+== Exports
|
|
|
|
|
|
-CSocket = any():: Socket for this connection.
|
|
|
-SockStatValues = list():: Socket statistics.
|
|
|
+The following function can be used when implementing
|
|
|
+transport modules:
|
|
|
|
|
|
-Get statistics for the given socket.
|
|
|
+* link:man:ranch_transport:sendfile(3)[ranch_transport:sendfile(3)] - Send a file on the socket
|
|
|
|
|
|
-=== getstat(CSocket, SockStats) -> {ok, SockStatValues} | {error, atom()}
|
|
|
+== Types
|
|
|
|
|
|
-CSocket = any():: Socket for this connection.
|
|
|
-SockStats = [atom()]:: Socket statistic names.
|
|
|
-SockStatValues = list():: Socket statistics.
|
|
|
+=== sendfile_opts()
|
|
|
|
|
|
-Get statistics for the given socket.
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+sendfile_opts() :: [{chunk_size, non_neg_integer()}]
|
|
|
+----
|
|
|
|
|
|
-=== shutdown(CSocket, How) -> ok | {error, atom()}
|
|
|
+Options accepted by the sendfile function and callbacks:
|
|
|
|
|
|
-CSocket = any():: Socket for this connection.
|
|
|
-How = read | write | read_write:: Which side(s) of the socket to close.
|
|
|
+chunk_size (8191)::
|
|
|
|
|
|
-Immediately close the socket in one or two directions.
|
|
|
+The chunk size, in bytes.
|
|
|
|
|
|
-=== sockname(Socket) -> {ok, {IP, Port}} | {error, atom()}
|
|
|
+=== socket()
|
|
|
|
|
|
-Socket = any():: Socket opened with listen/1 or accept/2.
|
|
|
-IP = inet:ip_address():: IP of the local endpoint.
|
|
|
-Port = inet:port_number():: Port of the local endpoint.
|
|
|
+[source,erlang]
|
|
|
+----
|
|
|
+socket() :: any()
|
|
|
+----
|
|
|
|
|
|
-Return the IP and port of the local endpoint.
|
|
|
+The socket.
|
|
|
|
|
|
-== Exports
|
|
|
+The exact type will vary depending on the transport module.
|
|
|
|
|
|
-=== sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts) -> {ok, SentBytes} | {error, atom()}
|
|
|
+== Changelog
|
|
|
|
|
|
-Transport = module():: Transport module for this socket.
|
|
|
-CSocket = any():: Socket for this connection.
|
|
|
-File = file:filename_all() | file:fd():: Filename or file descriptor for the file to be sent.
|
|
|
-Offset = non_neg_integer():: Begin sending at this position in the file.
|
|
|
-Bytes = non_neg_integer():: Send this many bytes.
|
|
|
-SentBytes = non_neg_integer():: This many bytes were sent.
|
|
|
-SfOpts = sendfile_opts():: Sendfile options.
|
|
|
+* *1.6*: The `socket()` type was added for documentation purposes.
|
|
|
+* *1.6*: The type of the sendfile filename was extended.
|
|
|
|
|
|
-Send data from a file to the given socket.
|
|
|
+== See also
|
|
|
|
|
|
-This function emulates the function `file:sendfile/{2,4,5}`
|
|
|
-and may be used when transports are not manipulating TCP
|
|
|
-directly.
|
|
|
+link:man:ranch(7)[ranch(7)],
|
|
|
+link:man:ranch_tcp(3)[ranch_tcp(3)],
|
|
|
+link:man:ranch_ssl(3)[ranch_ssl(3)]
|
Loïc Hoguin