Subversion Repositories HomeAutomation

/*********************************************************************

 *

 *                  TFTP Client module for Microchip TCP/IP Stack

 *

 *********************************************************************

 * FileName:        TFTPc.h

 * Dependencies:    StackTsk.h

 * Processor:       PIC18

 * Complier:        MCC18 v1.00.50 or higher

 *                  HITECH PICC-18 V8.10PL1 or higher

 * Company:         Microchip Technology, Inc.

 *

 * Software License Agreement

 *

 * The software supplied herewith by Microchip Technology Incorporated

 * (the “Company”) for its PICmicro® Microcontroller is intended and

 * supplied to you, the Company’s customer, for use solely and

 * exclusively on Microchip PICmicro Microcontroller products. The

 * software is owned by the Company and/or its supplier, and is

 * protected under applicable copyright laws. All rights are reserved.

 * Any use in violation of the foregoing restrictions may subject the

 * user to criminal sanctions under applicable laws, as well as to

 * civil liability for the breach of the terms and conditions of this

 * license.

 *

 * THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES,

 * WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED

 * TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A

 * PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,

 * IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR

 * CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.

 *

 * Author               Date    Comment

 *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 * Nilesh Rajbharti     8/5/03  Original        (Rev 1.0)

 ********************************************************************/

#ifndef TFTPC_H

#define TFTPC_H

#include "..\Include\StackTsk.h"

#include "..\Include\UDP.h"

// Number of seconds to wait before declaring TIMEOUT error on Get.

#define TFTP_GET_TIMEOUT_VAL        (3 * TICKS_PER_SECOND)

// Number of seconds to wait before declaring TIMEOUT error on Put

#define TFTP_ARP_TIMEOUT_VAL        (3 * TICKS_PER_SECOND)

// Number of attempts before declaring TIMEOUT error.

#define TFTP_MAX_RETRIES            (3)

// Retry count must be 1 or more.

#if TFTP_MAX_RETRIES <= 0

#error Retry count must at least be 1

#endif

// Enum. of results returned by most of the TFTP functions.

typedef enum _TFTP_RESULT

{

    TFTP_OK = 0,

    TFTP_NOT_READY,

    TFTP_END_OF_FILE,

    TFTP_ERROR,

    TFTP_RETRY,

    TFTP_TIMEOUT

} TFTP_RESULT;

// File open mode as used by TFTPFileOpen().

typedef enum _TFTP_FILE_MODE

{

    TFTP_FILE_MODE_READ = 1,

    TFTP_FILE_MODE_WRITE = 2

} TFTP_FILE_MODE;

// Standard error codes as defined by TFTP spec.

// Use to decode value retuned by TFTPGetError().

typedef enum _TFTP_ACCESS_ERROR

{

    TFTP_ERROR_NOT_DEFINED = 0,

    TFTP_ERROR_FILE_NOT_FOUND,

    TFTP_ERROR_ACCESS_VIOLATION,

    TFTP_ERROR_DISK_FULL,

    TFTP_ERROR_INVALID_OPERATION,

    TFTP_ERROR_UNKNOWN_TID,

    TFTP_ERROR_FILE_EXISTS,

    TFTP_ERROR_NO_SUCH_USE

} TFTP_ACCESS_ERROR;

/*********************************************************************

 * Function:        void TFTPOpen(IP_ADDR *host)

 *

 * PreCondition:    UDP module is already initialized

 *                  and at least one UDP socket is available.

 *

 * Input:           host        - IP address of remote TFTP server

 *

 * Output:          None

 *

 * Side Effects:    None

 *

 * Overview:        Initiates ARP for given host and prepares

 *                  TFTP module for next sequence of function calls.

 *

 * Note:            Use TFTPIsOpened() to check if a connection was

 *                  successfully opened or not.

 *

 ********************************************************************/

void TFTPOpen(IP_ADDR *host);

/*********************************************************************

 * Function:        TFTP_RESULT TFTPIsOpened(void)

 *

 * PreCondition:    TFTPOpen() is already called.

 *

 * Input:           None

 *

 * Output:          TFTP_OK if previous call to TFTPOpen is complete

 *

 *                  TFTP_TIMEOUT if remote host did not respond to

 *                          previous ARP request.

 *

 *                  TFTP_NOT_READY if remote has still not responded

 *                          and timeout has not expired.

 *

 * Side Effects:    None

 *

 * Overview:        Waits for ARP reply and opens a UDP socket

 *                  to perform further TFTP operations.

 *

 * Note:            Once opened, application may keep TFTP socket

 *                  open and future TFTP operations.

 *                  If TFTPClose() is called to close the connection

 *                  TFTPOpen() must be called again before performing

 *                  any other TFTP operations.

 ********************************************************************/

