fnGetTCP_Socket()

USOCKET fnGetTCP_Socket(unsigned char ucTos, unsigned short usIdleTimeout, int (*listener)(USOCKET, unsigned char, unsigned char *, unsigned short));

ucTos is the type of service (TOS) required by the socket with values of:
These values are self-explanatory and are set as TOS option to the TCP frames sent by the socket. Nowadays the values used are not generally of importance.

usIdleTimeout is the idle time of the TCP connection in seconds. When a connection is open and there is not TCP traffic for this amount of time the connection will be closed. A value of 0xfffe is the maximum value (18.2 hours). The value 0 is not allowed and the value 0xffff (or define INFINITE_TIMEOUT) is used for infinite timeout (meaning it never times out). It is generally recommended to use a realistic value since a connection left open due to the peer being turned off otherwise results in the socket being blocked for further use until the idle timeout kicks in or the missing peer is recognised due to a transmission failing.

listener is the call back function used on events for this socket and an example of a listener definition is:
int fnHTTPListener(USOCKET Socket, unsigned char ucEvent, unsigned char *ucIp_Data, unsigned shortusPortLen);
Socket is the socket reference that the listener is connected to.
ucIp_Data is a pointer to either the data carried in the TCP frame or else is a pointer to the IP address of the peer.
usPortLen is either the length of the data or the port number of the TCP connection.
ucEvent is the event, which can be one of the following (showing the use of ucIp_Data and usPortLen in each case):
See the following forum thread for more details about handling these events: µTasker forum TCP discussion.

The routine is used to allocate a TCP socket from the TCP socket pool. It returns the number of the allocated socket, if there was no problem.
An allocated USOCKET value of >= 0 is a valid socket number, whereby negative return values indicate failures as follows: The size of the TCP socket pool is defined in config.h by NO_OF_TCPSOCKETS. TCP sockets defined for use by HTTP, FTP, MODBUS/TCP, etc. are automatically reserved and user TCP sockets that will be needed should be added as required.
See #define NO_OF_TCPSOCKETS (NO_OF_HTTP_SESSIONS + FTP_SOCKETS + POP3_SOCKET + SMTP_SOCKET + NO_OF_TELNET_SESSIONS + TIME_SERVER_SOCKET + MODBUS_TCP_SOCKETS + USER_TCP_SOCKETS) // reserve the number of TCP sockets necessary for our configuration

Once a TCP socket has been obtained for use it can be immediately used as reference to connecting to remote servers or to install a listener.

Example

static int fnSMTPListener(USOCKET Socket, unsigned char ucEvent, unsigned char *ucIp_Data, unsigned short usPortLen);

static USOCKET SMTP_TCP_socket = -1;

extern int fnConnectSMTP(unsigned char *ucIP, unsigned char ucMode, const CHAR *(*fnCallback)(unsigned char, unsigned short *))
{
	if (SMTP_TCP_socket < 0) {                                           // we have no socket
		if ((SMTP_TCP_socket = fnGetTCP_Socket(TOS_MINIMISE_DELAY, TCP_DEFAULT_TIMEOUT, fnSMTPListener)) < 0) {
			return ERROR_SMTP_NOT_READY;
		}
	}
	....
}


// Local listener on SMTP port
//
static int fnSMTPListener(USOCKET Socket, unsigned char ucEvent, unsigned char *ucIp_Data, unsigned short usPortLen)
{
    if (Socket != SMTP_TCP_socket) {
        return APP_REJECT;                                               // ignore if not our socket
    }

    switch (ucEvent) {
    case TCP_EVENT_CONNECTED:
	....
    case TCP_EVENT_CONREQ:                                               // we do not accept connection requests
    default:
        return APP_REJECT;
    }
    return APP_ACCEPT;
}


See the following forum thread for additional details about working with TCP sockets: µTasker forum TCP discussion.

Related functions

fnReleaseTCP_Socket();
fnTCP_Listen();
fnGetTCP_state();
fnTCP_Activity();
fnTCP_Connect();
fnTCP_close();




Please use the µTasker forum to ask specific questions.