ITK Programmer's Guide

---

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

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

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
 

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