xHarbour Reference Documentation > Function Reference

INetDGramSend()

Sends data to a datagram socket.

Syntax

INetDGramSend( <pSocket>   , ;
               <cIPAddress>, ;
               <nPort>     , ;
               <cData>     , ;
              [<nBytes>]     ) --> nSentBytes

Arguments

<pSocket>

This is a pointer to a socket as returned by INetDGram() or INetDGramBind()

<cIPAddress>

This is a character string holding the IP address of a remote station in dotted notation (e.g. "192.168.1.145").

<nPort>

This is the numeric port number on the local computer to use for sending data. Valid port numbers must be in the range from 0 to 65535.

<cData>

A character string holding the actual data to send via <pSocket>.

<nBytes>

This is a numeric value specifying the number of bytes to send. It defaults to Len(<cBuffer>).

Return

The function returns a numeric value indicating the number of bytes sent on the socket, or -1 on error. Use function INetErrorCode() to detect the cause of failure.

Description

Function INetDGramSend() sends the number of <nBytes> bytes of <cData> from the local computer to the specified IP address and port via the datagram socket <pSocket>.

If the function succeds, it returns the number of bytes that are actually sent.

Note:  there is no guarantee that all the data requested to be sent is actually sent to the socket when its size exceeds the system datagram size. Therefore, the return value should be compared with the length of <cData> and, if a smaller value is returned, INetDGramSend() should be called iteratively to send remaining data until the message is complete.

Info

See also:	INetDGram(), INetDGramBind(), INetDGramRecv()
Category:	Datagram functions , Sockets functions , xHarbour extensions
Source:	vm\INet.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Examples

UDP Server

// This example implements a simple User Datagram Protocol server demonstrating
// basic steps for exchanging datagrams. A bound server socket is created with
// INetDGramBind(). Then the DO WHILE loop checks the keyboard twice a second.
// If no key is pressed, the server checks for incoming data with INetDataReady().
// If there is data, it is read in procedure ServeDGram() and an "OK!" response
// is returned to the connecting process.

   PROCEDURE Main
      LOCAL pSocket, cData

      CLS

      INetInit()

      // listen on port 1800
      pSocket := InetDGramBind( 1800 )

      ? "Server up and running", pSocket
      ? "Press any key to quit"

      DO WHILE Inkey(.5) == 0
         // check for incoming connection requests
         IF INetDataReady( pSocket ) > 0
            // process datagram connection
            ServeDGram( pSocket )
         ELSE
            // display some kind of "I am still alive" message
            ?? "."
         ENDIF
      ENDDO

      // close socket and cleanup memory
      INetClose( pSocket )
      INetCleanup()
   RETURN


   PROCEDURE ServeDGram( pSocket )
      LOCAL cBuffer, nBytes, cData := Space(80)

      // display IP address of client
      ? "Serving:", INetAddress( pSocket )

      // receive datagram (max 80 bytes in this example)
      nBytes := INetDGramRecv( pSocket, @cData, Len(cData) )

      ? "Bytes received:", nBytes
      ? "Data  received:", Left( cData, nBytes )

      // report "OK!" to remote process
      INetDGramSend( pSocket, INetAddress( pSocket ), INetPort( pSocket ), "OK!" )
   RETURN

UDP Client

// This example is the client side of a User Datagram Protocol communication.
// The client socket is created being capable of receiving broadcast messages.
// The user can enter data in a single GET. This data is transferred to the
// server process, and the response of the server process is displayed in the
// local process.
// Since a maximum of only 80 bytes is sent in the example, INetDGramSend()
// is not called iteratively.

   #include "Inkey.ch"

   PROCEDURE Main( cServerIPAddress )
      LOCAL pSocket, cData, nBytes

      IF Empty( cServerIPAddress )
         // IP address of the local station
         cServerIPAddress := "127.0.0.255"
      ENDIF

      INetInit()

      // create an unbound broadcast socket
      pSocket := INetDGRam( .T. )

      IF InetDGramSend( pSocket, cServerIPAddress, 1800, "ALIVE?" ) < 1
         ? "Unable to connect to "
         ?? cServerIPAddress, "Error:", InetErrorDesc( Socket )
         INetCleanUp()
         QUIT
      ELSE
         ? "Found a server at ", InetAddress( pSocket )
         WAIT
      ENDIF

      // set max. timeout to 10 seconds for receiving server response
      INetSetTimeout( pSocket, 10000 )

      DO WHILE Lastkey() <> K_ESC
         CLS

         // let the user enter some data
         cData := Space(80)
         @ 2,2 SAY "Enter a string:" GET cData PICTURE "@S30"
         READ

         IF Lastkey() == K_ESC
            EXIT
         ENDIF

         cData  := Trim( cData )
         nBytes := Len ( cData )

         InetDGramSend( pSocket, cServerIPAddress, 1800, cData, nBytes )

         CLS
         ? "sent:", LTrim(Str(nBytes)), "bytes"

         // Receive the server's response
         cData := Space( 80 )

         nBytes := INetDGramRecv( pSocket, @cData, 80 )

         IF INetErrorCode( pSocket ) == 0
            ? "received:", Left( cData, nBytes )
         ELSE
            ? "error:", INetErrorDesc( pSocket )
         ENDIF

         WAIT
      ENDDO

      // disconnect socket
      INetClose( pSocket )

      INetCleanUp()
   RETURN