All streams opened using ITK_TCPOpen MUST be
released using ITK_TCPRelease
.

Description:

Opens a TCP stream asynchronously (returns control
immediately without waiting for the connection to be
established with the remote host).
Use ITK_TCPStatus or ITK_TCPWaitConn
to wait for the connection to be established.

Use tcpOpt to open an SSL "client" stream instead of a
plain TCP stream (added in ITKv2.5). This option is only
available in the "Pro" version of ITK.

If remotePort is equal to 443 (HTTPS standard port
number), ITK will switch automatically to SSL.

This parameter is used only under MacTCP. Accepts values between 8192 and 32767.
Pass 0 for ITK to use a default buffer of 8KB (8192
bytes).

->

tcpOpt

Longint

TCP options (type of service field, leave 0 as
default)

This parameter is used only under MacTCP. See MacTCP Programmer's Manual for more
details on the "type of service" values.

option 1024 indicates that an SSL "client"
stream should be opened instead of a classical TCP
stream (added in ITKv2.5)

->

oldStream

Longint

old stream reference number to reuse (set to 0
to allocate a new stream)

This parameter is obsolete and shouldn't be
used anymore.

->

localPort

Integer

local port number

Pass 0 for ITK to choose a local port number.

->

localIP

Longint

local IP address This parameter is provided for multihoming
support.

<-

streamRef

Longint

stream reference number

Will return 0 if the stream couldn't be created.

Note#1: if
you add a "." at the beginning of the TCP address of the
remote host (ex: ".www.internet-toolkit.com"), ITK will
choose randomly one of the resolved addresses returned by
the DNS to do DNS load balancing (see ITK_Name2Addr
for more information).

Example:

