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) );
(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;
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
|
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
|
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;
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.
|
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 */
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 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 .... }
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");
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);
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);
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);
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);