Trivial File Transfer Protocol (TFTP) Client (Alpha)#

The TFTP Client facilitates file exchange between a client and any remote host over UDP. This component provides an easy-to-use solution for downloading and uploading files from a remote host. The TFTP client can be initialized with sl_tftp_clnt_init(), and the functions sl_tftp_clnt_get() and sl_tftp_clnt_put() can be used to download and upload files, respectively. Additionally, the block size and timeout options can be configured to negotiate between the server and the client, optimizing the transmission. The component implements the TFTP protocol as specified in RFC 1350.

To ensure proper functionality, a TFTP server, such as tftpd-hpa, must be prepared on the remote host.

The following code example shows how to download a file with TFTP Client:

#include "sl_tftp_clnt.h"

// TFTP data callback
// In this callback you can implement storing data chunks to flash, heap or any other memory.
static void tftp_data_hnd(sl_tftp_clnt_t * const clnt,
                          const uint8_t * const data_ptr,
                          const uint16_t data_size) {
  (void)data_ptr;
  (void)data_size;
  printf("Data received chunk %u (%u bytes)\n",
         clnt->packet.content.data.block_num,
         clnt->packet.content.data.data_size);
}

// TFTP error callback
// You can implement error handling in this callback.
static void tftp_error_hnd(sl_tftp_clnt_t * const clnt,
                           const uint16_t error_code,
                           const char *error_msg) {
  (void)clnt;
  printf("Error (%u): %s\n", error_code, error_msg);
}

static void tftp_get_file(void) {
  static sl_tftp_clnt_t tftp_clnt = { 0 };

  // Initialize Client instance
  if (sl_tftp_clnt_init(&tftp_clnt,
                        "2001:db8::1",
                        SL_TFTP_DEFAULT_HOST_PORT,
                        tftp_data_hnd,
                        tftp_error_hnd) != SL_STATUS_OK) {
    // Error handling
    return;
  }

  // Set blocksize option
  if (sl_tftp_clnt_set_option(&tftp_clnt,
                              SL_TFTP_OPT_EXT_BLOCKSIZE,
                              1228) != SL_STATUS_OK) {
    // Error handling
    return;
  }

  // Start to download a file
  if (sl_tftp_clnt_get(&tftp_clnt,
                       "test.txt") != SL_STATUS_OK) {
    // Error handling
    return;
  }

  while (1) {
    if (sl_tftp_clnt_is_op_finished(&tftp_clnt)) {
      printf("File download finished\n");
      break;
    }
    osDelay(1);
  }
}

Modules#

Configurations

Type definitions

Portable interface

Typedefs#

typedef void(*
sl_tftp_clnt_data_hnd_t)(sl_tftp_clnt_t *const clnt, const uint8_t *const data_ptr, const uint16_t data_size)

Data handler callback definition.

typedef void(*
sl_tftp_clnt_error_hnd_t)(sl_tftp_clnt_t *const clnt, const uint16_t error_code, const char *error_msg)

Error handler callback defintion.

Functions#

__STATIC_INLINE sl_status_t
sl_tftp_clnt_default_init(sl_tftp_clnt_t *const clnt)

Init TFTP Client default.

__STATIC_INLINE sl_status_t
sl_tftp_clnt_get(sl_tftp_clnt_t *const clnt, const char *file)

TFT Client Get.

sl_status_t
sl_tftp_clnt_init(sl_tftp_clnt_t *const clnt, const char *host, const uint16_t port, sl_tftp_clnt_data_hnd_t data_hnd, sl_tftp_clnt_error_hnd_t error_hnd)

Init TFTP Client.

bool
sl_tftp_clnt_is_op_finished(const sl_tftp_clnt_t *const clnt)

TFTP Client is finished operation.

bool
sl_tftp_clnt_is_op_get(const sl_tftp_clnt_t *const clnt)

TFTP Client is Get operation.

bool
sl_tftp_clnt_is_op_put(const sl_tftp_clnt_t *const clnt)

TFTP Client is Put operation.

bool
sl_tftp_clnt_is_op_rrq_wrq_failed(const sl_tftp_clnt_t *const clnt)

TFTP Client is RRQ or WRQ failed.

void
sl_tftp_clnt_print_pkt(const sl_tftp_pkt_t *const pkt)

Print packet.

__STATIC_INLINE sl_status_t
sl_tftp_clnt_put(sl_tftp_clnt_t *const clnt, const char *file)

TFT Client Put.

sl_status_t
sl_tftp_clnt_request(sl_tftp_clnt_t *const clnt, const uint16_t opcode, const char *file, const char *mode)

TFTP Client request.

void
sl_tftp_clnt_service_init(void)

Init TFTP Client service.

sl_status_t
sl_tftp_clnt_set_option(sl_tftp_clnt_t *const clnt, const char *opt, const uint32_t value)

Set TFTP Client option.

sl_status_t
sl_tftp_clnt_terminate_session(sl_tftp_clnt_t *const clnt)

TFTP Client terminate session.

Macros#

#define
SL_TFTP_DEFAULT_DATA_BLOCK_SIZE 512U

