HS TFTP 1.2 C Source Library

 ORDER NOW

 Contacts Us

Features

TFTP server and client

Defaults to 100 concurrent sessions

512 packet size

TFTP File upload

TFTP File download

customization

Hillstone Software provides additional services for customization, porting and integration of the library code to better suit the needs of your products

Release History

04 Oct 2007, Version 1.2
- base tested full release

01 Dec 2007, Version 1.2.1
- memory leak fix for packet buffers

02 Nov 2007, Version 1.2.3
- support for transfer of files between directories on same PC
- fix for Last ack not sent if size multiple of 512

22 Nov 2007, Version 1.2.4
- Fix memory leak in list library
- Added console demo application

03 Dev 2007, Version 1.2.5
- Fix memory corruption, prevent socket from closing twice

05 Jul 2008, Version 1.2.6
- fixed handle leak in socket layer when closing and de-initialising the library

overview

HS TFTP is a software library in C (supplied with full source code) which implements Trivial File Transfer Protocol (TFTP) over UDP socket layer according to RFC 1350. Support for client and server side for both file get and put are provided. Up to 100 concurrent sessions are supported.

HS TFTP is supplied in a form of full ANSI C source code and binaries and would require no or minimal integration effort by the customer, assisted by Hillstone Software after sales support.

The use of HS TFTP software library is royalty free. Here are The Terms of License

MODEL OF OPERATION

When user application initlialises Hs TFTP library, it provides interface callbacks for the services used by HS TFTP protocol module: timer management, memory management and event callbacks. This architecture makes it easy to port HS TFTP protocol module to any environment. HS TFTP internally at a lower layer interfaces to HS Sock library which provides UDP transport services. User application need not worry about Winsock - HS TFTP does all transmission, reception and event handling over socket layer.

TFTP module handles all protocol information flow, error recovery, acknowledgements, timeouts and so on. When it is appropriate to send next block of data HS TFTP will get next memory block from user application. Similarly, when data has been received HS TFTP module will get the next block of memory from user application to store data into

Along with XMODEM or as an alternative, TFTP is often used in embedded devices and appliances for the purpose of software or configuration upgrade or retrieval.

hs tftp library architecture

The library is a stand-alone module which links directly to customer application:
 

SOFTWARE LICENSE TERMS

Extract from HS TFTP v1.2 User Manual

1.1      HsTftpInit

Declaration:

extern int HsTftpInit(tftp_init_t *init);

Summary:
This function initialises HS TFTP Library and must be called first before any other functions are called. Init structure contains function pointers which must be initialised with function addresses in application layer. HS TFTP module will call these functions when it needs to manage timers and memory. 

Parameters:
hs_tftp_init_t *init - Pointer to initialisation structure, defined as follows: 

 Return values:

 Sample usage:

 /*
 * initiase TFTP library
 */

int init_tftp_library(void)
{
          tftp_init_t init = {0};
          int      rc; 

          init.get_tx_buffer      = tftp_get_buf_tx_cb;
          init.get_rx_buffer      = tftp_get_buf_rx_cb;
          init.start_timer_fn     = tftp_start_timer_cb;
          init.stop_timer_fn      = hs_tftp_stop_timer_cb;         

          rc = HsTftpInit(&init);

          if (rc == HS_TFTP_RC_OK)
                    tftp_initialised = 1; 

          return rc;
}

1.2       HsTftpDestroy

Declaration:
extern void HsTftpDestroy(void);

Summary:
De-allocates resources and closes HS TFTP services.

Parameters:
None

Return values:
None

Sample usage:

HsTftpDestroy();

1.3      HsTftpStartServer

Declaration:
extern int HsTftpStartServer(
          hs_tftp_srv_ev_fn_t *callback_fn,            // event callback (used for server mode)
          unsigned short         tftp_port                 // initial TFTP port of server
);

Summary:
Starts server operation of HS TFTP module.

Parameters:
unsigned short tftp_port – UDP port number the HS TFTP module listens for incoming TFTP client commands, recommended default value is 69.

hs_tftp_srv_ev_fn_t *callback_fn – function pointer to callback function in application layer which receives events related to the status of the server operations:

