diff options
Diffstat (limited to 'libparc/parc/algol/parc_Network.h')
| -rw-r--r-- | libparc/parc/algol/parc_Network.h | 299 |
1 files changed, 299 insertions, 0 deletions
diff --git a/libparc/parc/algol/parc_Network.h b/libparc/parc/algol/parc_Network.h new file mode 100644 index 00000000..58b8b1f3 --- /dev/null +++ b/libparc/parc/algol/parc_Network.h @@ -0,0 +1,299 @@ +/* + * Copyright (c) 2017 Cisco and/or its affiliates. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at: + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file parc_Network.h + * @ingroup networking + * @brief Basic Networking Support + * + */ +#ifndef libparc_parc_Networking_h +#define libparc_parc_Networking_h + +#include <arpa/inet.h> +#include <netinet/in.h> + +#include <parc/algol/parc_BufferComposer.h> +#include <parc/algol/parc_Buffer.h> + +#ifndef INPORT_ANY +#define INPORT_ANY 0 +#endif + +#ifdef _ANDROID_ +typedef uint16_t in_port_t; +#endif + +/** + * Parses any string in to an address, if possible + * + * The string may be an IPv6, IPv6 or hostname. If the string does not match an IPv4 or IPv6 nominal format, + * it will try to resolve the string as a hostname. If that fails, the function will return NULL. + * + * IMPORTANT: the returned pointer is allocated with <code>parcMemory_Allocate()</code> and you must use <code>parcMemory_Deallocate()</code>. + * + * @param [in] address An IPv4, IPv6, or hostname + * @param [in] port the port address + * + * @return NULL Could not parse the address or resolve as a hostname + * @return non-NULL a valid sockaddr. You shoule examine `sockaddr->sa_family` to determine IPv4 or IPv6. + * + * Example: + * @code + * { + * struct sockaddr *addr; + * addr = parcNetwork_SockAddress("1.2.3.4", 555); + * assertTrue(addr && addr->sa_family == AF_INET, "Addr not IPv4 for a dotted quad."); + * struct sockaddr_in *addr_in = (struct sockaddr_in *) addr; + * // ... + * parcMemory_Deallocate((void **)&addr); + * + * addr = parcNetwork_SockAddress("fe80::aa20:66ff:fe00:314a", 555); + * assertTrue(addr && addr->sa_family == AF_INET6, "Addr not IPv6."); + * struct sockaddr_in6 *addr_in6 = (struct sockaddr_in6 *) addr; + * // ... + * parcMemory_Deallocate((void **)&addr); + * + * addr = parcNetwork_SockAddress("alpha.parc.com", 555); + * assertTrue(addr && addr->sa_family == AF_INET, "Addr not IPv4 hostname with only ipv4 address."); + * // ... + * parcMemory_Deallocate((void **)&addr); + * + * addr = parcNetwork_SockAddress("Over the rainbow, way up high", 555); + * assertNull(addr, "Addr no null for bogus name."); + * + * } + * @endcode + */ +struct sockaddr *parcNetwork_SockAddress(const char *address, in_port_t port); + +/** + * Compose an allocated sockaddr_in structure. + * + * + * @param [in] address An IPv4, IPv6, or hostname + * @param [in] port the port address + * @return A pointer to an allocated struct sockaddr_in which must be freed by <code>parcMemory_Deallocate()</code>, or NULL on error. + * + * Example: + * @code + * <#example#> + * @endcode + */ +struct sockaddr_in *parcNetwork_SockInet4Address(const char *address, in_port_t port); + +/** + * Compose an allocated sockaddr_in6 structure. + * + * + * @param [in] address An IPv4, IPv6, or hostname + * @param [in] port the port address + * @param flowInfo + * @param scopeId + * @return A pointer to an allocated sockaddr_in6 structure that must be freed via parcMemory_Deallocate(), or NULL on error. + * + * Example: + * @code + * <#example#> + * @endcode + */ +struct sockaddr_in6 *parcNetwork_SockInet6Address(const char *address, in_port_t port, uint32_t flowInfo, uint32_t scopeId); + +/** + * Allocate a struct sockaddr_in + * + * @return A pointer to an allocated struct sockaddr_in which must be freed by {@link parcMemory_Deallocate()}, or NULL on error. + * + * Example: + * @code + * <#example#> + * @endcode + */ +struct sockaddr_in *parcNetwork_SockInet4AddressAny(void); + +/** + * Append the string representation of the `struct sockaddr_in` to a {@link PARCBufferComposer}. + * + * The position of the `PARCBufferComposer` is incremented by the number characters necessary to represent the `struct sockaddr_in` + * + * @param [in] address An IPv4, IPv6, or hostname + * @param [in,out] composer The instance of `PARCBufferComposer` to be modified. + * @return return + * + * Example: + * @code + * <#example#> + * @endcode + */ +PARCBufferComposer *parcNetwork_SockInet4Address_BuildString(const struct sockaddr_in *address, PARCBufferComposer *composer); + +/** + * Append the string representation of the `struct sockaddr_in6` to a `PARCBufferComposer`. + * + * The position of the `PARCBufferComposer` is incremented by the number characters necessary to represent the `struct sockaddr_in6` + * + * + * @param [in] address A pointer to the spckaddr_in6 to append. + * @param [in,out] composer a POinter to the `PARCBufferComposer` to modify. + * @return A pointer to the @p composer. + * + * Example: + * @code + * <#example#> + * @endcode + */ +PARCBufferComposer *parcNetwork_SockInet6Address_BuildString(const struct sockaddr_in6 *address, PARCBufferComposer *composer); + +/** + * The standard (IEEE 802) format for printing MAC-48 addresses in human-friendly form is six groups of two hexadecimal digits, + * separated by hyphens (-) or colons (:), in transmission order (e.g. `01-23-45-67-89-ab` or `01:23:45:67:89:ab`). + * This form is also commonly used for EUI-64. + * Another convention used by networking equipment uses three groups of four hexadecimal digits separated by dots (.) + * (e.g. `0123.4567.89ab` ), again in transmission order. + * + * @param [in] address A pointer to the adress of the string. + * @param [in] length The size of the buffer + * @param [in] composer A pointer to the buffer. + * @return A pointer to the `PARCBufferComposer` containing the built string. + * + * Example: + * @code + * <#example#> + * @endcode + */ +PARCBufferComposer *parcNetwork_LinkAddress_BuildString(const unsigned char *address, size_t length, PARCBufferComposer *composer); + +/** + * Parse a link address, expressed as a nul-terminated C string of the form + * `link://` followed by hexadecimal numbers representing single byte values, + * each value separated by either a ':' or '-' character. + * + * The standard (IEEE 802) format for printing MAC-48 addresses in human-friendly form is six groups of two hexadecimal digits, + * separated by hyphens (-) or colons (:), in transmission order (e.g. `01-23-45-67-89-ab` or `01:23:45:67:89:ab`). + * This form is also commonly used for EUI-64. + * + * Another convention used by networking equipment uses three groups of four hexadecimal digits separated by dots (.) + * (e.g. `0123.4567.89ab` ), again in transmission order. + * + * @param address A null-terminated C string of the form `link://` followed single byte values separated by ':' or '-'. + * @return A PARCBuffer instance containing the parsed bytes of the link address. + * + * Example: + * @code + * { + * + * PARCBuffer *address = parcNetwork_ParseLinkAddress("link://32-00-14-06-30-60"); + * + * } + * @endcode + * + * @see parcNetwork_ParseMAC48Address + */ +PARCBuffer *parcNetwork_ParseLinkAddress(const char *address); + +/** + * Parse a MAC-48 address, expressed as a nul-terminated C string of the standard (IEEE 802) + * format for printing MAC-48 addresses in human-friendly form is six groups of two hexadecimal digits, + * separated by hyphens (-) or colons (:), in transmission order (e.g. `01-23-45-67-89-ab` or `01:23:45:67:89:ab`). + * This form is also commonly used for EUI-64. + * + * Another convention used by networking equipment uses three groups of four hexadecimal digits separated by dots (.) + * (e.g. `0123.4567.89ab` ), again in transmission order. + * + * @param [in] address A null-terminated C string of the form `link://` followed single byte values separated by ':' or '-'. + * @param [out] result A pointer to a `PARCBuffer` for the result. + * @return `true` If the address was successfully parsed. + * @return `false` if the address was not successfully parsed. The output PARCBuffer is unmodified. + * + * Example: + * @code + * { + * + * PARCBuffer *address = parcNetwork_ParseMAC48Address("32-00-14-06-30-60"); + * + * } + * @endcode + */ +bool parcNetwork_ParseMAC48Address(const char *address, PARCBuffer *result); + +/** + * Return the address parsed from @p addressURI. + * + * @param [in] addressURI + * @return A pointer to the `sockaddr_in`. + * + * Example: + * @code + * <#example#> + * @endcode + */ +struct sockaddr_in *parcNetwork_ParseInet4Address(const char *addressURI); + +/** + * Determines if a socket is local + * + * A socket is local if: (a) PF_LOCAL/AF_UNIX, or (b) PF_INET and on the 127.0.0.0/8 network, + * or (c) PF_INET6 and equal to the ::1 address. Anything else is considered non-local. + * + * @param [in] sock A socket structure + * + * @return `true` The socket represents a local/loopback address + * @return `false` The socket is not a local/loopback address + * + * Example: + * @code + * { + * struct sockaddr *s = parcNetwork_SockAddress("127.1.1.1", 5900); + * assertTrue(parcNetwork_IsSocketLocal(s), "This will not assert"); + * parcMemory_Deallocate((void **)&s); + * } + * @endcode + */ +bool parcNetwork_IsSocketLocal(struct sockaddr *sock); + +/** + * Return true if two `sockaddr_in` instances are equal. + * + * The equality function that this evaluates must implement the following equivalence relations on non-null instances: + * + * * It is reflexive: for any non-null reference value x, parcNetwork_Inet4Equals(x, x) must return true. + * + * * It is symmetric: for any non-null reference values x and y, parcNetwork_Inet4Equals(x, y) must return true if and only if + * parcNetwork_Inet4Equals(y x) returns true. + * + * * It is transitive: for any non-null reference values x, y, and z, if + * parcNetwork_Inet4Equals(x, y) returns true and + * parcNetwork_Inet4Equals(y, z) returns true, + * then parcNetwork_Inet4Equals(x, z) must return true. + * + * * It is consistent: for any non-null reference values x and y, multiple invocations of parcNetwork_Inet4Equals(x, y) + * consistently return true or consistently return false. + * + * * For any non-null reference value x, equals(x, NULL)) must return false. + * + * @param [in] x A pointer to a struct sockaddr_in instance. + * @param [in] y A pointer to a struct sockaddr_in instance.s + * @return true the given sockaddr_in instances are equal. + * @return false the given sockaddr_in instances are not equal. + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + */ +bool parcNetwork_Inet4Equals(const struct sockaddr_in *x, const struct sockaddr_in *y); +#endif // libparc_parc_Networking_h |