TCP API Functions
The TCP API package includes the following main TCP API functions:
tcp_app_register()tcp_app_handle_destroy()tcp_api_next_avail_port_get()tcp_connection_with_source_open()tcp_connection_open_with_options()tcp_connection_open_with_options_core()tcp_appl_name_from_rem_port_get()tcp_data_send_with_options()tcp_data_send()tcp_receive_command_send()tcp_intf_hndl_copy()tcp_connection_close()tcp_connection_abort()tcp_conn_routing_instance_set()tcp_api_fatal_error()tcp_connection_local_addr_get()
The following section provides descriptions for each TCP API function.
tcp_app_register()
ApiT_Tcp_App_Handle tcp_app_register (Objid app_module_id)
- Abstract: Registers Application Layer with the API package in order to manage a single connection
- Argument: Object ID of the module containing the application process
- Return Value: Handle containing connection information needed on all subsequent calls to the API
tcp_app_handle_destroy()
void tcp_app_handle_destroy (ApiT_Tcp_App_Handle* tcp_hndl_ptr)
- Abstract: Unregister the Application Layer with the API package
- Argument: Handle returned from call to
tcp_app_register() - Return Value: None
tcp_api_next_avail_port_get()
int tcp_api_next_avail_port_get (ApiT_Tcp_App_Handle tcp_intf_hndl)
- Abstract: Returns the next available port on the TCP Interface for use by the calling application
- Argument: Handle returned from call to
tcp_app_register() - Return Value: The next available port number
tcp_connection_with_source_open()
int tcp_connection_with_source_open (ApiT_Tcp_App_Handle*, IpT_Address rem_addr,TcpT_Port rem_port, IpT_Address local_addr, TcpT_Port loc_port, int command, int ip_qos)
- Abstract: Open a TCP connection between the host and a remote host
- Arguments:
- Pointer to the handle returned from a call to
tcp_app_register() - IP address of the remote host (maybe ignored if command is
TCPC_COMMAND_OPEN_PASSIVE) - Port on the remote host
- IP address of the local host
- Port on the local host
- Command is either
TCPC_COMMAND_OPEN_PASSIVEorTCPC_COMMAND_OPEN_ACTIVE, depending on the desired connection type - QoS is value in the range 0–7 indicating desired setting as the precedence field in the IP datagram header
- Pointer to the handle returned from a call to
- Return Value: ID of the TCP connection
- Notes: If passive open, then upon receipt of
SYNpacket, an interrupt (with typeTCPC_IND_CONNECT_REQUEST) will be sent with ICItcp_open_ind - Warning: Deprecated. This will work only for IPv4.
tcp_connection_open_with_options()
int tcp_connection_open_with_options (ApiT_Tcp_App_Handle* tcp_hndl_ptr, InetT_Address rem_addr, TcpT_Port rem_port, int command, TcpT_Conn_Open_Options* options)
- Abstract: Open a TCP connection between the host and a remote host
- Arguments:
- Pointer to the handle returned from a call to
tcp_app_register() - IP address of the remote host (NOT ignored if command is
TCPC_COMMAND_OPEN_PASSIVE), Port on the remote host - command is either
TCPC_COMMAND_OPEN_PASSIVEorTCPC_COMMAND_OPEN_ACTIVE, depending on the desired connection type - Options as described in the Options Structure section
- Pointer to the handle returned from a call to
- Return Value: ID of the TCP connection
- Notes:
TCPC_IND_ESTABis sent when connection is established.TCPC_IND_ABORTEDis sent if an active open times out. If passive open, then upon receipt ofSYNpacket, an interrupt (with typeTCPC_IND_CONNECT_REQUEST) will be sent with ICItcp_open_indortcp_open_ind_inet
tcp_connection_open_with_options_core()
int tcp_connection_open_with_options_core (ApiT_Tcp_App_Handle* tcp_hndl_ptr, InetT_Address rem_addr, TcpT_Port rem_port, int command, TcpT_Conn_Open_Options* options, int routing_instance)
- Abstract: Open a TCP connection between the host and a remote host
- Arguments:
- Pointer to the handle returned from a call to
tcp_app_register() - IP address of the remote host (NOT ignored if command is
TCPC_COMMAND_OPEN_PASSIVE), Port on the remote host - command is either
TCPC_COMMAND_OPEN_PASSIVEorTCPC_COMMAND_OPEN_ACTIVE, depending on the desired connection type - Options as described in the Options Structure section
- routing_instance is used by BGP model only
- Pointer to the handle returned from a call to
- Return Value: ID of the TCP connection
- Notes:
TCPC_IND_ESTABis sent when connection is established.TCPC_IND_ABORTEDis sent if an active open times out. If passive open, then upon receipt ofSYNpacket, an interrupt (with typeTCPC_IND_CONNECT_REQUEST) will be sent with ICItcp_open_indortcp_open_ind_inet.
tcp_appl_name_from_rem_port_get()
void tcp_appl_name_from_rem_port_get (GnaT_App remote_port, char* appl_name)
- Abstract: Copies the application name (“Ftp”, “E-mail”, etc.) corresponding to the server port specified
- Arguments:
- Enumerated value indicating the application remote port
- Pointer to a destination buffer that will store the application name
- Note—This buffer must be large enough to hold the application string
- Return Value: None
tcp_data_send_with_options()
void tcp_data_send_with_options (ApiT_Tcp_App_Handle tcp_hndl, Packet* data_pkptr)
- Abstract: Send data packets over the connection once it is established
- Argument:
- Handle returned from call to
tcp_app_register() - Pointer to the packet the application wishes to send
- Options for the data block, logically ordered:
TCPC_OPT_NONE—same effect as tcp_data_send ()TCPC_OPT_FIN—send FIN (close) after the dataTCPC_OPT_URG—send data with the urgent flag
- Handle returned from call to
- Return Value: None
tcp_data_send()
void tcp_data_send (ApiT_Tcp_App_Handle tcp_hndl, Packet* data_pkptr)
- Abstract: Send data packets over the connection once it is established
- Arguments:
- Handle returned from call to
tcp_app_register() - Pointer to the packet the application wishes to send
- Handle returned from call to
- Return Value: None
tcp_receive_command_send()
void tcp_receive_command_send (ApiT_Tcp_App_Handle tcp_hndl, int receive_count)
- Abstract: Indicate to the TCP Interface that the application is prepared to receive one or more packets from the remote host
- Arguments:
- Handle returned from call to
tcp_app_register() - Maximum number of additional packets the application is willing to accept (i.e., in addition to the sum of all unfulfilled receive requests already issued)
- Handle returned from call to
- Return Value: None
tcp_intf_hndl_copy()
ApiT_Tcp_App_Handle tcp_intf_hndl_copy (ApiT_Tcp_App_Handle tcp_hndl)
- Abstract: Returns the original data handle passed as the parameter
tcp_hndl. This allows the application calling this function to copy the handle’s data values into a new variable - Arguments: Handle returned from call to
tcp_app_register() - Return Value: The same handle as the parameter
tcp_hndl
tcp_connection_close()
void tcp_connection_close (ApiT_Tcp_App_Handle tcp_hndl)
- Abstract: Close the connection after all data has been sent
- Arguments: Handle returned from call to
tcp_app_register() - Return Value: None
tcp_connection_abort()
void tcp_connection_abort (ApiT_Tcp_App_Handle tcp_hndl)
- Abstract: Terminate the connection early. This may be necessary due to the Application Layer requirements.
- Argument: Handle returned from call to
tcp_app_register() - Return Value: None
tcp_conn_routing_instance_set()
void tcp_conn_routing_instance_set (ApiT_Tcp_App_Handle tcp_hndl, int instance)
- Abstract: Sets the routing instance for TCP connection
- Argument:
- Handle returned from call to
tcp_app_register() - Integer instance number
- Handle returned from call to
- Return Value: None
tcp_api_fatal_error()
void tcp_api_fatal_error (const char* msg_str)
- Abstract: Copies the error message referenced by msg_str* to standard output and terminates the simulation
- Argument: Pointer to a string buffer containing the appropriate error message
- Return Value: None
tcp_connection_local_addr_get()
InetT_Address tcp_connection_local_addr_get (ApiT_Tcp_App_Handle* tcp_handle_ptr)
- Abstract: Determine the actual IP address used for connections
- Arguments: Handle returned from call to
tcp_app_register() - Return Value: A general IP address (either IPv4 or IPv6)
For more information in this section, see: