inc/FNetSockSocketUtility.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         FNetSockSocketUtility.h
  21 * @brief        This is the header file for the %SocketUtility class.
  22 *
  23 * This header file contains the declarations of the %SocketUtility class. @n
  24 * This class provides utility methods for socket operations.
  25 */
  26
  27 #ifndef _FNET_SOCK_SOCKET_UTILITY_H_
  28 #define _FNET_SOCK_SOCKET_UTILITY_H_
  29
  30 #include <FBaseCol.h>
  31
  32 namespace Tizen { namespace Net { namespace Sockets
  33 {
  34
  35 class _SocketUtilityImpl;
  36
  37 /**
  38 * @class        SocketUtility
  39 * @brief        This class provides the utility methods for the Socket class.
  40 *
  41 * @since    2.0
  42 *
  43 * The %SocketUtility class provides the utility methods for the Socket class.
  44 *
  45 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/net/sockets.htm">Sockets Guide</a>.
  46 */
  47 class _OSP_EXPORT_ SocketUtility
  48         : public Tizen::Base::Object
  49 {
  50
  51 public:
  52         /**
  53         * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
  54         *
  55         * @since                2.0
  56         */
  57         SocketUtility(void);
  58
  59         /**
  60         * This destructor overrides Tizen::Base::Object::~Object().
  61         *
  62         * @since        2.0
  63         */
  64         virtual ~SocketUtility(void);
  65
  66         /**
  67         * Initializes this instance of %SocketUtility.
  68         *
  69         * @since                2.0
  70         *
  71         * @return               An error code
  72         * @exception    E_SUCCESS                               The method is successful.
  73         * @exception    E_INVALID_STATE                 This instance is in an invalid state.
  74         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
  75         * @exception    E_SYSTEM                                Interface creation has failed.
  76         */
  77         result Construct(void);
  78
  79         /**
  80         * Determines the status of one or more sockets.
  81         *
  82         * @since                        2.0
  83         * @privlevel            public
  84         * @privilege            http://tizen.org/privilege/socket
  85         *
  86         * @return                       An error code
  87         * @param[in,out]        pCheckRead                                      A Tizen::Base::Collection::IList of Socket instances to check for readability
  88         * @param[in,out]        pCheckWrite                             A Tizen::Base::Collection::IList of Socket instances to check for writability
  89         * @param[in,out]        pCheckError                             A Tizen::Base::Collection::IList of Socket instances to check for errors
  90         * @param[in]            microSeconds                            The time to wait for a response, in microseconds
  91         * @exception            E_SUCCESS                                       The method is successful.
  92         * @exception            E_INVALID_SOCKET                        The socket is invalid.
  93         * @exception            E_INVALID_STATE                         The socket is in an invalid state.
  94         * @exception            E_UNSUPPORTED_OPTION            The specified parameters are not supported.
  95         * @exception            E_INVALID_ARG                           A specified input parameter is invalid.
  96         * @exception            E_TIMEOUT                                       The time limit has expired.
  97         * @exception            E_NETWORK_UNAVAILABLE           The network is unavailable.
  98         * @exception        E_OUT_OF_MEMORY                             The memory is insufficient.
  99         * @exception            E_SYSTEM                                        A system error has occurred.
 100         * @exception        E_PRIVILEGE_DENIED                  The application does not have the privilege to call this method.
 101         * @remarks              This method determines the status of one or more
 102         *               Socket instances. There must be at least one socket in an Tizen::Base::Collection::IList
 103         *               before this method is used.
 104         *               To check sockets for readability and writability use @c pCheckRead and @c pCheckWrite of type
 105         *                               %IList respectively by calling this method.
 106         *               To detect error conditions, use @c pCheckError.
 107         *               After calling this method, the %IList is filled with only those sockets that satisfy the conditions. @n
 108         *               All the receive operations succeed without blocking in the following cases: @n
 109         *                               -#  If the socket is in a listening state, the readability means that a call to Accept() succeeds without blocking.
 110         *                               -#  If the connection on a socket is accepted, the readability means that the data is available for reading. @n
 111         *               The readability can also indicate whether the remote socket has shutdown the connection. In this
 112         *               case a call to SecureSocket::Receive() or Socket::Receive() returns immediately with @c 0 bytes.
 113         *               If a non-blocking call to SecureSocket::Connect() or Socket::Connect() is made, the writability means that the connection is
 114         *                               successful and the @c pCheckError parameter identifies the sockets that are not
 115         *                               connected successfully. @n
 116         *               If a connection has already been established, the writability means that all the send operations
 117         *                               have succeeded without blocking.
 118         */
 119         result Select(Tizen::Base::Collection::IList* pCheckRead, Tizen::Base::Collection::IList* pCheckWrite, Tizen::Base::Collection::IList* pCheckError, int microSeconds);
 120
 121         /**
 122         * Converts the specified unsigned @c short integer from a host @c byte order to a network @c byte order.
 123         *
 124         * @since                2.0
 125         *
 126         * @return               An unsigned @c short integer in network @c byte order
 127         * @param[in]    hostShort               An unsigned @c short integer in host @c byte order
 128         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 129         * @see                  NtoHS()
 130         */
 131         unsigned short HtoNS(unsigned short hostShort);
 132
 133         /**
 134         * Converts the specified unsigned @c long integer from a host @c byte order to a network @c byte order.
 135         *
 136         * @since                2.0
 137         *
 138         * @return               An unsigned @c long integer in network @c byte order
 139         * @param[in]    hostLong                An unsigned @c long integer in host @c byte order
 140         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 141         * @see                  NtoHL()
 142         */
 143         unsigned long HtoNL(unsigned long hostLong);
 144
 145         /**
 146         * Converts the specified unsigned @c short integer from a network @c byte order to a host @c byte order.
 147         *
 148         * @since                2.0
 149         *
 150         * @return               An unsigned @c short integer in host @c byte order
 151         * @param[in]    netShort                An unsigned @c short integer in network @c byte order
 152         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 153         * @see                  HtoNS()
 154         */
 155         unsigned short NtoHS(unsigned short netShort);
 156
 157         /**
 158         * Converts the specified unsigned @c long integer from a network @c byte order to a host @c byte order.
 159         *
 160         * @since                2.0
 161         *
 162         * @return               An unsigned @c long integer in host @c byte order
 163         * @param[in]    netLong                 An unsigned @c long integer in network @c byte order
 164         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 165         * @see                  HtoNL()
 166         */
 167         unsigned long NtoHL(unsigned long netLong);
 168
 169 private:
 170         /**
 171         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 172         *
 173         * @param[in]    rhs                     An instance of %SocketUtility
 174         */
 175         SocketUtility(const SocketUtility& rhs);
 176
 177         /**
 178         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 179         *
 180         * @return               A reference to this instance
 181         * @param[in]    rhs                     An instance of %SocketUtility
 182         */
 183         SocketUtility& operator =(const SocketUtility& rhs);
 184
 185 private:
 186         _SocketUtilityImpl* __pSocketUtilityImpl;
 187
 188         friend class _SocketUtilityImpl;
 189 };
 190
 191 } } } // Tizen::Net::Sockets
 192 #endif // _FNET_SOCK_SOCKET_UTILITY_H_