` open a stream with an HTTP server
$stream := ITK_TCPOpen("www.internet-toolkit.com";80)
If ($stream#0)
...
$err := ITK_TCPRelease($stream)
End If
` open an SSL stream with an HTTPS server
$stream := ITK_TCPOpen("www.internet-toolkit.com";443;0;1024) ` SSL stream
If ($stream#0)
...
$err := ITK_TCPRelease($stream)
End If

All streams opened using ITK_TCPListen MUST be
released using ITK_TCPRelease
.

Description:

Opens a "passive" or "listening" TCP stream to receive
calls.
Like in ITK_TCPOpen, control is returned immediately without
waiting for a connection to be received and established.
Use ITK_TCPStatus or
ITK_TCPWaitConn to wait for the connection to be
established.

Use tcpOpt to create an SSL "server" stream instead of a
TCP stream (added in ITKv2.5).

If localPort is equal to 443 (HTTPS standard port
number), ITK will switch automatically to SSL.

SSL "server" is only available in the "Pro" version of
ITK with an additional SSL server license.

Note:

Under MacOS X, your application needs to run with root
privileges in order to listen on ports ranging from 1 to
1023.

Params:

In/Out

Parameter

Type

Example or note

->

hostFilter

Longint

TCP address of remote host

Pass 0 to accept connections from any remote
host, otherwise pass a numeric IP address to only
accept connections from the specified remote host.

->

portFilter

Integer

TCP remote port

Pass 0 to accept connections from any remote
port numbers, otherwise pass a port number to only
accept connections from the specified port number
(ex: 80 for HTTP, 25 for SMTP, see RFC#1700 for
assigned numbers).

->

localPort

Integer

local port number

Pass the local port number on which you want to
listen for incoming connections (ex: 80 for HTTP,
25 for SMTP, see RFC#1700 for assigned numbers).

->

rcvBuffer

Longint

Receive buffer size for this stream

This parameter is used only under MacTCP. Accepts values between 8192 and 32767.
Pass 0 for ITK to use a default buffer of 8KB (8192
bytes).

->

tcpOpt

Longint

TCP options (type of service field, leave 0 as
default)

This parameter is used only under MacTCP. See MacTCP Programmer's Manual for more
details on the "type of service" values.

option 2048 indicates that an SSL "server"
stream should be created instead of a classical TCP
stream (added in ITKv2.5)

->

oldStream

Longint

old stream reference number to reuse (pass 0 to
allocate a new stream)

This parameter is obsolete and shouldn't be
used anymore.

->

localIP

Longint

local IP address This parameter is provided for multihoming
support.

Pass 0 if you want to accept incoming
connections on all local IP addresses, otherwise,
pass one of the local IP addresses to only accept
incoming connection on the specified IP address.

Sends the data remaining in the output buffer (see
ITK_TCPSend ) and tells the
remote host that no more data will be sent.
After closing a stream, you can still receive data on it
until you use ITK_TCPRelease
.
This is possible because a TCP stream is made of two half
streams, each one used to send data from one host to the
other. Each half-stream can be closed separately (also
called half-close).

Warning:

Closing a stream doesn't releases the stream, but only
tells the remote host that you're done sending data.

Releases a TCP stream and all its associated buffers.
After this call, the streamRef should not be used anymore.

Note:

When calling ITK_TCPRelease , all data remaining
to be sent will not be sent. To avoid this, you must call
ITK_TCPClose and then monitor
ITK_TCPStatus to check that
the remote host has received all remaining data and that you
closed your half-stream.

Each successfull calls to ITK_TCPOpen and
ITK_TCPListen must be balanced by a call to
ITK_TCPRelease.

Returns the current status of a TCP stream or
miscellaneous information about the stream.
Use it to wait for a connection to be established (status=8)
or for the remote host to acknowledge a half-close.

**With SSL streams, bytesRcvd
and bytesSent indicate the number of SSL data transmitted,
SSLrawRcvd and SSLrawSent indicate the total raw
bytes of encrypted data really transmitted at the
TCP/IP layer level.

<-

status

Longint

current stream status code

-1 = invalid streamRef error
other negative values = any other error

Positive values are current status:

0

Closed

no connection exists on this stream

2

Listen

listening for an incoming connexion.

4

SYN received

incoming connection is being
established

6

SYN sent

outgoing connection is being
established

8

Established

connection is up

10

FIN Wait 1

connection is up; close has been sent

12

FIN Wait 2

connection is up; close has been sent
and acknowledged

14

Close Wait

connection is up; close has been
received

16

Closing

connection is up; close has been issued
and received

18

Last ACK

connection is up; close has been issued
and received

20

Time Wait

connection is being broken

see RFC#793, page 21

Example:

` wait for the connection to be established
Repeat
$s := ITK_TCPStatus($stream)
IDLE
Until (($s>=8) | ($s<0)) ` end if connected or error

Sends data through an established TCP stream.
ITK has its own send buffer which helps reducing the number
of calls to lower level TCP/IP layers when small chunks of
data are sent.
Filtering can be applied on the sent text.

0 = don't use ITK output buffer, flush its
content if it wasn't empty,
1 = use ITK's output buffer. It will be flushed
regularly by ITK.
Values above 255 indicate the maximum number of
bytes that may be buffered. If the output buffer
contains more than the value passed, ITK will flush
its output buffer.
ITK's send buffer will also be flushed when calling
ITK_TCPRcv or
ITK_TCPClose .

->

filterFlag

Longint

One or more encodings can be applied before
sending the data (or putting them in ITK's send
buffer). You may add flag values to apply several
filters.
See Table#1
for all filter flag values.

->

result

Longint

Returns the number of bytes currently stored in
ITK's output buffer.

Negative values indicates that an error occurred
on this stream (it may have been released by the
remote host).

Pass 0 if you want to receive all available data
(up to 32000 bytes which is the limit for Text
fields or variables in 4D).

->

filterFlag

Longint

One or more encodings can be applied before
sending the data (or putting it into ITK's receive
buffer). You may add flag values to apply several
filters at once.
See Table#1
for all filter flag values.

->

options

Longint

Options can be combined, ex:
5 = 1+4 = append + search in new data

0 = do not append received data to previous data
present in dataStorage
1 = append received data to previous data present
in dataStorage

Version 2.0.3 and above:
2 = the ending string will remain in ITK's receive
buffer
4 = do not search endstring in original data when
append is used

->

endString

String

end receive string

If this string is found in incoming data or
accumulated data (when the append flag is used),
ITK_TCPRcv will return all data up to this string
(including it), remaining data will be kept in
ITK's receive buffer.

ITK_TCPUnRcv can be used to put some data you
previously received back into ITK's receive buffer.
This data will be received in the next call to receiving
routines (like ITK_TCPRcv ,
ITK_TCPRcvBlob ,
ITK_TCPRcvFile , etc.).

Pass 0 if you want to receive all available data
(up to 32000 bytes which is the limit for Text
fields or variables in 4D).

<-

localPort

Integer

Local port number

One or more encodings can be applied before
sending the data (or putting it into ITK's receive
buffer). You may add flag values to apply several
filters at once.
See Table#1
for all filter flag values.

<-

srtt

Longint

Smoothed round trip time

This value is only available under MacTCP,
otherwise -1 is returned.

<-

localIP

Longint

Local IP address

This value is useful for multihomed systems
(like Windows NT or MacOS with OpenTransport 1.3 or
above).

ITK_SetTimeout can be used to set the default timeout
used by all "send" ITK routines (ITK_TCPSend,
ITK_TCPSendFile, ITK_TCPSendPict, ITK_TCPSendBlob).

By default, ITK doesn't use any timeout when sending
data. It can be usefull to set a timeout to avoid possible
"send locks" when the remote host becomes unreachable (crash
or disconnection for example).

When the send timeout is reached in one of the
ITK_TCPSend routines, the routine will return control , but
the status of the stream will remain the same.