logo

const class

inet::UdpSocket

sys::Obj
  inet::UdpSocket
   1  //
   2  // Copyright (c) 2007, Brian Frank and Andy Frank
   3  // Licensed under the Academic Free License version 3.0
   4  //
   5  // History:
   6  //   9 Feb 07  Brian Frank  Creation
   7  //
   8  
   9  **
  10  ** UdpSocket manages a UDP/IP datagram endpoint.
  11  **
  12  ** Note: UdpSocket is marked as a const class to give protocol developers
  13  ** the flexibility to process sockets on multiple threads.  However UdpSocket
  14  ** is inherently thread unsafe - therefore it is the developers responsibility
  15  ** to use this API in a thread safe manner.
  16  **
  17  const class UdpSocket
  18  {
  19  
  20  //////////////////////////////////////////////////////////////////////////
  21  // Construction
  22  //////////////////////////////////////////////////////////////////////////
  23  
  24    **
  25    ** Make a new unbound UDP socket.
  26    **
  27    new make() {}
  28  
  29  //////////////////////////////////////////////////////////////////////////
  30  // State
  31  //////////////////////////////////////////////////////////////////////////
  32  
  33    **
  34    ** Is this socket bound to a local address and port.
  35    **
  36    native Bool isBound()
  37  
  38    **
  39    ** Is this socket "connected" to a specific remote host.  Since
  40    ** UDP is not session oriented, connected just means we've used
  41    ** connect() to predefine the remote address where we want to
  42    ** send packets.
  43    **
  44    native Bool isConnected()
  45  
  46    **
  47    ** Is this socket closed.
  48    **
  49    native Bool isClosed()
  50  
  51  //////////////////////////////////////////////////////////////////////////
  52  // End Points
  53  //////////////////////////////////////////////////////////////////////////
  54  
  55    **
  56    ** Get the bound local address or null if unbound.
  57    **
  58    native IpAddress localAddress()
  59  
  60    **
  61    ** Get the bound local port or null if unbound.
  62    **
  63    native Int localPort()
  64  
  65    **
  66    ** Get the remote address or null if not connected to a specific end point.
  67    **
  68    native IpAddress remoteAddress()
  69  
  70    **
  71    ** Get the remote port or null if not connected to a specific end point.
  72    **
  73    native Int remotePort()
  74  
  75  //////////////////////////////////////////////////////////////////////////
  76  // Communication
  77  //////////////////////////////////////////////////////////////////////////
  78  
  79    **
  80    ** Bind this socket to the specified local address.  If addr is null
  81    ** then the default IpAddress for the local host is selected.  If port
  82    ** is null an ephemeral port is selected.  Throw IOErr if the port is
  83    ** already bound or the bind fails.  Return this.
  84    **
  85    native UdpSocket bind(IpAddress addr, Int port)
  86  
  87    **
  88    ** Connect this socket to the specified address and port.  Once
  89    ** connected packets may only be send to the remote using this socket.
  90    **
  91    native UdpSocket connect(IpAddress addr, Int port)
  92  
  93    **
  94    ** Send the packet to its specified remote endpoint.  If this is
  95    ** socket is connected to a specific remote address, then the packet's
  96    ** address and port must be null or ArgErr is thrown.  Throw IOErr
  97    ** on error.
  98    **
  99    ** The number of bytes sent is buf.remaining; upon return the buf
 100    ** is drained and position is advanced.
 101    **
 102    native Void send(UdpPacket packet)
 103  
 104    **
 105    ** Receive a packet on this socket's bound local address.  The resulting
 106    ** packet is filled in with the sender's address and port.  This method
 107    ** blocks until a packet is received.  If this socket's receiveTimeout
 108    ** option is configured, then receive will timeout with an IOErr.
 109    **
 110    ** The packet data is read into the Buf starting at it's current position.
 111    ** The buffer is *not* grown - at most Buf.capacity bytes are received.
 112    ** If the received message is longer than the packet's capacity then the
 113    ** message is silently truncated (weird Java behavior).  Upon return the
 114    ** Buf size and position are updated to reflect the bytes read.  If packet
 115    ** is null, then a new packet is created with a capacity of 4kb.
 116    **
 117    native UdpPacket receive(UdpPacket packet := null)
 118  
 119    **
 120    ** Disconnect this socket from its remote address.  Do nothing
 121    ** if not connected. Return this.
 122    **
 123    native UdpSocket disconnect()
 124  
 125    **
 126    ** Close this socket.  This method is guaranteed to never throw
 127    ** an IOErr.  Return true if the socket was closed successfully
 128    ** or false if the socket was closed abnormally.
 129    **
 130    native Bool close()
 131  
 132  //////////////////////////////////////////////////////////////////////////
 133  // Socket Options
 134  //////////////////////////////////////////////////////////////////////////
 135  
 136    **
 137    ** Access the SocketOptions used to tune this socket.  The
 138    ** following options apply to UdpSockets:
 139    **   - broadcast
 140    **   - receiveBufferSize
 141    **   - sendBufferSize
 142    **   - reuseAddress
 143    **   - receiveBufferSize
 144    **   - trafficClass
 145    **  Accessing other option fields will throw UnsupportedErr.
 146    **
 147    native SocketOptions options()
 148  
 149    internal native Bool getBroadcast()
 150    internal native Void setBroadcast(Bool v)
 151  
 152    internal native Int getReceiveBufferSize()
 153    internal native Void setReceiveBufferSize(Int v)
 154  
 155    internal native Int getSendBufferSize()
 156    internal native Void setSendBufferSize(Int v)
 157  
 158    internal native Bool getReuseAddress()
 159    internal native Void setReuseAddress(Bool v)
 160  
 161    internal native Duration getReceiveTimeout()
 162    internal native Void setReceiveTimeout(Duration v)
 163  
 164    internal native Int getTrafficClass()
 165    internal native Void setTrafficClass(Int v)
 166  
 167  }