1 /* 2 * Copyright (c) 2020 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 Broadcast 18 * @{ 19 * 20 * @brief Provides data subscription and data push for services. 21 * 22 * With this module, the Service, Feature, or other modules can broadcast events or data. \n 23 * All services that listen to these events or data can receive these broadcasts. \n 24 * 25 * @since 1.0 26 * @version 1.0 27 */ 28 29 /** 30 * @file broadcast_intertface.h 31 * 32 * @brief Provides the external interfaces and basic type definitions of the broadcast service. 33 * 34 * The interface and type are used for subscribing to and publishing events and data. \n 35 * 36 * @since 1.0 37 * @version 1.0 38 */ 39 40 #ifndef LITE_BROADCAST_INTERFACE_H 41 #define LITE_BROADCAST_INTERFACE_H 42 43 #include <ohos_errno.h> 44 #include "feature.h" 45 #include "iunknown.h" 46 #include "message.h" 47 48 #ifdef __cplusplus 49 #if __cplusplus 50 extern "C" { 51 #endif 52 #endif 53 54 /** 55 * @brief Indicates the name of the broadcast service. 56 * 57 * @since 1.0 58 * @version 1.0 */ 59 #define BROADCAST_SERVICE "Broadcast" 60 61 /** 62 * @brief Indicates the name of the pub/sub feature. 63 * 64 * @since 1.0 65 * @version 1.0 66 */ 67 #define PUB_SUB_FEATURE "Provider and subscriber" 68 69 /** 70 * @brief Indicates the topic of an event or data, which is used to distinguish different types of 71 * events or data. 72 * 73 * @since 1.0 74 * @version 1.0 75 */ 76 typedef uint32 Topic; 77 78 /** 79 * @brief Enumerates error codes unique to the Broadcast service. 80 */ 81 enum BroadcastErrCode { 82 /** Error code showing that a topic has been subscribed to */ 83 EC_ALREADY_SUBSCRIBED = EC_SUCCESS + 1 84 }; 85 86 typedef struct Consumer Consumer; 87 88 /** 89 * @brief Defines the topic consumer used to receive events and push data. You need to implement 90 * this struct for your application. 91 */ 92 struct Consumer { 93 /** Consumer ID */ 94 const Identity *identity; 95 96 /** 97 * @brief Defines how the consumer will process the events or data of a released topic. 98 * 99 * You can implement this function for consumers to process topics associated with the them. \n 100 * Note that the passed topic must have been subscribed by the consumer. Otherwise, the 101 * function does nothing. \n 102 * 103 * @param consumer Indicates <b>this</b> pointer of the consumer. 104 * @param topic Indicates the pointer to the topic to be processed. 105 * @param origin Indicates the pointer to the data to be processed. 106 * @since 1.0 107 * @version 1.0 108 */ 109 void (*Notify)(Consumer *consumer, const Topic *topic, const Request *origin); 110 111 /** 112 * @brief Checks whether two consumers are equal. 113 * 114 * You need to implement this function to prevent repeated topic subscription. \n 115 * 116 * @param current Indicates the pointer to the current consumer. 117 * @param other Indicates the pointer to the target consumer to compare. 118 * @return Returns <b>TRUE</b> if the two consumers are equal; returns <b>FALSE</b> otherwise. 119 * @since 1.0 120 * @version 1.0 121 */ 122 BOOL (*Equal)(const Consumer *current, const Consumer *other); 123 }; 124 125 typedef struct Provider Provider; 126 127 /** 128 * @brief Defines the provider of events and data of a topic. 129 */ 130 struct Provider { 131 /** 132 * @brief Publishes events and data of a specified topic. 133 * 134 * The events or data is published by the publisher, sent to all consumers who have subscribed 135 * to the topic, and processed by the consumers. \n 136 * 137 * @param iUnknown Indicates external interface of the pub/sub feature. 138 * @param topic Indicates the pointer to the topic to publish. 139 * @param data Indicates the pointer to the data to publish. 140 * @param len Indicates the length of the data to be published. The length must be the same as 141 * the <b>data</b> length. The caller must ensure the validity of this parameter. 142 * @return Returns <b>TRUE</b> if the topic is successfully published; returns <b>FALSE</b> 143 * otherwise. 144 * @since 1.0 145 * @version 1.0 146 */ 147 BOOL (*Publish)(IUnknown *iUnknown, const Topic *topic, uint8 *data, int16 len); 148 }; 149 150 typedef struct Subscriber Subscriber; 151 152 /** 153 * @brief Defines the subscriber for external interfaces to subscribe to events and data of a topic. 154 */ 155 struct Subscriber { 156 /** 157 * @brief Adds a specified topic to the Broadcast service. 158 * 159 * The specified topic is added by the subscriber. \n 160 * A topic can be subscribed to only after being added. \n 161 * 162 * @param iUnknown Indicates external interface of the pub/sub feature. 163 * @param topic Indicates the topic to be subscribed to. 164 * @return Returns <b>EC_SUCCESS</b> if the topic is successfully added; returns other error 165 * codes if the topic fails to be added. 166 * @since 1.0 167 * @version 1.0 168 */ 169 int (*AddTopic)(IUnknown *iUnknown, const Topic *topic); 170 171 /** 172 * @brief Subscribes to a specified topic for consumers. 173 * 174 * Call this function on the subscriber. The topic to be subscribed to must have been added to 175 * the Broadcast service. \n 176 * 177 * @param iUnknown Indicates external interface of the pub/sub feature. 178 * @param topic Indicates the topic to be subscribed to. 179 * @param consumer Indicates the consumer who subscribes to the topic. 180 * @return Returns <b>EC_SUCCESS</b> if the subscription is successful; returns other error 181 * codes if the subscription fails. 182 * @since 1.0 183 * @version 1.0 184 */ 185 int (*Subscribe)(IUnknown *iUnknown, const Topic *topic, Consumer *consumer); 186 187 /** 188 * @brief Modifies the consumer of a specified topic. 189 * 190 * 191 * 192 * @param iUnknown Indicates the pointer to the external interface of the pub/sub feature. 193 * @param topic Indicates the pointer to the topic whose consumer will be modified. 194 * @param old Indicates the pointer to the original consumer of the topic. 195 * @param current Indicates the pointer to the new consumer of the topic. 196 * @return Returns the pointer of the original consumer if the modification is successful; 197 * returns <b>NULL</b> otherwise. 198 * @since 1.0 199 * @version 1.0 200 */ 201 Consumer *(*ModifyConsumer)(IUnknown *iUnknown, const Topic *topic, Consumer *old, Consumer *current); 202 203 /** 204 * @brief Unsubscribes from a specified topic. 205 * 206 * This function cancels the subscription relationship between the specified topic and 207 * consumer. \n 208 * 209 * @param iUnknown Indicates external interface of the pub/sub feature. This parameter is used 210 * to obtain subscription relationships. 211 * @param topic Indicates the pointer to the topic to unsubscribe from. 212 * @param consumer Indicates the pointer to the consumer. 213 * @return Returns the pointer of the consumer if the unsubscription is successful; returns 214 * <b>NULL</b> otherwise. 215 * @since 1.0 216 * @version 1.0 217 */ 218 Consumer *(*Unsubscribe)(IUnknown *iUnknown, const Topic *topic, const Consumer *consumer); 219 }; 220 221 typedef struct PubSubInterface PubSubInterface; 222 223 struct PubSubInterface { 224 INHERIT_IUNKNOWN; 225 Subscriber subscriber; 226 Provider provider; 227 }; 228 229 #ifdef __cplusplus 230 #if __cplusplus 231 } 232 #endif 233 #endif 234 #endif // LITE_BROADCAST_INTERFACE_H 235 /** @} */ 236