typedef long hs_tftp_srv_ev_fn_t(long handle, int ev_code, long arg1, long arg2);
handle – currently unused
ev_code – one of the following values:

HS_TFTP_EV_WRITE_REQ – write request received from remote TFTP client (client wants to send file)
Arg1 – pointer to null terminated filename string
Arg2 – 32 bit remote IP address (address of TFTP client sending this request)

HS_TFTP_EV_READ_REQ - read request received from remote TFTP client (client wants to get file)
Arg1 – pointer to null terminated filename string
Arg2 – 32 bit remote IP address (address of TFTP client sending this request)

Return values: 

Sample usage:

/*
* Event calback from TFTP library (server mode)
*/

long hs_tftp_ev_server_handler(long handle, int ev_code, long arg1, long arg2)
{
            unsigned char *file;

            if (!tftp_initialised)
                        return 0;

             if (!handle)
                       return 0; 

            switch (ev_code)
            {
            case HS_TFTP_EV_WRITE_REQ:
                        file = (unsigned char *)arg1;
                        process_file_write_request(file, arg2);
                        break; 

            case HS_TFTP_EV_READ_REQ:
                        file = (unsigned char *)arg1;
                        process_file_read_request(file, arg2);
                        break;
            }
            return 0;
}

 /* Start server mode */
void StartServer(void)
{
            int rc; 

            if (!tftp_initialised)
            {
                        rc = init_tftp_library();
                        if (rc != HS_TFTP_RC_OK)
                        {
                                    printf("HsTFTP init failed. Error %d\n", rc);      
                                    return;
                        }
            }           

            if (!server_started)
            {
                        rc = HsTftpStartServer(hs_tftp_ev_server_handler, TFTP_PORT);
                        if (rc != HS_TFTP_RC_OK)
                        {                     
                                    printf("Server failed to start. HS TFTP Error: %d\n", rc);
                                    return;
                        }
                        server_started = TRUE;
            }
            else
            {
                        printf("Server mode already running\n");
                        return;
            } 

            printf("Server mode started OK\n");
}

1.4      HsTftpServerStartReceive

Declaration:

extern
int HsTftpServerStartReceive(       
          hs_tftp_ev_fn_t       *callback_fn,  // event callback (used for indication of completion or error)
          long                       *handle,        // Connection handle returned after transfer initiated
          long                       user_handle); // upper layer context handle

Summary:
Start receiving requested file from remote peer (in Server mode). This function is called in response to HS_TFTP_EV_WRITE_REQ event, which occurs when a write request for a file is received from remote TFTP client

Parameters:
hs_tftp_ev_fn_t *callback_fn – function pointer to a callback function in application (user) layer code which receives notifications related to this transfer session.

typedef long hs_tftp_ev_fn_t(long handle, int ev_code, long arg1, long arg2);
handle – application layer handle
ev_code – event, one of the following:

HS_TFTP_EV_ERR_TMOUT – session timed out and closed
HS_TFTP_RX_COMPLETE – receive transfer completed successfully

Arg1 and arg2 are currently unused
long *handle – pointer to long variable to received TFTP module connection handle after file transfer is initiated.
long user_handle – application layer context handle. This handle is saved into corresponding TFTP session context and is returned unchanged as a parameter in various notification callbacks from HS TFTP to application layer code.

Return values:

 Sample usage:

