path: root/lib/inets/src/tftp/tftp.erl

%%
%% %CopyrightBegin%
%% 
%% Copyright Ericsson AB 2005-2012. All Rights Reserved.
%% 
%% The contents of this file are subject to the Erlang Public License,
%% Version 1.1, (the "License"); you may not use this file except in
%% compliance with the License. You should have received a copy of the
%% Erlang Public License along with this software. If not, it can be
%% retrieved online at http://www.erlang.org/.
%% 
%% Software distributed under the License is distributed on an "AS IS"
%% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
%% the License for the specific language governing rights and limitations
%% under the License.
%% 
%% %CopyrightEnd%
%%
%%

%%%-------------------------------------------------------------------
%%% File    : tftp.erl
%%% Author  : Hakan Mattsson <[email protected]>
%%% Description : Trivial FTP
%%% Created : 18 May 2004 by Hakan Mattsson <[email protected]>
%%%-------------------------------------------------------------------
%%% 
%%% This is a complete implementation of the following IETF standards:
%%%
%%%    RFC 1350, The TFTP Protocol (revision 2).
%%%    RFC 2347, TFTP Option Extension.
%%%    RFC 2348, TFTP Blocksize Option.
%%%    RFC 2349, TFTP Timeout Interval and Transfer Size Options.
%%%
%%% The only feature that not is implemented in this release is
%%% the "netascii" transfer mode.
%%%
%%% The start/1 function starts a daemon process which, listens for
%%% UDP packets on a port. When it receives a request for read or
%%% write it spawns a temporary server process which handles the
%%% actual transfer of the file. On the client side the read_file/3
%%% and write_file/3 functions spawns a temporary client process which
%%% establishes contact with a TFTP daemon and performs the actual
%%% transfer of the file.
%%%
%%% Most of the options are common for both the client and the server
%%% side, but some of them differs a little. Here are the available
%%% options:
%%%     
%%%   {debug, Level}
%%%
%%%     Level = none | error | warning brief | normal | verbose | all
%%%     
%%%     Controls the level of debug printouts. The default is none.
%%%     
%%%   {host, Host}
%%%
%%%     The name or IP address of the host where the TFTP daemon
%%%     resides. This option is only used by the client. See
%%%     'inet' about valid host names.
%%%     
%%%   {port, Port}
%%%
%%%     Port = integer()
%%%     
%%%     The TFTP port where the daemon listens. It defaults to the
%%%     standardized number 69. On the server side it may sometimes
%%%     make sense to set it to 0, which means that the daemon just
%%%     will pick a free port (which is returned by the start/1
%%%     function).
%%%     
%%%     If a socket has somehow already has been connected, the
%%%     {udp, [{fd, integer()}]} option can be used to pass the
%%%     open file descriptor to gen_udp. This can be automated
%%%     a bit by using a command line argument stating the
%%%     prebound file descriptor number. For example, if the
%%%     Port is 69 and the file descriptor 22 has been opened by
%%%     setuid_socket_wrap. Then the command line argument
%%%     "-tftpd_69 22" will trigger the prebound file
%%%     descriptor 22 to be used instead of opening port 69.
%%%     The UDP option {udp, [{fd, 22}]} autmatically be added.
%%%     See init:get_argument/ about command line arguments and
%%%     gen_udp:open/2 about UDP options.
%%%
%%%   {port_policy, Policy}
%%%
%%%     Policy = random | Port | {range, MinPort, MaxPort}
%%%     Port = MinPort = MaxPort = integer()
%%%     
%%%     Policy for the selection of the temporary port which is used
%%%     by the server/client during the file transfer. It defaults to
%%%     'random' which is the standardized policy. With this policy a
%%%     randomized free port used. A single port or a range of ports
%%%     can be useful if the protocol should pass thru a firewall.
%%%   
%%%   {prebound_fd, InitArgFlag}
%%%
%%%     InitArgFlag = atom()
%%%
%%%     If a socket has somehow already has been connected, the
%%%     {udp, [{fd, integer()}]} option can be used to pass the
%%%     open file descriptor to gen_udp.
%%%
%%%     The prebound_fd option makes it possible to pass give the
%%%     file descriptor as a command line argument. The typical
%%%     usage is when used in conjunction with setuid_socket_wrap
%%%     to be able to open privileged sockets. For example if the
%%%     file descriptor 22 has been opened by setuid_socket_wrap
%%%     and you have choosen my_tftp_fd as init argument, the
%%%     command line should like this "erl -my_tftp_fd 22" and 
%%%     FileDesc should be set to my_tftpd_fd. This would 
%%%     automatically imply {fd, 22} to be set as UDP option.
%%%   
%%%   {udp, UdpOptions}
%%%
%%%      Options to gen_udp:open/2.
%%%
%%%   {use_tsize, Bool}
%%%
%%%     Bool = boolean()
%%%     
%%%     Flag for automated usage of the "tsize" option. With this set
%%%     to true, the write_file/3 client will determine the filesize
%%%     and send it to the server as the standardized "tsize" option.
%%%     A read_file/3 client will just acquire filesize from the
%%%     server by sending a zero "tsize".
%%%     
%%%   {max_tsize, MaxTsize}
%%%
%%%     MaxTsize = integer() | infinity
%%%     
%%%     Threshold for the maximal filesize in bytes. The transfer will
%%%     be aborted if the limit is exceeded. It defaults to
%%%     'infinity'.
%%%
%%%   {max_conn, MaxConn}
%%%   
%%%     MaxConn = integer() | infinity
%%%     
%%%     Threshold for the maximal number of active connections. The
%%%     daemon will reject the setup of new connections if the limit
%%%     is exceeded. It defaults to 'infinity'.
%%%     
%%%   {TftpKey, TftpVal}
%%%
%%%      TftpKey = string()
%%%      TftpVal = string()
%%%
%%%      The name and value of a TFTP option.
%%%      
%%%   {reject, Feature}
%%%   
%%%      Feature = Mode | TftpKey
%%%      Mode    = read | write
%%%      TftpKey = string()
%%%      
%%%      Control which features that should be rejected.
%%%      This is mostly useful for the server as it may restrict
%%%      usage of certain TFTP options or read/write access.
%%%
%%%   {callback, {RegExp, Module, State}}
%%%
%%%    	 RegExp = string()
%%%    	 Module = atom()
%%%    	 State  = term()
%%%    	 
%%%      Registration of a callback module. When a file is to be
%%%      transferred, its local filename will be matched to the
%%%      regular expressions of the registered callbacks. The first
%%%      matching callback will be used the during the transfer.The
%%%      callback module must implement the 'tftp' behaviour.
%%%
%%%      On the server side the callback interaction starts with a
%%%      call to open/5 with the registered initial callback
%%%      state. open/5 is expected to open the (virtual) file. Then
%%%      either the read/1 or write/2 functions are invoked
%%%      repeatedly, once per transfererred block. At each function
%%%      call the state returned from the previous call is
%%%      obtained. When the last block has been encountered the read/1
%%%      or write/2 functions is expected to close the (virtual)
%%%      file.and return its last state. The abort/3 function is only
%%%      used in error situations. prepare/5 is not used on the server
%%%      side.
%%%      
%%%      On the client side the callback interaction is the same, but
%%%      it starts and ends a bit differently. It starts with a call
%%%      to prepare/5 with the same arguments as open/5
%%%      takes. prepare/5 is expected to validate the TFTP options,
%%%      suggested by the user and return the subset of them that it
%%%      accepts. Then the options is sent to the server which will
%%%      perform the same TFTP option negotiation procedure. The
%%%      options that are accepted by the server is forwarded to the
%%%      open/5 function on the client side. On the client side the
%%%      open/5 function must accept all option as is or reject the
%%%      transfer. Then the callback interaction follows the same
%%%      pattern as described above for the server side. When the last
%%%      block is encountered in read/1 or write/2 the returned stated
%%%      is forwarded to the user and returned from read_file/3 or
%%%      write_file/3.
%%%-------------------------------------------------------------------

