inc/FNetSockSocketIpMulticastRequestOption.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18
  19 /**
  20 * @file         FNetSockSocketIpMulticastRequestOption.h
  21 * @brief        This is the header file for the %IpMulticastRequestOption class.
  22 *
  23 * This header file contains the declarations of the %IpMulticastRequestOption class.
  24 */
  25
  26 #ifndef _FNET_SOCK_SOCKET_IP_MULTICAST_REQUEST_OPTION_H_
  27 #define _FNET_SOCK_SOCKET_IP_MULTICAST_REQUEST_OPTION_H_
  28
  29 #include <FBaseObject.h>
  30 #include <FNetNetEndPoint.h>
  31
  32 namespace Tizen { namespace Net { namespace Sockets
  33 {
  34
  35 class _IpMulticastRequestOptionImpl;
  36
  37 /**
  38 * @class        IpMulticastRequestOption
  39 * @brief        This class supports the multicasting in sockets for sending and receiving multicast datagram packets.
  40 *                       For multicasting, a socket must be of type NET_SOCKET_TYPE_DATAGRAM.
  41 *
  42 * @since        2.0
  43 *
  44 * The %IpMulticastRequestOption class supports the multicasting in sockets for sending and receiving multicast datagram packets.
  45 *                       For multicasting, a socket must be of type ::NET_SOCKET_TYPE_DATAGRAM.
  46 *
  47 *       For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/net/sockets.htm">Sockets Guide</a>.
  48 *
  49 * @see          Tizen::Net::Sockets::Socket::SetSockOpt(NetSocketOptLevel, NetSocketOptName, const IpMulticastRequestOption&)
  50 *
  51 * The following example demonstrates how to use the %IpMulticastRequestOption class with the multicast sender.
  52 *
  53 *       @code
  54 *                               result res = E_SUCCESS;
  55 *
  56 *                               // Creates the socket.
  57 *                               Socket* pSocket = new Socket();
  58 *                               res = pSocket->Construct(NET_SOCKET_AF_IPV4, NET_SOCKET_TYPE_DATAGRAM, NET_SOCKET_PROTOCOL_UDP);
  59 *
  60 *                               // Adds the listener.
  61 *                               MySocketListener* pSockListener = new MySocketListener();
  62 *                               res = pSocket->AddSocketListener(*pSockListener);
  63 *
  64 *                               // Selects the async event(non-blocking mode).
  65 *                               res = pSocket->AsyncSelectByListener(NET_SOCKET_EVENT_WRITE);
  66 *
  67 *                               // Creates the multicast group end point to send the data.
  68 *                               Ip4Address multicastAddr("224.1.1.1"); // Multicast group address
  69 *                               unsigned short multicastPort = XXXX;  // Multicast group port
  70 *                               NetEndPoint multicastEndPoint(multicastAddr, multicastPort);
  71 *
  72 *                               // Creates the data to send.
  73 *                               const char* pSendData = "Send";
  74 *                               Tizen::Base::ByteBuffer txBuffer;
  75 *                               txBuffer.Construct(strlen(pSendData) + 1);
  76 *                               txBuffer.SetArray((byte*)pSendData, 0, strlen(pSendData));
  77 *                               txBuffer.Flip();
  78 *
  79 *                               // Sends the data to the multicast group
  80 *                               res = ptSocket->SendTo(txBuffer, multicastEndPoint);
  81 *       @endcode
  82 *
  83 * The following example demonstrates how to use the %IpMulticastRequestOption class with the multicast receiver.
  84 *
  85 *       @code
  86 *                               result res = E_SUCCESS;
  87 *
  88 *                               // Creates the socket.
  89 *                               Socket* pSocket = new Socket();
  90 *                               res = pSocket->Construct(NET_SOCKET_AF_IPV4, NET_SOCKET_TYPE_DATAGRAM, NET_SOCKET_PROTOCOL_UDP);
  91 *
  92 *                               // Adds the listener.
  93 *                               MySocketListener* pSockListener = new MySocketListener();
  94 *                               res = pSocket->AddSocketListener(*pSockListener);
  95 *
  96 *                               // Selects the async event(non-blocking mode).
  97 *                               res = pSocket->AsyncSelectByListener(NET_SOCKET_EVENT_READ);
  98 *
  99 *                               // Binds the local interface end point to receive the data.
 100 *                               Ip4Address localAddr(NET_SOCKET_INADDR_ANY); // Any incoming interface
 101 *                               unsigned short localPort = XXXX;  // Multicast group port
 102 *                               NetEndPoint localEndPoint(localAddr, localPort);
 103 *                               res = pSocket->Bind(localEndPoint);
 104 *
 105 *                               // Creates the multicast group end point.
 106 *                               Ip4Address multicastAddr("224.1.1.1"); // Multicast group address
 107 *                               unsigned short multicastPort = YYYY;  // Any available port, which will not be used for other operations
 108 *                               NetEndPoint multicastEndPoint(multicastAddr, multicastPort);
 109 *
 110 *                               // Creates the local interface end point.
 111 *                               Ip4Address interfaceAddr(NET_SOCKET_INADDR_ANY); // Local interface address
 112 *                               unsigned short interfacePort = ZZZZ;  // Any available port, which will not be used for other operations
 113 *                               NetEndPoint interfaceEndPoint(interfaceAddr, interfacePort);
 114 *
 115 *                               // Specifies the IpMulticastRequestOption.
 116 *                               IpMulticastRequestOption ipMreq(multicastEndPoint, interfaceEndPoint);
 117 *
 118 *                               // Joins the multicast group.
 119 *                               res = pSocket->SetSockOpt(NET_SOCKET_IPPROTO_IP, NET_SOCKET_IP_ADD_MEMBERSHIP, ipMreq);
 120 *
 121 *                               // Creates the buffer to receive the data.
 122 *                               Tizen::Base::ByteBuffer rxBuffer;
 123 *                               rxBuffer.Construct(MAX_BUFFER_SIZE);
 124 *
 125 *                               // Receives the data from the multicast group.
 126 *                               res = pSocket->ReceiveFrom(rxBuffer, localEndPoint);
 127 *       @endcode
 128 */
 129 class _OSP_EXPORT_ IpMulticastRequestOption
 130         : public Tizen::Base::Object
 131 {
 132
 133 public:
 134         /**
 135          * Initializes this instance of %IpMulticastRequestOption with the specified parameters.
 136          *
 137          * @since               2.0
 138          *
 139          * @param[in]   multicastAddress                A NetEndPoint instance containing the IP address and port of the multicast group to join
 140          * @param[in]   interfaceAddress                A NetEndPoint instance containing the IP address and port of the network interface on which the datagram
 141          *                                                                              packets will be received
 142          * @exception   E_SUCCESS                               The method is successful.
 143          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 144          * @exception   E_SYSTEM                                An internal error has occurred.
 145          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 146          */
 147         IpMulticastRequestOption(const NetEndPoint& multicastAddress, const NetEndPoint& interfaceAddress);
 148
 149         /**
 150          * This destructor overrides Tizen::Base::Object::~Object().
 151          *
 152          * @since               2.0
 153          */
 154         virtual ~IpMulticastRequestOption(void);
 155
 156         /**
 157         * Copying of objects using this copy constructor is allowed.
 158         *
 159         * @since                2.0
 160         *
 161         * @param[in]    rhs                     An instance of %IpMulticastRequestOption
 162         */
 163         IpMulticastRequestOption(const IpMulticastRequestOption& rhs);
 164
 165         /**
 166         * Copying of objects using this copy assignment operator is allowed.
 167         *
 168         * @since                2.0
 169         *
 170         * @return               A reference to this instance
 171         * @param[in]    rhs                     An instance of %IpMulticastRequestOption
 172         */
 173         IpMulticastRequestOption& operator =(const IpMulticastRequestOption& rhs);
 174
 175 public:
 176         /**
 177          * Sets the multicast group NetEndPoint instance with the specified instance.
 178          *
 179          * @since               2.0
 180          *
 181          * @return              An error code
 182          * @param[in]   multicastAddress                A NetEndPoint instance containing the IP address and port of the multicast group to join
 183          * @exception   E_SUCCESS                               The method is successful.
 184          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 185          */
 186         result SetMulticastEndPoint(NetEndPoint& multicastAddress);
 187
 188         /**
 189          * Sets the network interface NetEndPoint with the specified instance.
 190          *
 191          * @since               2.0
 192          *
 193          * @return              An error code
 194          * @param[in]   interfaceAddress                A NetEndPoint instance containing the address and port of the network interface on which the datagram
 195          *                                                                              packets will be received
 196          * @exception   E_SUCCESS                               The method is successful.
 197          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 198          */
 199         result SetInterfaceEndPoint(NetEndPoint& interfaceAddress);
 200
 201         /**
 202         * Gets the NetEndPoint of the multicast group.
 203         *
 204         * @since                2.0
 205         *
 206         * @return               The multicast group NetEndPoint, @n
 207         *                               else @c null if the multicast group %NetEndPoint is @c null
 208         * @exception    E_SUCCESS                               The method is successful.
 209         * @exception    E_INVALID_STATE                 The group end point is in an invalid state.
 210         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 211         */
 212         const NetEndPoint* GetMulticastEndPoint(void) const;
 213
 214         /**
 215         * Gets the NetEndPoint of the network interface.
 216         *
 217         * @since                2.0
 218         *
 219         * @return               The network interface NetEndPoint, @n
 220         *                               else @c null if the network interface %NetEndPoint is @c null
 221         * @exception    E_SUCCESS                       The method is successful.
 222         * @exception    E_INVALID_STATE         The interface end point is in an invalid state.
 223         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 224         */
 225         const NetEndPoint* GetInterfaceEndPoint(void) const;
 226
 227         /**
 228          * Compares the specified instance of %IpMulticastRequestOption with the calling instance.
 229          *
 230          * @since               2.0
 231          * @return              @c true if the values match, @n
 232          *                      else @c false
 233          * @param[in]   obj     The other Tizen::Base::Object to compare
 234          * @see                 Tizen::Base::Object::Equals()
 235          */
 236         virtual bool Equals(const Tizen::Base::Object& obj) const;
 237
 238         /**
 239          * Gets the hash value of the current instance.
 240          *
 241          * @since               2.0
 242          *
 243          * @return      The hash value of the current instance
 244          */
 245         virtual int GetHashCode(void) const;
 246
 247 private:
 248         /**
 249         * This default constructor is intentionally declared as private so that only the platform can create an instance.
 250         */
 251         IpMulticastRequestOption(void);
 252
 253 private:
 254         _IpMulticastRequestOptionImpl* __pIpMulticastRequestOptionImpl;
 255
 256         friend class _IpMulticastRequestOptionImpl;
 257 };
 258
 259 } } } // Tizen::Net::Sockets
 260 #endif // _FNET_SOCK_SOCKET_IP_MULTICAST_REQUEST_OPTION_H_