/* server mode - process file write request */
void process_file_write_request(unsigned char *filename,  long arg2)
{
          int                         rc;
          unsigned char          ipstr[20] = {0};

          server_conn_ctx_t *pCtx;         

          HsSockInetNtoa(arg2, ipstr);

          printf("file write request from (%s) %s\n", ipstr, filename);

          pCtx = tftp_alloc_srvconn_ctx();
          if (!pCtx)
          {
                   printf("rejected: no free contexts\n");
                   HsTftpRejectRq(HS_TFTP_EV_WRITE_REQ,
                                  HS_TFTP_SERVER_ERR_USER, "no free contexts");
                   return;
          } 

          pCtx->hFile = CreateFile(filename,            // file to open
                   GENERIC_WRITE,                          // open for writing
                   0,                                                        // no sharing
                   NULL,                                         // default security
                   OPEN_ALWAYS,                            // overwrite existing file
                   FILE_ATTRIBUTE_NORMAL,             // normal file
                   NULL);  

          if (pCtx->hFile == INVALID_HANDLE_VALUE)
                   pCtx->hFile = NULL; 

          if (!pCtx->hFile)
          {
                   printf("rejected: file open error\n"); 
                   tftp_free_srvconn_ctx(pCtx);                  

                   /* Reject request */
                   HsTftpRejectRq(HS_TFTP_EV_WRITE_REQ, HS_TFTP_SERVER_ERR_FIO, NULL);
                   return;
          } 

          pCtx->is_server_session = TRUE;
          pCtx->is_send = FALSE; 

          tftp_add_srvconn(pCtx);         

          rc = HsTftpServerStartReceive(hs_tftp_server_ev_handler, &pCtx->tftp_handle, (long)pCtx);
          if (rc != HS_TFTP_RC_OK)
          {
                   printf("Server Start Receive failed RC (%u)\n", rc);
                   hs_tftp_cleanup_ctx(pCtx);
                   return;
          } 

          printf("Server receive transfer started\n");
}

1.5      HsTftpServerStartSend

Declaration:

extern int HsTftpServerStartSend(
          hs_tftp_ev_fn_t       *callback_fn,  // event callback (used for infication of completion or error)
          long                       *handle,        // Connection handle returned after transfer initiated
          long                       user_handle); // upper layer context handle 

Summary:
Start sending requested file to remote peer (in Server mode). This function is called in response to HS_TFTP_EV_READ_REQ event, which occurs when a read request for a file is received from remote TFTP client 

Parameters:
hs_tftp_ev_fn_t *callback_fn – function pointer to a callback function in application (user) layer code which receives notifications related to this transfer session. 

typedef long hs_tftp_ev_fn_t(long handle, int ev_code, long arg1, long arg2);
handle – application layer handle
ev_code – event, one of the following:
HS_TFTP_EV_ERR_TMOUT – session timed out and closed
HS_TFTP_RX_COMPLETE – receive transfer completed successfully
Arg1 and arg2 are currently unused

long *handle – pointer to long variable to received TFTP module connection handle after file transfer is initiated.
long user_handle – application layer context handle. This handle is saved into corresponding TFTP session context and is returned unchanged as a parameter in various notification callbacks from HS TFTP to application layer code. 

Return values:

Sample usage:

 /* server mode - process file read request */
void process_file_read_request(unsigned char *filename, long arg2)
{
          int rc;
          long fsize = 0;
          unsigned char ipstr[20] = {0};
          server_conn_ctx_t *pCtx;

          HsSockInetNtoa(arg2, ipstr);

          printf("file read request from (%s) %s\n", ipstr, filename);

          pCtx = tftp_alloc_srvconn_ctx();

          if (!pCtx)

          {
                   printf("rejected: no free contexts\n");
                   HsTftpRejectRq(HS_TFTP_EV_READ_REQ, HS_TFTP_SERVER_ERR_USER, "no free contexts");
                   return;
          }         

          pCtx->hFile = CreateFile(filename, GENERIC_READ, FILE_SHARE_READ, NULL,
                                                          OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);

          if (pCtx->hFile == INVALID_HANDLE_VALUE)
                   pCtx->hFile = NULL; 

          fsize = (long)GetCompressedFileSize(filename, NULL);
          if ((!pCtx->hFile) || (!fsize))
          {
                   printf("rejected: file open error\n");
                   HsTftpRejectRq(HS_TFTP_EV_READ_REQ, HS_TFTP_SERVER_ERR_FNOTFOUND, NULL);

                   hs_tftp_cleanup_ctx(pCtx);
                   return;
          }

          pCtx->fblock = pCtx->rxbuf;
          pCtx->is_server_session = TRUE;
          pCtx->is_send = TRUE; 

          tftp_add_srvconn(pCtx);

          rc = HsTftpServerStartSend(hs_tftp_server_ev_handler, &pCtx->tftp_handle, (long)pCtx);
          if (rc != HS_TFTP_RC_OK)
          {
                   printf("Server Start Send failed RC (%u)\n", rc);
                   hs_tftp_cleanup_ctx(pCtx);
                   return;
          }

           pCtx->total_blocks = fsize / TFTP_BLK_SIZE;

           printf("Server send transfer started\n");
}

