mDNSMacOSX/mdns_objects/mdns_address.h

   1 /*
   2  * Copyright (c) 2019 Apple Inc. All rights reserved.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     https://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __MDNS_ADDRESS_H__
  18 #define __MDNS_ADDRESS_H__
  19
  20 #include "mdns_base.h"
  21
  22 #include <stdint.h>
  23
  24 MDNS_DECL(address);
  25
  26 MDNS_ASSUME_NONNULL_BEGIN
  27
  28 __BEGIN_DECLS
  29
  30 /*!
  31  *      @brief
  32  *              Creates an address object that represents an IPv4 address and port number.
  33  *
  34  *      @param addr
  35  *              The IPv4 address as an unsigned 32-bit integer in host byte order.
  36  *
  37  *      @param port
  38  *              The port number in host byte order.
  39  *
  40  *      @result
  41  *              An address object or NULL if the system was out of memory.
  42  */
  43 MDNS_RETURNS_RETAINED MDNS_WARN_RESULT _Nullable
  44 mdns_address_t
  45 mdns_address_create_ipv4(uint32_t addr, uint16_t port);
  46
  47 /*!
  48  *      @brief
  49  *              Creates an address object that represents an IPv6 address and port number.
  50  *
  51  *      @param addr
  52  *              The IPv6 address as an array of octets in network byte order.
  53  *
  54  *      @param port
  55  *              The port number in host byte order.
  56  *
  57  *      @param scope_id
  58  *              The scope ID.
  59  *
  60  *      @result
  61  *              An address object or NULL if the system was out of memory.
  62  */
  63 MDNS_RETURNS_RETAINED MDNS_WARN_RESULT _Nullable
  64 mdns_address_t
  65 mdns_address_create_ipv6(const uint8_t addr[static 16], uint16_t port, uint32_t scope_id);
  66
  67 /*!
  68  *      @brief
  69  *              Creates an address object that represents the IPv4 or IPv6 address and optional port number specified by a
  70  *              string.
  71  *
  72  *      @param ip_addr_str
  73  *              The textual representation of the IPv4 or IPv6 address and optional port number as an ASCII C string.
  74  *
  75  *      @result
  76  *              An address object or NULL if the system was out of memory.
  77  *
  78  *      @discussion
  79  *              IPv4 addresses must be in dot-decimal notation, e.g., "192.0.2.1". A port can be specified for an IPv4 address
  80  *              by appending a ':' character followed by the port number in decimal notation, e.g., "192.0.2.1:443".
  81  *
  82  *              IPv6 addresses must be in any of the three conventional forms described by
  83  *              <https://tools.ietf.org/html/rfc3513#section-2.2>. For example, "2001:0db8:0000:0000:0000:0000:0000:0001",
  84  *              "2001:db8::1", or "::ffff:192.0.2.1".
  85  *
  86  *              A port can be specified for an IPv6 address by enclosing the IPv6 address's textual representation in square
  87  *              brackets, then appending a ':' character followed by the port number in decimal notation. For example,
  88  *              "[2001:db8::1]:443".
  89  *
  90  *              If a port is not specified, a port number of zero is assumed.
  91  */
  92 MDNS_RETURNS_RETAINED mdns_address_t _Nullable
  93 mdns_address_create_from_ip_address_string(const char *ip_addr_str);
  94
  95 /*!
  96  *      @brief
  97  *              Return a pointer to a sockaddr structure that represents an address object's IPv4 or IPv6 address and port.
  98  *
  99  *      @param address
 100  *              The address object.
 101  *
 102  *      @result
 103  *              A pointer to a sockaddr structure.
 104  *
 105  *      @discussion
 106  *              The pointer returned by this function can be safely cast to a pointer to a sockaddr_in structure if the value
 107  *              of the sockaddr structure's sa_family member variable is AF_INET, which is the case for IPv4 addresses.
 108  *
 109  *              Likewise, the pointer can be safely cast to a pointer to a sockaddr_in6 structure if the value of the sockaddr
 110  *              structure's sa_family member variable is AF_INET6, which is the case for IPv6 addresses.
 111  */
 112 const struct sockaddr *
 113 mdns_address_get_sockaddr(mdns_address_t address);
 114
 115 /*!
 116  *      @brief
 117  *              Returns an address's port number.
 118  *
 119  *      @param address
 120  *              The address.
 121  */
 122 uint16_t
 123 mdns_address_get_port(mdns_address_t address);
 124
 125 __END_DECLS
 126
 127 MDNS_ASSUME_NONNULL_END
 128
 129 #endif  // __MDNS_ADDRESS_H__