ITK Programmer's Guide

 

Table of contents | Intro | General | TCP Low Level | TCP High Level | UDP | DNS | PPP
Encoding/Decoding | Internet Config | Goodies | Cryptography & SSL | Appendix

 

Chapter 4 : Higher-level TCP/IP routines

   

   

Chapter contents:

About this chapter...

This chapter describes high level TCP/IP routines provided by ITK.

These routines allow some more sophisticated using of TCP streams.

Note:

ITK high level routines do not directly interact one with the other. For example, ITK_TCPSendFile and ITK_TCPRecvFile are not "symmetric" routines that can be used "as is" on both ends of a stream to transfer a file.

ITK_TCPSendfile sends tha data contained in a given file, while ITK_TCPRecvFile stores all incoming data into a given file, but the incoming data have no link with where it came from (a file or something else) and ITK_TCPRecvfile will need to have some "end of file" condition to stop storing data in the receiving file. you have to handle this yourself.

This also applies for blob sending and receiving.

To determine when the "end" condition occurs, you may have to tranfer the size of the file or blob you're about to transfer so that the receiver knows the number of bytes to receive, you may also use some "end string" (but in that case, be sure this end string is not contained in the data you're about to transfer), or you may also choose to close the stream.

ITK_TCPSendFile

Syntax:

result := ITK_TCPSendFile (streamRef;pathname;filterFlag;sendBlockSize;startOffset;endOffset;options)

Description:

Sends a file through a TCP stream. Under MacOS, only the data fork of the file is sent, an option parameter introduced with version 2.0.3 of Internet ToolKit allows to send the resource fork under MacOS.
After sending the file, the stream is left opened.
Filtering can be applied on the sent file.

The last two parameters allow to send only a portion of the file.

ITK's internal buffer is flushed before sending the file.

Note:

ITK_SetTimeout can be used to set a "maximum send timeout" to be used by ITK when sending data.

It the event that the remote host doesn't close the stream gracefully (disconnection, crash, etc) this "maximum send timeout" will avoid ITK to keep trying sending data.

Params:

In/Out

Parameter

Type

   

Example or note

->

 

streamRef

 

Longint

 

stream reference number

As returned by ITK_TCPOpen or ITK_TCPListen .

->

pathname

Text

pathname of the file to send

Under Windows, the full pathname must be passed, ex: "C:\MYSTUFF\MYFILE.TXT".  

->

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.

->

sendBlockSize

Longint

send block size (byte count for I/O operations, leave to 0 to use default value)

This parameter tells ITK which size to use for each data block read from the file and send through the stream.

->

startOffset

Longint

starting offset of the portion of the file to send, leave 0 to start at the beginning of the file.

Offsets in the file are starting at 0, so the second byte of the file has its offset equal to 1, etc.

->

endOffset

Longint

ending offset of the portion of the file to send, leave 0 to send up to the end of the file.

See above.

->

options

Longint

Option flags, leave 0 for standard options

0 = send data fork
1 = send resource fork (MacOS only)

This parameter has been introduced in version 2.0.3 of Internet ToolKit.

<-

result

Longint

   

Negative values indicate that an error occurred on the stream (it may have been released by the remote host).
-1= invalid stream
-2 = error opening the file
other negative values: MacOS error codes

Example: 

