SocketAddress.h

00001 
00002 /* SocketAddress
00003  * Copyright (c) 2015 ARM Limited
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef SOCKET_ADDRESS_H
00019 #define SOCKET_ADDRESS_H
00020 
00021 #include "nsapi_types.h"
00022 #include "mbed_toolchain.h"
00023 
00024 // Predeclared classes
00025 class NetworkStack;
00026 class NetworkInterface;
00027 
00028 
00029 /** SocketAddress class
00030  *
00031  *  Representation of an IP address and port pair.
00032  *  @addtogroup netsocket
00033  */
00034 class SocketAddress {
00035 public:
00036     /** Create a SocketAddress from a hostname and port
00037      *
00038      *  The hostname may be either a domain name or an IP address. If the
00039      *  hostname is an IP address, no network transactions will be performed.
00040      *
00041      *  On failure, the IP address and port will be set to zero
00042      *
00043      *  @param stack    Network stack to use for DNS resolution
00044      *  @param host     Hostname to resolve
00045      *  @param port     Optional 16-bit port, defaults to 0
00046      *  @deprecated
00047      *      Constructors hide possible errors. Replaced by
00048      *      NetworkInterface::gethostbyname.
00049      */
00050     template <typename S>
00051     MBED_DEPRECATED_SINCE("mbed-os-5.1.3",
00052                           "Constructors hide possible errors. Replaced by "
00053                           "NetworkInterface::gethostbyname.")
00054     SocketAddress(S *stack, const char *host, uint16_t port = 0)
00055     {
00056         _SocketAddress(nsapi_create_stack(stack), host, port);
00057     }
00058 
00059     /** Create a SocketAddress from a raw IP address and port
00060      * 
00061      * To construct from a host name, use NetworkInterface::gethostbyname
00062      *
00063      *  @param addr     Raw IP address
00064      *  @param port     Optional 16-bit port, defaults to 0
00065      */
00066     SocketAddress(nsapi_addr_t addr = nsapi_addr_t(), uint16_t port = 0);
00067 
00068     /** Create a SocketAddress from an IP address and port
00069      *
00070      *  @param addr     Null-terminated representation of the IP address
00071      *  @param port     Optional 16-bit port, defaults to 0
00072      */
00073     SocketAddress(const char *addr, uint16_t port = 0);
00074 
00075     /** Create a SocketAddress from raw IP bytes, IP version, and port
00076      *
00077      *  @param bytes    Raw IP address in big-endian order
00078      *  @param version  IP address version, NSAPI_IPv4 or NSAPI_IPv6
00079      *  @param port     Optional 16-bit port, defaults to 0
00080      */
00081     SocketAddress(const void *bytes, nsapi_version_t version, uint16_t port = 0);
00082 
00083     /** Create a SocketAddress from another SocketAddress
00084      *
00085      *  @param addr  SocketAddress to copy
00086      */
00087     SocketAddress(const SocketAddress &addr);
00088 
00089     /** Destructor */
00090     ~SocketAddress();
00091 
00092     /** Set the IP address
00093      *
00094      *  @param addr     Null-terminated represention of the IP address
00095      *  @return         True if address is a valid representation of an IP address,
00096      *                  otherwise False and SocketAddress is set to null
00097      */
00098     bool set_ip_address(const char *addr);
00099 
00100     /** Set the raw IP bytes and IP version
00101      *
00102      *  @param bytes    Raw IP address in big-endian order
00103      *  @param version  IP address version, NSAPI_IPv4 or NSAPI_IPv6
00104      */
00105     void set_ip_bytes(const void *bytes, nsapi_version_t version);
00106 
00107     /** Set the raw IP address
00108      *
00109      *  @param addr     Raw IP address
00110      */
00111     void set_addr(nsapi_addr_t addr);
00112 
00113     /** Set the port
00114      *
00115      *  @param port     16-bit port
00116      */
00117     void set_port(uint16_t port);
00118 
00119     /** Get the human-readable IP address
00120      *
00121      *  Allocates memory for a string and converts binary address to
00122      *  human-readable format. String is freed in the destructor.
00123      *
00124      *  @return         Null-terminated representation of the IP Address
00125      */
00126     const char *get_ip_address() const;
00127 
00128     /*  Get the raw IP bytes
00129      *
00130      *  @return         Raw IP address in big-endian order
00131      */
00132     const void *get_ip_bytes() const;
00133 
00134     /** Get the IP address version
00135      *
00136      *  @return         IP address version, NSAPI_IPv4 or NSAPI_IPv6
00137      */
00138     nsapi_version_t get_ip_version() const;
00139 
00140     /** Get the raw IP address
00141      *
00142      *  @return         Raw IP address
00143      */
00144     nsapi_addr_t get_addr() const;
00145 
00146     /** Get the port
00147      *
00148      *  @return         The 16-bit port
00149      */
00150     uint16_t get_port() const;
00151 
00152     /** Test if address is zero
00153      *
00154      *  @return         True if address is not zero
00155      */
00156     operator bool() const;
00157 
00158     /** Copy address from another SocketAddress
00159      *
00160      * @param addr  SocketAddress to copy
00161      */
00162     SocketAddress &operator=(const SocketAddress &addr);
00163 
00164     /** Compare two addresses for equality
00165      *
00166      *  @return         True if both addresses are equal
00167      */
00168     friend bool operator==(const SocketAddress &a, const SocketAddress &b);
00169 
00170     /** Compare two addresses for equality
00171      *
00172      *  @return         True if both addresses are not equal
00173      */
00174     friend bool operator!=(const SocketAddress &a, const SocketAddress &b);
00175 
00176 private:
00177     void _SocketAddress(NetworkStack *iface, const char *host, uint16_t port);
00178 
00179     mutable char *_ip_address;
00180     nsapi_addr_t _addr;
00181     uint16_t _port;
00182 };
00183 
00184 
00185 #endif
00186 
00187 /** @}*/