UDPSocket.h

00001 /* Copyright (c) 2013 Henry Leinen (henry[dot]leinen [at] online [dot] de)
00002  *
00003  * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
00004  * and associated documentation files (the "Software"), to deal in the Software without restriction,
00005  * including without limitation the rights to use, copy, modify, merge, publish, distribute,
00006  * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
00007  * furnished to do so, subject to the following conditions:
00008  *
00009  * The above copyright notice and this permission notice shall be included in all copies or
00010  * substantial portions of the Software.
00011  *
00012  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
00013  * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
00014  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
00015  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00016  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00017  */
00018 #ifndef __UDPSOCKET_H__
00019 #define __UDPSOCKET_H__
00020 
00021 #include "Socket/Socket.h"
00022 #include "Socket/Endpoint.h"
00023 
00024 /** Class UDPSocket, inherits from class Socket and implements the functionality of a UDP Socket when using a WifiPlusClick module.
00025   * @note Please note that the functionality provided by a WifiPlusClick module is limited. Neither broadcasting nor multicasting functionality is possible.
00026   */
00027 class UDPSocket : public Socket
00028 {
00029 public:
00030     /** UDPSocket constructor to instantiate a UDPSocket object.  */
00031     UDPSocket();
00032     
00033     /** Function init provides initialization of the UDPSocket object.
00034       * @returns : true if successfull, or false otherwise.
00035       */
00036     int init(void);
00037     
00038     /** Function bind will bind a UDPSocket to a local port. The socket object should not already have been used for other purposes before.
00039       * @note Please note that there is currently no check implemented as to wheather or not the socket has already been used before.
00040       * @parameter port : The port to which to bind the UDPSocket to. If the port is specified as zero, a non-zero value beginning with 1024 will be selected.
00041       * @returns : 0 if successfull, or -1 otherwise.
00042       */
00043     int bind(unsigned int port = 0);
00044     
00045     /** Function join_multicast_group.
00046       * @note This function is not implemented as the WifiPlusClick module does not support this functionality.
00047       */
00048     int join_multicast_group(const char *address);
00049     
00050     /** Function set_broadcasting.
00051       * @note This fnction is not implemented as the WifiPlusClick module does not support this functionality.
00052       */
00053     int set_broadcasting(bool broadcast=true);
00054     
00055     /** Function sendTo implements sending of a packet to a specific endpoint. Make sure to use it on an initialized or bound socket.
00056       * @param remote : a reference to a valid endpoint specifying the remote ip-address and the remote port where to send the packet.
00057       * @param packet : a pointer to a valid buffer containing the packet data to send.
00058       * @param length : Specifies the number of data bytes to send.
00059       * @returns : the number of databytes actually sent or -1 on failure.
00060       */
00061     int sendTo(Endpoint &remote, char *packet, int length);
00062     
00063     /** Function receiveFrom implements receiving a packet of data on a socket. The remote address will be provided on return. Make sure to use it on an initialized or bound socket.
00064       * @param remote : a reference to an endpoint, which will receive the remote ip-address and the remote port from where data was returned.
00065       * @param packet : a data buffer which will receive the received data. The buffer must be at least as larget as length bytes.
00066       * @param length : The maximum number of bytes to receive. Please make sure that the buffer packet is large enough to hold this data completely.
00067       * @returns : the number of databytes actually received or -1 on failure. @note there may be more data received than what the buffer can store. Any data that does not fit in the buffer is discarded !
00068       */
00069     int receiveFrom(Endpoint &remote, char *packet, int length);
00070 };
00071 
00072 #endif // __UDPSOCKET_H__