Tcp4u - TCP related functions


Tcp4uErrorString


This function returns the error string associated with the given error code.
This function uses the following association:

TCP4U_SUCCESS
Successful call
TCP4U_ERROR
Network error
TCP4U_TIMEOUT
Timeout in recv or accept
TCP4U_HOSTUNKNOWN
Reference to Unknown host
TCP4U_NOMORESOCKET
All sockets has been used up
TCP4U_NOMORERESOURCE
No more free resource
TCP4U_CONNECTFAILED
Connect function has failed
TCP4U_UNMATCHEDLENGTH
TcpPPRecv : Error in length
TCP4U_BINDERROR
Bind failed (Task already started?)
TCP4U_OVERFLOW
Overflow during TcpPPRecv/TcpRecvUntilStr
TCP4U_EMPTYBUFFER
TcpPPRecv receives 0 byte
TCP4U_CANCELLED
Call cancelled by signal or TcpAbort
TCP4U_INSMEMORY
Not enough memory to perform function
TCP4U_SOCKETCLOSED
Host has closed connection
OTHER...
Not an Tcp4 return code
Syntax:  Tcp4uErrorString (int Rc)

Argument:

Rc
An error code


Return:

LPCSTR
A long pointer on the error string associated with Rc.

Example : 
   Rc = TcpRecv (Socket, sz, sizeof sz, HFILE_ERROR);
   if (Rc < TCP4U_SUCCESS)
      fprintf ( stderr, "Tcp4u error: <%s>\n", Tcp4uErrorString(Rc) );

TcpAbort


