↑ Software ↑
GEONius.com
6-Jan-2004
 E-mail 

udp_util - UDP/IP Networking Utilities

The UDP_UTIL package implements a high-level interface to UDP/IP network communications. Under the UDP protocol, processes send datagrams to each other. Unlike TCP, UDP has no concept of a connection; messages are individually routed to one or more destination endpoints through a single socket. Also unlike TCP, UDP does not guarantee reliable transmission; messages may be lost or sent out of order.

In the UDP_UTIL package, the endpoints of a connection-less UDP "connection" are called, well, endpoints. A given program may create an anonymous UDP endpoint bound to a system-assigned network port: 

    udpCreate (NULL, NULL, &endpoint) ;
or it may create a UDP endpoint bound to a predetermined network port (specified by name or port number): 

    udpCreate ("name", NULL, &endpoint) ;
Client processes generally create anonymous UDP endpoints for the purpose of sending messages to a server process at a predetermined network port. With an anonymous endpoint, a client must let the server(s) know its port number before the client can receive messages from the server(s). The act of sending a datagram to the server(s) automatically supplies the server(s) with the client's port number and IP address.

By creating a UDP endpoint bound to a predetermined network port, a server is immediately ready to receive datagrams sent by clients to that port; the clients already know the port number, so there is no need for the server to send messages first.

To send a datagram from one endpoint to another, you must specify the network address of the destination endpoint. Since the destination endpoint probably belongs to another process, possibly on a remote host, the UDP_UTIL package requires you to create a proxy endpoint for the destination endpoint: 

    udpCreate ("name[@host]", source, &destination) ;
A proxy endpoint simply specifies the network address of the destination endpoint; the proxy endpoint is not bound to a network port and it has no operating system socket associated with it. The proxy endpoint is internally linked with its source endpoint, so, when a datagram is sent to the proxy, udpWrite() automatically sends the datagram through the source endpoint to the destination. A source endpoint may have many proxy endpoints, but a given proxy endpoint is only linked to a single source. (If you have multiple source endpoints, you can create multiple proxy endpoints for the same destination.)

When a datagram is read from an anonymous or predetermined endpoint, udpRead() returns the text of the datagram and a proxy endpoint for the sender of the datagram. The proxy endpoint can be used to return a response to the sender: 

    char  message[64], response[32] ;
    UdpEndpoint  me, you ;
    ...
						-- Read message.
    udpRead (me, -1.0, sizeof message, message, NULL, &you) ;
						-- Send response.
    udpWrite (you, -1.0, sizeof response, response) ;
Although there is no harm in doing so, there is no need to delete proxy endpoints; they are automatically garbage-collected when their source endpoint is deleted.

The following is a very simple server process that creates a UDP endpoint bound to a predetermined network port and then reads and displays messages received from clients: 

    #include  <stdio.h>				-- Standard I/O definitions.
    #include  "udp_util.h"			-- UDP utilities.

    main (int argc, char *argv[])
    {
        char  buffer[128] ;
        UdpEndpoint  client, server ;
						-- Create UDP endpoint.
        udpCreate ("name", NULL, &server) ;

        for ( ; ; ) {				-- Read and display messages.
            udpRead (server, -1.0, 128, buffer, NULL, &client) ;
            printf ("From %s: %s\n", udpName (client), buffer) ;
        }

    }
The following client process creates an anonymous UDP endpoint and sends 16 messages through that endpoint to the server: 

    #include  <stdio.h>				-- Standard I/O definitions.
    #include  "udp_util.h"			-- UDP utilities.

    main (int argc, char *argv[])
    {
        char  buffer[128] ;
        int  i ;
        UdpEndpoint  client, server ;

        udpCreate (NULL, NULL, &client) ;	-- Create client and target.
        udpCreate ("name[@host]", client, &server) ;

        for (i = 0 ;  i < 16 ;  i++) {		-- Send messages.
            sprintf (buffer, "Hello for the %dth time!", i) ;
            udpWrite (server, -1.0, strlen (buffer) + 1, buffer) ;
        }

        udpDestroy (client) ;			-- Deletes client and target.

    }
Note that client is the anonymous endpoint and server is a proxy for the destination endpoint.

Public Procedures

udpCreate() - creates a UDP endpoint.
udpDestroy() - destroys a UDP endpoint.
udpFd() - returns the file descriptor for an endpoint's socket.
udpIsReadable() - checks if a datagram is waiting to be read.
udpIsUp() - checks if an endpoint is up.
udpIsWriteable() - checks if a datagram can be written.
udpName() - returns the name of an endpoint.
udpRead() - reads a datagram.
udpSetBuf() - changes the sizes of an endpoint's receive and send buffers.
udpWrite() - sends a datagram.

Source Files

udp_util.c
udp_util.h

(See libnet for the complete source, including support routines and build files.)

Alex Measday  /  E-mail