| # 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: |
ITK_TCPSendFile ITK_TCPRecvFile ITK_TCPSendPict | ITK_TCPSendBlob ITK_TCPRecvBlob
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
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) ` receive available data in a blob
      ...

Back to top

#####

CQ/14-Feb-2001