Struct Tcp4Protocol

Source

#[repr(C)]pub struct Tcp4Protocol {
    pub get_mode_data: unsafe extern "efiapi" fn(this: *mut Self, connection_state: *mut Tcp4ConnectionState, config_data: *mut Tcp4ConfigData, ip4_mode_data: *mut Ip4ModeData, managed_network_config_data: *mut c_void, simple_network_mode: *mut NetworkMode) -> Status,
    pub configure: unsafe extern "efiapi" fn(this: *mut Self, config_data: *const Tcp4ConfigData) -> Status,
    pub routes: unsafe extern "efiapi" fn(this: *mut Self, delete_route: Boolean, subnet_address: *const Ipv4Address, subnet_mask: *const Ipv4Address, gateway_address: *const Ipv4Address) -> Status,
    pub connect: unsafe extern "efiapi" fn(this: *mut Self, token: *mut Tcp4ConnectionToken) -> Status,
    pub accept: unsafe extern "efiapi" fn(this: *mut Self, listen_token: *mut Tcp4ListenToken) -> Status,
    pub transmit: unsafe extern "efiapi" fn(this: *mut Self, token: *mut Tcp4IoToken) -> Status,
    pub receive: unsafe extern "efiapi" fn(this: *mut Self, token: *mut Tcp4IoToken) -> Status,
    pub close: unsafe extern "efiapi" fn(this: *mut Self, close_token: *mut Tcp4CloseToken) -> Status,
    pub cancel: unsafe extern "efiapi" fn(this: *mut Self, completion_token: *mut Tcp4CompletionToken) -> Status,
    pub poll: unsafe extern "efiapi" fn(this: *mut Self) -> Status,
}

Fields§

§

get_mode_data: unsafe extern "efiapi" fn(this: *mut Self, connection_state: *mut Tcp4ConnectionState, config_data: *mut Tcp4ConfigData, ip4_mode_data: *mut Ip4ModeData, managed_network_config_data: *mut c_void, simple_network_mode: *mut NetworkMode) -> Status

Get the current operational status.

get_mode_data copies the current operational settings of this instance into user-supplied structs. This function can also be used to retrieve the operational setting of underlying drivers such as IPv4, MNP, or SNP.

§configure: unsafe extern "efiapi" fn(this: *mut Self, config_data: *const Tcp4ConfigData) -> Status

Initialize or brutally reset the operational parameters for this instance.

No other Tcp4Protocol operation can be executed by this instance until it is configured properly. For an active Tcp4Protocol instance, after a proper configuration it may call Tcp4Protocol::connect to initiates the three-way handshake. For a passive Tcp4Protocol instance, its state will transition to Tcp4ConnectionState::LISTEN after configuration, and accept may be called to listen for incoming TCP connection requests. If config_data is set to NULL, the instance is reset. Resetting process will be done brutally; the state machine will be set to Tcp4ConnectionState::CLOSED directly, the receive queue and transmit queue will be flushed, and no traffic will be allowed through this instance.

§

routes: unsafe extern "efiapi" fn(this: *mut Self, delete_route: Boolean, subnet_address: *const Ipv4Address, subnet_mask: *const Ipv4Address, gateway_address: *const Ipv4Address) -> Status

Add or delete routing entries.

The most specific route is selected by comparing the subnet_address with the destination IP address arithmetically ANDed with the subnet_mask.

The default route is added with both subnet_address and subnet_mask set to 0.0.0.0. The default route matches all destination IP addresses if there is no more specific route.

A direct route is added with gateway_address set to 0.0.0.0. Packets are sent to the destination host if its address can be found in the Address Resolution Protocol (ARP) cache or it is on the local subnet. If the instance is configured to use default address, a direct route to the local network will be added automatically.

Each TCP instance has its own independent routing table. An instance that uses the default IP address will have a copy of the Ipv4Config2Protocol’s routing table. The copy will be updated automatically whenever the IP driver reconfigures its instance. As a result, the previous modification to the instance’s local copy will be lost.

The priority of checking the route table is specific to the IP implementation, and every IP implementation must comply with RFC 1122.

Note: There is no way to set up routes to other network interface cards (NICs) because each NIC has its own independent network stack that shares information only through EFI TCPv4 variable.

§connect: unsafe extern "efiapi" fn(this: *mut Self, token: *mut Tcp4ConnectionToken) -> Status

