PXENV_TFTP_OPEN
[PXE TFTP API]

TFTP OPEN. More...

Data Structures
struct	s_PXENV_TFTP_OPEN
	Parameter block for pxenv_tftp_open(). More...
Defines
#define	PXENV_TFTP_OPEN   0x0020
	PXE API function code for pxenv_tftp_open().
Typedefs
typedef struct s_PXENV_TFTP_OPEN	PXENV_TFTP_OPEN_t
Functions
PXENV_EXIT_t	pxenv_tftp_open (struct s_PXENV_TFTP_OPEN *tftp_open)
	TFTP OPEN.

---

Detailed Description

TFTP OPEN.

---

Define Documentation

#define PXENV_TFTP_OPEN   0x0020

PXE API function code for pxenv_tftp_open().

Definition at line 583 of file pxe_api.h.

Referenced by pxe_api_call().

---

Typedef Documentation

typedef struct s_PXENV_TFTP_OPEN PXENV_TFTP_OPEN_t

Definition at line 601 of file pxe_api.h.

---

Function Documentation

PXENV_EXIT_t pxenv_tftp_open

(

struct s_PXENV_TFTP_OPEN *

tftp_open

)

TFTP OPEN.

Parameters:

	tftp_open	Pointer to a struct s_PXENV_TFTP_OPEN
	s_PXENV_TFTP_OPEN::ServerIPAddress	TFTP server IP address
	s_PXENV_TFTP_OPEN::GatewayIPAddress	Relay agent IP address, or 0.0.0.0
	s_PXENV_TFTP_OPEN::FileName	Name of file to open
	s_PXENV_TFTP_OPEN::TFTPPort	TFTP server UDP port
	s_PXENV_TFTP_OPEN::PacketSize	TFTP blksize option to request

Return values:

	PXENV_EXIT_SUCCESS	File was opened
	PXENV_EXIT_FAILURE	File was not opened
	s_PXENV_TFTP_OPEN::Status	PXE status code
	s_PXENV_TFTP_OPEN::PacketSize	Negotiated blksize

Exceptions:

PXENV_STATUS_TFTP_INVALID_PACKET_SIZE

Requested blksize too small

Opens a TFTP connection for downloading a file a block at a time using pxenv_tftp_read().

If s_PXENV_TFTP_OPEN::GatewayIPAddress is 0.0.0.0, normal IP routing will take place. See the relevant implementation note for more details.

On x86, you must set the s_PXE::StatusCallout field to a nonzero value before calling this function in protected mode. You cannot call this function with a 32-bit stack segment. (See the relevant implementation note for more details.)

Note:

According to the PXE specification version 2.1, this call "opens a file for reading/writing", though how writing is to be achieved without the existence of an API call pxenv_tftp_write() is not made clear.

Despite the existence of the numerous statements within the PXE specification of the form "...if a TFTP/MTFTP or UDP connection is active...", you cannot use pxenv_tftp_open() and pxenv_tftp_read() to read a file via MTFTP; only via plain old TFTP. If you want to use MTFTP, use pxenv_tftp_read_file() instead. Astute readers will note that, since pxenv_tftp_read_file() is an atomic operation from the point of view of the PXE API, it is conceptually impossible to issue any other PXE API call "if an MTFTP connection is active".

Definition at line 244 of file pxe_tftp.c.

References pxe_tftp_connection::blksize, DBG, EINPROGRESS, s_PXENV_TFTP_OPEN::FileName, pxe_tftp_connection::max_offset, s_PXENV_TFTP_OPEN::PacketSize, pxe_tftp_close(), pxe_tftp_open(), PXENV_EXIT_FAILURE, PXENV_EXIT_SUCCESS, PXENV_STATUS, pxe_tftp_connection::rc, s_PXENV_TFTP_OPEN::ServerIPAddress, s_PXENV_TFTP_OPEN::Status, step(), s_PXENV_TFTP_OPEN::TFTPPort, pxe_tftp_connection::xfer, and xfer_window().

Referenced by pxe_api_call().

                                                                     {
        int rc;

        DBG ( "PXENV_TFTP_OPEN" );

        /* Guard against callers that fail to close before re-opening */
        pxe_tftp_close ( 0 );

        /* Open connection */
        if ( ( rc = pxe_tftp_open ( tftp_open->ServerIPAddress,
                                    tftp_open->TFTPPort,
                                    tftp_open->FileName,
                                    tftp_open->PacketSize,
                                    0) ) != 0 ) {
                tftp_open->Status = PXENV_STATUS ( rc );
                return PXENV_EXIT_FAILURE;
        }

        /* Wait for OACK to arrive so that we have the block size */
        while ( ( ( rc = pxe_tftp.rc ) == -EINPROGRESS ) &&
                ( pxe_tftp.max_offset == 0 ) ) {
                step();
        }
        pxe_tftp.blksize = xfer_window ( &pxe_tftp.xfer );
        tftp_open->PacketSize = pxe_tftp.blksize;
        DBG ( " blksize=%d", tftp_open->PacketSize );

        /* EINPROGRESS is normal; we don't wait for the whole transfer */
        if ( rc == -EINPROGRESS )
                rc = 0;

        tftp_open->Status = PXENV_STATUS ( rc );
        return ( rc ? PXENV_EXIT_FAILURE : PXENV_EXIT_SUCCESS );
}