asUDP Xtra
v 4.1 march 2016
Antoine Schmitt

Home page : http://www.schmittmachine.com/asUDP.html

———————————————————
——————Conditions of use—————
———————————————————

Freeware. Use at your own risks.

———————————————————
———————Description———————
———————————————————

The asUDP Xtra does UDP datagram send and receive.
Shockwave-safe and autodownloadable.
Designed to be used with Director.

The port to MacOS Mavericks has been made possible with support from www.experientialdesignlab.com.

———————————————————
————Technical Requirements————
———————————————————

- MacOSX 10.5 to 10.9 / Windows XP to Windows 8
- >= Director 11

———————————————————
——————Installation————————
———————————————————

Note that since v3.1, the asUDP Xtra requires the presence of the BytesXtra Xtra. This (free) Xtra is delivered with the asUDP Xtra.

Drop the Xtra files into the Xtras folder of Director

On Windows, use the asUDP.x32+ BytesXtra.x32 files.
On Macintosh with Director >=11, use the asUDP.xtra + BytesXtra.xtra files.

———————————————————
——————Version History——————
———————————————————

Feb 2007: v1.0.0
Apr 2007 : v2.0.0
- getLocalIP is now forbidden in Shockwave (returns 0)
- added setSendingPort function to set the sending port (useful to get replies through firewalls)
- added the getBytesWithSenderInfo function to reply to a message
Sep 07 : v2.1.0
- fixed a bug on Windows, where receiving a packet larger than 1024 bytes blocked the Xtra forever. Now the limit is 1Mb.
Mar08 : v3.0
- ported to d11 and Unicode
- autodownloadable
- fixed bug : on Windows, calling getBytes when no bytes where available crashed the Xtra.
Apr08: v3.1
- ported to BytesXtra
March 2014 :  v3.2
- ported to Mac sockets. Now works under Mac OSX 10.9 Mavericks
March 2014 : v4.0
- Xtra now free. Does not require the registration code.
March 2016 : v4.1
- added management of multiple IPs on a single machine. Added getLocalIPs function and modified startListen function

———————————————
———————API———————
———————————————

// ----- General info

UDP is with TCP the main communication protocol on the internet. You can find many documentation on the web about these protocols. UDP is faster than TCP but less realiable : it does not ensure data delivery nor data ordering, it just tries its best. TCP does ensure data delivery (data is sure to arrive), and data ordering (data is received in the order in which it was sent). UDP is sent when data loss or ordering is not important, like for redundant data like a continuous flow of value of a given mesure (the mouse position, a player position in a game, etc...)

The basic idea of UDP and TCPis that a program listens to a 'port' on the local computer, and another program sends data to this port, which is thus received by the first program. The sending program can be running on the same computer or on a remote computer on the internet or intranet. There are 65536 ports on any computer, numbered from 0 to 65535. The computers are adressed using their IP adresses (ex: "192.168.0.1"). If you want two programs to talk back and forth, you make each program listen to a port on their respective computers and send data to the other program's port. Only one program can listen to a given port on a given computer.

The data sent are abitrary bytes. The meaning of these bytes is up to the two communicating programs. UDP does not interpret these bytes in any way, it just delivers them as fast as possible.