TFTP Default data block size.

#define
SL_TFTP_DEFAULT_HOST_PORT 69U

Default TFTP host port.

#define
SL_TFTP_DEFAULT_SRV_RET_TIMEOUT_SEC 1U

TFTP Default server retransmit timeout interval in seconds.

#define
SL_TFTP_ERRORCODE_ACCVIOL 2U

Access violation.

#define
SL_TFTP_ERRORCODE_DISKFULL 3U

Disk full or allocation exceeded.

#define
SL_TFTP_ERRORCODE_FEXIST 6U

File already exists.

#define
SL_TFTP_ERRORCODE_FNOTFOUND 1U

File not found.

#define
SL_TFTP_ERRORCODE_ILLEGALOP 4U

Illegal TFTP operation.

#define
SL_TFTP_ERRORCODE_NOTDEF 0U

Not defined, see error message (if any).

#define
SL_TFTP_ERRORCODE_NOUSR 7U

No such user.

#define
SL_TFTP_ERRORCODE_OPTNEGOTFAIL 8U

Terminate transfer due to option negotiation.

#define
SL_TFTP_ERRORCODE_UNKNTID 5U

Unknown transfer ID.

#define
SL_TFTP_MODE_NETASCII_STR "netascii"

Netascii mode string.

#define
SL_TFTP_MODE_NETASCII_STR_LEN 8U

Netascii mode string length.

#define
SL_TFTP_MODE_OCTET_STR "octet"

Octet mode string.

#define
SL_TFTP_MODE_OCTET_STR_LEN 5U

Octet mode string length.

#define
SL_TFTP_OPCODE_ACK 4U

TFTP Acknowledgement operation code.

#define
SL_TFTP_OPCODE_DATA 3U

TFTP Data operation code.

#define
SL_TFTP_OPCODE_ERROR 5U

TFTP Error operation code.

#define
SL_TFTP_OPCODE_OACK 6U

TFTP Option Acknowledgement operation code.

#define
SL_TFTP_OPCODE_RRQ 1U

TFTP Read Request operation code.

#define
SL_TFTP_OPCODE_WRQ 2U

TFTP Write Request operation code.

#define
SL_TFTP_OPT_EXT_BLOCKSIZE "blksize"

TFTP Blocksize Option.

#define
SL_TFTP_OPT_EXT_BLOCKSIZE_LEN 7U

TFTP Blocksize Option length.

#define
SL_TFTP_OPT_EXT_MULTICAST "multicast"

TFTP Multicast Option.

#define
SL_TFTP_OPT_EXT_MULTICAST_LEN 9U

TFTP Multicast Option length.

#define
SL_TFTP_OPT_EXT_TIMEOUT_INTERVAL "timeout"

TFTP Timeout Interval Option.

#define
SL_TFTP_OPT_EXT_TIMEOUT_INTERVAL_LEN 7U

TFTP Timeout Interval Option length.

#define
SL_TFTP_OPT_EXT_TRANSFER_SIZE "tsize"

TFTP Transfer Size Option.

#define
SL_TFTP_OPT_EXT_TRANSFER_SIZE_LEN 5U

TFTP Transfer Size Option length.

#define
SL_TFTP_OPT_EXT_WINDOWSIZE "windowsize"

TFTP Windowsize Option.

#define
SL_TFTP_OPT_EXT_WINDOWSIZE_LEN 10U

TFTP Windowsize Option length.

#define
SL_TFTP_SERVICE_LOOP while (1)

TFTP Service loop definition.

#define
SL_TFTP_STR_MAX_LEN 256UL

TFTP string max length (filename, mode)

Typedef Documentation#

sl_tftp_clnt_data_hnd_t#

typedef void(* sl_tftp_clnt_data_hnd_t) (sl_tftp_clnt_t *const clnt, const uint8_t *const data_ptr, const uint16_t data_size) )(sl_tftp_clnt_t *const clnt, const uint8_t *const data_ptr, const uint16_t data_size)

Data handler callback definition.


sl_tftp_clnt_error_hnd_t#

typedef void(* sl_tftp_clnt_error_hnd_t) (sl_tftp_clnt_t *const clnt, const uint16_t error_code, const char *error_msg) )(sl_tftp_clnt_t *const clnt, const uint16_t error_code, const char *error_msg)

Error handler callback defintion.


Function Documentation#

sl_tftp_clnt_default_init#

__STATIC_INLINE sl_status_t sl_tftp_clnt_default_init (sl_tftp_clnt_t *const clnt)

Init TFTP Client default.

Parameters
TypeDirectionArgument NameDescription
sl_tftp_clnt_t *const[inout]clnt

Client to initialize

Initialize Client with default values from config file parameters: host: SL_TFTP_CLNT_DEFAULT_HOST port: SL_TFTP_DEFAULT_HOST_PORT data_hnd: simple hex dump callback error_hnd: error code and message printer Returns

  • sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL


sl_tftp_clnt_get#

__STATIC_INLINE sl_status_t sl_tftp_clnt_get (sl_tftp_clnt_t *const clnt, const char * file)