$stream := ITK_TCPOpen("host.domain.com";80)
If ($stream#0)
  ... ` wait for connection to be established
  $err := ITK_TCPSendFile($stream;"C:\MYFILE.TXT")
  ...
 
Back to top

ITK_TCPRecvFile

Syntax:

result := ITK_TCPRecvFile (streamRef;pathname;filterFlag;optFlag;timeout;maxLen)

Description:

Stores all data received on a TCP stream into a file.
ITK_TCPRcvFile returns control when:

  • the stream is closed by the remote host,
  • no data has been received during the timeout value,
  • the maximum length has been reached (introduced in v2.0.4),
  • an error occurred on the stream or on the file (I/O error, disk full, etc.).

Filtering can be applied on the received file.

The stream is automatically released before returning control to 4D unless the option flags are set to keep the stream (see optFlag below).

Params:

In/Out

Parameter

Type

   

Example or note

->

 

streamRef

 

Longint

 

stream reference number

As returned by ITK_TCPOpen or ITK_TCPListen .

->

pathname

Text

pathname of the file to use to store incoming data

Under Windows, the full pathname must be passed, ex: "C:\MYSTUFF\MYFILE.TXT".   

->

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.

->

optFlag

Longint

Values:

  • 1 = append to existing file
  • 2 = do not release the stream

One or more options can be requested. You may add flag values to apply several options at once.

Ex: 0 = nothing special
3 = append to existing file and do not release the stream

->

timeout

Longint

Timeout value in seconds

0 = infinite time

->

maxLen

Longint

maximum length of data to be received

0 = no maximum length (parameter added in v2.0.4)

<-

result

Longint

Negative values indicate that an error occurred.

Example: 

$stream := ITK_TCPOpen("host.domain.com";80)
If ($stream#0)
  ... ` wait for connection to be established
  $err := ITK_TCPRecvFile($stream;"C:\MYFILE.TXT") `
End If
Back to top

ITK_TCPSendPict

Syntax:

result := ITK_TCPSendPict (streamRef;picture;startOffset;endOffset)

Description:

Sends a picture content or a part of it through an established TCP stream.
ITK_TCPSendPict will look for GIF or JPEG data and only send them if present in the picture.

In that case, the picture must already be JPEG or GIF compressed, for example:

COMPRESS PICTURE($myPict;"jpeg";500) 

$err := 
         
         ITK_TCPSendPict
         ($stream;$myPict)  

or 

$err := 
         
         ITK_TCPSendPict
         
         ($stream;
         
         ITK_Pict2GIF($myPict))

Note:

ITK_SetTimeout can be used to set a "maximum send timeout" to be used by ITK when sending data.

It the event that the remote host doesn't close the stream gracefully (disconnection, crash, etc) this "maximum send timeout" will avoid ITK to keep trying sending data.

Params:

In/Out

Parameter

Type

   

Example or note

->

 

streamRef

 

Longint

 

stream reference number

As returned by ITK_TCPOpen or ITK_TCPListen .

->

picture

Picture

Picture to send

   

->

startOffset

Longint

Starting offset of data to send

Pass 0 to send data from the beginning of the picture.

->

endOffset

Longint

Ending offset of data to send

Pass -1 to send the full content of the picture without looking for GIF or JPEG data.

<-

result

Longint

   

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

Example: 

COMPRESS PICTURE($myPict;"jpeg";500) 
$err := ITK_TCPSendPict($stream;$myPict) 
 

or 

$err := ITK_TCPSendPict($stream;ITK_Pict2GIF($myPict)) 
 
Back to top

ITK_TCPSendBlob

Syntax:

result := ITK_TCPSendBlob (streamRef;blob;flushFlag;filterFlag;startOffset;endOffset)

Description:

Sends a blob content or a part of it through an established TCP stream.
ITK has its own send buffer which help 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 data.

Note:

ITK_SetTimeout can be used to set a "maximum send timeout" to be used by ITK when sending data.

It the event that the remote host doesn't close the stream gracefully (disconnection, crash, etc) this "maximum send timeout" will avoid ITK to keep trying sending data.

Params:

In/Out

Parameter

Type

   

Example or note

->

 

streamRef

 

Longint

 

stream reference number

As returned by ITK_TCPOpen or ITK_TCPListen .

->

blob

Blob

data to send

   

->

flushFlag

Longint

 

   

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

->

filterFlag

Longint

   

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

->

startOffset

Longint

Starting offset of data to send

Pass 0 to send data from the beginning of the blob.

->

endOffset

Longint

Ending offset of data to send

Pass 0 to send data up to the end of the blob.

<-

result

Longint

   

Returns the number of bytes currently store in ITK's send buffer upon return.

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

Example: 

$stream := ITK_TCPOpen("www.internet-toolkit.com";80)
If ($stream#0)
  ... ` wait for connection to be established
  $err := ITK_TCPSendBlob($stream;myBlob)   ` send the whole blob content
  $err := ITK_TCPSendBlob($stream;myBlob;0;0;0;1024) ` send first 1024 bytes of the blob
  ...
 
Back to top

ITK_TCPRecvBlob

Syntax:

result := ITK_TCPRecvBlob (streamRef;dataStorage;maxLen;filterFlag;options;endString;timeout)

Description:

Receives data through an established TCP stream.
Remaining data in ITK's send buffer are sent if present.
Filtering can be applied on the received data.

ITK_TCPRecvBlob will return control:

  • immediately if endString is empty
  • when endString is received
  • when maxLen bytes have been received
  • after timeout has expired

Warning:

The stream will be released automatically after receiving the blob, unless option 2 is used.

Params:

In/Out

Parameter

Type

   

Example or note

->

 

streamRef

 

Longint

 

stream reference number

As returned by ITK_TCPOpen or ITK_TCPListen .

->

dataStorage

Blob

storage variable or field

Content is replaced or appended depending on appendFlag

->

maxLen

Longint

 

maximum length of data to be received

Pass 0 if you want to receive all available data.

->

filterFlag

Longint

   

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

->

options

Longint

 

Values:

  • 1 = append to existing blob
  • 2 = do not release the stream after receiving the blob
  • 4 = look for endstring only in new incoming data
  • 8 = remove endstring at the end of the blob

One or more options can be requested. You may add flag values to apply several options at once.

Ex: 0 = nothing special
3 = append to existing blob and do not release the stream

->

endString

Text

end receive string

ITK_TCPRcv will return data until this string is found. If this string is found in incoming data, ITK_TCPRcv will return all data up to this string, remaining data will be kept in ITK's receive buffer.

->

timeout

Longint

maximum time to wait for endString (in 1/60th of a second)

Special values:
-1 = infinite time
0 = no timeout, returns control immediately

<-

result

Longint

returns number of bytes received or any error code (negative value).

-1 = invalid stream reference number

Example: 

$stream := ITK_TCPOpen("mail.internet-toolkit.com";25)
if ($stream#0)
  ... ` wait for connection to be established
  $result := ITK_TCPRecvBlob($stream; $myBlob; 0; 0; 2) ` receive available data in a blob
  ...
 
Back to top

CQ/14-Feb-2001