third_party/ot-br-posix/repo/src/mdns/mdns.hpp

   1 /*
   2  *    Copyright (c) 2017, The OpenThread Authors.
   3  *    All rights reserved.
   4  *
   5  *    Redistribution and use in source and binary forms, with or without
   6  *    modification, are permitted provided that the following conditions are met:
   7  *    1. Redistributions of source code must retain the above copyright
   8  *       notice, this list of conditions and the following disclaimer.
   9  *    2. Redistributions in binary form must reproduce the above copyright
  10  *       notice, this list of conditions and the following disclaimer in the
  11  *       documentation and/or other materials provided with the distribution.
  12  *    3. Neither the name of the copyright holder nor the
  13  *       names of its contributors may be used to endorse or promote products
  14  *       derived from this software without specific prior written permission.
  15  *
  16  *    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  17  *    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18  *    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19  *    ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  20  *    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21  *    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22  *    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23  *    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24  *    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25  *    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26  *    POSSIBILITY OF SUCH DAMAGE.
  27  */
  28
  29 /**
  30  * @file
  31  *   This file includes definitions for mDNS publisher.
  32  */
  33
  34 #ifndef OTBR_AGENT_MDNS_HPP_
  35 #define OTBR_AGENT_MDNS_HPP_
  36
  37 #include <vector>
  38
  39 #include <sys/select.h>
  40
  41 #include "common/types.hpp"
  42
  43 namespace otbr {
  44
  45 namespace Mdns {
  46
  47 /**
  48  * @addtogroup border-router-mdns
  49  *
  50  * @brief
  51  *   This module includes definition for MDNS service.
  52  *
  53  * @{
  54  */
  55
  56 /**
  57  * This interface defines the functionality of MDNS service.
  58  *
  59  */
  60 class Publisher
  61 {
  62 public:
  63     /**
  64      * This structure represents a name/value pair of the TXT record.
  65      *
  66      */
  67     struct TxtEntry
  68     {
  69         const char *   mName;        ///< The name of the TXT entry.
  70         size_t         mNameLength;  ///< The length of the name of the TXT entry.
  71         const uint8_t *mValue;       ///< The value of the TXT entry.
  72         size_t         mValueLength; ///< The length of the value of the TXT entry.
  73
  74         TxtEntry(const char *aName, const char *aValue)
  75             : TxtEntry(aName, reinterpret_cast<const uint8_t *>(aValue), strlen(aValue))
  76         {
  77         }
  78
  79         TxtEntry(const char *aName, const uint8_t *aValue, size_t aValueLength)
  80             : TxtEntry(aName, strlen(aName), aValue, aValueLength)
  81         {
  82         }
  83
  84         TxtEntry(const char *aName, size_t aNameLength, const uint8_t *aValue, size_t aValueLength)
  85             : mName(aName)
  86             , mNameLength(aNameLength)
  87             , mValue(aValue)
  88             , mValueLength(aValueLength)
  89         {
  90         }
  91     };
  92
  93     typedef std::vector<TxtEntry> TxtList;
  94
  95     /**
  96      * MDNS state values.
  97      *
  98      */
  99     enum class State
 100     {
 101         kIdle,  ///< Unable to publishing service.
 102         kReady, ///< Ready for publishing service.
 103     };
 104
 105     /**
 106      * This function pointer is called when MDNS service state changed.
 107      *
 108      * @param[in]   aContext        A pointer to application-specific context.
 109      * @param[in]   aState          The new state.
 110      *
 111      */
 112     typedef void (*StateHandler)(void *aContext, State aState);
 113
 114     /**
 115      * This method reports the result of a service publication.
 116      *
 117      * @param[in]  aName     The service instance name.
 118      * @param[in]  aType     The service type.
 119      * @param[in]  aError    An error that indicates whether the service publication succeeds.
 120      * @param[in]  aContext  A user context.
 121      *
 122      */
 123     typedef void (*PublishServiceHandler)(const char *aName, const char *aType, otbrError aError, void *aContext);
 124
 125     /**
 126      * This method reports the result of a host publication.
 127      *
 128      * @param[in]  aName     The host name.
 129      * @param[in]  aError    An OTBR error that indicates whether the host publication succeeds.
 130      * @param[in]  aContext  A user context.
 131      *
 132      */
 133     typedef void (*PublishHostHandler)(const char *aName, otbrError aError, void *aContext);
 134
 135     /**
 136      * This method sets the handler for service publication.
 137      *
 138      * @param[in]  aHandler  A handler which will be called when a service publication is finished.
 139      * @param[in]  aContext  A user context which is associated to @p aHandler.
 140      *
 141      */
 142     void SetPublishServiceHandler(PublishServiceHandler aHandler, void *aContext)
 143     {
 144         mServiceHandler        = aHandler;
 145         mServiceHandlerContext = aContext;
 146     }
 147
 148     /**
 149      * This method sets the handler for host publication.
 150      *
 151      * @param[in]  aHandler  A handler which will be called when a host publication is finished.
 152      * @param[in]  aContext  A user context which is associated to @p aHandler.
 153      *
 154      */
 155     void SetPublishHostHandler(PublishHostHandler aHandler, void *aContext)
 156     {
 157         mHostHandler        = aHandler;
 158         mHostHandlerContext = aContext;
 159     }
 160
 161     /**
 162      * This method starts the MDNS service.
 163      *
 164      * @retval OTBR_ERROR_NONE  Successfully started MDNS service;
 165      * @retval OTBR_ERROR_MDNS  Failed to start MDNS service.
 166      *
 167      */
 168     virtual otbrError Start(void) = 0;
 169
 170     /**
 171      * This method stops the MDNS service.
 172      *
 173      */
 174     virtual void Stop(void) = 0;
 175
 176     /**
 177      * This method checks if publisher has been started.
 178      *
 179      * @retval true     Already started.
 180      * @retval false    Not started.
 181      *
 182      */
 183     virtual bool IsStarted(void) const = 0;
 184
 185     /**
 186      * This method publishes or updates a service.
 187      *
 188      * @param[in]   aHostName           The name of the host which this service resides on. If NULL is provided,
 189      *                                  this service resides on local host and it is the implementation to provide
 190      *                                  specific host name. Otherwise, the caller MUST publish the host with method
 191      *                                  PublishHost.
 192      * @param[in]   aName               The name of this service.
 193      * @param[in]   aType               The type of this service.
 194      * @param[in]   aPort               The port number of this service.
 195      * @param[in]   aTxtList            A list of TXT name/value pairs.
 196      *
 197      * @retval  OTBR_ERROR_NONE     Successfully published or updated the service.
 198      * @retval  OTBR_ERROR_ERRNO    Failed to publish or update the service.
 199      *
 200      */
 201     virtual otbrError PublishService(const char *   aHostName,
 202                                      uint16_t       aPort,
 203                                      const char *   aName,
 204                                      const char *   aType,
 205                                      const TxtList &aTxtList) = 0;
 206
 207     /**
 208      * This method un-publishes a service.
 209      *
 210      * @param[in]   aName               The name of this service.
 211      * @param[in]   aType               The type of this service.
 212      *
 213      * @retval  OTBR_ERROR_NONE     Successfully un-published the service.
 214      * @retval  OTBR_ERROR_ERRNO    Failed to un-publish the service.
 215      *
 216      */
 217     virtual otbrError UnpublishService(const char *aName, const char *aType) = 0;
 218
 219     /**
 220      * This method publishes or updates a host.
 221      *
 222      * Publishing a host is advertising an A/AAAA RR for the host name. This method should be called
 223      * before a service with non-null host name is published.
 224      *
 225      * @param[in]  aName           The name of the host.
 226      * @param[in]  aAddress        The address of the host.
 227      * @param[in]  aAddressLength  The length of @p aAddress.
 228      *
 229      * @retval  OTBR_ERROR_NONE          Successfully published or updated the host.
 230      * @retval  OTBR_ERROR_INVALID_ARGS  The arguments are not valid.
 231      * @retval  OTBR_ERROR_ERRNO         Failed to publish or update the host.
 232      *
 233      */
 234     virtual otbrError PublishHost(const char *aName, const uint8_t *aAddress, uint8_t aAddressLength) = 0;
 235
 236     /**
 237      * This method un-publishes a host.
 238      *
 239      * @param[in]  aName  A host name.
 240      *
 241      * @retval  OTBR_ERROR_NONE     Successfully un-published the host.
 242      * @retval  OTBR_ERROR_ERRNO    Failed to un-publish the host.
 243      *
 244      */
 245     virtual otbrError UnpublishHost(const char *aName) = 0;
 246
 247     /**
 248      * This method performs the MDNS processing.
 249      *
 250      * @param[in]   aReadFdSet          A reference to fd_set ready for reading.
 251      * @param[in]   aWriteFdSet         A reference to fd_set ready for writing.
 252      * @param[in]   aErrorFdSet         A reference to fd_set with error occurred.
 253      *
 254      */
 255     virtual void Process(const fd_set &aReadFdSet, const fd_set &aWriteFdSet, const fd_set &aErrorFdSet) = 0;
 256
 257     /**
 258      * This method updates the fd_set and timeout for mainloop.
 259      *
 260      * @param[inout]    aReadFdSet      A reference to fd_set for polling read.
 261      * @param[inout]    aWriteFdSet     A reference to fd_set for polling read.
 262      * @param[inout]    aErrorFdSet     A reference to fd_set for polling error.
 263      * @param[inout]    aMaxFd          A reference to the current max fd in @p aReadFdSet and @p aWriteFdSet.
 264      * @param[inout]    aTimeout        A reference to the timeout. Update this value if the MDNS service has
 265      *                                  pending process in less than its current value.
 266      *
 267      */
 268     virtual void UpdateFdSet(fd_set & aReadFdSet,
 269                              fd_set & aWriteFdSet,
 270                              fd_set & aErrorFdSet,
 271                              int &    aMaxFd,
 272                              timeval &aTimeout) = 0;
 273
 274     virtual ~Publisher(void) {}
 275
 276     /**
 277      * This function creates a MDNS publisher.
 278      *
 279      * @param[in]   aProtocol           Protocol to use for publishing. AF_INET6, AF_INET or AF_UNSPEC.
 280      * @param[in]   aDomain             The domain to register in. Set nullptr to use default mDNS domain ("local.").
 281      * @param[in]   aHandler            The function to be called when this service state changed.
 282      * @param[in]   aContext            A pointer to application-specific context.
 283      *
 284      * @returns A pointer to the newly created MDNS publisher.
 285      *
 286      */
 287     static Publisher *Create(int aProtocol, const char *aDomain, StateHandler aHandler, void *aContext);
 288
 289     /**
 290      * This function destroys the MDNS publisher.
 291      *
 292      * @param[in]   aPublisher          A pointer to the publisher.
 293      *
 294      */
 295     static void Destroy(Publisher *aPublisher);
 296
 297     /**
 298      * This function decides if two service types (names) are equal.
 299      *
 300      * Different implementations may or not append a dot ('.') to the service type (name)
 301      * and we can not compare if two service type are equal with `strcmp`. This function
 302      * ignores the trailing dot when comparing two service types.
 303      *
 304      * @param[in]  aFirstType   The first service type.
 305      * @param[in]  aSecondType  The second service type.
 306      *
 307      * returns  A boolean that indicates whether the two service types are equal.
 308      *
 309      */
 310     static bool IsServiceTypeEqual(const char *aFirstType, const char *aSecondType);
 311
 312     /**
 313      * This function writes the TXT entry list to a TXT data buffer.
 314      *
 315      * The output data is in standard DNS-SD TXT data format.
 316      * See RFC 6763 for details: https://tools.ietf.org/html/rfc6763#section-6.
 317      *
 318      * @param[in]     aTxtList    A TXT entry list.
 319      * @param[out]    aTxtData    A TXT data buffer.
 320      * @param[inout]  aTxtLength  As input, it is the length of the TXT data buffer;
 321      *                            As output, it is the length of the TXT data written.
 322      *
 323      * @retval  OTBR_ERROR_NONE          Successfully write the TXT entry list.
 324      * @retval  OTBR_ERROR_INVALID_ARGS  The input TXT data buffer cannot hold the TXT data.
 325      *
 326      */
 327     static otbrError EncodeTxtData(const TxtList &aTxtList, uint8_t *aTxtData, uint16_t &aTxtLength);
 328
 329 protected:
 330     enum : uint8_t
 331     {
 332         kMaxTextEntrySize = 255,
 333     };
 334
 335     PublishServiceHandler mServiceHandler        = nullptr;
 336     void *                mServiceHandlerContext = nullptr;
 337
 338     PublishHostHandler mHostHandler        = nullptr;
 339     void *             mHostHandlerContext = nullptr;
 340 };
 341
 342 /**
 343  * @}
 344  */
 345
 346 } // namespace Mdns
 347
 348 } // namespace otbr
 349
 350 #endif // OTBR_AGENT_MDNS_HPP_