TFT Client Get.

Parameters
TypeDirectionArgument NameDescription
sl_tftp_clnt_t *const[inout]clnt

Client

const char *[in]file

File name

Get file from server in octet mode Returns

  • sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL


sl_tftp_clnt_init#

sl_status_t sl_tftp_clnt_init (sl_tftp_clnt_t *const clnt, const char * host, const uint16_t port, sl_tftp_clnt_data_hnd_t data_hnd, sl_tftp_clnt_error_hnd_t error_hnd)

Init TFTP Client.

Parameters
TypeDirectionArgument NameDescription
sl_tftp_clnt_t *const[inout]clnt

Client to initialize

const char *[in]host

Host address string

const uint16_t[in]port

Port number

sl_tftp_clnt_data_hnd_t[in]data_hnd

Data handler callback

sl_tftp_clnt_error_hnd_t[in]error_hnd

Error handler callback

Initialize TFTP Client context Returns

  • sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL


sl_tftp_clnt_is_op_finished#

bool sl_tftp_clnt_is_op_finished (const sl_tftp_clnt_t *const clnt)

TFTP Client is finished operation.

Parameters
TypeDirectionArgument NameDescription
const sl_tftp_clnt_t *const[in]clnt

Client

Check read or write operations wheither is in progress Returns

  • true Is finished

  • false Is in progress


sl_tftp_clnt_is_op_get#

bool sl_tftp_clnt_is_op_get (const sl_tftp_clnt_t *const clnt)

TFTP Client is Get operation.

Parameters
TypeDirectionArgument NameDescription
const sl_tftp_clnt_t *const[in]clnt

Client

Check Read operation is in progress Returns

  • true Is in progress otherwise false


sl_tftp_clnt_is_op_put#

bool sl_tftp_clnt_is_op_put (const sl_tftp_clnt_t *const clnt)

TFTP Client is Put operation.

Parameters
TypeDirectionArgument NameDescription
const sl_tftp_clnt_t *const[in]clnt

Client

Check Write operation is in progress Returns

  • true Is in progress otherwise false


sl_tftp_clnt_is_op_rrq_wrq_failed#

bool sl_tftp_clnt_is_op_rrq_wrq_failed (const sl_tftp_clnt_t *const clnt)

TFTP Client is RRQ or WRQ failed.

Parameters
TypeDirectionArgument NameDescription
const sl_tftp_clnt_t *const[in]clnt

Client

Check Read or Write Request operation is failed Returns

  • true Is failed otherwise false


sl_tftp_clnt_print_pkt#

void sl_tftp_clnt_print_pkt (const sl_tftp_pkt_t *const pkt)

Print packet.

Parameters
TypeDirectionArgument NameDescription
const sl_tftp_pkt_t *const[in]pkt

Packet to print

Print packet info in json format


sl_tftp_clnt_put#

__STATIC_INLINE sl_status_t sl_tftp_clnt_put (sl_tftp_clnt_t *const clnt, const char * file)

TFT Client Put.

Parameters
TypeDirectionArgument NameDescription
sl_tftp_clnt_t *const[inout]clnt

Client

const char *[in]file

File name to store data

Send buffer content to file on remote server Returns

  • sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL


sl_tftp_clnt_request#

sl_status_t sl_tftp_clnt_request (sl_tftp_clnt_t *const clnt, const uint16_t opcode, const char * file, const char * mode)

TFTP Client request.

Parameters
TypeDirectionArgument NameDescription
sl_tftp_clnt_t *const[inout]clnt

Client

const uint16_t[in]opcode

Operation code: SL_TFTP_OPCODE_RRQ or SL_TFTP_OPCODE_WRQ

const char *[in]file

File name to put or get

const char *[in]mode

Mode string

Send request for Server (RRQ or WRQ) Returns

  • sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL


sl_tftp_clnt_service_init#

void sl_tftp_clnt_service_init (void )

Init TFTP Client service.

Parameters
TypeDirectionArgument NameDescription
voidN/A

Initialize TFTP client OS objects


sl_tftp_clnt_set_option#

sl_status_t sl_tftp_clnt_set_option (sl_tftp_clnt_t *const clnt, const char * opt, const uint32_t value)

Set TFTP Client option.

Parameters
TypeDirectionArgument NameDescription
sl_tftp_clnt_t *const[inout]clnt

Client

const char *[in]opt

Option string

const uint32_t[in]value

Option value

Set TFTP Client option in the TFTP client instance. The supported options are:

  • SL_TFTP_OPT_EXT_BLOCKSIZE: Blocksize option (8 - 1228 for Wi-SUN)

  • SL_TFTP_OPT_EXT_TIMEOUT_INTERVAL: Timeout interval option (1 - 255) Returns

    • sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL


sl_tftp_clnt_terminate_session#

sl_status_t sl_tftp_clnt_terminate_session (sl_tftp_clnt_t *const clnt)

TFTP Client terminate session.

Parameters
TypeDirectionArgument NameDescription
sl_tftp_clnt_t *const[inout]clnt

Client

Terminate TFTP session Returns

  • sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL