1 /* 2 * Copyright (c) 2021 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 #ifndef IPROCESSCOMMUNICATOR_H 17 #define IPROCESSCOMMUNICATOR_H 18 19 #include <string> 20 #include <vector> 21 #include <cstdint> 22 #include <functional> 23 #include <memory> 24 #include "store_types.h" 25 26 namespace DistributedDB { 27 // The DeviceInfos may contain other fields(Can only be auxiliary information) besides identifier field in the future. 28 struct DeviceInfos { 29 std::string identifier; // An unique and fixed identifier representing a device, such as UUID. 30 }; 31 32 struct ExtendInfo { 33 std::string appId; 34 std::string storeId; 35 std::string userId; 36 std::string dstTarget; 37 }; 38 39 class ExtendHeaderHandle { 40 public: ExtendHeaderHandle()41 ExtendHeaderHandle() {}; ~ExtendHeaderHandle()42 virtual ~ExtendHeaderHandle() {}; 43 // headSize should be 8 byte align 44 // return OK and headSize = 0 if no need to fill Head Data 45 // return OK and headSize > 0 if permit sync and will call FillHeadData 46 // return NO_PERMISSION if not permit sync GetHeadDataSize(uint32_t & headSize)47 virtual DBStatus GetHeadDataSize(uint32_t &headSize) 48 { 49 headSize = 0; 50 return OK; 51 }; 52 // return OK if fill data ok 53 // return not OK if fill data failed FillHeadData(uint8_t * data,uint32_t headSize,uint32_t totalLen)54 virtual DBStatus FillHeadData(uint8_t *data, uint32_t headSize, uint32_t totalLen) 55 { 56 (void)data; 57 (void)headSize; 58 (void)totalLen; 59 return OK; 60 }; 61 }; 62 63 // In OnDeviceChange, all field of devInfo should be valid, isOnline true for online and false for offline. 64 // The concept of online or offline: 65 // 1: Can be at the physical device level, which means the remote device can be visible and communicable by local device 66 // 2: Can also be at the process level, which means the same ProcessCommunicator(with same processLabel) had been 67 // started on the remote device and thus visible and communicable by this local ProcessCommunicator. 68 using OnDeviceChange = std::function<void(const DeviceInfos &devInfo, bool isOnline)>; 69 70 // In OnDataReceive, all field of srcDevInfo should be valid 71 using OnDataReceive = std::function<void(const DeviceInfos &srcDevInfo, const uint8_t *data, uint32_t length)>; 72 73 // For all functions with returnType DBStatus: 74 // return DBStatus::OK if successful, otherwise DBStatus::DB_ERROR if anything wrong. 75 // Additional information of reason why failed can be present in the log by the implementation. 76 // For "Get" or "Is" functions, implementation should notice that concurrent call is possible. 77 class IProcessCommunicator { 78 public: 79 // The distributeddb in one process can only use one ProcessCommunicator at the same time 80 // The ProcessCommunicator can only Start one processLabel at the same time 81 // The ProcessCommunicator can Start again after stop 82 // The processLabel should not be an empty string 83 virtual DBStatus Start(const std::string &processLabel) = 0; 84 85 // The Stop should only be called after Start successfully 86 virtual DBStatus Stop() = 0; 87 88 // The register function can be called anytime regardless of whether started or stopped. 89 // There will only be one callback at the same time for each function 90 // If register again, the latter callback replace the former callback. 91 // Register nullptr as callback to do unregister semantic. 92 // For concurrency security of implementation, there should be lock between register_operation and callback_event. 93 virtual DBStatus RegOnDeviceChange(const OnDeviceChange &callback) = 0; 94 virtual DBStatus RegOnDataReceive(const OnDataReceive &callback) = 0; 95 96 // The SendData function should only be called after Start successfully 97 // Only the identifier field of dstDevInfo must be valid, no requirement for other field. 98 virtual DBStatus SendData(const DeviceInfos &dstDevInfo, const uint8_t *data, uint32_t length) = 0; 99 100 // The GetMtuSize function can be called anytime regardless of whether started or stopped. 101 // The mtuSize should not less than 1K otherwise it will be regard as 1K. 102 // For run on OHOS, there is agreement that the mtuSize should be nearly 5M. 103 virtual uint32_t GetMtuSize() = 0; 104 105 // The GetLocalDeviceInfos function should only be called after Start successfully 106 // All field of returned DeviceInfos must be valid, the identifier must not be empty and changed between time. 107 virtual DeviceInfos GetLocalDeviceInfos() = 0; 108 109 // The GetRemoteOnlineDeviceInfosList function should only be called after Start successfully 110 // All field of returned DeviceInfos must be valid, should not contain duplicate device or local device 111 virtual std::vector<DeviceInfos> GetRemoteOnlineDeviceInfosList() = 0; 112 113 // The IsSameProcessLabelStartedOnPeerDevice function should only be called after Start successfully 114 // Only the identifier field of peerDevInfo must be valid, no requirement for other field. 115 // If the peer device is offline, then return false. 116 // If the peer device is online but no ProcessCommunicator with same processLabel had started on it, return false. 117 // If the peer device is online and ProcessCommunicator with same processLabel had started on it, return true. 118 virtual bool IsSameProcessLabelStartedOnPeerDevice(const DeviceInfos &peerDevInfo) = 0; 119 ~IProcessCommunicator()120 virtual ~IProcessCommunicator() {}; 121 122 // For ABI compatibility reason, temporarily place this method at last and offer a fake implementation. 123 // The valid mtuSize range from 1K to 5M, value beyond this range will be set to the upper or lower limit. GetMtuSize(const DeviceInfos & devInfo)124 virtual uint32_t GetMtuSize(const DeviceInfos &devInfo) 125 { 126 if (devInfo.identifier.empty()) { 127 // Error case(would never happen actually) to avoid "unused-parameter" warning. 128 return 0; 129 } 130 return GetMtuSize(); 131 } 132 133 // The valid timeout range from 5s to 60s, value beyond this range will be set to the upper or lower limit. GetTimeout()134 virtual uint32_t GetTimeout() 135 { 136 return 5 * 1000; // 5 * 1000ms 137 }; 138 139 // The valid timeout range from 5s to 60s, value beyond this range will be set to the upper or lower limit. GetTimeout(const DeviceInfos & devInfo)140 virtual uint32_t GetTimeout(const DeviceInfos &devInfo) 141 { 142 if (devInfo.identifier.empty()) { 143 // Error case(would never happen actually) to avoid "unused-parameter" warning. 144 return 5 * 1000; // 5 * 1000ms 145 } 146 return GetTimeout(); 147 } 148 GetExtendHeaderHandle(const ExtendInfo & paramInfo)149 virtual std::shared_ptr<ExtendHeaderHandle> GetExtendHeaderHandle(const ExtendInfo ¶mInfo) 150 { 151 (void)paramInfo; 152 return nullptr; 153 } 154 // called after OnDataReceive 155 // return NO_PERMISSION while no need to handle the dataBuff if remote device userId is not mate with local userId 156 // return INVALID_FORMAT and headLength = 0 if data service can not deSerialize the buff 157 // return OK if deSerialize ok and get HeadLength/localUserId successfully CheckAndGetDataHeadInfo(const uint8_t * data,uint32_t totalLen,uint32_t & headLength,std::vector<std::string> & userId)158 virtual DBStatus CheckAndGetDataHeadInfo(const uint8_t *data, uint32_t totalLen, uint32_t &headLength, 159 std::vector<std::string> &userId) 160 { 161 (void)data; 162 (void)totalLen; 163 (void)userId; 164 headLength = 0; 165 return OK; 166 } 167 }; 168 } // namespace DistributedDB 169 170 #endif // IPROCESSCOMMUNICATOR_H 171