[This all works very much like a P.O.Box in a postoffice, just much faster. You start renting a POBox, which has a number. Only you can access it. Other people can send to it using the address of the postoffice and the POBox number. People from the same postoffice can send to this box, or people from other postofices, or yourself actually can send to you own box,. The postoffice never opens the letters, the postoffice sometimes looses letters and does not ensure the ordering of the letters. If you want to answer, you send a letter to the sender's PObox, if he has one. UDP is just much much faster : data delivery usually is as instantaneous as possible : VoIP, video streaming, etc.. is usually done using the UDP protocol]

The asUDP Xtra is just like another program speaking UDP : it can talk UDP to another program, or to another asUDP Xtra, or to itself actually. With the asUDP Xtra, you start to listen to a port using the startListen(localPort) function. You send to a port using the sendBytes(bytes, IPaddress, portNumber) function. You stop listening with the stopListen() function. You check that bytes have been received using the bytesReceived() function and you actually get the bytes using the getBytes() function. You can also know the local computer's IP address using the getLocalIP function.

//------ bytes object

Since version 3.0, the asUDP Xtra uses a 'bytes' object, which is needed because lingo Unicode strings cannot contain binary data anymore.
Since version 3.1, this bytes objects are provided by the BytesXtra Xtra.

//----- asUDP Xtra API

The Xtra is instantiated with the call:

gUDPXtra = new(Xtra "asUDP")

All later calls can be in the form:
func(gUDPXtra, args...)
or the new form
gUDPXtra.func(args...)

The Xtra is released at the end by calling the free function and setting it to VOID:
free(gUDPXtra)
object = VOID

Most functions return 0 (zero) if an error occurred.
If an error occured, the function getError returns a human-readable string describing the error.

Argument types:
int = integer (ex: 16)
str = string (ex: "abcde")
float = float (ex: 1.2)
list = lingo list (ex: ["ab", "cd"])

———————————————
—————Functions——————
———————————————

new(Xtra "asUDP")
—————————
ex: gUDPXtra = new(Xtra "asUDP")

Creates the Xtra instance and returns it.
Only one instance of the Xtra should exist at any given time. Creating multiple instances may result in various problems.
The Xtra should be released at the end by calling the free function and setting the variable to VOID.

See also : free

free(object me)
—————————
ex: free(gUDPXtra)
ex: gUDPXtra.free()

Stops all receiving, frees all memory, frees the Xtra instance.
Do not call any other function on the Xtra instance after this call.
Advice : set the variable to VOID, just to be sure:

gUDPXtra.free()
gUDPXtra = VOID

see also : new

str getLocalIP(object me)
—————————
ex: localIP = gUDPXtra.getLocalIP()

Returns the IP address of the (first) network card of your computer. The IP address is a string of the form xxx.xxx.xxx.xxx (ex: 192.168.0.1)

In shockwave, this function returns a crypted token which represents the IP (example : "%GDKQIUHSF%"). You can pass back this token to the asUDP Xtra when an IP is required, for example in sendBytes: the Xtra will decrypt it. Note that the token is only valid in this player and in the current session : when the movie is restarted previously generated tokens will not work any more.

You can also send to the local IP address by using the IP address "127.0.0.1" or the "localhost" destination.

Returns 0 if failed. Use getError to get a description of the error.

See also : getLocalIPs, startListen, sendBytes

list getLocalIPs(object me)
—————————
ex: localIPs = gUDPXtra.getLocalIPs()

Returns the list IP addresses of all network cards of your computer. An IP address is a string of the form xxx.xxx.xxx.xxx (ex: 192.168.0.1).

In shockwave, each IP address is a crypted token which represents the IP (example : "%GDKQIUHSF%"). You can pass back this token to the asUDP Xtra when an IP is required, for example in sendBytes or startListen: the Xtra will decrypt it. Note that the token is only valid in this player and in the current session : when the movie is restarted previously generated tokens will not work any more.

You can also send to the local IP address by using the IP address "127.0.0.1" or the "localhost" destination.

Returns 0 if failed. Use getError to get a description of the error.

See also : getLocalIP, startListen, sendBytes

int startListen(object me, integer localPort [, string IP])
—————————
ex: err = gUDPXtra.startListen(53000)
ex: err = gUDPXtra.startListen(53000, "192.168.0.1")

Requests the Xtra to listen to a port number.
localPort is an integer > 0 and <= 65535.
IP is an IP of the local machine. This argument is optional. If omitted, listens on the default network card.

The Xtra instance can only listen to one port at a given time. If you call this function again with another port, the Xtra will stop listening to the first port. Use stopListen to stop listening to the port.

The Xtra can only listen to a port on the local computer.

The port number to use is up to you. Traditionnaly, low numbers are reserved for traditional IP services (HTTP, SMTP, etc...). And numbers 49152 through 65535 are for use by private applications. For example, you can use 53000. See http://www.iana.org/assignments/port-numbers for information about port numbers. Note that only one application on the computer can listen to a given port at a given time : if the localPort is already used by another application, the startListen function will return an error (-3247). You should then choose another port.

Once the Xtra has called startListen, another Xtra (in another Director movie), or the same Xtra in the same Director movie, or any UDP datagram application actually, can start sending bytes to the listening Xtra by sending it to the localPort. Using the asUDP Xtra, this is done using the sendBytes function.

You can use the bytesReceived function to know if bytes have been received on the port. And if so, you can get them using the getBytes function.

(Geek talk : this function creates a non-blocking datagram UDP socket on the given port)

Returns 0 if failed. Use getError to get a description of the error.

See also : stopListen, sendBytes

int stopListen(object me)
—————————
ex: err = gUDPXtra.stopListen()

Requests the Xtra to stop listening.

Returns 0 if failed. Use getError to get a description of the error.

See also : startListen, sendBytes

int bytesReceived(object me)
—————————
ex: err = gUDPXtra.bytesReceived()

Returns the number of bytes that have been received on the port. Returns 0 if no bytes have been received.

You can only call this function after having started to listen to a port, using the startListen function.

If some bytes have been received, you can get them using the getBytes function.

(Geek talk : this number is the size of the next pending datagram of the socket)

See also : startListen, getBytes

bytes getBytes(object me)
—————————
ex: data = gUDPXtra.getBytes()

Returns the bytes waiting on the port, as a 'bytes' object (see above). If no bytes are waiting, returns an empty bytes object. You can only call this function after having started to listen to the port, using the startListen function. Before calling getBytes, you can call bytesReceived to be sure that bytes are ready, but this is not mandatory of course.

Note that the length of the returned data may not be equal to the value returned by bytesReceived, since many packets may be waiting on the port.

This function removes the returned bytes from the port : the next call to getBytes will return the next incoming packet.

Example :

data = gUDPXtra.getBytes()
-- this output ALL the bytes of data to the message window, as integers
repeat with i = 1 to data.size
    put data[i]
end repeat

(Geek talk : this returns the next pending datagram of the socket)

Returns 0 if failed. Use getError to get a description of the error.

See also : startListen, bytesReceived

bytes getBytesWithSenderInfo(object me)
—————————
ex: bytesAndInfo= gUDPXtra.getBytesWithSenderInfo()

This function returns a list of 3 values : the bytes exactely like the getBytes function, the sender IP address and the sender port number. This function is useful to reply to the sender.

In shockwave, this function returns a crypted token which represents the sender IP (example : "%GDKQIUHSF%"). You can pass back this token to the asUDP Xtra when an IP is required, for example in sendBytes: the Xtra will decrypt it. Note that the token is only valid in this player and in the current session : when the movie is restarted previously generated tokens will not work any more.

Returns 0 if no bytes have been received.

You can only call this function after having started to listen to a port, using the startListen function.

See also : startListen, getBytes

int sendBytes(object me, bytes data, string destIP, integer destPort)
—————————
ex: gUDPXtra.sendBytes(newBytesFromString("abc"), "localhost", 53000)
ex: gUDPXtra.sendBytes(newBytesFromString("abc"), "192.168.1.100", 53000)
ex:
data = newBytes(3)
data[1] = 1
data[2] = 0
data[3] = 2
gUDPXtra.sendBytes(data, "192.168.1.100", 53000)

Sends bytes to a port on a computer. If something (like another, or the same, asUDP Xtra) is listening to this port on this computer, it will receive the bytes asap.

Note that this is UDP : UDP does not garantee that it will deliver the data, it just garantees that it will do its best. If you want reliability, use TCP (which is slower). This Xtra does not do TCP. Note also that UDP does not garantee ordering : you can send two datagrams one after the other and they can arrive in any order at the other end.

The data is a 'bytes' object (see above). All its bytes are sent.

destIP is the destination computer ID address, which is a string, like "192.168.0.100". The computer can be the local computer or a remote computer. To address the local computer, use the address "localhost", or "127.0.0.1", which tradionnaly represents the local computer.

You can use this function without calling startListen first, of course, since this function only sends.

(Geek talk : this function sends a datagram datagram to the remote port)

Returns 0 if failed, 1 if succeeded. Use getError to get a description of the error.

See also : startListen, getBytes

int setSendingPort(object me, integer sendingPort)
—————————
ex: err = gUDPXtra.setSendingPort(53003)
ex: err = gUDPXtra.setSendingPort(VOID)

Sets the local port from which the data is sent to the given argument sendingPort.

This is useful for communication through firewalls. When the Xtra sends data, it does so from a sending port on the local machine. By default, this sending port is unknown (chosen at random by the underlying mechanism). When an UDP message gets to a destination application, this destination may answer by sending an answer to the originating machine. For example to a predefined port on which the sending application is listening. Or to the port from which the original message was sent. Firewalls only accept incoming messages going to ports from which an original message was already sent in the past : they only accept answers. The setSendingPort function allows two application to communicate through a firewall:
- the sending application listens on a port P
- it sets the sending port to P also
- it sends data to the destination application
- this destination can answer, using the sending IP and port, and the answer will go through the firewall. This is the standard way of doing (this is how browsers work for example).

If the destination application also uses the asUDP Xtra, it can determine the sending port and IP using the getBytesWithSenderInfo function.

Returns 0 if failed, 1 if succeeded. Use getError to get a description of the error.See also : startListen, getBytes

str getError(object me)
—————————
ex: errorString = gUDPXtra.getError()

Returns a string describing the last error that occured when calling functions of the Xtra.

——————————————————————
—— Packages : Autodownloadable Version ——
——————————————————————

The asUDP Xtra is autodownloadable from the internet, so that it is usable inside a Shockwave movie available on a web site.

In order provide the asUDP Xtra for automatic download, follow these instructions:
- locate the packages in the delivery that you have received. There should be one package per platform (currently xpku and w32).
- put the packages in a single location on a server. eg:
http://www.myserver.com/packs/asUDP.xpku (for D11 Mac)
http://www.myserver.com/packs/asUDP.w32 (for Windows)
(Do not put www.schmittmachine.com here, as the packages are *not* autodownloadable from the schmittmachine.com web site. Put them on your web site, alongside your Shockwave movie for example.)
- modify the xtrainfo.txt file in the Director folder to reference this location, eg:
; asUDP Xtra
[#namePPC:"asUDP", #nameW32:"asUDP.x32",#package:"http://www.myserver.com/packs/asUDP"]
- restart Director
- add a reference to the package in your movie:
Open a movie that uses asUDP Xtra. From the Modify\Movie\Xtras dialog in Director, select the asUDP Xtra in the list of xtras.
The "Download if needed" checkbox should now be enabled. (If it's not enabled, make sure the filename in xtrainfo.txt matches the actual filename for the xtra.)
Click on the checkbox and director will load information from the online package file for each platform and add it to the current movie. If it does not, something is wrong, please check all steps above.
- publish your shockwave movie, and install it on your server. Each user that plays your Shockwave will automatically dowload the asUDP Xtra from the http address you have specified.
For more information on the Packaging and Autodownload process, check Adobe's web site.

——————————————————————