TFTP_RESULT TFTPIsOpened(void);

/*********************************************************************

 * Macro:           void TFTPClose(void)

 *

 * PreCondition:    TFTPOpen is already called and TFTPIsOpened()

 *                  returned TFTP_OK.

 *

 * Input:           None

 *

 * Output:          None

 *

 * Side Effects:    None

 *

 * Overview:        Closes TFTP client socket.

 *

 * Note:            Once closed, application must do TFTPOpen to

 *                  perform any new TFTP operations.

 *

 *                  If TFTP server does not change during application

 *                  life-time, one may not need to call TFTPClose

 *                  and keep TFTP socket open.

 ********************************************************************/

#define TFTPClose(void)     UDPClose(_tftpSocket)

    extern UDP_SOCKET _tftpSocket;

/*********************************************************************

 * Macro:           BOOL TFTPIsFileOpenReady(void)

 *

 * PreCondition:    TFTPOpen is already called and TFTPIsOpened()

 *                  returned TFTP_OK.

 *

 * Input:           None

 *

 * Output:          TRUE, if it is ok to call TFTPOpenFile()

 *                  FALSE, if otherwise.

 *

 * Side Effects:    None

 *

 * Overview:        Checks to see if it is okay to send TFTP file

 *                  open request to remote server.

 *

 * Note:            None

 ********************************************************************/

#define TFTPIsFileOpenReady()       UDPIsPutReady(_tftpSocket)

/*********************************************************************

 * Function:        void TFTPOpenFile(char *fileName,

 *                                    TFTP_FILE_MODE mode)

 *

 * PreCondition:    TFPTIsFileOpenReady() = TRUE

 *

 * Input:           fileName        - File name that is to be opened.

 *                  mode            - Mode of file access

 *                                    Must be

 *                                      TFTP_FILE_MODE_READ for read

 *                                      TFTP_FILE_MODE_WRITE for write

 *

 * Output:          None

 *

 * Side Effects:    None

 *

 * Overview:        Prepares and sends TFTP file name and mode packet.

 *

 * Note:            By default, this funciton uses "octet" or binary

 *                  mode of file transfer.

 *                  Use TFTPIsFileOpened() to check if file is

 *                  ready to be read or written.

 ********************************************************************/

void TFTPOpenFile(char *fileName, TFTP_FILE_MODE mode);

/*********************************************************************

 * Function:        TFTP_RESULT TFTPIsFileOpened(void)

 *

 * PreCondition:    TFTPOpenFile() is called.

 *

 * Input:           None

 *

 * Output:          TFTP_OK if file is ready to be read or written

 *

 *                  TFTP_RETRY if previous attempt was timed out

 *                  needs to be retried.

 *

 *                  TFTP_TIMEOUT if all attempts were exhausted.

 *

 *                  TFTP_NOT_ERROR if remote server responded with

 *                  error

 *

 *                  TFTP_NOT_READY if file is not yet opened.

 *

 * Side Effects:    None

 *

 * Overview:        Waits for remote server response regarding

 *                  previous attempt to open file.

 *                  If no response is received within specified

 *                  timeout, fnction returns with TFTP_RETRY

 *                  and application logic must issue another

 *                  TFTPFileOpen().

 *

 * Note:            None

 ********************************************************************/

TFTP_RESULT TFTPIsFileOpened(void);

/*********************************************************************

 * Function:        void TFTPCloseFile(void)

 *

 * PreCondition:    TFTPOpenFile() was called and TFTPIsFileOpened()

 *                  had returned with TFTP_OK.

 *

 * Input:           None

 *

 * Output:          None

 *

 * Side Effects:    None

 *

 * Overview:        If file is opened in read mode, it makes sure

 *                  that last ACK is sent to server

 *                  If file is opened in write mode, it makes sure

 *                  that last block is sent out to server and

 *                  waits for server to respond with ACK.

 *

 * Note:            TFTPIsFileClosed() must be called to confirm

 *                  if file was really closed.

 ********************************************************************/

void TFTPCloseFile(void);

/*********************************************************************

 * Function:        TFTP_RESULT TFPTIsFileClosed(void)

 *

 * PreCondition:    TFTPCloseFile() is already called.

 *

 * Input:           None

 *

 * Output:          TFTP_OK if file was successfully closdd

 *

 *                  TFTP_RETRY if file mode was Write and remote

 *                  server did not receive last packet.

 *                  Application must retry with last block.

 *

 *                  TFTP_TIMEOUT if all attempts were exhausted

 *                  in closing file.

 *

 *                  TFTP_ERROR if remote server sent an error

 *                  in response to last block.

 *                  Actual error code may be read by calling

 *                  TFTPGetError()

 *

 *                  TFTP_NOT_READY if file is not closed yet.

 *

 * Side Effects:    None

 *

 * Overview:        If file mode is Read, it simply makes that

 *                  last block is acknowledged.

 *                  If file mode is Write, it waits for server ack.

 *                  If no ack was received within specified timeout

 *                  instructs appliaction to resend last block.

 *                  It keeps track of retries and declares timeout

 *                  all attempts were exhausted.

 *

 * Note:            None

 ********************************************************************/

