diff options
author | James Fish <[email protected]> | 2013-04-02 00:49:07 +0100 |
---|---|---|
committer | James Fish <[email protected]> | 2013-08-16 18:44:24 +0100 |
commit | ca6817880ee5592cf890fb5a71da41f52818d29a (patch) | |
tree | 79a0bb2b006fab3e1b23d267c0eb06633c37c015 /guide/transports.md | |
parent | c767739ee3e917c9ce3c67827e655f10d6c191f9 (diff) | |
download | ranch-ca6817880ee5592cf890fb5a71da41f52818d29a.tar.gz ranch-ca6817880ee5592cf890fb5a71da41f52818d29a.tar.bz2 ranch-ca6817880ee5592cf890fb5a71da41f52818d29a.zip |
Add Transport:sendfile/4,/5
Adds offset based sendfile to transports. Same behaviour as
file:sendfile/4,/5 except socket and file arguments are reversed and
either a raw file or a filename can be used.
sendfile/2,/4,/5 now compulsory callbacks in ranch_transport.
ranch_tcp:sendfile/2 now defaults to a chunk_size of 8191 - the default
for ranch_ssl:sendfile/2. The same default is used for both
ranch_tcp:sendfile/4,5 and ranch_ssl:sendfile/4,5.
Diffstat (limited to 'guide/transports.md')
-rw-r--r-- | guide/transports.md | 32 |
1 files changed, 32 insertions, 0 deletions
diff --git a/guide/transports.md b/guide/transports.md index 1844ac9..aaf530f 100644 --- a/guide/transports.md +++ b/guide/transports.md @@ -119,6 +119,34 @@ end. You can easily integrate active sockets with existing Erlang code as all you really need is just a few more clauses when receiving messages. +Sending files +------------- + +As in the previous section it is assumed `Transport` is a valid transport +handler and `Socket` is a connected socket obtained through the listener. + +To send a whole file, with name `Filename`, over a socket: + +```erlang +{ok, SentBytes} = Transport:sendfile(Socket, Filename). +``` + +Or part of a file, with `Offset` greater than or equal to 0, `Bytes` number of +bytes and chunks of size `ChunkSize`: + +```erlang +Opts = [{chunk_size, ChunkSize}], +{ok, SentBytes} = Transport:sendfile(Socket, Filename, Offset, Bytes, Opts). +``` + +To improve efficiency when sending multiple parts of the same file it is also +possible to use a file descriptor opened in raw mode: + +```erlang +{ok, RawFile} = file:open(Filename, [raw, read, binary]), +{ok, SentBytes} = Transport:sendfile(Socket, RawFile, Offset, Bytes, Opts). +``` + Writing a transport handler --------------------------- @@ -131,3 +159,7 @@ socket. These do not need to be common to all transports as it's easy enough to write different initialization functions for the different transports that will be used. With one exception though. The `setopts/2` function *must* implement the `{active, once}` and the `{active, true}` options. + +If the transport handler doesn't have a native implementation of `sendfile/5` a +fallback is available, `ranch_transport:sendfile/6`. The extra first argument +is the transport's module. See `ranch_ssl` for an example. |