| # 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 5 : Low-level UDP routines
Chapter contents: |
ITK_UDPCreate ITK_UDPRelease ITK_UDPSend | ITK_UDPRcv ITK_UDPMTUSize
About this chapter... | This chapter describes low-level UDP routines provided by ITK. UDP is a connectionless protocol that can be used to transfer small amounts of data without requiring to open a connection between two computers. UDP is used for example by the DNS query protocol or by Syslog.
Note: | Multiple UDP ports are only supported under MacTCP.

ITK_UDPCreate
Syntax: | udpRef := ITK_UDPCreate (startPort;endPort;bufferSize)
Description: | Creates an UDP endpoint on the specified port or ports in order to receive or send UDP datagrams. ITK_UDPCreate returns a reference to the UDP endpoint which you later use in further UDP calls. Each UDP endpoint created using ITK_UDPCreate must be released using ITK_UDPRelease (see example below).
Params: |
In/Out | Parameter | Type |  | Example or note
-> | startPort | Longint | port number of the UDP endpoint to create | Standard port numbers are assigned in RFC#1700.
-> | endPort | Longint |  | MacTCP only
-> | bufferSize | Longint | Size of receiving buffer | The size of the receiving buffer will determine how many received datagrams can be buffered.
<- | result | Longint | UDP endpoint reference number | Returns 0 if the endpoint couldn't be created.
Example: |
    $udp := ITK_UDPCreate(4000;0;8192)
    If ($udp # 0)
      Repeat
        $err := ITK_UDPRcv($udp; $data; $remAddr; $remPort)
        ...
      Until ...
      $err := ITK_UDPRelease($udp)
      $udp := 0 ` so that we're sure we won't release it again
    End If

Back to top

ITK_UDPRelease
Syntax: | result := ITK_UDPRelease (udpRef)
Description: | Releases an UDP endpoint. The udpRef should not be used anymore. Be sure to call ITK_UDPRelease only once on an udpRef.
Params: |
In/Out | Parameter | Type |  | Example or note
-> | udpRef | Longint | UDP endpoint reference number | As returned by ITK_UDPCreate
<- | result | Longint |  | Negative values indicate that or occurred.
Example: |
    $udp := ITK_UDPCreate(4000;0;8192)
    If ($udp # 0)
      Repeat
        $err := ITK_UDPRcv($udp; $data; $remAddr; $remPort)
        ...
      Until ...
      $err := ITK_UDPRelease($udp)
      $udp := 0 ` so that we're sure we won't release it again
    End If

Back to top

ITK_UDPSend
Syntax: | result := ITK_UDPSend (udpRef;data;remAddr;remPort;localPort)
Description: | Sends data through an UDP endpoint to another UDP endpoint.
Params: |
In/Out | Parameter | Type |  | Example or note
-> | udpRef | Longint | UDP endpoint reference number | As returned by ITK_UDPCreate
-> | data | Text | data to send | Note that an UDP datagram has a limited size. Use ITK_UDPMTUSize to know the maximum number of bytes that can be transferred using an UDP datagram. You can also send an empty datagram.
-> | remAddr | Longint | IP addr (obtained for example using ITK_Name2Addr) of the remote host. |
-> | remPort | Longint | Destination port number on the remote host. | Standard port number are assigned in RFC#1700. We recommend you to comply with this RFC.
-> | localPort | Longint | Local port number to use | This value is only supported with MacTCP when using multiple port UDP endpoints.
-> | result | Longint |  | 0 indicates that no error occurred, negative value indicates that an error occurred.
Example: |
    $udp := ITK_UDPCreate(4000;0;8192)
    If ($udp # 0)
      $data := ITK_UDPSend($udp; $data; $remAddr; $remPort)
      $err := ITK_UDPRelease($udp)
      $udp := 0 ` so that we're sure we won't release it again
    End If

Back to top

ITK_UDPRcv
Syntax: | result := ITK_UDPRcv (udpRef;data;remAddr;remPort;localPort;timeout)
Description: | Waits for an UDP packet on an UDP endpoint.
Params: |
In/Out | Parameter | Type |  | Example or note
-> | udpRef | Longint | UDP endpoint reference number | As returned by ITK_UDPCreate
<- | data | Text | received data | Be aware that you can receive empty datagram. In that case, you can obtain information about the sender through the remAddr and remPort parameters.
<- | remAddr | Longint | IP address of the sender host. |
<- | remPort | Longint | Port number of the sender's UDP endpoint. |
<- | localPort | Longint | Local port number that received this UDP datagram. | This value is only available when using multiple port UDP endpoints under MacTCP.
-> | timeout | Longint | Maximum time to wait for a datagram. | 0 = infinite time Positive value = timeout in seconds Negative value = timeout in ticks (1/60th of a second) (introduced in ITK v2.0.3)
<- | result | Longint |  | 0 = no error occurred, negative value indicates that an error occurred.
Example: |
    $udp := ITK_UDPCreate(4000;0;8192)
    If ($udp # 0)
      Repeat
        $err := ITK_UDPRcv($udp; $data; $remAddr; $remPort)
        ...
      Until ...
      $err := ITK_UDPRelease($udp)
      $udp := 0 ` so that we're sure we won't release it again
    End If

Back to top

ITK_UDPMTUSize
Syntax: | result := ITK_UDPMTUSize (remAddr)
Description: | Returns the MTU (Maximum Transfer Unit) size for a given remote IP address. This value correspond to the maximum size of a datagram that can be transferred (sent or received) with the given IP address.
Params: |
In/Out | Parameter | Type |  | Example or note
-> | remAddr | Longint | IP address of the remote host | As returned by ITK_Name2Addr
<- | result | Longint |  | Positive value are the MTUSize, negative values indicates that an error occurred.
Example: |
    $remAddr := ITK_Name2Addr("www.internet-toolkit.com")
    $maxSize := ITK_UDPMTUSize($remAddr)

Back to top

CQ/2-Feb-1999