Tcp4u - TCP related functions

• Tcp4uErrorString
• TcpAbort
• TcpAccept
• TcpClose
• TcpConnect
• TcpFlush
• TcpGetListenSocket
• TcpGetRemoteID
• TcpIsDataAvail / TcpIsOOBDataAvail
• TcpPPRecv
• TcpPPSend
• TcpRecv
• TcpRecvUntilStr
• TcpSend

Tcp4uErrorString

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

Syntax:  Tcp4uErrorString (int Rc)

Argument:

Return:

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:

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:

Returns

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:

Returns:

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:

Return:

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:

Return:

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:

Return:

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:

Returns:

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:

Returns:

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:

Returns:

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:

Returns:

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:

Returns:

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:

Returns:

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:

Returns:

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