1.6      HsTftpRejectRq

Declaration:
extern void HsTftpRejectRq(int rq, int reason, unsigned char *str);

Summary:
Sends TFTP ERROR packet (in server mode) to remote TFTP client with specified reason code and descriptive ASCII string. This function may be called in response to HS_TFTP_EV_WRITE_REQ and HS_TFTP_EV_READ_REQ events.

Parameters:
rq – currently unused
reason – reason code, one of the following:
HS_TFTP_SERVER_ERR_FIO - FILE I/o error
HS_TFTP_SERVER_ERR_FNOTFOUND - file not found
HS_TFTP_SERVER_ERR_USER - user defined error, send supplied error string

Str – pointer to zero terminated ASCII string to send with the ERROR packet, only valid if reason is HS_TFTP_SERVER_ERR_USER. 

Return values:
None 

Sample usage:
HsTftpRejectRq(HS_TFTP_EV_WRITE_REQ, HS_TFTP_SERVER_ERR_USER, "no free contexts");

1.7      HsTftpTransfer

Declaration:

extern int HsTftpTransfer(

int                  operation,             // packet type
          unsigned long  dest_ip,                 // remote end IP address
          unsigned char *filename,               // filename (0 terminated)
          hs_tftp_ev_fn_t *callback_fn,        // event callback (used for indication of completion or error)
          unsigned short tftp_port,               // initial TFTP port of server
          long              *handle,                 // Connection handle returned after transfer initiated
          long              user_handle);           // upper layer context 

Summary:
This function is used to initiate client mode Send or Receive file transfer.

Parameters:
operation – type of transfer to start:
TFTP_OP_SEND_FILE – start sending file to remote TFTP server
TFTP_OP_GET_FILE – start receiving file from remote TFTP server 

dest_ip – 32 bit remote TFTP server IP address
filename – name of file to send or receive (pointer to zero terminated ASCII string)
callback_fn – pointer to event callback used for indication of completion or errors.

Callback function prototype:
typedef long hs_tftp_ev_fn_t(long handle, int ev_code, long arg1, long arg2);
handle – user application layer context
ev_code – event, one of the following:
HS_TFTP_EV_ERR_TMOUT – TFTP transfer timed out, session closed
HS_TFTP_RX_COMPLETE – receive transfer complete
HS_TFTP_EV_ERR_RXED – remote TFTP server send aborted transfer, arg2 – pointer to zero terminated error string from received TFTP ERROR packet

tftp_port – TFTP port at remote server to send the request to (normally 69)
*handle – pointer to long variable to receive TFTP session handle after the function returns
user_handle – application layer context handle to be stored by HS TFTP module in this session context.

Return values:

 Sample usage:

             rc = HsTftpTransfer(TFTP_OP_SEND_FILE, dest_ip, &filename[i],
                  hs_tftp_ev_handler, TFTP_PORT, &pCtx->tftp_handle, (long)pCtx);

1.8      HsTftpTimerExpired

Declaration:
extern void HsTftpTimerExpired(long timer_handle);

Summary:
Function called from user code when timer previously started by HS TFTP has expired

Parameters:
timer_handle - timer handle

Return values:
None

Sample usage:

/*
 * windows timer callback
 */

TIMERPROC TimerProc(HWND hwnd,  UINT uMsg, UINT_PTR idEvent,  DWORD dwTime)
{
            KillTimer(hwnd, idEvent); 

            HsTftpTimerExpired((long)idEvent);

            return 0;
} 

1.9      HsTftpAbort

Declaration:
extern int HsTftpAbort(long handle);

Summary:
Abort current operation and cleanly disconnect remote end based on passed connection handle. This function is going to send TFTP ERROR packet to remote end with the string “Aborted by user” and cleanup local TFTP session context. 

Parameters:
handle – TFTP module session handle 

Return values:

Sample usage:

HsTftpAbort(pCtx->tftp_handle);