src/lib/mdns/platform/Mdns.h

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *
   5  *    Licensed under the Apache License, Version 2.0 (the "License");
   6  *    you may not use this file except in compliance with the License.
   7  *    You may obtain a copy of the License at
   8  *
   9  *        http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *    Unless required by applicable law or agreed to in writing, software
  12  *    distributed under the License is distributed on an "AS IS" BASIS,
  13  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  *    See the License for the specific language governing permissions and
  15  *    limitations under the License.
  16  */
  17
  18 /**
  19  *    @file
  20  *      This file defines the platform API to publish and subscribe mDNS
  21  *      services.
  22  *
  23  *      You can find the implementation in src/platform/\<PLATFORM\>/MdnsImpl.cpp.
  24  */
  25
  26 #pragma once
  27
  28 #include <stdint.h>
  29
  30 #include "core/CHIPError.h"
  31 #include "inet/IPAddress.h"
  32 #include "inet/InetInterface.h"
  33 #include "lib/core/Optional.h"
  34
  35 namespace chip {
  36 namespace Mdns {
  37
  38 static constexpr uint8_t kMdnsNameMaxSize         = 33;
  39 static constexpr uint8_t kMdnsProtocolTextMaxSize = 8;
  40 static constexpr uint8_t kMdnsTypeMaxSize         = 32;
  41 static constexpr uint16_t kMdnsTextMaxSize        = 64;
  42
  43 enum class MdnsServiceProtocol : uint8_t
  44 {
  45     kMdnsProtocolUdp = 0,
  46     kMdnsProtocolTcp,
  47     kMdnsProtocolUnknown = 255,
  48 };
  49
  50 struct TextEntry
  51 {
  52     const char * mKey;
  53     const uint8_t * mData;
  54     size_t mDataSize;
  55 };
  56
  57 struct MdnsService
  58 {
  59     char mName[kMdnsNameMaxSize + 1];
  60     char mType[kMdnsTypeMaxSize + 1];
  61     MdnsServiceProtocol mProtocol;
  62     Inet::IPAddressType mAddressType;
  63     uint16_t mPort;
  64     chip::Inet::InterfaceId mInterface;
  65     TextEntry * mTextEntries;
  66     size_t mTextEntrySize;
  67     const char ** mSubTypes;
  68     size_t mSubTypeSize;
  69     Optional<chip::Inet::IPAddress> mAddress;
  70 };
  71
  72 /**
  73  * The callback function for mDNS resolve.
  74  *
  75  * The callback function SHALL NOT take the ownership of the service pointer or
  76  * any pointer inside this structure.
  77  *
  78  * @param[in] context     The context passed to ChipMdnsBrowse or ChipMdnsResolve.
  79  * @param[in] result      The mdns resolve result, can be nullptr if error happens.
  80  * @param[in] error       The error code.
  81  *
  82  */
  83 using MdnsResolveCallback = void (*)(void * context, MdnsService * result, CHIP_ERROR error);
  84
  85 /**
  86  * The callback function for mDNS browse.
  87  *
  88  * The callback function SHALL NOT take the ownership of the service pointer or
  89  * any pointer inside this structure.
  90  *
  91  * @param[in] context       The context passed to ChipMdnsBrowse or ChipMdnsResolve.
  92  * @param[in] services      The service list, can be nullptr.
  93  * @param[in] servicesSize  The size of the service list.
  94  * @param[in] error         The error code.
  95  *
  96  */
  97 using MdnsBrowseCallback = void (*)(void * context, MdnsService * services, size_t servicesSize, CHIP_ERROR error);
  98
  99 using MdnsAsyncReturnCallback = void (*)(void * context, CHIP_ERROR error);
 100
 101 /**
 102  * This function intializes the mdns module
 103  *
 104  * @param[in] initCallback    The callback for notifying the initialization result.
 105  * @param[in] errorCallback   The callback for notifying internal errors.
 106  * @param[in] context         The context passed to the callbacks.
 107  *
 108  * @retval CHIP_NO_ERROR  The initialization succeeds.
 109  * @retval Error code     The initialization fails
 110  *
 111  */
 112 CHIP_ERROR ChipMdnsInit(MdnsAsyncReturnCallback initCallback, MdnsAsyncReturnCallback errorCallback, void * context);
 113
 114 /**
 115  * This function sets the host name for services.
 116  *
 117  * @param[in] hostname   The hostname.
 118  *
 119  */
 120 CHIP_ERROR ChipMdnsSetHostname(const char * hostname);
 121
 122 /**
 123  * This function publishes an service via mDNS.
 124  *
 125  * Calling the function again with the same service name, type, protocol,
 126  * interface and port but different text will update the text published.
 127  * This function will NOT take the ownership of service->mTextEntries memory.
 128  *
 129  * @param[in] service   The service entry.
 130  *
 131  * @retval CHIP_NO_ERROR                The publish succeeds.
 132  * @retval CHIP_ERROR_INVALID_ARGUMENT  The service is nullptr.
 133  * @retval Error code                   The publish fails.
 134  *
 135  */
 136 CHIP_ERROR ChipMdnsPublishService(const MdnsService * service);
 137
 138 /**
 139  * This function stops publishing service via mDNS.
 140  *
 141  * @retval CHIP_NO_ERROR                The publish stops successfully.
 142  * @retval Error code                   Stopping the publish fails.
 143  *
 144  */
 145 CHIP_ERROR ChipMdnsStopPublish();
 146
 147 /**
 148  * This function browses the services published by mdns
 149  *
 150  * @param[in] type        The service type.
 151  * @param[in] protocol    The service protocol.
 152  * @param[in] addressType The protocol version of the IP address.
 153  * @param[in] interface   The interface to send queries.
 154  * @param[in] callback    The callback for found services.
 155  * @param[in] context     The user context.
 156  *
 157  * @retval CHIP_NO_ERROR                The browse succeeds.
 158  * @retval CHIP_ERROR_INVALID_ARGUMENT  The type or callback is nullptr.
 159  * @retval Error code                   The browse fails.
 160  *
 161  */
 162 CHIP_ERROR ChipMdnsBrowse(const char * type, MdnsServiceProtocol protocol, chip::Inet::IPAddressType addressType,
 163                           chip::Inet::InterfaceId interface, MdnsBrowseCallback callback, void * context);
 164
 165 /**
 166  * This function resolves the services published by mdns
 167  *
 168  * @param[in] browseResult  The service entry returned by @ref ChipMdnsBrowse
 169  * @param[in] interface     The interface to send queries.
 170  * @param[in] callback      The callback for found services.
 171  * @param[in] context       The user context.
 172  *
 173  * @retval CHIP_NO_ERROR                The resolve succeeds.
 174  * @retval CHIP_ERROR_INVALID_ARGUMENT  The name, type or callback is nullptr.
 175  * @retval Error code                   The resolve fails.
 176  *
 177  */
 178 CHIP_ERROR ChipMdnsResolve(MdnsService * browseResult, chip::Inet::InterfaceId interface, MdnsResolveCallback callback,
 179                            void * context);
 180
 181 } // namespace Mdns
 182 } // namespace chip