TFTP_RESULT TFTPIsFileClosed(void);

/*********************************************************************

 * Function:        TFTP_RESULT TFTPIsGetReady(void)

 *

 * PreCondition:    TFTPOpenFile() is called with TFTP_FILE_MODE_READ

 *                  and TFTPIsFileOpened() returned with TRUE.

 *

 * Input:           None

 *

 * Output:          TFTP_OK if it there is more data byte available

 *                  to read

 *

 *                  TFTP_TIMEOUT if timeout occurred waiting for

 *                  new data.

 *

 *                  TFTP_END_OF_FILE if end of file has reached.

 *

 *                  TFTP_ERROR if remote server returned ERROR.

 *                      Actual error code may be read by calling

 *                      TFTPGetError()

 *

 *                  TFTP_NOT_READY if still waiting for new data.

 *

 * Side Effects:    None

 *

 * Overview:        Waits for data block.  If data block does not

 *                  arrive within specified timeout, it automatically

 *                  sends out ack for previous block to remind

 *                  server to send next data block.

 *                  If all attempts are exhausted, it returns with

 *                  TFTP_TIMEOUT.

 *

 * Note:            By default, this funciton uses "octet" or binary

 *                  mode of file transfer.

 ********************************************************************/

TFTP_RESULT TFTPIsGetReady(void);

/*********************************************************************

 * Function:        BYTE TFTPGet(void)

 *

 * PreCondition:    TFTPOpenFile() is called with TFTP_FILE_MODE_READ

 *                  and TFTPIsGetReady() = TRUE

 *

 * Input:           None

 *

 * Output:          data byte as received from remote server.

 *

 * Side Effects:    None

 *

 * Overview:        Fetches next data byte from TFTP socket.

 *                  If end of data block is reached, it issues

 *                  ack to server so that next data block can be

 *                  received.

 *

 * Note:            Use this function to read file from server.

 ********************************************************************/

BYTE TFTPGet(void);

/*********************************************************************

 * Function:        TFTP_RESULT TFTPIsPutReady(void)

 *

 * PreCondition:    TFTPOpenFile() is called with TFTP_FILE_MODE_WRITE

 *                  and TFTPIsFileOpened() returned with TRUE.

 *

 * Input:           None

 *

 * Output:          TFTP_OK if it is okay to write more data byte.

 *

 *                  TFTP_TIMEOUT if timeout occurred waiting for

 *                  ack from server

 *

 *                  TFTP_RETRY if all server did not send ack

 *                  on time and application needs to resend

 *                  last block.

 *

 *                  TFTP_ERROR if remote server returned ERROR.

 *                  Actual error code may be read by calling

 *                  TFTPGetError()

 *

 *                  TFTP_NOT_READY if still waiting...

 *

 * Side Effects:    None

 *

 * Overview:        Waits for ack from server.  If ack does not

 *                  arrive within specified timeout, it it instructs

 *                  application to retry last block by returning

 *                  TFTP_RETRY.

 *

 *                  If all attempts are exhausted, it returns with

 *                  TFTP_TIMEOUT.

 *

 * Note:            None

 ********************************************************************/

TFTP_RESULT TFTPIsPutReady(void);

/*********************************************************************

 * Function:        void TFTPPut(BYTE c)

 *

 * PreCondition:    TFTPOpenFile() is called with TFTP_FILE_MODE_WRITE

 *                  and TFTPIsPutReady() = TRUE

 *

 * Input:           c       - Data byte that is to be written

 *

 * Output:          None

 *

 * Side Effects:    None

 *

 * Overview:        Puts given data byte into TFTP socket.

 *                  If end of data block is reached, it

 *                  transmits entire block.

 *

 * Note:            Use this function to write file to server.

 ********************************************************************/

void TFTPPut(BYTE c);

/*********************************************************************

 * Macro:           WORD TFTPGetError(void)

 *

 * PreCondition:    One of the TFTP function returned with

 *                  TFTP_ERROR result.

 *

 * Input:           None

 *

 * Output:          Error code as returned by remote server.

 *                  Application may use TFTP_ACCESS_ERROR enum. to

 *                  decode standard error code.

 *

 * Side Effects:    None

 *

 * Overview:        Returns previously saved error code.

 *

 * Note:            None

 ********************************************************************/

#define TFTPGetError()      (_tftpError)

    extern WORD _tftpError;

#endif