(Windows only)
This function cancels a Winsocket blocking operation for this task.
This function is not mandatory under Unix, since any signal sent to the application will cancel a blocking Tcp4u call.
As said above, while a process is waiting for a blocking call to be completed, it continues to receive messages (Timer, user's actions). This blocking operation must be canceled before any other network related functions can be called.
When TcpAbort returns, the blocking call is canceled, but has not returned the control to the application. Thus the following code does not free the socket:

    case WM_CLOSE :
          TcpAbort ();
          TcpClose (& Socket);
          PostQuitMessage(0);

The TcpClose call will fails if a blocking call is in progress. TcpAbort has marked it as canceled, but a pause is necessary.

Syntax:TcpAbort ()

Return:

TCP4U_SUCCESS
The blocking call has been canceled

Example:


This example shows one of the safest ways to close an application.

  case WM_TIMER :
        KillTimer (hWnd, wParam);
        PostMessage (hWnd, wParam, 0, 0l);
        break;
  case WM_CLOSE :
        TcpAbort ();
        SetTimer (hWnd, WM_USER, 100, NULL);
        break;
  case WM_USER :
        TcpClose (& Socket);
        Tcp4uCleanup  ();
        DestroyWindow (hWnd);
        PostQuitMessage(0);
        break;

TcpAccept


This function waits for a connection and establishes it. The functions blocks until a client tries to establish a connection with the host.
This function must be called after a successful TcpGetListenSocket.

Syntax: TcpAccept (SOCKET *pConnSock, SOCKET ListenSock, UINT TimeOut)

Arguments:

pConnSock
A pointer on a socket descriptor. TcpAccept fills it with a value which identifies the connection.
ListenSock
A socket descriptor given by the FtpGetListenSock
TimeOut
the value of the timeout in second. 0 means that the function will block until a connection is requested.


Returns

TCP4U_BUFFERFREED
The function can not write into pConnSock
TCP4U_CANCELLED
The call has been cancelled by TcpAbort or Tcp4uCleanup
TCP4U_ERROR
An unexpected error has occurred or a blocking call is in progress
TCP4U_TIMEOUT
A timeout occurred
TCP4U_SUCCESS
A connection has been requested and its descriptor is available in the pConnSocket descriptor

TcpClose


This function closes a socket created with TcpAccept, TcpGetListenSocket or TcpConnect. After successful completion, the socket descriptor is set to INVALID_SOCKET.

Syntax: TcpClose (SOCKET *pSock)

Arguments:

pSock
A pointer on a socket descriptor. TcpClose fills it to INVALID_SOCKET.


Returns:

TCP4U_BUFFERFREED
The function can not write into pSock
TCP4U_ERROR
An unexpected error has occurred or a blocking call is in progress
TCP4U_SUCCESS
The Socket has been successfully closed. *pSock has been set to INVALID_SOCKET

TcpConnect


This function tries to establish a connection with a remote peer. A server process must be waiting on the same port on the remote host for a successful completion.

Syntax: TcpConnect (SOCKET *pS, LPCSTR szHost, LPCSTR szService, 
                    unsigned short *lpPort)

Arguments:

pS
A pointer on a socket descriptor. It is filled by TcpConnect
szHost
The name or the IP-Address of the server to be reached
szService
The name of the TCP service which is to be used (NULL if any)
lpPort
A 32-bit pointer on a 16-bit integer. This integer contains the value of the Port which is to be used. If the argument szService is not NULL, TcpConnect tries to locate the port in the file service, if it fails the value contained into lpPort is used, if it succeeds TcpConnect fills the value to the port returned.


Return:

TCP4U_BUFFERFREED
The function can not write into pS
TCP4U_CONNECTFAILED
The server can not be reached or no process are listening on the port.
TCP4U_ERROR
An unexpected error has occurred or a blocking call is in progress
TCP4U_HOSTUNKNOWN
The host has not been found in the file hosts, or the dotted address is not valid (ie: "10.10.10.543")
TCP4U_NOMORESOCKET
All sockets have been used.
TCP4U_SUCCESS
The connection has been established and its descriptor is available in the pS descriptor


Example:
This sample app will try to establish a connection with the FTP server szHost. It waits for its answer, then closes the connection and terminates.

if (Tcp4uInit () != TCP4U_SUCCESS)   return 0;
   Rc = TcpConnect (& CSock, szHost, "ftp", & nPort);
   if (Rc==TCP4U_SUCCESS)
     {
       TcpRecv (CSock, szReply, sizeof szReply-1, 60, HFILE_ERROR);
       TcpClose (& CSock);  
       printf ("Connection successful on port %d\nserver said:\n\n%s\n",
                nPort, szReply);
     }
   else   printf ("Connection failed\nerror %d", Rc);
Tcp4uCleanup ();
return 0;

TcpFlush


This function empties the reception buffer of a given socket.

Syntax:  TcpFlush (SOCKET S)

Arguments:

S
A Socket returned by TcpConnect or TcpAccept.


Return:

TCP4U_CANCELLED
Operation has been cancelled with TcpAbort, Tcp4uCleanup or a user signal
TCP4U_ERROR
An unexpected error has occurred or a blocking call is in progress
TCP4U_SOCKETCLOSED
The remote peer has closed its connection. No more data are to be received.
TCP4U_SUCCESS
Reception buffer is now empty.


TcpGetListenSocket


This function prepares the application for accepting connection on a given port. This is one of the first call that a server application should attempt.
The socket is created with the SO_REUSEADDR rule in order to allow several connections on the same port.

Syntax:   TcpGetListenSocket (SOCKET *pS, LPCSTR szService, 
                              unsigned short *lpPort, 
                              int nPendingConnection)

Arguments:

pS
A pointer on a socket descriptor. It is filled with a value which is to be passed to TcpAccept in order to establish connection.
szService
A string pointer on the service used by the application. If the pointer is NULL or the service has not been found, the value given into lpPort is used.
lpPort
A pointer on a value which should contain the port on which the application should await connections. If szService is a valid service name, lpPort will contain the port corresponding to this service.
NPendingConnection
The maximum length to which the queue of pending connection may grow. Illegal values (less than 1 or greater than 5) are replaced by the nearest legal value.


Return:

TCP4U_BUFFERFREED
The pS pointer is not usable.
TCP4U_CANCELLED
Operation has been cancelled with TcpAbort, Tcp4uCleanup or a user signal.
TCP4U_ERROR
An unexpected error has occurred or a blocking call is in progress
TCP4U_NOMORESOCKET
All sockets have been used up.
TCP4U_SUCCESS
The application is now listening for incoming connections. TcpAccept must be called to establish them.


Example:
This sample application is an FTP server which accepts any incoming connection then rejects the client by sending a reject string and dies. Since this sample does not have a window, it must be tested by an FTP client as shown above.

#include <tcp4u.h>
static char szRejectStr[] = "421 Sorry, just a fake FTP server";
int main (void)
{
SOCKET         ListenSock, ConnSock;
int            Rc;
unsigned short nPort=0;
   if (Tcp4uInit () != TCP4U_SUCCESS)   return 0;
   Rc = TcpGetListenSocket (& ListenSock, "ftp", & nPort, 1);
   if (Rc==TCP4U_SUCCESS)
     {
        Rc = TcpAccept (& ConnSock, ListenSock, 0);
        if (Rc==TCP4U_SUCCESS)
          {
            TnSend (ConnSock, szRejectStr, FALSE, HFILE_ERROR);
            TcpClose (& ConnSock);
          }
        TcpClose (& ListenSock); 
      }
   Tcp4uCleanup ();
return 0;
}  /* main */    

TcpGetRemoteID


This function identifies the peer station connected to the specified socket.

Syntax:     TcpGetRemoteID (SOCKET s, LPSTR szStrName, int uNameSize, 
                            DWORD *lpAddress)

Arguments:

S
The socket by which the peer station is connected.
SzStrName
A pointer on a string which is to be filled with the name of the station. If this pointer is NULL, the name of the station is not returned.
uNameSize
The size of the buffer szStrName.
lpAddress
A pointer on a double word which is to be filled with the IP address of the station. If this pointer is NULL, the IP-Address is not returned.


Returns:

TCP4U_ERROR
The IP-stack was unable to get the name of the remote station. The socket descriptor does not identify a connection.
TCP4U_OVERFLOW
The name is longer than the given buffer.
TCP4U_SUCCESS
The requested data are available.

Example:
char StationName[64];
DWORD IPAddress;
unsigned char *cAdd = (char *) &IPAddress;
   TcpGetRemoteID (Skt, StationName, sizeof StationName, &IPAddress);
   printf ("Remote Station on socket %d is %s, Address %u.%u.%u.%u",
             Skt, StationName, cAdd[0], cAdd[1], cAdd[2], cAdd[3]);


TcpIsDataAvail / TcpIsOOBDataAvail


TcpIsDataAvail returns TRUE if data are available in the reception queue of socket S. The application can assume that the next TcpRecv function will return immediately.
Note that TcpPPRecv can still block since it waits for a whole message.
TcpIsOOBDataAvail checks if Out Of Band data (a datagram with an high priority) have been received.

Syntax:     TcpIsDataAvail (SOCKET s)
            TcpIsOOBDataAvail (SOCKET s)

Arguments:

S
The socket by which the peer station is connected.


Returns:

TRUE
Data have been received. The next TcpRecv call will copy them into an application's buffer
FALSE
No data available. The next tcpRecv call will block

Example :
   TcpRecv (skt, szBuf, sizeof szBuf, 0, HFILE_ERROR);
   /* before processing data into szBuf check if OOB have */
   /* been received                                        */
   if (TcpIsOOBDataAvail(skt))
   {
     ... process out of Band data ....
   }

TcpPPRecv


This function receives a frame with a timeout. The first 16-bits of this frame contains its length in network order. They are NOT passed into the user's buffer.
This is a safe way to exchange binary structures in a client-server application. The server will neither hang nor crash if a bad structure is sent: it will just return errors such as TCP4U_TIMEOUT, TCP4U_OVERFLOW or TCP4U_UNMATCHEDLENGTH.

Syntax:   TcpPPRecv (SOCKET s, LPSTR szBuf, unsigned uBufSize, 
                     unsigned uTimeOut, BOOL bExact, HFILE hLogFile)

Arguments:

s
The descriptor of the connection returned by TcpConnect or TcpAccept
szBuf
The user's buffer
uBufSize
Its size in bytes
uTimeOut
The timeout in second
bExact
Specify if the TcpPPRecv function should receive exactly uBufSize bytes
hLogFile
A file (returned by _lopen, _lcreat) in which the data are written To disable this feature, this argument should be HFILE_ERROR


Returns:

TCP4U_BUFFERFREED
The user's buffer has been released.
TCP4U_CANCELLED
The request has been cancelled by TcpAbort or Tcp4uCleanup
TCP4U_EMPTYBUFFFER
The frame is empty. (Its length is 0 byte)
TCP4U_ERROR
An unexpected error has occurred or a blocking call is already in progress
TCP4U_INSMEMORY
Tcp4w can not allocate its temporary buffers
TCP4U_OVERFLOW
The frame to be received is greater than the user's buffer
TCP4U_SOCKETCLOSED
The remote host has closed its connection.
TCP4U_UNMATCHEDLENGTH
The parameter bExact is set to TRUE and the expected length differs from the received one.
>= TCP4U_SUCCESS
The length in bytes of the received frame. The frame is copied into the user's buffer except the first two bytes.

Example:
struct S_my {...} S;
  Rc = TcpPPRecv (Skt, (LPSTR) & S, sizeof S, 60, TRUE, HFILE_ERROR);
  if (Rc>=TCP4U_SUCCESS)
    printf ("Exact structure has been received: %d==%d\n, Rc, sizeof S);
  if (Rc==TCP4U_UNMATCHEDLENGTH) 
     printf ("Data have not struct S_my type\n");


TcpPPSend


This function sends a two-bytes frame which are the size of the data to be sent, then the data are sent.
This function should be used while the peer process is waiting on a TcpPPRecv call.

Syntax: TcpPPSend (SOCKET s, LPCSTR szBuf, unsigned uBufSize, HFILE hLogFile)

Arguments:

s
The descriptor of the connection returned by TcpConnect or TcpAccept
szBuf
The user's buffer
uBufSize
Its size in bytes
hLogFile
A file (returned by _lopen, _lcreat) in which the data are written. To disable this feature, this argument should be HFILE_ERROR


Returns:

TCP4U_CANCELLED
The request has been cancelled by TcpAbort or Tcp4uCleanup
TCP4U_ERROR
An unexpected error has occurred or a blocking call is already in progress
TCP4U_INSMEMORY
Tcp4w can not allocate its temporary buffers
TCP4U_SUCCESS
The data have been sent.

Example:
struct S_my {...} S;
  Rc = TcpPPSend (Skt, (LPCSTR) & S, sizeof S, HFILE_ERROR);


TcpRecv


This function receives data sent by the remote station.


Syntax:  TcpRecv (SOCKET s, LPSTR szBuf, unsigned uBufSize, 
                  unsigned uTimeOut, HFILE hLogFile)

Arguments:

s
The descriptor of the connection returned by TcpConnect or TcpAccept
szBuf
The user's buffer
uBufSize
Its size in bytes
uTimeOut
The timeout in second
hLogFile
A file (returned by _lopen, _lcreat) in which the data are written. To disable this feature, this argument should be HFILE_ERROR


Returns:

TCP4U_BUFFERFREED
The user's buffer has been released.
TCP4U_CANCELLED
The request has been cancelled by TcpAbort or Tcp4uCleanup
TCP4U_EMPTYBUFFFER
The frame is empty. (Its length is 0 byte)
TCP4U_ERROR
An unexpected error has occurred or a blocking call is already in progress
TCP4U_INSMEMORY
Tcp4w can not allocate its temporary buffers
TCP4U_OVERFLOW
The frame to be received is greater than the user's buffer
TCP4U_SOCKETCLOSED
The remote host has closed its connection.
>=TCP4U_SUCCESS
The length in bytes of the received frame. The frame is copied into the user's buffer except the first two bytes.

Example:
char szBuf[64];
  Rc = TcpRecv (Skt, szBuf, sizeof szBuf, 60, HFILE_ERROR);
  wsprintf (szStr,"%d bytes have been received\nBuffer %s",Rc,szBuf);
  MessageBox (hWnd, szStr, "Test Tcp4w", MB_OK); 


TcpRecvUntilStr


This function receives data sent by the remote station until a particular string has been received.
Note: This function should not be used with the Novell stack LAN Workplace.

Syntax:TcpRecvUntilStr (SOCKET s, LPSTR szBuf, unsigned *lpBufSize,
                           LPCSTR szStop, unsigned uStopSize, 
                           BOOL bCaseSensitive,
                           unsigned uTimeOut, HFILE hLogFile);

Arguments:

s
The descriptor of the connection returned by TcpConnect or TcpAccept
szBuf
The user's buffer
lpBufSize
A pointer on a word which must be initialized with the size of the user's buffer. In return, this word will contain the length of the received frame.
szStop
The string which ends the reception
uStopSize
The length of this string
bCaseSensitive
set to TRUE if the end-string is case sensitive.
uTimeOut
The timeout in second
hLogFile
A file (returned by _lopen, _lcreat) in which the data are written. To disable this feature, this argument should be HFILE_ERROR


Returns:

TCP4U_BUFFERFREED
The user's buffer has been released.
TCP4U_CANCELLED
The request has been cancelled by TcpAbort or Tcp4uCleanup
TCP4U_ERROR
An unexpected error has occurred or a blocking call is already in progress
TCP4U_INSMEMORY
Tcp4w can not allocate its temporary buffers
TCP4U_OVERFLOW
The user's buffer has been filled and the searched string has not been received.
TCP4U_SOCKETCLOSED
The remote host has closed its connection.
TCP4U_SUCCESS
The string has been received (all previously received bytes have been copied into the user's buffer, NOT the szStop string).

Example:
char szBuf[64];
char szEndStr[] = "#END#";
UINT nLength = sizeof szBuf;
  Rc = TcpRecvUntilStr (Skt, szBuf, & nLength,
                        szEndStr, sizeof szEndStr, 60, HFILE_ERROR);
  printf ("%d bytes have been received\nBuffer %s", nLength, szBuf);


TcpSend


This function sends the given data to the remote connected peer.

Syntax:    TcpSend (SOCKET s, LPCSTR szBuf, unsigned uBufSize, 
                    BOOL bHighPriority, HFILE hLogFile)

Arguments:

s
The descriptor of the connection returned by TcpConnect or TcpAccept
szBuf
The user's buffer
uBufSize
Its size in bytes
bHighPriority
set to TRUE if the date are to be sent in Out Of Band mode.
hLogFile
A file (returned by _lopen, _lcreat) in which the data are written. To disable this feature, this argument should be HFILE_ERROR


Returns:

TCP4U_CANCELLED
The request has been cancelled by TcpAbort or Tcp4uCleanup
TCP4U_ERROR
An unexpected error has occurred or a blocking call is already in progress
TCP4U_INSMEMORY
Tcp4w can not allocate its temporary buffers
TCP4U_SUCCESS
The data have been sent.

Example:
char szBuf[] = "Bonjour";
  Rc = TcpSend (Skt, szBuf, lstrlen(szBuf)+1, FALSE, HFILE_ERROR);


Overview Multi purpose func. TCP functions Telnet related func HTTP functions UDP functions SMTP functions
Tcp4u version 3.31 by Ph. Jounin and Laurent Le Bras Last updated: 10th march 1998