LXR 6.1/​cpukit/​include/​rtems/​tftp.h	Source navigation Diff markup Identifier search General search
	Version: 6.1 Revert   Change

File indexing completed on 2025-05-11 08:24:14

 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
  * @file
  *
  * @ingroup RTEMSImplTFTPFS
  *
  * @brief This header file provides interfaces and functions used to
  *   implement the TFTP file system.
  *
  * This file declares the public functions of the Trivial File
  * Transfer Protocol (TFTP) file system.
  */
 
 /*
  * Copyright (C) 1998 W. Eric Norum <eric@norum.ca>
  * Copyright (C) 2022 embedded brains GmbH & Co. KG
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  * 1. Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
  * 2. Redistributions in binary form must reproduce the above copyright
  *    notice, this list of conditions and the following disclaimer in the
  *    documentation and/or other materials provided with the distribution.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
 
 #ifndef _RTEMS_TFTP_H
 #define _RTEMS_TFTP_H
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 #include <stdint.h>
 #include <rtems/fs.h>
 
 /**
  * @brief Do not call directly, use mount().
  *
  * @ingroup RTEMSImplTFTPFS
  *
  * Filesystem Mount table entry.
  */
 int rtems_tftpfs_initialize(
   rtems_filesystem_mount_table_entry_t *mt_entry,
   const void *data
 );
 
 /**
  * @defgroup RTEMSAPITFTPFS Trivial File Transfer Protocol (TFTP) API
  *
  * @ingroup RTEMSAPIIO
  *
  * @brief The TFTP client library provides an API to read files from and
  *   to write files to remote servers using the Trivial File Transfer
  *   Protocol (TFTP).
  *
  * See the _RTEMS Filesystem Design Guide_ Chapter _Trivial FTP Client
  * Filesystem_.
  *
  * Usage as TFTP File System
  * =========================
  *
  * To open `/bootfiles/image` on `hostname` for reading:
  *
  *     fd = open ("/TFTP/hostname:bootfiles/image", O_RDONLY);
  *
  * The `TFTP` is the mount path and the `hostname` must be
  *
  * + an IPv4 address (like `127.0.0.1`) or
  * + the (full-qualified) name of an IPv4 host (acceptable to
  *  `gethostbyname()`)
  *
  * IPv6 is currently not supported. `bootfiles/image` is a path on the
  * TFTP server `hostname` where the file (here `image`) can be found.
  *
  * Usage of TFTP Client
  * ====================
  *
  * The pseudo-code below shows the principal usage for reading a file.
  *
  * @code
  *   int res;
  *   ssize_t bytes;
  *   void *tftp_handle;
  *   tftp_net_config config;
  *   const size_t buffer_size = 4000;
  *   char data_buffer[buffer_size];
  *
  *   tftp_initialize_net_config( &config );
  *   config.options.window_size = 1; // Set desired config values
  *
  *   res = tftp_open(
  *     "127.0.0.1",
  *     "filename.txt",
  *     true, // is_for_reading
  *     &config,
  *     &tftp_handle
  *   );
  *
  *   if ( res != 0 || tftp_handle == NULL ) {
  *     // Error
  *   }
  *
  *   // Use tftp_read() (probably in a loop) ...
  *   bytes = tftp_read(
  *     tftp_handle,
  *     data_buffer,
  *     buffer_size
  *   );
  *   // ... or use tftp_write() instead when the file is open for writing.
  *
  *   res = tftp_close( tftp_handle );
  *
  *   if ( res != 0 ) {
  *     // Error ... check! Especially when writing!
  *   }
  * @endcode
  *
  * @{
  */
 
 /*
  * The functions below use of the TFTP client library standalone
  * - i.e. without going through the file system.
  */
 
 /**
  * @brief This block size meets RFC 1350 and avoids the sending of
  *   the `blksize` option to the TFTP server.
  */
 #define TFTP_RFC1350_BLOCK_SIZE 512
 
 /**
  * @brief This window size avoids the sending of the `windowsize`
  *   option to the TFTP server.
  *
  * This effectively mimics the operation defined in RFC 1350 which
  * does not know any window size.
  */
 #define TFTP_RFC1350_WINDOW_SIZE 1
 
 /**
  * @brief This block size is suggested in RFC 2348 and is used as
  *   default if no different block size is provided.
  */
 #define TFTP_DEFAULT_BLOCK_SIZE 1456
 
 /**
  * @brief This window size is suggested in RFC 2348 and is used as
  *   default if no different window size is provided.
  */
 #define TFTP_DEFAULT_WINDOW_SIZE 8
 
 /**
  * @brief This structure represents TFTP options negotiated between
  *   client and server.
  *
  * RFC 2347 is the basis for the TFTP option.
  */
 typedef struct tftp_options {
   /**
    * @brief This member represents the desired size of a data block.
    *
    * The TFTP blocksize option is introduced in RFC 2348.  It defines the
    * number of octets in the data packets transferred.  Valid values
    * range between 8 and 65464 octets, inclusive.  Values larger
    * than 1468 may cause packet fragmentation over standard Ethernet.
    * A value of 512 will prevent this option from being sent to
    * the server.
    *
    * The default value is 1456.
    */
   uint16_t block_size;
 
   /**
    * @brief This member represents the desired size of a window.
    *
    * The TFTP windowsize option is introduced in RFC 7440.  It defines the
    * number of data packets send before the receiver must send an
    * acknowledgment packet.  Valid values range between 1 and 65535
    * packets, inclusive.  Simple TFTP servers usually do not support this
    * option.  This option may negatively contribute to network
    * congestion.  This can be avoided by using a window size of 1.
    * A value of 1 will prevent this option from being sent to
    * the server.
    *
    * The default value is 8.
    */
   uint16_t window_size;
 } tftp_options;
 
 /**
  * @brief This structure represents configuration value used by the TFTP
  *   client.
  *
  * As defaults the values suggested in RFC 7440 are used.
  */
 typedef struct tftp_net_config {
   /**
    * @brief This member defines how many attempts are made to send a
    *   network packet to the server.
    *
    * Repetitions occur when the server does not response to a packet
    * send by the client within a timeout period.  When the here defined
    * number of repetitions is reached and the server does still not
    * respond, the connection is considered broken and the file transfer
    * is ended with an error.
    *
    * The default value is 6.
    */
   uint16_t retransmissions;
 
   /**
    * @brief This member defines the port on which the server is listening
    *   for incoming connections.
    *
    * The default port number is 69.
    */
   uint16_t server_port;
 
   /**
    * @brief This member defines the maximum time in milliseconds the
    *   client waits for an answer packet from the server.
    *
    * If the time out is exceeded, the client will re-transmit the last
    * packet it send to the server.  In case @c window_size is larger one,
    * several packets may subject to re-transmission.
    *
    * Note that this timeout applies only after the first re-transmission
    * of a packet. The timeout till the first re-transmission is
    * @c first_timeout.
    *
    * The default value is 1000ms.
    */
   uint32_t timeout;
 
   /**
    * @brief This member defines the maximum time in milliseconds the
    *   client waits for the first answer packet from the server.
    *
    * The @c first_timeout is used instead of the regular @c timeout
    * for the first wait-period directly after the client sends a packet
    * for the first time to the server.  That is, this is the timeout
    * of the first re-transmission.  For any following re-transmissions
    * of the current packet the regular @c timeout is used.
    *
    * The default value is 400ms.
    */
   uint32_t first_timeout;
 
   /**
    * @brief This member represents the options to be sent to the server.
    *
    * These option values are sent to the server.  Yet, the server may
    *
    *   + ignore one or all options
    *   + ask the client to use a different value for an option
    *   + reject the whole request with an error
    *
    * If the server rejects a request with options, the current client
    * implementation will automatically send a second request without
    * options.  Hence, the user should be aware that the actual file
    * transfer may not use the option values specified here.
    */
   tftp_options options;
 } tftp_net_config;
 
 /**
  * @brief Set all members of a @c tftp_net_config structure to their
  *   default values.
  *
  * @param config references a @c tftp_net_config structure.
  *   The values are set to the defaults defined in
  *   @ref tftp_net_config "`type tftp_net_config`".
  */
 void tftp_initialize_net_config(
   tftp_net_config *config
 );
 
 /**
  * @brief Opens and starts a TFTP client session to read or write a
  *   single file.
  *
  * This directive resolves the hostname or IP address, establishes a connection
  * to the TFTP server and initiates the data transfer.  It will not return
  * before an error is encountered or the TFTP server has responded to the
  * read or write request with a network packet.
  *
  * TFTP uses timeouts (of unspecified length).  It does not know keep-alive
  * messages.  If the client does not respond to the server in due time,
  * the server sets the connection faulty and drops it.  To avoid this
  * the user of this code must read or write enough data fast enough.
  *
  * "Enough data" means at least so much data which fills a single data
  * packet or all packets of a window if windows are used.  The data
  * can be read or written in anything from one single large chunk to
  * byte-by-byte pieces.  The point is, one cannot pause the reading
  * or writing for longer periods of time.
  *
  * @param hostname is the IPv4 address as string or the name of the TFTP
  *   server to connect to.
  * @param path is the pathname at the TFTP server side of the file to
  *   read or write.  According to RFC 1350 the path must be in
  *   NETASCII.  This is ASCII as defined in "USA Standard Code for
  *   Information Interchange" with the modifications specified in "Telnet
  *   Protocol Specification".
  * @param is_for_reading indicated whether the file is to be read or written.
  *   A value of @c true indicates that the file is intended to be read from
  *   the server.  A value of @c false indicates that the file is to be
  *   written to the server.
  * @param config either references a structure defining the configuration
  *   values for this file transfer or is @c NULL.  If it is @c NULL, default
  *   configuration values are used.  See @ref tftp_net_config
  *   "type tftp_net_config" for a description and the defaults values.
  *   This function copies the data so that the memory pointed to by
  *   @c config can be used for other purposes after the call returns.
  * @param[out] tftp_handle references a place where a handle of the connection
  *   can be stored.  On success a pointer to a handle is stored.  On failure
  *   (return value other than 0) a @c NULL pointer is stored.  This handle
  *   must be provided to all further calls to @c tftp_read(),
  *   @c tftp_write(), and @c tftp_close().
  *
  *   When this directive stores a non-NULL pointer in this place, a call
  *   to @c tftp_close() is mandatory to release allocated resources.
  *   This parameter cannot be @c NULL.
  *
  * @retval 0 When the client session was opened successfully.
  * @return Returns a POSIX @c errno value in case an error occurred.
  */
 int tftp_open(
   const char  *hostname,
   const char  *path,
   bool   is_for_reading,
   const tftp_net_config *config,
   void **tftp_handle
 );
 
 /**
  * @brief Read data from a TFTP server.
  *
  * This directive attempts to read data from a TFTP connection open for
  * reading.
  *
  * Upon success, the buffer is always filled with @c count bytes of received
  * data with the exception when the end of the file has been reached.
  *
  * TFTP cannot recover from errors.  Once an error is reported, the
  * connection must be and can only be closed.
  *
  * @param tftp_handle is the reference returned by a call to tftp_open().
  *   The file must be opened for reading.
  * @param[out] buffer references a memory area into which the received
  *   data is written.
  * @param count defines the size of the @c buffer in bytes.
  *
  * @retval 0 The end of the file has been reached.  There is no more data.
  * @return If greater or equal to 0, returns the number of bytes written
  *   into the buffer.  If the return value is negative, an error occurred.
  *   In this case the negated value is a POSIX @c errno value.
  */
 ssize_t tftp_read(
   void   *tftp_handle,
   void   *buffer,
   size_t  count
 );
 
 /**
  * @brief Write data to a TFTP server.
  *
  * This directive attempts to write data to a TFTP connection open for
  * writing.
  *
  * On a successful call, all data in the @c buffer will be used.  Yet, this
  * does not imply that all data is actually sent.  This depends on
  * whether a whole data packet or window can be filled.
  *
  * TFTP cannot recover from errors.  Once an error is reported, the connection
  * must be and can only be closed.
  *
  * @param tftp_handle is the reference returned by a call to tftp_open().
  *   The file must be opened for writing.
  * @param buffer references a memory area which contains the data to be
  *   sent.
  * @param count defines the size of the data in @c buffer in bytes.
  *
  * @return If greater or equal to 0, returns the number of bytes used
  *   from the buffer.  The value is always @c count on a successful call.
  *   If the return value is negative, an error occurred.  In this case
  *   the negated value is a POSIX @c errno value.
  */
 ssize_t tftp_write(
   void       *tftp_handle,
   const void *buffer,
   size_t      count
 );
 
 /**
  * @brief Close a TFTP client connection.
  *
  * This directive sends all data which are still stored in a write buffer
  * to the server (if any), tells the server that the connection ends (if
  * required by RFC 1350) and releases any resources allocated at the
  * client side.
  *
  * @note Especially, when writing a file to the server, the return
  * code of `tftp_close()` should be checked.  Invoking
  * `tftp_close()` triggers the sending of the last -- not
  * completely filled -- data block.  This may fail the same way as any
  * `tftp_write()` may fail.  Therefore, an error returned by
  * `tftp_close()` likely indicates that the file was not
  * completely transferred.
  *
  * @param tftp_handle is the reference returned by a call to tftp_open().
  *   If this parameter is @c NULL, the directive call is a no-op.
  *
  * @retval 0 When the client session was closed successfully.
  * @return Returns a POSIX @c errno value in case an error occurred.
  */
 int tftp_close(
   void *tftp_handle
 );
 
 /** @} */
 
 #ifdef __cplusplus
 }
 #endif
 
 #endif

This page was automatically generated by the 2.3.7 LXR engine. The LXR team