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 buffer_util.h
31  *
32  * @brief Provides the APIs for allocating, releasing, serializing, and deserializing the <b>BufferHandle</b> object.
33  *
34  * @since 1.0
35  */
36 
37 #ifndef HDI_BUFFER_UTIL_H
38 #define HDI_BUFFER_UTIL_H
39 
40 #include "buffer_handle.h"
41 #include "hdf_sbuf.h"
42 
43 /**
44  * @brief Defines the maximum value of the <b>reserveFds</b> in <b>BufferHandle</b>.
45  */
46 #define MAX_RESERVE_FDS 1024
47 
48 /**
49  * @brief Defines the maximum value of the <b>reserveInts</b> in <b>BufferHandle</b>.
50  */
51 #define MAX_RESERVE_INTS 1024
52 
53 #ifdef __cplusplus
54 extern "C" {
55 #endif /* __cplusplus */
56 
57 /**
58  * @brief Allocates a <b>BufferHandle</b> object.
59  *
60  * You can use this API to create the default <b>BufferHandle</b> object
61  * based on the specified <b>reserveFds</b> and <b>reserveInts</b>.
62  *
63  * @param reserveFds Indicates the file descriptor (FD) count (<b>0</b> to <b>MAX_RESERVE_FDS</b>) in <b>reserve[0]</b>.
64  * @param reserveInts Indicates the integer count (<b>0</b> to <b>MAX_RESERVE_FDS</b>) in <b>reserve[reserveFds]</b>.
65  * @return Returns the pointer to the <b>BufferHandle</b> allocated if the operation is successful;
66  * returns <b>NULL</b> otherwise.
67  */
68 BufferHandle *AllocateNativeBufferHandle(uint32_t reserveFds, uint32_t reserveInts);
69 
70 /**
71  * @brief Clones a <b>BufferHandle</b> object.
72  *
73  * You can use this API to create a <b>BufferHandle</b> object from a given <b>BufferHandle</b> object.
74  *
75  * @param other Indicates the pointer to the <b>BufferHandle</b> object to clone.
76  * @return Returns the pointer to the <b>BufferHandle</b> created if the operation is successful;
77  * returns <b>NULL</b> otherwise.
78  */
79 BufferHandle *CloneNativeBufferHandle(const BufferHandle *other);
80 
81 /**
82  * @brief Releases a <b>BufferHandle</b> object.
83  *
84  * @param handle Indicates the pointer to the <b>BufferHandle</b> object to release.
85  */
86 void FreeNativeBufferHandle(BufferHandle *handle);
87 
88 /**
89  * @brief Serializes a <b>BufferHandle</b> object.
90  *
91  * You can use this API to write a <b>BufferHandle</b> object to a <b>HdfSBuf</b> object.
92  * <b>HdfSbufWriteNativeBufferHandle</b> and <b>HdfSbufReadNativeBufferHandle</b> are used in pairs.
93  *
94  * @param data Indicates the pointer to the <b>HdfSBuf</b> object.
95  * @param handle Indicates the pointer to the <b>BufferHandle</b> object to serialize.
96  */
97 bool HdfSbufWriteNativeBufferHandle(struct HdfSBuf *data, const BufferHandle *handle);
98 
99 /**
100  * @brief Deserializes a <b>BufferHandle</b> object.
101  *
102  * You can use this API to read a <b>BufferHandle</b> object from a <b>HdfSBuf</b> object
103  * according to the serialization format and create a new <b>BufferHandle</b> object.
104  * <b>HdfSbufWriteNativeBufferHandle</b> and <b>HdfSbufReadNativeBufferHandle</b> are used in pairs.
105  *
106  * @param data Indicates the pointer to the <b>HdfSBuf</b> object.
107  * @return Returns the pointer to the <b>BufferHandle</b> obtained if the operation is successful;
108  * returns <b>NULL</b> otherwise.
109  */
110 BufferHandle *HdfSbufReadNativeBufferHandle(struct HdfSBuf *data);
111 
112 #ifdef __cplusplus
113 }
114 #endif /* __cplusplus */
115 
116 #endif /* HDI_BUFFER_UTIL_H */