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 kMdnsTypeMaxSize  = 32;
  40 static constexpr uint16_t kMdnsTextMaxSize = 64;
  41
  42 enum class MdnsServiceProtocol : uint8_t
  43 {
  44     kMdnsProtocolUdp = 0,
  45     kMdnsProtocolTcp,
  46     kMdnsProtocolUnknown = 255,
  47 };
  48
  49 struct TextEntry
  50 {
  51     const char * mKey;
  52     const uint8_t * mData;
  53     size_t mDataSize;
  54 };
  55
  56 struct MdnsService
  57 {
  58     char mName[kMdnsNameMaxSize + 1];
  59     char mType[kMdnsTypeMaxSize + 1];
  60     MdnsServiceProtocol mProtocol;
  61     Inet::IPAddressType mAddressType;
  62     uint16_t mPort;
  63     chip::Inet::InterfaceId mInterface;
  64     TextEntry * mTextEntries;
  65     size_t mTextEntrySize;
  66     const char ** mSubTypes;
  67     size_t mSubTypeSize;
  68     Optional<chip::Inet::IPAddress> mAddress;
  69 };
  70
  71 /**
  72  * The callback function for mDNS resolve.
  73  *
  74  * The callback function SHALL NOT take the ownership of the service pointer or
  75  * any pointer inside this structure.
  76  *
  77  * @param[in] context     The context passed to ChipMdnsBrowse or ChipMdnsResolve.
  78  * @param[in] result      The mdns resolve result, can be nullptr if error happens.
  79  * @param[in] error       The error code.
  80  *
  81  */
  82 using MdnsResolveCallback = void (*)(void * context, MdnsService * result, CHIP_ERROR error);
  83
  84 /**
  85  * The callback function for mDNS browse.
  86  *
  87  * The callback function SHALL NOT take the ownership of the service pointer or
  88  * any pointer inside this structure.
  89  *
  90  * @param[in] context       The context passed to ChipMdnsBrowse or ChipMdnsResolve.
  91  * @param[in] services      The service list, can be nullptr.
  92  * @param[in] servicesSize  The size of the service list.
  93  * @param[in] error         The error code.
  94  *
  95  */
  96 using MdnsBrowseCallback = void (*)(void * context, MdnsService * services, size_t servicesSize, CHIP_ERROR error);
  97
  98 using MdnsAsyncReturnCallback = void (*)(void * context, CHIP_ERROR error);
  99
 100 /**
 101  * This function intializes the mdns module
 102  *
 103  * @param[in] initCallback    The callback for notifying the initialization result.
 104  * @param[in] errorCallback   The callback for notifying internal errors.
 105  * @param[in] context         The context passed to the callbacks.
 106  *
 107  * @retval CHIP_NO_ERROR  The initialization succeeds.
 108  * @retval Error code     The initialization fails
 109  *
 110  */
 111 CHIP_ERROR ChipMdnsInit(MdnsAsyncReturnCallback initCallback, MdnsAsyncReturnCallback errorCallback, void * context);
 112
 113 /**
 114  * This function sets the host name for services.
 115  *
 116  * @param[in] hostname   The hostname.
 117  *
 118  */
 119 CHIP_ERROR ChipMdnsSetHostname(const char * hostname);
 120
 121 /**
 122  * This function publishes an service via mDNS.
 123  *
 124  * Calling the function again with the same service name, type, protocol,
 125  * interface and port but different text will update the text published.
 126  * This function will NOT take the ownership of service->mTextEntries memory.
 127  *
 128  * @param[in] service   The service entry.
 129  *
 130  * @retval CHIP_NO_ERROR                The publish succeeds.
 131  * @retval CHIP_ERROR_INVALID_ARGUMENT  The service is nullptr.
 132  * @retval Error code                   The publish fails.
 133  *
 134  */
 135 CHIP_ERROR ChipMdnsPublishService(const MdnsService * service);
 136
 137 /**
 138  * This function stops publishing service via mDNS.
 139  *
 140  * @retval CHIP_NO_ERROR                The publish stops successfully.
 141  * @retval Error code                   Stopping the publish fails.
 142  *
 143  */
 144 CHIP_ERROR ChipMdnsStopPublish();
 145
 146 /**
 147  * This function browses the services published by mdns
 148  *
 149  * @param[in] type        The service type.
 150  * @param[in] protocol    The service protocol.
 151  * @param[in] addressType The protocol version of the IP address.
 152  * @param[in] interface   The interface to send queries.
 153  * @param[in] callback    The callback for found services.
 154  * @param[in] context     The user context.
 155  *
 156  * @retval CHIP_NO_ERROR                The browse succeeds.
 157  * @retval CHIP_ERROR_INVALID_ARGUMENT  The type or callback is nullptr.
 158  * @retval Error code                   The browse fails.
 159  *
 160  */
 161 CHIP_ERROR ChipMdnsBrowse(const char * type, MdnsServiceProtocol protocol, chip::Inet::IPAddressType addressType,
 162                           chip::Inet::InterfaceId interface, MdnsBrowseCallback callback, void * context);
 163
 164 /**
 165  * This function resolves the services published by mdns
 166  *
 167  * @param[in] browseResult  The service entry returned by @ref ChipMdnsBrowse
 168  * @param[in] interface     The interface to send queries.
 169  * @param[in] callback      The callback for found services.
 170  * @param[in] context       The user context.
 171  *
 172  * @retval CHIP_NO_ERROR                The resolve succeeds.
 173  * @retval CHIP_ERROR_INVALID_ARGUMENT  The name, type or callback is nullptr.
 174  * @retval Error code                   The resolve fails.
 175  *
 176  */
 177 CHIP_ERROR ChipMdnsResolve(MdnsService * browseResult, chip::Inet::InterfaceId interface, MdnsResolveCallback callback,
 178                            void * context);
 179
 180 } // namespace Mdns
 181 } // namespace chip