|
HS TFTP v1.2
Company License |
HS TFTP v1.2
Distribution License |
-
The Software is defined as
"HS TFTP v1.2" source code, binaries and documentation
-
The use of The Software is
royalty-free.
-
This license grants the
Company (Licensee)
the right to use,
modify, re-compile, re-release
The Software
-
This license grants the
Company (Licensee)
the right to make derivative works
based on The Software
-
The (re-)distribution or
the use of the Software outside the Company is prohibited
|
-
The Software is defined as
"HS TFTP v1.2" source code, binaries and documentation
-
The use of The Software is
royalty-free.
-
This license grants the
Company (Licensee)
the right to use,
modify, re-compile, re-release
The Software
-
This license grants the
Company (Licensee)
the right to make derivative works
based on The Software
-
This license grants the
Company (Licensee) the right to re-distribute The Software as
part of company products in any form and / or to use the
Software both within and outside the Company
|
Extract from
HS TFTP v1.2 User Manual
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:
|
parameter |
Description |
|
hs_tftp_get_buf_t *get_tx_buffer
hs_tftp_get_buf_t *get_rx_buffer |
Prototype
unsigned char *hs_tftp_get_buf_t(long handle, unsigned int
*length, int *cmd);
Parameters:
handle application (user) layer context handle
*length Length of memory block. HS TFTP will pass number of
bytes requested here. The user code sets the value to the actual
number of bytes granted. While most of the time number of
requested bytes equals number of given bytes, for example the
last block may be shorter due to end of file, so the given
length is less than requested.
*cmd
this is intended for exchange of additional information or
commands between user code and HS TFTP module currently not
used.
Return:
pointer to memory buffer in user code or NULL if no memory
available or nothing to give (end of transmission or end of
file)
Description:
These functions shall be called from HS TFTP module when it
needs to send next block of data (on reception of ACK from
remote peer) or when data has been successfully received and now
needs to be copied to user space from HS TFTP space.
|
|
hs_tftp_start_timer_t *start_timer_fn; |
Prototype:
long hs_tftp_start_timer_t(long handle, unsigned long secs);
Parameters:
handle TFTP module context handle
secs number of seconds to timeout after.
Return:
Timer handle. Currently the same as application (user) context
handle
Description:
This function in user code will be called from Hs TFTP code to
start a timer with a specified number of seconds.
|
|
hs_tftp_stop_timer_t *stop_timer_fn |
Prototype:
void hs_tftp_stop_timer_t(long handle);
Parameters:
Handle timer handle
Return:
No
return
Description:
This function will be used by HS TFTP module to stop (destroy) a
timer previously started with start_timer_fn.
|
Return values:
|
Value |
Description |
|
HS_TFTP_RC_OK |
Success |
|
HS_TFTP_RC_INIT |
HS TFTP already initialised |
|
HS_TFTP_RC_INVALID_PAR |
Invalid parameter |
|
HS_TFTP_SOCK_STARTUP_FAIL |
UDP layer initialisation failed |
|
HS_TFTP_RC_NO_MEM |
No free contexts |
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;
}
Declaration:
extern void HsTftpDestroy(void);
Summary:
De-allocates resources and closes HS TFTP services.
Parameters:
None
Return values:
None
Sample usage:
HsTftpDestroy();
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:
|
Value |
Description |
|
HS_TFTP_RC_OK |
Success |
|
HS_TFTP_RC_UDP_SOCK_OPEN |
UDP layer failed to open session on specified UDP port |
|
HS_TFTP_RC_INVALID_PAR |
Invalid parameter |
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");
}
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:
|
Value |
Description |
|
HS_TFTP_RC_OK |
Success |
|
HS_TFTP_RC_UDP_SOCK_OPEN |
UDP layer failed to open session |
|
HS_TFTP_RC_INVALID_PAR |
Invalid parameter |
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");
}
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:
|
Value |
Description |
|
HS_TFTP_RC_OK |
Success |
|
HS_TFTP_RC_UDP_SOCK_OPEN |
UDP layer failed to open session |
|
HS_TFTP_RC_INVALID_PAR |
Invalid parameter |
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");
}
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");
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:
|
Value |
Description |
|
HS_TFTP_RC_OK |
Success |
|
HS_TFTP_RC_UDP_SOCK_OPEN |
UDP layer failed to open session |
|
HS_TFTP_RC_INVALID_PAR |
Invalid parameter |
|
HS_TFTP_RC_NO_FREE_CTX |
HS TFTP module has no more free session contexts |
|
HS_TFTP_RC_UDP_SOCK_SEND |
UDP layer failed to send TFTP packet |
Sample usage:
rc =
HsTftpTransfer(TFTP_OP_SEND_FILE, dest_ip, &filename[i],
hs_tftp_ev_handler, TFTP_PORT, &pCtx->tftp_handle,
(long)pCtx);
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;
}
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:
|
Value |
Description |
|
HS_TFTP_RC_OK |
Success |
|
HS_TFTP_RC_NOT_INIT |
TFTP module not initialised |
|
HS_TFTP_RC_INVALID_PAR |
Invalid parameter |
Sample usage:
HsTftpAbort(pCtx->tftp_handle);
|