-module(tftp).

%%-------------------------------------------------------------------
%% Interface
%%-------------------------------------------------------------------

%% Public functions
-export([
	 read_file/3,
	 write_file/3,
	 start/1,
	 info/1,
	 change_config/2,
	 start/0
	]).

%% Application local functions
-export([
	 start_standalone/1,
	 start_service/1,
	 stop_service/1, 
	 services/0,
	 service_info/1
	]).


-type peer() :: {PeerType :: inet | inet6,
		 PeerHost :: inet:ip_address(),
		 PeerPort :: port()}.

-type access() :: read | write.

-type options() :: [{Key :: string(), Value :: string()}].

-type error_code() :: undef | enoent | eacces | enospc |
		      badop | eexist | baduser | badopt |
		      integer().

-callback prepare(Peer :: peer(),
		  Access :: access(),
		  Filename :: file:name(),
		  Mode :: string(),
		  SuggestedOptions :: options(),
		  InitialState :: [] | [{root_dir, string()}]) ->
    {ok, AcceptedOptions :: options(), NewState :: term()} |
    {error, {Code :: error_code(), string()}}.

-callback open(Peer :: peer(),
	       Access :: access(),
	       Filename :: file:name(),
	       Mode :: string(),
	       SuggestedOptions :: options(),
	       State :: [] | [{root_dir, string()}] | term()) ->
    {ok, AcceptedOptions :: options(), NewState :: term()} |
    {error, {Code :: error_code(), string()}}.

