[[tags: egg]]
'''udp6''' is an interface to User Datagram Protocol sockets
over IPv4 and IPv6.
[[toc:]]
== Overview
This is a superset of the functionality of the [[/egg/udp|udp]]
extension, primarily adding IPv6 support while maintaining a
backwards-compatible API. It is implemented on top of the
[[/egg/socket|socket]] egg,
== Interface
(udp-open-socket)
(udp-open-socket*)
Returns a new UDP socket object, which is simply a datagram {{socket}}
object created by the [[/egg/socket|socket]] egg.
The starred version is provided for
API compatibility; here it does the same as the unstarred version, as
all sockets are nonblocking.
(udp-bind! SOCKET HOST PORT)
Binds a UDP socket to an address and port as specified by {{HOST}} and
{{PORT}}. {{HOST}} may be a string consisting of an IP address or
hostname, or {{#f}}, in which case the unspecified address is used. If
{{PORT}} is 0, a port will be allocated by the system automatically.
(udp-connect! SOCKET HOST PORT)
Connect a socket. In the case of UDP this does nothing more than
associate a peer address with the socket in the kernel for use with
later calls to {{send(2)}}. UDP is a connectionless protocol.
(udp-send SOCKET STRING)
Send the bytes in {{STRING}} through {{SOCKET}} to its peer, as specified with a previous call to {{udp-connect!}}. If the socket is not connected, the system will return an error.
(udp-sendto SOCKET HOST PORT STRING)
Send the bytes in {{STRING}} through {{SOCKET}} to {{PORT}} on {{HOST}}.
(udp-recv SOCKET LENGTH)
Receive a packet and store the data in string of size {{LENGTH}}. Returns two values: the number of bytes received and the string consisting the message.
(udp-recvfrom SOCKET LENGTH)
Same as {{udp-recv}} except that two additional values are returned: the host string and port number from which the packet was received.
(udp-close-socket SOCKET)
Close a socket.
(udp-socket? THING)
Test whether {{THING}} is a UDP socket.
(udp-bound? SOCKET)
Test whether a UDP socket is bound to a local address and port.
(udp-connected? SOCKET)
Test whether a peer address and port has been associated with a UDP socket with a call to {{udp-connect!}}.
(udp-bound-port SOCKET)
Returns the port to which the socket is bound.
== UDP ports
Input and output Scheme ports can be created from a connected UDP
socket using {{socket-i/o-ports}} from the [[/egg/socket|socket]] egg.
An example will be provided in the future.
== Example
(use udp6)
(define s (udp-open-socket))
(udp-connect! s "localhost" 13) ; daytime service
(udp-send s "\n")
(receive (n data host port) (udp-recvfrom s 64)
(print n " bytes from " host ":" port ": " data))
(udp-close-socket s)
;; Prints one of the following:
;; 26 bytes from 127.0.0.1:13: Wed Dec 24 11:53:14 2003
;; 26 bytes from ::1:13: Wed Dec 24 11:53:14 2003
This example can also be written directly with the [[/egg/socket|socket]] egg:
(use socket)
(define s (socket-connect/ai
(address-information "localhost" 13 type: sock/dgram)))
(socket-send s "\n")
(receive (data addr) (socket-receive-from s 64)
(print (string-length data) " bytes from "
(sockaddr->string addr) ": " data))
(socket-close s)
;; Prints one of the following:
;; 26 bytes from 127.0.0.1:13: Sat Feb 12 03:53:46 CST 2011
;; 26 bytes from [::1]:13: Sat Feb 12 03:53:46 CST 2011
== Bugs and limitations
Multicast is not yet implemented.
== About this egg
=== Author
[[http://3e8.org|Jim Ursetto]]. Originally by Category 5, with
several enhancements by Daishi Kato, but has been rewritten on
top of the [[/egg/socket|socket]] egg.
=== Version History
; 0.1 : Initial release
See [[/egg/udp|udp]] for previous history (up to 1.14).
=== License
Copyright (c) 2011, Jim Ursetto
Copyright (c) 2003-2004, Category 5
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer. Redistributions in
binary form must reproduce the above copyright notice, this list of
conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution. Neither the name of the
author nor the names of its contributors may be used to endorse or
promote products derived from this software without specific prior
written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.