ACE/ace/SOCK_Dgram.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    SOCK_Dgram.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_SOCK_DGRAM_H
  12 #define ACE_SOCK_DGRAM_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include "ace/SOCK.h"
  16 #include "ace/INET_Addr.h"
  17
  18 // Included so users have access to ACE_RECVPKTINFO and ACE_RECVPKTINFO6 .
  19 #include "ace/OS_NS_sys_socket.h"
  20
  21 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  22 # pragma once
  23 #endif /* ACE_LACKS_PRAGMA_ONCE */
  24
  25 #include "ace/Addr.h"
  26
  27 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  28
  29 class ACE_Time_Value;
  30
  31 /**
  32  * @class ACE_SOCK_Dgram
  33  *
  34  * @brief Defines the member functions for the ACE_SOCK datagram
  35  * abstraction.
  36  */
  37 class ACE_Export ACE_SOCK_Dgram : public ACE_SOCK
  38 {
  39 public:
  40   /// Default constructor.
  41   ACE_SOCK_Dgram ();
  42
  43   /// This is a BSD-style method (i.e., no QoS) for initiating a socket
  44   /// dgram that will accept datagrams at the <local> address.
  45   ACE_SOCK_Dgram (const ACE_Addr &local,
  46                   int protocol_family = ACE_PROTOCOL_FAMILY_INET,
  47                   int protocol = 0,
  48                   int reuse_addr = 0,
  49                   int ipv6_only = 0);
  50
  51   /**
  52    * This is a QoS-enabed method for initiating a socket dgram that
  53    * will accept datagrams at the <local> address.  The @a qos_params
  54    * are passed to <ACE_OS::join_leaf>.
  55    */
  56   ACE_SOCK_Dgram (const ACE_Addr &local,
  57                   int protocol_family,
  58                   int protocol,
  59                   ACE_Protocol_Info *protocolinfo,
  60                   ACE_SOCK_GROUP g = 0,
  61                   u_long flags = 0,
  62                   int reuse_addr = 0,
  63                   int ipv6_only = 0);
  64
  65   /// This is a BSD-style method (i.e., no QoS) for initiating a socket
  66   /// dgram that will accept datagrams at the <local> address.
  67   int open (const ACE_Addr &local,
  68             int protocol_family = ACE_PROTOCOL_FAMILY_INET,
  69             int protocol = 0,
  70             int reuse_addr = 0,
  71             int ipv6_only = 0);
  72
  73   /**
  74    * This is a QoS-enabed method for initiating a socket dgram that
  75    * will accept datagrams at the <local> address.  The @a qos_params
  76    * are passed to <ACE_OS::join_leaf>.
  77    */
  78   int open (const ACE_Addr &local,
  79             int protocol_family,
  80             int protocol,
  81             ACE_Protocol_Info *protocolinfo,
  82             ACE_SOCK_GROUP g = 0,
  83             u_long flags = 0,
  84             int reuse_addr = 0,
  85             int ipv6_only = 0);
  86
  87   /// Default dtor.
  88   ~ACE_SOCK_Dgram ();
  89
  90   // = Data transfer routines.
  91   /// Send an @a n byte @a buf to the datagram socket (uses <sendto(3)>).
  92   ssize_t send (const void *buf,
  93                 size_t n,
  94                 const ACE_Addr &addr,
  95                 int flags = 0) const;
  96
  97   /// Receive an @a n byte @a buf from the datagram socket (uses
  98   /// <recvfrom(3)>).
  99   ssize_t recv (void *buf,
 100                 size_t n,
 101                 ACE_Addr &addr,
 102                 int flags = 0) const;
 103
 104   /**
 105    * Allows a client to read from a socket without having to provide a
 106    * buffer to read.  This method determines how much data is in the
 107    * socket, allocates a buffer of this size, reads in the data, and
 108    * returns the number of bytes read.  The caller is responsible for
 109    * deleting the member in the <iov_base> field of <io_vec> using the
 110    * ``delete []'' syntax.
 111    */
 112   ssize_t recv (iovec *io_vec,
 113                 ACE_Addr &addr,
 114                 int flags = 0,
 115                 const ACE_Time_Value *timeout = 0) const;
 116
 117   /// Send an <iovec> of size @a n to the datagram socket (uses
 118   /// <sendmsg(3)>).
 119   ssize_t send (const iovec iov[],
 120                 int n,
 121                 const ACE_Addr &addr,
 122                 int flags = 0) const;
 123
 124   /// Recv an <iovec> of size @a n to the datagram socket (uses
 125   /// <recvmsg(3)>).  The IP destination address will be placed in @a
 126   /// *to_addr if it is not null and set_option has been called with
 127   /// 1) level IPPROTO_IP, option ACE_RECVPKTINFO, and value 1 for
 128   /// IPV4 addresses or 2) IPPROTO_IPV6, option ACE_RECVPKTINFO6, and
 129   /// value 1 for IPV6 addresses.
 130   ssize_t recv (iovec iov[],
 131                 int n,
 132                 ACE_Addr &addr,
 133                 int flags = 0,
 134                 ACE_INET_Addr *to_addr = 0) const;
 135
 136   /**
 137    * Wait up to @a timeout amount of time to receive a datagram into
 138    * @a buf.  The ACE_Time_Value indicates how long to blocking
 139    * trying to receive.  If @a timeout == 0, the caller will block
 140    * until action is possible, else will wait until the relative time
 141    * specified in *@a timeout elapses).  If <recv> times out a -1 is
 142    * returned with @c errno == ETIME.  If it succeeds the number of
 143    * bytes received is returned.
 144    */
 145   ssize_t recv (void *buf,
 146                 size_t n,
 147                 ACE_Addr &addr,
 148                 int flags,
 149                 const ACE_Time_Value *timeout) const;
 150
 151   /**
 152    * Wait up to @a timeout amount of time to send a datagram to
 153    * @a buf.  The ACE_Time_Value indicates how long to blocking
 154    * trying to receive.  If @a timeout == 0, the caller will block
 155    * until action is possible, else will wait until the relative time
 156    * specified in *@a timeout elapses).  If <send> times out a -1 is
 157    * returned with @c errno == ETIME.  If it succeeds the number of
 158    * bytes sent is returned.
 159    */
 160   ssize_t send (const void *buf,
 161                 size_t n,
 162                 const ACE_Addr &addr,
 163                 int flags,
 164                 const ACE_Time_Value *timeout) const;
 165
 166   /// Send <buffer_count> worth of @a buffers to @a addr using overlapped
 167   /// I/O (uses <WSASendTo>).  Returns 0 on success.
 168   ssize_t send (const iovec buffers[],
 169                 int buffer_count,
 170                 size_t &number_of_bytes_sent,
 171                 int flags,
 172                 const ACE_Addr &addr,
 173                 ACE_OVERLAPPED *overlapped,
 174                 ACE_OVERLAPPED_COMPLETION_FUNC func) const;
 175
 176   /// Recv <buffer_count> worth of @a buffers from @a addr using
 177   /// overlapped I/O (uses <WSARecvFrom>).  Returns 0 on success.
 178   ssize_t recv (iovec buffers[],
 179                 int buffer_count,
 180                 size_t &number_of_bytes_recvd,
 181                 int &flags,
 182                 ACE_Addr &addr,
 183                 ACE_OVERLAPPED *overlapped,
 184                 ACE_OVERLAPPED_COMPLETION_FUNC func) const;
 185
 186   /// Send an @a n byte @a buf to the datagram socket (uses <WSASendTo>).
 187   ssize_t send (const void *buf,
 188                 size_t n,
 189                 const ACE_Addr &addr,
 190                 int flags,
 191                 ACE_OVERLAPPED *overlapped,
 192                 ACE_OVERLAPPED_COMPLETION_FUNC func) const;
 193
 194   /// Receive an @a n byte @a buf from the datagram socket (uses
 195   /// <WSARecvFrom>).
 196   ssize_t recv (void *buf,
 197                 size_t n,
 198                 ACE_Addr &addr,
 199                 int flags,
 200                 ACE_OVERLAPPED *overlapped,
 201                 ACE_OVERLAPPED_COMPLETION_FUNC func) const;
 202
 203   // = Meta-type info.
 204   typedef ACE_INET_Addr PEER_ADDR;
 205
 206   /// Dump the state of an object.
 207   void dump () const;
 208
 209   /// Set NIC to use as multicast interface.
 210   int set_nic (const ACE_TCHAR *net_if,
 211                int addr_family = AF_UNSPEC);
 212
 213   /// Declare the dynamic allocation hooks.
 214   ACE_ALLOC_HOOK_DECLARE;
 215
 216 protected:
 217   /// Open is shared by this and by <LSOCK_Dgram>.
 218   int shared_open (const ACE_Addr &local,
 219                    int protocol_family,
 220                    int ipv6_only = 0);
 221
 222   /// Create a multicast addr/if pair, in format useful for system calls.
 223   /// If mreq param is NULL, just verify the passed addr/interface specs.
 224   int make_multicast_ifaddr (ip_mreq *mreq,     // Put result here, if != NULL.
 225                              const ACE_INET_Addr &mcast_addr,
 226                              const ACE_TCHAR *net_if);
 227
 228 #if defined (ACE_HAS_IPV6)
 229   /// Create a multicast addr/if pair, in format useful for system calls.
 230   /// If mreq param is NULL, just verify the passed addr/interface specs.
 231   int make_multicast_ifaddr6 (ipv6_mreq *mreq,   // Put result here, if != NULL.
 232                               const ACE_INET_Addr &mcast_addr,
 233                               const ACE_TCHAR *net_if);
 234
 235 #endif /* ACE_HAS_IPV6 */
 236
 237 private:
 238   /// Do not allow this function to percolate up to this interface...
 239   int  get_remote_addr (ACE_Addr &) const;
 240 };
 241
 242 ACE_END_VERSIONED_NAMESPACE_DECL
 243
 244 #if defined (__ACE_INLINE__)
 245 #include "ace/SOCK_Dgram.inl"
 246 #endif /* __ACE_INLINE__ */
 247
 248 #include /**/ "ace/post.h"
 249 #endif /* ACE_SOCK_DGRAM_H */