Initiate a nonblocking TCP connection request for an active TCP instance.

connect initiates an active open to the remote peer configured in the current TCP instance if it is configured as active. If the connection succeeds or fails due to any error, the token.completion_token.event will be signaled and token.completion_token.status will be updated accordingly. This function can only be called for the TCP instance in the Tcp4ConnectionState::CLOSED state. The instance will transition to Tcp4ConnectionState::SYN_SENT if the function returns Status::SUCCESS. If the TCP three-way handshake succeeds, its state will become Tcp4ConnectionState::ESTABLISHED, otherwise, the state will return to Tcp4ConnectionState::CLOSED.

§accept: unsafe extern "efiapi" fn(this: *mut Self, listen_token: *mut Tcp4ListenToken) -> Status

Listen on the passive instance to accept an incoming connection request. This is a nonblocking operation.

The accept function initiates an asynchronous accept request to wait for an incoming connection on the passive TCP instance. If a remote peer successfully establishes a connection with this instance, a new TCP instance will be created and its handle will be returned in new_child_handle. The newly created instance is configured by inheriting the passive instance’s configuration and is ready for use upon return. The instance is in the Tcp4ConnectionState::ESTABLISHED state.

The new_child_handle will be signaled when a new connection is accepted, the user aborts the listen, or the connection is reset.

This function can only be called when the current TCP instance is in Tcp4ConnectionState::LISTEN state.

§transmit: unsafe extern "efiapi" fn(this: *mut Self, token: *mut Tcp4IoToken) -> Status

Queues outgoing data into the transmit queue.

The transmit function queues a sending request to this instance along with the user data. The status of the token is updated and the event in the token will be signaled once the data is sent out or some error occurs.

§receive: unsafe extern "efiapi" fn(this: *mut Self, token: *mut Tcp4IoToken) -> Status

Places an asynchronous receive request into the receiving queue.

receive places a completion token into the receive packet queue. This function is always asynchronous. The caller must allocate the token.completion_token.event and the fragment_buffer used to receive data. They also must fill data_length which represents the whole length of all fragment_buffer. When the receive operation completes, the driver updates the token.completion_token.status and token.packet.rx_data fields and and the token.completion_token.event is signaled. If data was received, the data and its length will be copied into the fragment_table. At the same time, the full length of received data will be recorded in the data_length fields. Providing a proper notification function and context for the event will enable the user to receive the notification and receiving status. That notification function is guaranteed to not be re-entered.

§close: unsafe extern "efiapi" fn(this: *mut Self, close_token: *mut Tcp4CloseToken) -> Status

Disconnect a TCP connection gracefully or reset a TCP connection. This function is a nonblocking operation.

Initiate an asynchronous close token to TCP driver. After close is called, any buffered transmission data will be sent by TCP driver and the current instance will have a graceful close working flow described as RFC 793 if abort_on_close is set to false, otherwise, a reset packet will be sent by the TCP driver to quickly disconnect this connection. When the close operation completes successfully the TCP instance is in Tcp4ConnectionState::CLOSED state, all pending asynchronous operations are signaled, and any buffers used for TCP network traffic are flushed.

§cancel: unsafe extern "efiapi" fn(this: *mut Self, completion_token: *mut Tcp4CompletionToken) -> Status

Abort an asynchronous connection, listen, transmission or receive request.

The cancel function aborts a pending connection, listen, transmit or receive request. If completion_token is not NULL and the token is in the connection, listen, transmission or receive queue when it is being cancelled, its status will be set to Status::ABORTED and then event will be signaled. If the token is not in one of the queues, which usually means that the asynchronous operation has completed, Status::NOT_FOUND is returned. If completion_token is NULL, all asynchronous tokens issued by Tcp4Protocol::connect, Tcp4Protocol::accept, Tcp4Protocol::transmit and Tcp4Protocol::receive will be aborted.

§poll: unsafe extern "efiapi" fn(this: *mut Self) -> Status

Poll to receive incoming data and transmit outgoing segments.

The poll function increases the rate that data is moved between the network and application and can be called when the TCP instance is created successfully. Its use is optional.

In some implementations, the periodical timer in the MNP driver may not poll the underlying communications device fast enough to avoid dropping packets. Drivers and applications that are experiencing packet loss should try calling the poll function at a high frequency.