1 /* 2 * Copyright (c) 2022-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 DriverHdi 18 * @{ 19 * 20 * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, 21 * load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to 22 * automatically generate code in interface description language (IDL). 23 * 24 * The HDF and IDL code generated allow the system ability to accesses HDI driver services. 25 * 26 * @since 1.0 27 */ 28 29 /** 30 * @file native_buffer.h 31 * 32 * @brief Provides C++ interfaces for <b>NativeBuffer</b>. 33 * 34 * <b>NativeBuffer</b> is the wrapper of <b>BufferHandle</b>. 35 * It manages the <b>BufferHandle</b> objects and applies to the HDI layer. 36 * 37 * @since 1.0 38 */ 39 40 #ifndef HDI_NATIVE_BUFFER_H 41 #define HDI_NATIVE_BUFFER_H 42 43 #include <message_parcel.h> 44 #include "buffer_handle.h" 45 46 namespace OHOS { 47 namespace HDI { 48 namespace Base { 49 using OHOS::MessageParcel; 50 using OHOS::Parcelable; 51 52 /** 53 * @brief Defines the <b>NativeBuffer</b> class. 54 * 55 */ 56 class NativeBuffer : public Parcelable { 57 public: 58 NativeBuffer(); 59 virtual ~NativeBuffer(); 60 explicit NativeBuffer(const BufferHandle *handle); 61 62 NativeBuffer(const NativeBuffer &other); 63 NativeBuffer(NativeBuffer &&other) noexcept; 64 65 NativeBuffer &operator=(const NativeBuffer &other); 66 NativeBuffer &operator=(NativeBuffer &&other) noexcept; 67 68 /** 69 * @brief Marshals this <b>NativeBuffer</b> object into a <b>MessageParcel</b> object. 70 * <b>Marshalling()</b> and <b>Unmarshalling()</b> are used in pairs. 71 * 72 * @param parcel Indicates the <b>MessageParcel</b> object to which the <b>NativeBuffer</b> object is marshalled. 73 * @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise. 74 */ 75 bool Marshalling(Parcel &parcel) const override; 76 77 /** 78 * @brief Unmarshals a <b>NativeBuffer</b> object from a <b>MessageParcel</b> object. 79 * <b>Marshalling()</b> and <b>Unmarshalling()</b> are used in pairs. 80 * 81 * @param parcel Indicates the <b>MessageParcel</b> object from 82 * which the <b>BufferHandle</b> object is unmarshalled. 83 * @return Returns the <b>NativeBuffer</b> object obtained if the operation is successful; 84 * returns <b>nullptr</b> otherwise. 85 */ 86 static sptr<NativeBuffer> Unmarshalling(Parcel &parcel); 87 88 /** 89 * @brief Clones a <b>BufferHandle</b> object. 90 * 91 * You can use this API to clone the <b>BufferHandle</b> object held by a <b>NativeBuffer</b> object. 92 * 93 * @return Returns the pointer to the <b>BufferHandle</b> cloned if the operation is successful; 94 * returns <b>nullptr</b> otherwise. 95 */ 96 BufferHandle *Clone(); 97 98 /** 99 * @brief Moves this <b>BufferHandle</b> object. 100 * 101 * This API transfers the ownership of the <b>BufferHandle</b> object held by the <b>NativeBuffer</b> object. 102 * After the ownership is transferred, 103 * you need to use <b>FreeNativeBufferHandle</b> to release the <b>BufferHandle</b> object. 104 * 105 * @return Returns the pointer to the <b>BufferHandle</b> object after the move if the operation is successful; 106 * returns <b>nullptr</b> otherwise. 107 */ 108 BufferHandle *Move() noexcept; 109 110 /** 111 * @brief Sets a <b>BufferHandle</b> object. 112 * 113 * You can use this API to set the owner of a <b>BufferHandle</b> object. 114 * 115 * @param handle Indicates the <b>BufferHandle</b> object to set. 116 * @param isOwner Indicates whether the <b>BufferHandle</b> object is managed by a <b>NativeBuffer</b> object. 117 * The value <b>true</b> means the <b>BufferHandle</b> object is managed by the<b>NativeBuffer</b> object; 118 * the value <b>false</b> means the opposite. The default value is <b>false</b>. 119 * @param destructor Indicates the function used to release the <b>BufferHandle</b> object. 120 * By default, <b>FreeNativeBufferHandle</b> is used. 121 */ 122 void SetBufferHandle(BufferHandle *handle, bool isOwner = false, 123 std::function<void(BufferHandle *)> destructor = nullptr); 124 125 /** 126 * @brief Obtains this <b>BufferHandle</b> object. 127 * 128 * The <b>NativeBuffer</b> object still hold the <b>BufferHandle</b> object. 129 * 130 * @return Returns the pointer to the <b>BufferHandle</b> object obtained if the operation is successful; 131 * returns <b>nullptr</b> otherwise. 132 */ 133 BufferHandle *GetBufferHandle() noexcept; 134 135 /** 136 * @brief Prints dump information. 137 * 138 * @return Returns dump information about this <b>BufferHandle</b> object. 139 */ 140 std::string Dump() const; 141 private: 142 bool ExtractFromParcel(Parcel &parcel); 143 static bool WriteReserveData(MessageParcel &messageParcel, const BufferHandle &handle); 144 static bool ReadReserveData(MessageParcel &messageParcel, BufferHandle &handle); 145 void DestroyBuffer(); 146 BufferHandle *handle_; 147 bool isOwner_; 148 std::function<void(BufferHandle *)> bufferDestructor_; 149 }; 150 } // namespace Base 151 } // namespace HDI 152 } // namespace OHOS 153 154 #endif // HDI_NATIVE_BUFFER_H 155