Source/Base/Network/Socket.dox

   1 #include "OSGConfig.h"
   2
   3 using namespace OSG;
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16 #if 0
  17
  18 /*! \page PageBaseSocket Socket
  19
  20 Socket baseclass. The Socket class wraps a socket descriptor. This
  21 class has no additional state variables. It is only h handle to the
  22 underlaying descriptor. Class createion and destruction has no
  23 influence to any descriptor. Use open to assign a descriptor and
  24 close to remove it from the system. If this class is copied, then
  25 there are to classes which uses the same descriptor. This is
  26 ok until you call close for one of this classes.
  27 One purpose of this implementation is to hide the differences between
  28 Windows and Unix sockets. Calls to this class should behave equally
  29 on all systems. As a result, some methods will not work as an
  30 experienced Windows ore Unix programmer maight expect. Please refere
  31 to the function docu to get details about this.
  32
  33 Stream sockets
  34
  35 A stream socket is an endpoint for a reliable point to point
  36 communication. The following example code shows, how to establish a
  37 stream socket connection.
  38
  39 <PRE>
  40 // server code
  41 StreamSocket socket,client;
  42 socket.open();
  43 socket.bind(SocketAddress(SocketAddress::ANY,12345));
  44 client=socket.accept();
  45 client.send(buffer,100);
  46 client.close();
  47 socket.close();
  48
  49 // client code
  50 StreamSocket server;
  51 server.open();
  52 server.connect(SocketAddress("localhost",12345));
  53 server.recv(buffer,100);
  54 server.close();
  55 </PRE>
  56
  57 The method bind() assigns the socket to a given port and network
  58 device. If the network device is ANY, then the socket will accept
  59 connections from all network interfaces. If the port number is zero,
  60 then a free port is assigned. In the above example, the socket will
  61 accept incoming connections at each interface on the port
  62 12345. StreamSocket::accept() waits for a incoming connection. For
  63 each incoming connection a new socket object will be created. With
  64 send and recv data can be transferred over the connection. By default
  65 all calls will block until the operation has finished.
  66
  67 Datagram sockets
  68
  69 Datagram sockets are not connection orientated. There is no connect or
  70 accept methods for datagram sockets. You have to provide a destination
  71 address for each send and will get a source address for each recv
  72 call. There is no guarantee that packages will arrive and there is no
  73 guarantee for the order in which the package will arrive. The followin
  74 code shows how to wait for incoming packages at port 22222.
  75
  76 <PRE>
  77 SocketAddress client;
  78 DgramSocket socket;
  79 socket.open();
  80 socket.bind(SocketAddress(SocketAddress::ANY,22222))
  81 socket.recvFrom(buffer,100,client);
  82 socket.close();
  83 </PRE>
  84
  85 This is the code to send the package. This is a simple example. If the
  86 package gets lost for example because the server is not started, then
  87 this code wont work. If your application relays on reliable data
  88 transmission, then StreamSockets should be used.
  89
  90 <PRE>
  91 DgramSocket sock;
  92 SocketAddress server;
  93 socket.open();
  94 socket.sendTo("hallo",100,SocketAddress("localhost",22222));
  95 socket.close();
  96 </PRE>
  97
  98 Exceptions:
  99
 100 All socket methods will throw exceptions if the desired function could
 101 not be finished. All socket related exceptions are derived from the
 102 SocketException class. All socket calls should be enclosed in
 103 try/catch blocks. For example, if you want to check if a connect
 104 operation was successful then you should use the following code.
 105
 106 <PRE>
 107 try
 108 {
 109     server..connect(SocketAddress("localhost",12345));
 110 }
 111 catch(SocketException &e)
 112 {
 113     SFATAL << "Unable to connect to server:" << e.what() << endl;
 114 }
 115 </PRE>
 116
 117 Each exceptions contains the system error text that causes the error
 118 situation. This text can be accessed by SocketException::what(). The
 119 text is given as an std:string object.
 120
 121 Broadcast Messages
 122
 123 Broadcast packages are a special case of datagram packages. Broadcast
 124 packages are send to each host in a network. For broadcasting packages
 125 a special address type is used. For example with the address
 126 SocketAddress(SocketAddress::BROADCAST,2345) packages will be send to each
 127 host on port number 2345. Equal to normal datagram sockets, broadcast
 128 packages are transmitted not reliable.
 129
 130 Multicast Messages
 131
 132 With multicast it is possible to send packages to more then one
 133 destination. In contrast to broadcast the package is not send to all
 134 hosts but only to those hosts that have joined a multicast group. A
 135 multicast group is specified with special IP addresses
 136 (224.xxx.xxx.xxx). To write a package to the multicast group
 137 224.22.33.33 at port 4444 you could use
 138
 139 <PRE>
 140 socket.sendTo(buffer,100,SocketAddress("224.22.33.44",4444)
 141 </PRE>
 142
 143 The receive has to join this group. The following examples shows how
 144 to join and leave multicast groups. It is possible to join more then
 145 one group.
 146
 147 <PRE>
 148 socket.bind(SocketAddress(SocketAddress::ANY,4444));
 149 socket.join(SocketAddress("224.22.33.44"));
 150 socket.join(SocketAddress("224.0.0.52"));
 151 socket.join(SocketAddress("224.0.0.53"));
 152 socket.leave(SocketAddress("224.0.0.52"));
 153 </PRE>
 154
 155 With multicast groups you also have to bind your socket to a network
 156 device and port. In the example above only those packages are received
 157 that are send to port 4444. With multicast it often happens, that you
 158 have more then one member of a multicast group on a single host. If
 159 you try to call bind for the same port multiple times, then you will
 160 get socket exceptions. To be able to assign more then one process to
 161 the same port you have to call  socket.setReusePort(true) before the
 162 call to bind.
 163
 164 It is possible set the network device that is used to send
 165 multicast packages. By default the system uses the first device
 166 that is capable to send multicast packages.
 167
 168 <PRE>
 169 socket.setInterface(SocketAddress("192.168.10.1"));
 170 </PRE>
 171
 172
 173 Nonblocking IO
 174
 175 In many applications it is not possible or not wanted to block
 176 execution until an accept() or recv() call has finished. Each socket
 177 has methods to ask if it is possible to read or write data without
 178 blocking. The followin examples shows how to wait for data without
 179 blocking.
 180
 181 <UL>
 182 <LI>socket.waitReadable(0): Don't wait, returns true if data is
 183 available otherwise it returns false.
 184 <LI>socket.waitReadable(0.5): If data arrives in the next .5 seconds
 185 then true is returned. Otherwise false is returned.
 186 <LI>socket.waitReadable(-1): Wait until data is available and then
 187 return true. This function call is equal to a blocking read.
 188 <LI>socket.waitWritable(10): If the socket is able to send data in the
 189 next 10 seconds, then true is returned. Otherwise false.
 190 </UL>
 191
 192 With this simple interface it is possible to wait a specified time for
 193 incoming or outgoing data. But it is only possible to wait for exactly one
 194 socket. If it is necessary to wait for more then one socket then the
 195 Selection class could be used.  A selection specifies for each socket
 196 for what kind of event the system should wait.
 197
 198 <PRE>
 199 SocketSelection s;
 200 s.setRead(socket1);
 201 s.setRead(socket2);
 202 s.select(.1);
 203 if(s.isSetRead(sock1))
 204    socket 1 is readable
 205 if(s.isSetRead(sock2))
 206    socket 1 is readable
 207 </PRE>
 208
 209 A call of selection.select(seconds) waits the given number of seconds for the
 210 events set with setRead() or serWrite(). It returns after the first occurrence
 211 of an event.  If no events occur in the given periode then 0 is
 212 returned. Otherwise the number of readable and writable sockets is
 213 returned. The method select() modifies the selection object. You have to call
 214 setRead() and setWrite() for each time, you want to call select(). If the
 215 SocketSelection is constant, then you can use an other version of select. With
 216 s.select(seconds,rs) s will not be modified. The result will be set into the
 217 SocketSelection rs. You have to call rs.isReadable(sock) instead of
 218 s.isReadable(sock).
 219
 220 IO-Buffers
 221
 222 If data should be read from more then one socket, then the performance could
 223 be improved by not reading from the first socket that provides data but from
 224 that socket with the most data in the input buffer. With socket.getAvailable()
 225 the number of bytes in the input buffer could be retrieved. In addition the
 226 Socket class provides the functions setWriteBufferSize and setReadBufferSize
 227 set the size of input and output buffers. Current sizes can be retrieved with
 228 getReadBufferSize and getWriteBufferSize.
 229
 230 */
 231 #endif