1 /* 2 * Copyright (c) 2021-2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup SoftBus 18 * @{ 19 * 20 * @brief Provides high-speed, secure communication between devices. 21 * 22 * This module implements unified distributed communication capability management between nearby devices, and provides 23 * link-independent device discovery and transmission interfaces to support service publishing and data transmission. 24 * 25 * @since 1.0 26 * @version 1.0 27 */ 28 /** @} */ 29 30 /** 31 * @file discovery_service.h 32 * 33 * @brief Declares functions and constants for the discovery service of the Intelligent Soft Bus. 34 * 35 * The functions are used to perform 36 * the following operations: \n 37 * <ul> 38 * <li>Publishing service and stop publishing service functions</li> 39 * <li>Start the discovery function and stop the discover function</li> 40 * 41 * @since 1.0 42 * @version 1.0 43 */ 44 45 #ifndef DISCOVERY_SERVICE_H 46 #define DISCOVERY_SERVICE_H 47 48 #include "softbus_common.h" 49 50 #ifdef __cplusplus 51 #if __cplusplus 52 extern "C" { 53 #endif 54 #endif 55 56 /** 57 * @brief Indicates the maximum length of the device address in <b>IDiscoveryCallback</b>. 58 * 59 */ 60 #define CONNECT_ADDR_LEN 46 61 62 /** 63 * @brief Enumerates error codes for service publishing failures. 64 * 65 * The error codes are returned to the caller through <b>IPublishCallback</b>. 66 * 67 */ 68 typedef enum { 69 /* Unsupported medium */ 70 PUBLISH_FAIL_REASON_NOT_SUPPORT_MEDIUM = 1, 71 /* internal error */ 72 PUBLISH_FAIL_REASON_INTERNAL = 2, 73 /* Unknown reason */ 74 PUBLISH_FAIL_REASON_UNKNOWN = 0xFF 75 } PublishFailReason; 76 77 /** 78 * @brief Defines the callbacks for successful and failed service publishing. 79 * 80 */ 81 typedef struct { 82 /** Callback for successful publishing */ 83 void (*OnPublishSuccess)(int publishId); 84 /** Callback for failed publishing */ 85 void (*OnPublishFail)(int publishId, PublishFailReason reason); 86 } IPublishCallback; 87 88 /** 89 * @brief Enumerates error codes for service subscription failures. 90 * 91 * The error codes are returned to the caller through <b>IDiscoveryCallback</b>. 92 * 93 */ 94 typedef enum { 95 /* Unsupported medium */ 96 DISCOVERY_FAIL_REASON_NOT_SUPPORT_MEDIUM = 1, 97 /* internal error */ 98 DISCOVERY_FAIL_REASON_INTERNAL = 2, 99 /* Unknown error */ 100 DISCOVERY_FAIL_REASON_UNKNOWN = 0xFF 101 } DiscoveryFailReason; 102 103 /** 104 * @brief Defines a callback for service subscription. 105 * 106 * Three types of callbacks are available. 107 * 108 */ 109 typedef struct { 110 /** Callback that is invoked when a device is found */ 111 void (*OnDeviceFound)(const DeviceInfo *device); 112 /** Callback for a subscription failure */ 113 void (*OnDiscoverFailed)(int subscribeId, DiscoveryFailReason failReason); 114 /** Callback for a subscription success */ 115 void (*OnDiscoverySuccess)(int subscribeId); 116 } IDiscoveryCallback; 117 118 /** 119 * @brief Publishing service, the discovered end publishes its own information, 120 * which can be discovered by other devices. 121 * Peer devices in the same LAN as the device that publishes this service can discover this service as needed. 122 * The service is identified by <b>publicId</b> and <b>pkgName</b>. 123 * @see {@link UnPublishService} 124 * @param[in] pkgName Indicates the pointer to the service package name, which can contain a maximum of 64 bytes. 125 * @param[in] info Indicates the pointer to the service publishing information. 126 * For details, see {@link PublishInfo}. 127 * @param[in] cb Indicates the pointer to the service publishing callback. 128 * For details, see {@link IPublishCallback}. 129 * @return <b>SOFTBUS_INVALID_PARAM</b> if any parameter is null or invalid. 130 * @return <b>SOFTBUS_DISCOVER_NOT_INIT</b> if the Intelligent SoftBus client fails to be initialized. 131 * @return <b>SOFTBUS_LOCK_ERR</b> if the mutex fails to be locked. 132 * @return <b>SOFTBUS_OK</b> if the service is successfully published. 133 * @deprecated Please use PublishLNN instead, for details, see {@link PublishLNN}. 134 */ 135 int PublishService(const char *pkgName, const PublishInfo *info, const IPublishCallback *cb); 136 137 /** 138 * @brief Stop publishing service functions, stop publishing its own capability information, 139 * and other devices cannot find it. 140 * @see {@link PublishService} 141 * @param[in] pkgName Indicates the pointer to the service package name, which can contain a maximum of 64 bytes. 142 * @param[in] publishId Indicates the service ID. 143 * @return <b>SOFTBUS_INVALID_PARAM</b> if <b>pkgName</b> is invalid. 144 * @return <b>SOFTBUS_DISCOVER_NOT_INIT</b> if the Intelligent SoftBus client fails to be initialized. 145 * @return <b>SOFTBUS_OK</b> if the service is successfully unpublished. 146 * @deprecated Please use StopPublishLNN instead, for details, see {@link StopPublishLNN}. 147 */ 148 int UnPublishService(const char *pkgName, int publishId); 149 150 /** 151 * @brief Start the discovery function, the discovered end begins to discover other devices 152 * and obtains the information of the remote device. 153 * Information about the device that publishes the service will be reported to the device that subscribes to 154 * the service. The service is identified by <b>subscribeId</b> and <b>pkgName</b>. 155 * @see {@link StopDiscovery} 156 * @param[in] pkgName Indicates the pointer to the service package name, which can contain a maximum of 64 bytes. 157 * @param[in] info Indicates the pointer to the service subscription information. 158 * For details, see {@link SubscribeInfo}. 159 * @param[in] cb Indicates the service subscription callback. For details, see {@link IDiscoveryCallback}. 160 * @return <b>SOFTBUS_INVALID_PARAM</b> if any parameter is null or invalid. 161 * @return <b>SOFTBUS_DISCOVER_NOT_INIT</b> if the Intelligent SoftBus client fails to be initialized. 162 * @return <b>SOFTBUS_LOCK_ERR</b> if the mutex fails to be locked. 163 * @return <b>SOFTBUS_OK</b> if the service subscription is successful. 164 * @deprecated Please use RefreshLNN instead, for details, see {@link RefreshLNN}. 165 */ 166 int StartDiscovery(const char *pkgName, const SubscribeInfo *info, const IDiscoveryCallback *cb); 167 168 /** 169 * @brief Stop the discovery function, at this time no longer capture device information of other devices at this time. 170 * @see {@link StartDiscovery} 171 * @param[in] pkgName Indicates the pointer to the service package name, which can contain a maximum of 64 bytes. 172 * @param[in] subscribeId Indicates the service ID. 173 * @return <b>SOFTBUS_INVALID_PARAM</b> if <b>pkgName</b> is invalid. 174 * @return <b>SOFTBUS_DISCOVER_NOT_INIT</b> if the Intelligent SoftBus client fails to be initialized. 175 * @return <b>SOFTBUS_OK</b> if the service unsubscription is successful. 176 * @deprecated Please use StopRefreshLNN instead, for details, see {@link StopRefreshLNN}. 177 */ 178 int StopDiscovery(const char *pkgName, int subscribeId); 179 180 #ifdef __cplusplus 181 #if __cplusplus 182 } 183 #endif /* __cplusplus */ 184 #endif /* __cplusplus */ 185 186 #endif /* DISCOVERY_SERVICE_H */ 187