fnet_inet.h

00001 /**************************************************************************
00002 *
00003 * Copyright 2011-2016 by Andrey Butok. FNET Community.
00004 * Copyright 2008-2010 by Andrey Butok. Freescale Semiconductor, Inc.
00005 * Copyright 2003 by Andrey Butok. Motorola SPS.
00006 *
00007 ***************************************************************************
00008 *
00009 *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00010 *  not use this file except in compliance with the License.
00011 *  You may obtain a copy of the License at
00012 *
00013 *  http://www.apache.org/licenses/LICENSE-2.0
00014 *
00015 *  Unless required by applicable law or agreed to in writing, software
00016 *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00017 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00018 *  See the License for the specific language governing permissions and
00019 *  limitations under the License.
00020 *
00021 **********************************************************************/
00022 /*!
00023 * @brief Address-conversion functions API.
00024 *
00025 ***************************************************************************/
00026 
00027 #ifndef _FNET_INET_H_
00028 
00029 #define _FNET_INET_H_
00030 
00031 /*! @addtogroup fnet_socket
00032 */
00033 /*! @{ */
00034 
00035 #if defined(__cplusplus)
00036 extern "C" {
00037 #endif
00038 
00039 /***************************************************************************/ /*!
00040  *
00041  * @brief    Converts an IPv4 address into a string in Internet
00042  *           standard dotted-decimal format.
00043  *
00044  *
00045  * @param addr       Structure that represents an Internet address.
00046  *
00047  * @param res_str    Pointer to a character buffer will contain the resulting
00048  *                   text address in standard "." notation.@n
00049  *                   The @c res_str buffer must be at least 16 bytes long
00050  *                   (@ref FNET_IP4_ADDR_STR_SIZE).
00051  *
00052  *
00053  *
00054  * @return This function always returns the @c res_str.
00055  *
00056  * @see fnet_inet_aton(), fnet_inet_ntop(), fnet_inet_pton()
00057  *
00058  ******************************************************************************
00059  *
00060  * This function takes an Internet address structure, specified by the @c addr
00061  * parameter, and returns a null-terminated ASCII string, representing the
00062  * address in "." (dot) notation as in "a.b.c.d" into buffer pointed to by the
00063  * @c res_str.
00064  *
00065  * @note
00066  * fnet_inet_ntop() extends the fnet_inet_ntoa() function to support multiple
00067  * address families. @n
00068  * fnet_inet_ntoa() is now considered to be deprecated.
00069  *
00070  ******************************************************************************/
00071 fnet_char_t *fnet_inet_ntoa( struct in_addr addr, fnet_char_t *res_str );
00072 
00073 /***************************************************************************/ /*!
00074  *
00075  * @brief    Converts the string in the standard dotted-decimal notation
00076  *           to an integer value, suitable for use as an IPv4 address.
00077  *
00078  *
00079  * @param cp         Null-terminated character string representing a number
00080  *                   expressed in the Internet standard "." (dotted) notation.
00081  *
00082  * @param addr       Pointer to an integer will contain a suitable
00083  *                   binary representation of the Internet address @c cp.
00084  *
00085  * @return This function returns:
00086  *   - @ref FNET_OK if no error occurs.
00087  *   - @ref FNET_ERR if the string in the @c cp parameter does not contain
00088  *     a legitimate Internet address.
00089  *
00090  * @see fnet_inet_aton(), fnet_inet_ntop(), fnet_inet_pton()
00091  *
00092  ******************************************************************************
00093  *
00094  * This function interprets the character string specified by the @c cp
00095  * parameter. This string represents a numeric Internet address expressed
00096  * in the Internet standard "." notation. The value returned, pointed to by the @c addr,
00097  * is a number suitable for use as an Internet address.@n
00098  * @note
00099  * fnet_inet_pton() extends the fnet_inet_aton() function to support multiple
00100  * address families. @n
00101  * fnet_inet_aton() is now considered to be deprecated.
00102  *
00103  ******************************************************************************/
00104 fnet_return_t fnet_inet_aton( fnet_char_t *cp, struct in_addr *addr );
00105 
00106 /***************************************************************************/ /*!
00107  *
00108  * @brief   Converts IPv4 or IPv6 address from binary to text form.
00109  *
00110  *
00111  * @param family   The address family (@ref AF_INET or @ref AF_INET6).
00112  *
00113  * @param addr  Pointer to the IP address in network-byte order.
00114  *
00115  * @param str   Pointer to a buffer in which to store the NULL-terminated
00116  *              string representation of the IP address.@n
00117  *              For an IPv4 address, the @c str buffer must be at least 16 bytes long
00118  *                   (@ref FNET_IP4_ADDR_STR_SIZE).@n
00119  *              For an IPv6 address, the @c str buffer must be at least 46 bytes long
00120  *                   (@ref FNET_IP6_ADDR_STR_SIZE).@n
00121  *
00122  * @param str_len  Length of the @c str buffer.
00123  *
00124  *
00125  * @return This function returns:
00126  *   - pointer to a buffer containing the string representation of IP
00127  *     address (the @c str), if no error occurs,
00128  *   - @ref FNET_NULL if an error occurs.
00129  *
00130  * @see fnet_inet_pton()
00131  *
00132  ******************************************************************************
00133  *
00134  * This function converts the network address structure, specified by the @c addr
00135  * parameter, in the @c addr_family address family into a character string.
00136  * The resulting string is copied to the buffer pointed to by @c str.
00137  *
00138  * @note
00139  * fnet_inet_ntop() extends the fnet_inet_ntoa() function to support multiple
00140  * address families. @n
00141  * fnet_inet_ntoa() is now considered to be deprecated.
00142  *
00143  ******************************************************************************/
00144 fnet_char_t *fnet_inet_ntop(fnet_address_family_t family, const void *addr, fnet_char_t *str, fnet_size_t str_len);
00145 
00146 /***************************************************************************/ /*!
00147  *
00148  * @brief    Converts IPv4 and IPv6 addresses from text to binary form.
00149  *
00150  *
00151  * @param family     The address family (@ref AF_INET or @ref AF_INET6).
00152  *
00153  * @param str        Null-terminated character string that contains the text
00154  *                   representation of the IP address to convert to numeric
00155  *                   binary form.
00156  *
00157  * @param addr       Pointer to a buffer in which to store the numeric binary
00158  *                   representation of the IP address @c str.
00159  *
00160  * @param addr_len   Length of the @c addr buffer.
00161  *
00162  * @return This function returns:
00163  *   - @ref FNET_OK if no error occurs.
00164  *   - @ref FNET_ERR if the string in the @c str parameter does not contain
00165  *     a legitimate Internet address.
00166  *
00167  * @see fnet_inet_ntop()
00168  *
00169  ******************************************************************************
00170  *
00171  * This function converts the character string @c src into a network address
00172  * structure in the @c addr_family address family, then copies the network
00173  * address structure to the @c addr buffer.
00174  *
00175  * @note
00176  * fnet_inet_pton() extends the fnet_inet_aton() function to support multiple
00177  * address families. @n
00178  * fnet_inet_aton() is now considered to be deprecated.
00179  *
00180  ******************************************************************************/
00181 fnet_return_t fnet_inet_pton (fnet_address_family_t family, const fnet_char_t *str, void *addr, fnet_size_t addr_len);
00182 
00183 
00184 /***************************************************************************/ /*!
00185  *
00186  * @brief    Converts IPv4 and IPv6 addresses from text to socket-address structure.
00187  *
00188  * @param str        Null-terminated character string that contains the text
00189  *                   representation of the IP address to convert to socket-address
00190  *                   structure.
00191  *
00192  * @param addr       Pointer to a socket-address structure to be filled.
00193 
00194  *
00195  * @return This function returns:
00196  *   - @ref FNET_OK if no error occurs.
00197  *   - @ref FNET_ERR if the string in the @c str parameter does not contain
00198  *     a legitimate Internet address.
00199  *
00200  * @see fnet_inet_pton()
00201  *
00202  ******************************************************************************
00203  *
00204  * This function converts the character string @c src into a socket-address
00205  * structure.
00206  *
00207  ******************************************************************************/
00208 fnet_return_t fnet_inet_ptos (const fnet_char_t *str, struct sockaddr *addr);
00209 
00210 #if defined(__cplusplus)
00211 }
00212 #endif
00213 
00214 /*! @} */
00215 
00216 #endif /* _FNET_INET_H_ */