Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages   Examples  

TCP API functions

Detailed Description

These are the functions that applications need to use in order to communicate using TCP as well as to work with TCP sockets so as to achieve such a communication.

Functions

INT8 tcp_getsocket (UINT8, UINT8, UINT16, INT32(*)(INT8, UINT8, UINT32, UINT32))
 Allocate a free socket in TCP socket pool.

INT8 tcp_releasesocket (INT8)
 Release a TCP socket.

INT8 tcp_listen (UINT8, UINT16)
 Put TCP socket to listen on a given port.

INT8 tcp_connect (UINT8, UINT32, UINT16, UINT16)
 Initialize connection establishment towards remote IP&port.

INT16 tcp_send (INT8, UINT8 *, UINT16, UINT16)
 Send user data over TCP using given TCP socket.

INT8 tcp_close (UINT8)
 Initiate TCP connection closing procedure.

INT8 tcp_getstate (UINT8)
 Get current state of the socket.

INT16 tcp_checksend (UINT8)
 Checks if it's possible to send data using given socket.

INT8 tcp_abort (UINT8)
 Reset connection and place socket to closed state.

Function Documentation

INT8 tcp_getsocket (  UINT8    soctype,
UINT8    tos,
UINT16    tout,
INT32(*    listener)(INT8, UINT8, UINT32, UINT32)
) 
 

Author:
Date:
21.07.2002
Parameters:
soctype  type of socket wanted. Can take one of the following values:
tos  type of service for socket. For now only TCP_TOS_NORMAL.
tout  Timeout of socket in seconds. Defines after how many seconds of inactivity (application not sending and/or receiving any data over TCP connection) will the TCP socket automatically be closed.
listener  pointer to callback function that will be invoked by the TCP/IP stack to inform socket application of certain events. See tcpc_demo_eventlistener() and tcps_demo_eventlistener() for more information on events and possible actions.
Returns:
  • -1 - Error getting requested socket
  • >=0 - Handle to reserved socket
Invoke this function to try to obtain a free socket from TCP socket pool. Function returns a handle to the free socket that is later used for accessing the allocated socket (opening, connecting, sending data, closing, aborting, etc.).
Examples:
tcp_client_demo.c, and tcp_server_demo.c.

Definition at line 155 of file tcp.c.

References tcb::event_listener, tcb::flags, tcb::locport, tcb::rem_ip, tcb::remport, tcb::state, TCP_STATE_FREE, TCP_STATE_RESERVED, TCP_TYPE_CLIENT, TCP_TYPE_CLIENT_SERVER, TCP_TYPE_NONE, TCP_TYPE_SERVER, TIMERTIC, tcb::tos, tcb::tout, and tcb::type.

Referenced by https_init(), pop3c_init(), and smtpc_init().

INT8 tcp_releasesocket (  INT8    sochandle ) 
 

Author:
Date:
21.07.2002
Parameters:
sochandle  handle to socket to be released
Returns:
  • -1 - Error releasing the socket (Wrong socket handle or socket not in proper state to be released)
  • >=0 - handle of the released socket (can not be used any more untill allocated again with tcp_getsocket()).
Once the application does not need the TCP socket any more it can invoke this function in order to release it. This is usefull if there is a very limited number of sockets (in order to save some memory) shared among several applications.

Definition at line 228 of file tcp.c.

References tcb::event_listener, tcb::flags, tcb::locport, tcb::rem_ip, tcb::remport, tcb::state, TCP_STATE_CLOSED, TCP_STATE_FREE, TCP_STATE_RESERVED, TCP_TYPE_NONE, tcb::tos, and tcb::type.

INT8 tcp_listen (  UINT8    sochandle,
UINT16    port
) 
 

Author:
Date:
21.07.2002
Parameters:
sochandle  handle to socket to be placed to listen state
port  TCP port number on which it should listen
Returns:
  • -1 - Error
  • >=0 - OK (Socket put to listening state. Handle to socket returned)
This function will attempt to put socket to listening state. This is only possible if socket was defined as either TCP_TYPE_SERVER or TCP_TYPE_CLIENT_SERVER. If basic correctness checks pass, socket is put to listening mode and corresponding tcb entry is initialized.
Examples:
tcp_server_demo.c.

Definition at line 290 of file tcp.c.

References tcb::event_listener, tcb::flags, tcb::locport, tcb::myflags, tcb::receive_next, tcb::rem_ip, tcb::remport, tcb::retries_left, tcb::send_mtu, tcb::send_next, tcb::send_unacked, tcb::state, TCP_STATE_CLOSED, TCP_STATE_LISTENING, TCP_STATE_RESERVED, TCP_STATE_TIMED_WAIT, TCP_TYPE_SERVER, and tcb::type.

Referenced by https_init().

INT8 tcp_connect (  UINT8    sochandle,
UINT32    ip,
UINT16    rport,
UINT16    myport
) 
 

Author:
Date:
21.07.2002
Parameters:
sochandle  handle to socket to be used for connection establishment
ip  remote IP address to connect to
rport  remote port number to connect to
myport  local port to use for connection. This value can be specified directly or, if a value of 0 is given, TCP module will determine local TCP port automatically.
Returns:
  • -1 - Error
  • >=0 - OK (Connection establishment procedure started. Socket handle returned.)