-callback read(State :: term()) -> {more, binary(), NewState :: term()} |
				   {last, binary(), integer()} |
				   {error, {Code :: error_code(), string()}}.

-callback write(binary(), State :: term()) ->
    {more, NewState :: term()} |
    {last, FileSize :: integer()} |
    {error, {Code :: error_code(), string()}}.

-callback abort(Code :: error_code(), string(), State :: term()) -> 'ok'.

-include("tftp.hrl").


%%-------------------------------------------------------------------
%% read_file(RemoteFilename, LocalFilename, Options) ->
%%   {ok, LastCallbackState} | {error, Reason}
%%
%% RemoteFilename     = string()
%% LocalFilename      = binary | string()
%% Options            = [option()]
%% LastCallbackState  = term()
%% Reason             = term()
%%
%% Reads a (virtual) file from a TFTP server
%%
%% If LocalFilename is the atom 'binary', tftp_binary will be used as
%% callback module. It will concatenate all transferred blocks and
%% return them as one single binary in the CallbackState.
%%
%% When LocalFilename is a string, it will be matched to the
%% registered callback modules and hopefully one of them will be
%% selected. By default, tftp_file will be used as callback module. It
%% will write each transferred block to the file named
%% LocalFilename. The number of transferred bytes will be returned as
%% LastCallbackState.
%%-------------------------------------------------------------------

read_file(RemoteFilename, LocalFilename, Options) ->
    tftp_engine:client_start(read, RemoteFilename, LocalFilename, Options).
    
%%-------------------------------------------------------------------
%% write(RemoteFilename, LocalFilename, Options) ->
%%   {ok, LastCallbackState} | {error, Reason}
%%
%% RemoteFilename    = string()
%% LocalFilename     = binary() | string()
%% Options           = [option()]
%% LastCallbackState = term()
%% Reason            = term()
%%
%% Writes a (virtual) file to a TFTP server
%% 
%% If LocalFilename is a binary, tftp_binary will be used as callback
%% module. The binary will be transferred block by block and the number
%% of transferred bytes will be returned as LastCallbackState.
%%
%% When LocalFilename is a string, it will be matched to the
%% registered callback modules and hopefully one of them will be
%% selected. By default, tftp_file will be used as callback module. It
%% will read the file named LocalFilename block by block. The number
%% of transferred bytes will be returned as LastCallbackState.
%%-------------------------------------------------------------------

write_file(RemoteFilename, LocalFilename, Options) ->
    tftp_engine:client_start(write, RemoteFilename, LocalFilename, Options).

%%-------------------------------------------------------------------
%% start(Options) -> {ok, Pid} | {error, Reason}
%% 
%% Options = [option()]
%% Pid     = pid()
%% Reason  = term()
%%
%% Starts a daemon process which listens for udp packets on a
%% port. When it receives a request for read or write it spawns
%% a temporary server process which handles the actual transfer
%% of the (virtual) file.
%%-------------------------------------------------------------------

start(Options) ->
    tftp_engine:daemon_start(Options).

%%-------------------------------------------------------------------
%% info(Pid) -> {ok, Options} | {error, Reason}
%% 
%% Options = [option()]
%% Reason  = term()
%%
%% Returns info about a tftp daemon, server or client process
%%-------------------------------------------------------------------

info(Pid) ->
    tftp_engine:info(Pid).

%%-------------------------------------------------------------------
%% change_config(Pid, Options) -> ok | {error, Reason}
%% 
%% Options = [option()]
%% Reason  = term()
%%
%% Changes config for a tftp daemon, server or client process
%% Must be used with care.
%%-------------------------------------------------------------------

change_config(Pid, Options) ->
    tftp_engine:change_config(Pid, Options).

%%-------------------------------------------------------------------
%% start() -> ok | {error, Reason}
%% 
%% Reason = term()
%%
%% Start the application
%%-------------------------------------------------------------------

start() ->
    application:start(inets).

%%-------------------------------------------------------------------
%% Inets service behavior
%%-------------------------------------------------------------------

start_standalone(Options) ->
    start(Options).

start_service(Options) ->
    tftp_sup:start_child(Options).

stop_service(Pid) ->
    tftp_sup:stop_child(Pid).

services() ->
    tftp_sup:which_children().

service_info(Pid) ->
    info(Pid).