Invoke this function to start connection establishment procedure towards remote host over some socket. This is only possible if socket was defined as either TCP_TYPE_CLIENT or TCP_TYPE_CLIENT_SERVER. Function will make some basic checks and if everything is OK, corresponding tcb socket entry will be initialized and connection procedure started.
Examples:
tcp_client_demo.c.

Definition at line 377 of file tcp.c.

References tcb::event_listener, tcb::flags, tcb::locport, tcb::myflags, tcb::rem_ip, tcb::remport, tcb::send_mtu, tcb::send_next, tcb::send_unacked, tcb::state, tcp_getfreeport(), tcp_initseq(), tcp_newstate(), tcp_sendcontrol(), TCP_STATE_CLOSED, TCP_STATE_LISTENING, TCP_STATE_RESERVED, TCP_STATE_SYN_SENT, TCP_TYPE_CLIENT, and tcb::type.

INT16 tcp_send (  INT8    sockethandle,
UINT8 *    buf,
UINT16    blen,
UINT16    dlen
) 
 

Author:
Date:
25.07.2002
Parameters:
sockethandle  handle to TCP socket to be used for sending data
buf  pointer to data buffer (start of user data)
blen  buffer length in bytes (without space reserved at the beginning of buffer for headers)
dlen  length of user data to be sent (in bytes)
Returns:
  • -1 - Error
  • >0 - OK (number represents number of bytes actually sent)
Warning:
  • buf parameter is a pointer to data to be sent in user buffer. But note that there MUST be sufficient free buffer space before that data for TCP header (of MIN_TCP_HLEN size).
Invoke this function to initiate data sending over TCP connection established over a TCP socket. Since data is not buffered (in order to reduce RAM memory consumption) new data can not be sent until data that was previously sent is acknowledged. So, application knows when it can send new data either by:
  • waiting for TCP_EVENT_ACK in event_listener function
  • invoking tcp_check_send() function to check if it is possible to send data
Examples:
tcp_client_demo.c, and tcp_server_demo.c.

Definition at line 481 of file tcp.c.

References tcb::myflags, process_tcp_out(), tcb::send_mtu, tcb::send_next, tcb::send_unacked, tcb::state, and TCP_STATE_CONNECTED.

INT8 tcp_close (  UINT8    sochandle ) 
 

Author:
Date:
21.07.2002
Parameters:
sochandle  handle to socket on which TCP connection is to be closed
Returns:
  • -2 - there is unacked data on this socket. Try again later.
  • -1 - Error
  • >=0 - OK (connection closing procedure started. Handle to socket returned)
Invoke this function to start connetion closing procedure over a given socket. Note that connection is not immediately closed. It may take some time for that to happen. Event_listener function will be invoked with appropriate event when that really happens.

Definition at line 549 of file tcp.c.

References tcb::flags, tcb::myflags, tcb::send_next, tcb::send_unacked, tcb::state, tcp_newstate(), tcp_sendcontrol(), TCP_STATE_CLOSED, TCP_STATE_CLOSING, TCP_STATE_CONNECTED, TCP_STATE_FINW1, TCP_STATE_FINW2, TCP_STATE_LAST_ACK, TCP_STATE_LISTENING, TCP_STATE_SYN_RECEIVED, TCP_STATE_SYN_SENT, and TCP_STATE_TIMED_WAIT.

INT8 tcp_getstate (  UINT8    sochandle ) 
 

Author:
Date:
21.07.2002
Parameters:
sochandle  handle to the socket to be queried
Returns:
  • -1 - Error
  • >0 - Socket state
Use this function for querying socket state. This is usually not needed directly, but could be usefull for some special purposes.

Definition at line 648 of file tcp.c.

References tcb::state.

INT16 tcp_checksend (  UINT8    sochandle ) 
 

Author:
Date:
23.07.2002
Parameters:
sochandle  handle to the socket to be inspected
Returns:
  • -1 - not possible to send over a socket (previously sent data is still not akcnowledged)
  • >0 - it is possible to send data over a socket
Invoke this function to get information whether it is possible to send data or not. This may, sometimes, be preffered way of getting this type of information to waiting for TCP_EVENT_ACK in event_listener function.
Examples:
tcp_client_demo.c, and tcp_server_demo.c.

Definition at line 690 of file tcp.c.

References tcb::send_mtu, tcb::send_next, tcb::send_unacked, tcb::state, and TCP_STATE_CONNECTED.

INT8 tcp_abort (  UINT8    sochandle ) 
 

Author:
Date:
21.07.2002
Parameters:
sochandle  handle to socket to be aborted
Returns:
  • -1 - error
  • >=0 - OK (value represents handle to aborted socket)
Use this function in cases when TCP connection must be immediately closed. Note that the preffered (more elegant) way of closing the TCP connection is to invoke tcp_close() which starts a proper closing procedure. tcp_abort should be used only in cases when it is really necessary to immediately and quickly close the connection.

Definition at line 736 of file tcp.c.

References tcb::myflags, tcb::state, tcp_newstate(), tcp_sendcontrol(), TCP_STATE_CLOSED, TCP_STATE_CLOSING, TCP_STATE_CONNECTED, TCP_STATE_FINW1, TCP_STATE_FINW2, TCP_STATE_FREE, TCP_STATE_LAST_ACK, TCP_STATE_LISTENING, TCP_STATE_RESERVED, TCP_STATE_SYN_RECEIVED, TCP_STATE_SYN_SENT, and TCP_STATE_TIMED_WAIT.

Generated on Sat Jan 25 17:13:16 2003 for OpenTCP by doxygen1.2.18