openharmony/drivers_framework
1
0
Fork 0
mirror of https://github.com/openharmony/drivers_framework.git synced 2026-07-19 16:24:45 -04:00
Code Issues Packages Projects Releases Wiki Activity

optimize hdf utils dirs

Browse Source 
Signed-off-by: yuanbo <yuanbo@huawei.com>
This commit is contained in:
yuanbo
2021-09-28 16:19:08 +08:00
parent 9e102e7ced
commit d467d9ae6d
20 changed files with 5 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/utils/device_resource_if.h
+447
View File
@@ -0,0 +1,447 @@
/*
* Copyright (c) 2020-2021 Huawei Device Co., Ltd.
*
* HDF is dual licensed: you can use it either under the terms of
* the GPL, or the BSD license, at your option.
* See the LICENSE file in the root of this repository for complete details.
*/
/**
* @addtogroup DriverConfig
* @{
*
* @brief Defines APIs for HDF driver developers to read driver configuration information.
*
* During version compilation of the device resource source file defined by developers, the compilation tool
* (for example, the compilation tool of the HCS file is hc-gen) generates bytecodes. When the HDF starts,
* it transfers the bytecode memory to the <b>DriverConfig</b> module. The <b>DriverConfig</b> module converts
* the bytecodes into a configuration tree and provides APIs for developers to query the tree.
*
* @since 1.0
* @version 1.0
*/
/**
* @file device_resource_if.h
*
* @brief Declares the APIs for querying the configuration tree.
*
* @since 1.0
* @version 1.0
*/
#ifndef DEVICE_RESOURCE_IF_H
#define DEVICE_RESOURCE_IF_H
#include "hdf_base.h"
#ifdef __cplusplus
#if __cplusplus
extern "C" {
#endif
#endif /* __cplusplus */
/**
* @brief Enumerates configuration file types.
*/
typedef enum {
HDF_CONFIG_SOURCE = 0, /**< HDF configuration file */
INVALID, /**< Invalid configuration file type */
} DeviceResourceType;
/**
* @brief Defines the attributes of a tree node in the configuration tree.
*
* The tree node attributes are saved in a linked list. The information about each node in the linked list contains
* the attribute name, attribute value, and pointer that points to the next attribute.
*/
struct DeviceResourceAttr {
const char *name; /**< Pointer to the attribute name */
const char *value; /**< Pointer to the attribute value */
struct DeviceResourceAttr *next; /**< Pointer to the next attribute of the node in the configuration tree. */
};
/**
* @brief Defines a tree node in the configuration tree.
*
* The tree node information includes the node name, unique node ID, node attributes, parent node, child nodes,
* and sibling nodes.
*/
struct DeviceResourceNode {
const char *name; /**< Pointer to the node name */
uint32_t hashValue; /**< Unique ID of a node */
struct DeviceResourceAttr *attrData; /**< Pointer to the node attributes */
struct DeviceResourceNode *parent; /**< Pointer to the parent node */
struct DeviceResourceNode *child; /**< Pointer to a child node */
struct DeviceResourceNode *sibling; /**< Pointer to a sibling node */
};
/**
* @brief Provides functions for obtaining information about the device resource configuration tree.
*
* This structure provides functions for obtaining information about the device resource configuration tree,
* including the root node, the <b>unit</b> attribute data, and the <b>String</b> attribute data.
*
* @since 1.0
* @version 1.0
*/
struct DeviceResourceIface {
/**
* @brief Obtains the root node of the configuration tree.
*
* When the driver framework is started, a configuration tree is created. You can use this function to obtain
* the root node of the configuration tree.
*
* @return Returns the root node of the configuration tree if the operation is successful;
* returns <b>NULL</b> otherwise.
* @since 1.0
* @version 1.0
*/
const struct DeviceResourceNode *(*GetRootNode)(void);
/**
* @brief Obtains the value of a <b>BOOL</b> attribute of a configuration tree node.
*
* @param node Indicates the pointer to the configuration tree node.
* @param attrName Indicates the pointer to the name of the attribute.
*
* @return Returns <b>true</b> if the operation is successful and the value of the <b>BOOL</b> attribute is
* <b>true</b>; returns <b>false</b> otherwise.
* @since 1.0
* @version 1.0
*/
bool (*GetBool)(const struct DeviceResourceNode *node, const char *attrName);
/**
* @brief Obtains the value of a <b>Uint8</b> attribute of a configuration tree node.
*
* @param node Indicates the pointer to the configuration tree node.
* @param attrName Indicates the pointer to the name of the attribute.
* @param value Indicates the pointer to the memory that stores the obtained data. The memory is applied
* by the user.
* @param def Indicates the value to fill into the memory pointed by <b>value</b> if the operation fails.
*
* @return Returns <b>0</b> if the attribute value is obtained successfully; returns a negative value otherwise.
* @since 1.0
* @version 1.0
*/
int32_t (*GetUint8)(const struct DeviceResourceNode *node, const char *attrName, uint8_t *value, uint8_t def);
/**
* @brief Obtains the value of a <b>Unit8</b> array attribute numbered <b>index</b> of a configuration tree node.
*
* @param node Indicates the pointer to the configuration tree node.
* @param attrName Indicates the pointer to the name of the array attribute.
* @param index Indicates the number of the index (counting from 0) where the value is to obtain.
* @param value Indicates the pointer to the memory that stores the obtained data. The memory is applied
* by the user.
* @param def Indicates the value to fill into the memory pointed by <b>value</b> if the operation fails.
*
* @return Returns <b>0</b> if the array attribute value is obtained successfully; returns a negative value
* otherwise.
* @since 1.0
* @version 1.0
*/
int32_t (*GetUint8ArrayElem)(const struct DeviceResourceNode *node, const char *attrName, uint32_t index,
uint8_t *value, uint8_t def);
/**
* @brief Obtains the value of a <b>Uint8</b> array attribute of a configuration tree node.
*
* @param node Indicates the pointer to the configuration tree node.
* @param attrName Indicates the pointer to the name of the array attribute.
* @param value Indicates the pointer to the array that stores the obtained data. The memory of the array is applied
* by the user.
* @param len Indicates the length of the array.
* @param def Indicates the value to fill into <b>value</b> if the operation fails. If the obtained attribute value
* contains 16-bit, 32-bit, or 64-bit data, the element corresponding to the 16-bit, 32-bit, or 64-bit data in the
* array is filled using the value of <b>def</b>, and the other elements are filled with the actual value obtained.
* If the failure is caused by other exceptions, the first element in the array is filled using the value of
* <b>def</b>.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
* @since 1.0
* @version 1.0
*/
int32_t (*GetUint8Array)(const struct DeviceResourceNode *node, const char *attrName, uint8_t *value, uint32_t len,
uint8_t def);
/**
* @brief Obtains the value of a <b>Uint16</b> attribute of a configuration tree node.
*
* @param node Indicates the pointer to the configuration tree node.
* @param attrName Indicates the pointer to the name of the attribute.
* @param value Indicates the pointer to the memory that stores the obtained data. The memory is applied
* by the user.
* @param def Indicates the value to fill into the memory pointed by <b>value</b> if the operation fails.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
* @since 1.0
* @version 1.0
*/
int32_t (*GetUint16)(const struct DeviceResourceNode *node, const char *attrName, uint16_t *value, uint16_t def);
/**
* @brief Obtains the value of a <b>Uint16</b> array attribute numbered <b>index</b> of a configuration tree node.
*
* @param node Indicates the pointer to the configuration tree node.
* @param attrName Indicates the pointer to the name of the array attribute.
* @param index Indicates the number of the index (counting from 0) where the value is to obtain.
* @param value Indicates the pointer to the memory that stores the obtained data. The memory is applied
* by the user.
* @param def Indicates the value to fill into the memory pointed by <b>value</b> if the operation fails.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
* @since 1.0
* @version 1.0
*/
int32_t (*GetUint16ArrayElem)(const struct DeviceResourceNode *node, const char *attrName, uint32_t index,
uint16_t *value, uint16_t def);
/**
* @brief Obtains the values of a <b>Uint16</b> array attribute of a configuration tree node.
*
* @param node Indicates the pointer to the configuration tree node.
* @param attrName Indicates the pointer to the name of the array attribute.
* @param value Indicates the pointer to the array that stores the obtained data. The memory of the array is applied
* by the user.
* @param len Indicates the length of the array.
* @param def Indicates the value to fill into <b>value</b> if the operation fails. If the obtained attribute value
* contains 32-bit or 64-bit data, the element corresponding to the 32-bit or 64-bit data in the array is filled
* using the value of <b>def</b>, and the other elements are filled with the actual value obtained. If the failure
* is caused by other exceptions, the first element in the array is filled using the value of <b>def</b>.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
* @since 1.0
* @version 1.0
*/
int32_t (*GetUint16Array)(const struct DeviceResourceNode *node, const char *attrName, uint16_t *value,
uint32_t len, uint16_t def);
/**
* @brief Obtains the value of a <b>Uint32</b> attribute of a configuration tree node.
*
* @param node Indicates the pointer to the configuration tree node.
* @param attrName Indicates the pointer to the name of the attribute.
* @param value Indicates the pointer to the memory that stores the obtained data. The memory is applied
* by the user.
* @param def Indicates the value to fill into the memory pointed by <b>value</b> if the operation fails.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
* @since 1.0
* @version 1.0
*/
int32_t (*GetUint32)(const struct DeviceResourceNode *node, const char *attrName, uint32_t *value, uint32_t def);
/**
* @brief Obtains the value of a <b>Uint32</b> array attribute numbered <b>index</b> of a configuration tree node.
*
* @param node Indicates the pointer to the configuration tree node.
* @param attrName Indicates the pointer to the name of the array attribute.
* @param index Indicates the number of the index (counting from 0) where the value is to obtain.
* @param value Indicates the pointer to the memory that stores the obtained data. The memory is applied
* by the user.
* @param def Indicates the value to fill into the memory pointed by <b>value</b> if the operation fails.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
* @since 1.0
* @version 1.0
*/
int32_t (*GetUint32ArrayElem)(const struct DeviceResourceNode *node, const char *attrName, uint32_t index,
uint32_t *value, uint32_t def);
/**
* @brief Obtains the values of a <b>Uint32</b> array attribute of a configuration tree node.
*
* @param node Indicates the pointer to the configuration tree node.
* @param attrName Indicates the pointer to the name of the array attribute.
* @param value Indicates the pointer to an array that stores the obtained data.
* @param len Indicates the pointer to the array that stores the obtained data. The memory of the array is applied
* by the user.
* @param def Indicates the value to fill into <b>value</b> if the operation fails. If the obtained attribute value
* contains 64-bit data, the element corresponding to the 64-bit data in the array is filled using the value of
* <b>def</b>, and the other elements are filled with the actual value obtained. If the failure is caused by other
* exceptions, the first element in the array is filled using the value of <b>def</b>.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
* @since 1.0
* @version 1.0
*/
int32_t (*GetUint32Array)(const struct DeviceResourceNode *node, const char *attrName, uint32_t *value,
uint32_t len, uint32_t def);
/**
* @brief Obtains the value of a <b>Uint64</b> attribute of a configuration tree node.
*
* @param node Indicates the pointer to the configuration tree node.
* @param attrName Indicates the pointer to the name of the attribute.
* @param value Indicates the pointer to the memory that stores the obtained data. The memory is applied
* by the user.
* @param def Indicates the value to fill into the memory pointed by <b>value</b> if the operation fails.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
* @since 1.0
* @version 1.0
*/
int32_t (*GetUint64)(const struct DeviceResourceNode *node, const char *attrName, uint64_t *value, uint64_t def);
/**
* @brief Obtains the value of a <b>Uint64</b> array attribute numbered <b>index</b> of a configuration tree node.
*
* @param node Indicates the pointer to the configuration tree node.
* @param attrName Indicates the pointer to the name of the array attribute.
* @param index Indicates the number of the index (counting from 0) where the value is to obtain.
* @param value Indicates the pointer to the memory that stores the obtained data. The memory is applied
* by the user.
* @param def Indicates the value to fill into the memory pointed by <b>value</b> if the operation fails.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
* @since 1.0
* @version 1.0
*/
int32_t (*GetUint64ArrayElem)(const struct DeviceResourceNode *node, const char *attrName, uint32_t index,
uint64_t *value, uint64_t def);
/**
* @brief Obtains the values of a <b>Uint64</b> array attribute of a configuration tree node.
*
* @param node Indicates the pointer to the configuration tree node.
* @param attrName Indicates the pointer to the name of the array attribute.
* @param value Indicates the pointer to the array that stores the obtained data. The memory of the array is applied
* by the user.
* @param len Indicates the length of the array.
* @param def Indicates the value to fill into the first element in the <b>value</b> array if the operation fails.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
* @since 1.0
* @version 1.0
*/
int32_t (*GetUint64Array)(const struct DeviceResourceNode *node, const char *attrName, uint64_t *value,
uint32_t len, uint64_t def);
/**
* @brief Obtains the value of a <b>String</b> attribute of a configuration tree node.
*
* @param node Indicates the pointer to the configuration tree node.
* @param attrName Indicates the pointer to the name of the attribute.
* @param value Indicates the double pointer to the memory where the obtained data is stored. The string memory is
* provided by the function implementer. Users only need to transfer the double pointer. The memory cannot be
* released after being used.
* @param def Indicates the value to be passed to <b>value</b> if the operation fails.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
* @since 1.0
* @version 1.0
*/
int32_t (*GetString)(const struct DeviceResourceNode *node, const char *attrName, const char **value,
const char *def);
/**
* @brief Obtains the value of a <b>String</b> array attribute numbered <b>index</b> of a configuration tree node.
*
* @param node Indicates the pointer to the configuration tree node.
* @param attrName Indicates the pointer to the name of the array attribute.
* @param index Indicates the number of the index (counting from 0) where the value is to obtain.
* @param value Indicates the double pointer to the memory where the obtained data is stored. The string memory is
* provided by the function implementer. Users only need to transfer the double pointer. The memory cannot be
* released after being used.
* @param def def Indicates the value to be passed to <b>value</b> if the operation fails.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
* @since 1.0
* @version 1.0
*/
int32_t (*GetStringArrayElem)(const struct DeviceResourceNode *node, const char *attrName, uint32_t index,
const char **value, const char *def);
/**
* @brief Obtains the number of values for an array attribute of a configuration tree node.
*
* @param node Indicates the pointer to the configuration tree node.
* @param attrName Indicates the pointer to the name of the array attribute.
*
* @return Returns the number of values for an array attribute if the operation is successful;
* return a negative value otherwise.
* @since 1.0
* @version 1.0
*/
int32_t (*GetElemNum)(const struct DeviceResourceNode *node, const char *attrName);
/**
* @brief Obtains a specified child node of the current tree node based on the value of a specific reserved
* attribute (for example, the reserved attribute of the HCS is <b>match_attr</b>).
*
* There is a specific reserved attribute in the syntax of the device resource configuration source file.
* If this attribute is set for a tree node, you can obtain the node based on the attribute value.
* Users can set the attribute value based on the usage of their own nodes, but they must ensure that the attribute
* values are unique.
*
* @param node Indicates the pointer to the node for whom a child node is to be obtained. The node can be the child
* node's parent node or grandparent node.
* @param attrValue Indicates the pointer to the value of the reserved attribute configured for the child node.
*
* @return Returns the target node if the operation is successful; returns <b>NULL</b> otherwise.
* @since 1.0
* @version 1.0
*/
const struct DeviceResourceNode *(*GetNodeByMatchAttr)(const struct DeviceResourceNode *node,
const char *attrValue);
/**
* @brief Obtains the child node with a specified node name from a parent node.
*
* @param node Indicates the pointer to the parent node.
* @param nodeName Indicates the pointer to the name of the child node to obtain.
*
* @return Returns the child nodes if the operation is successful; returns <b>NULL</b> otherwise.
* @since 1.0
* @version 1.0
*/
const struct DeviceResourceNode *(*GetChildNode)(const struct DeviceResourceNode *node, const char *nodeName);
/**
* @brief Obtains the node that is specified by a node-type attribute of a configuration tree node.
*
* If the attribute value is a configuration tree node, the path of the node is converted to a globally unique
* <b>hashValue</b> when the device resource source file is compiled (for example, the compilation tool of the HCS
* source file is hc-gen). For details about the <b>hashValue</b>, see {@link struct DeviceResourceNode}.
* When you obtain a tree node using the node-type attribute, you obtain the <b>hashValue</b> through the node-type
* attribute first, and then traverse the tree to obtain the tree node corresponding to the <b>hashValue</b>.
*
* @param node Indicates the pointer to the tree node whose attribute is to obtain.
* @param attrName Indicates the pointer to the name of attribute whose value is a node path.
* @return Returns the target node if the operation is successful; returns <b>NULL</b> otherwise.
* @since 1.0
* @version 1.0
*/
const struct DeviceResourceNode *(*GetNodeByRefAttr)(const struct DeviceResourceNode *node, const char *attrName);
};
/**
* @brief Obtains the device resource interface handle of the corresponding configuration tree type.
*
* You can use the obtained handle to use the device resource interface.
*
* @param type Indicates the type of the device resource interface handle to obtain.
*
* @return Returns the device resource interface handle if the operation is successful; returns <b>NULL</b> otherwise.
* @since 1.0
* @version 1.0
*/
struct DeviceResourceIface *DeviceResourceGetIfaceInstance(DeviceResourceType type);
/**
* @brief Traverses the attributes of the current configuration tree node.
*
* This operation is a <b>for</b> loop in essence.
*
* @param node Indicates the configuration tree node to traverse.
* @param attr Indicates the traversed attributes.
* @since 1.0
* @version 1.0
*/
#define DEV_RES_NODE_FOR_EACH_ATTR(node, attr) \
for ((attr) = (node)->attrData; (attr) != NULL; (attr) = (attr)->next)
/**
* @brief Traverses the child nodes of the current configuration tree node.
*
* This operation is a <b>for</b> loop in essence.
*
* @param node Indicates the configuration tree node to traverse.
* @param childNode Indicates the traversed child nodes.
* @since 1.0
* @version 1.0
*/
#define DEV_RES_NODE_FOR_EACH_CHILD_NODE(node, childNode) \
for ((childNode) = (node)->child; (childNode) != NULL; (childNode) = (childNode)->sibling)
#ifdef __cplusplus
#if __cplusplus
}
#endif
#endif /* __cplusplus */
#endif /* DEVICE_RESOURCE_IF_H */
/** @} */
include/utils/hdf_sbuf.h
+608
View File
@@ -0,0 +1,608 @@
/*
* Copyright (c) 2020-2021 Huawei Device Co., Ltd.
*
* HDF is dual licensed: you can use it either under the terms of
* the GPL, or the BSD license, at your option.
* See the LICENSE file in the root of this repository for complete details.
*/
/**
* @addtogroup Core
* @{
*
* @brief Provides functions to use the OpenHarmony Driver Foundation (HDF).
*
* The HDF implements driver framework capabilities such as driver loading, service management, driver message model,
* and power management.
* You can develop drivers based on the HDF.
*
* @since 1.0
*/
/**
* @file hdf_sbuf.h
*
* @brief Declares functions related to the HDF SBUF. The HDF provides data serialization and deserialization
* capabilities for data transmission between user-space applications and kernel-space drivers.
*
* @since 1.0
*/
#ifndef HDF_SBUF_H
#define HDF_SBUF_H
#include "hdf_base.h"
#ifdef __cplusplus
extern "C" {
#else
typedef uint16_t char16_t;
#endif /* __cplusplus */
struct HdfSBuf;
struct HdfSbufImpl;
struct HdfRemoteService;
/**
* @brief Enumerates HDF SBUF types.
*
* @since 1.0
*/
enum HdfSbufType {
SBUF_RAW = 0, /* SBUF used for communication between the user space and the kernel space */
SBUF_IPC, /* SBUF used for inter-process communication (IPC) */
SBUF_IPC_HW, /* Reserved for extension */
SBUF_TYPE_MAX, /* Maximum value of the SBUF type */
};
/**
* @brief Writes a data segment to a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param data Indicates the pointer to the data segment to write.
* @param writeSize Indicates the size of the data segment to write. The maximum value is 512 KB.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufWriteBuffer(struct HdfSBuf *sbuf, const void *data, uint32_t writeSize);
/**
* @brief Writes unpadded data to a <b>SBuf</b>. You can call {@link HdfSbufReadUnpadBuffer} to read the unpadded data.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param data Indicates the pointer to the data to write. The value cannot be a null pointer.
* @param writeSize Indicates the size of the data to write. The value cannot be <b>0</b>.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufWriteUnpadBuffer(struct HdfSBuf *sbuf, const uint8_t *data, uint32_t writeSize);
/**
* @brief Writes a 64-bit unsigned integer to a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the 64-bit unsigned integer to write.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufWriteUint64(struct HdfSBuf *sbuf, uint64_t value);
/**
* @brief Writes a 32-bit unsigned integer to a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the 32-bit unsigned integer to write.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufWriteUint32(struct HdfSBuf *sbuf, uint32_t value);
/**
* @brief Writes a 16-bit unsigned integer to a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the 16-bit unsigned integer to write.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufWriteUint16(struct HdfSBuf *sbuf, uint16_t value);
/**
* @brief Writes an 8-bit unsigned integer to a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the 8-bit unsigned integer to write.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufWriteUint8(struct HdfSBuf *sbuf, uint8_t value);
/**
* @brief Writes a 64-bit signed integer to a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the 64-bit signed integer to write.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufWriteInt64(struct HdfSBuf *sbuf, int64_t value);
/**
* @brief Writes a 32-bit signed integer to a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the 32-bit signed integer to write.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufWriteInt32(struct HdfSBuf *sbuf, int32_t value);
/**
* @brief Writes a 16-bit signed integer to a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the 16-bit signed integer to write.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufWriteInt16(struct HdfSBuf *sbuf, int16_t value);
/**
* @brief Writes an 8-bit signed integer to a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the 8-bit signed integer to write.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufWriteInt8(struct HdfSBuf *sbuf, int8_t value);
/**
* @brief Writes a string to a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the pointer to the string to write.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufWriteString(struct HdfSBuf *sbuf, const char *value);
/**
* @brief Writes a wide character string to a <b>SBuf</b>.
* The SBUF of the <b>SBUF_RAW</b> type does not support this function.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the pointer to the wide character string to write.
* @param size Indicates the size of the wide character string to write.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufWriteString16(struct HdfSBuf *sbuf, const char16_t *value, uint32_t size);
/**
* @brief Writes a floating-point number to a <b>SBuf</b>.
* The SBUF of the <b>SBUF_RAW</b> type does not support this function.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the floating-point number to write.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufWriteFloat(struct HdfSBuf *sbuf, float value);
/**
* @brief Writes a double-precision floating-point number to a <b>SBuf</b>.
* The SBUF of the <b>SBUF_RAW</b> type does not support this function.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the double-precision floating-point number to write.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufWriteDouble(struct HdfSBuf *sbuf, double value);
/**
* @brief Writes a file descriptor to a <b>SBuf</b>.
* The SBUF of the <b>SBUF_RAW</b> type does not support this function.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param fd Indicates the file descriptor to write.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufWriteFileDescriptor(struct HdfSBuf *sbuf, int fd);
/**
* @brief Writes an IPC service to a <b>SBuf</b>. The SBUF of the <b>SBUF_RAW</b> type does not support this function.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param service Indicates the pointer to the IPC service to write.
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
*
* @since 1.0
*/
int32_t HdfSBufWriteRemoteService(struct HdfSBuf *sbuf, const struct HdfRemoteService *service);
/**
* @brief Reads an IPC service from a <b>SBuf</b>.
* The SBUF of the <b>SBUF_RAW</b> type does not support this function.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @return Returns the pointer to the IPC service object if the operation is successful;
* returns a null pointer otherwise.
*
* @since 1.0
*/
struct HdfRemoteService *HdfSBufReadRemoteService(struct HdfSBuf *sbuf);
/**
* @brief Reads a file descriptor from a <b>SBuf</b>.
* The SBUF of the <b>SBUF_RAW</b> type does not support this function.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @return Returns a valid file descriptor if the operation is successful; returns a negative value otherwise.
*
* @since 1.0
*/
int HdfSbufReadFileDescriptor(struct HdfSBuf *sbuf);
/**
* @brief Reads a double-precision floating-point number from a <b>SBuf</b>.
* The SBUF of the <b>SBUF_RAW</b> type does not support this function.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the pointer to the double-precision floating-point number read,
* which is requested by the caller.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufReadDouble(struct HdfSBuf *sbuf, double *value);
/**
* @brief Reads a floating-point number from a <b>SBuf</b>.
* The SBUF of the <b>SBUF_RAW</b> type does not support this function.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the pointer to the floating-point number read, which is requested by the caller.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufReadFloat(struct HdfSBuf *sbuf, float *value);
/**
* @brief Reads a wide character string from a <b>SBuf</b>.
* The SBUF of the <b>SBUF_RAW</b> type does not support this function.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @return Returns the pointer to the wide character string if the operation is successful;
* returns a null pointer otherwise.
*
* @since 1.0
*/
const char16_t *HdfSBufReadString16(struct HdfSBuf *sbuf);
/**
* @brief Reads a data segment from a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param data Indicates the double pointer to the data read. The data read is stored in <b>*data</b>,
* which is requested by the caller. The memory pointed to by <b>*data</b> is managed by
* the <b>SBuf</b> and they share the same lifecycle.
* @param readSize Indicates the pointer to the size of the data read.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufReadBuffer(struct HdfSBuf *sbuf, const void **data, uint32_t *readSize);
/**
* @brief Reads unpadded data from a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param length Indicates the length of the data to read.
* @return Returns the pointer to the unpadded data if the operation is successful; returns a null pointer otherwise.
*
* @since 1.0
*/
const uint8_t *HdfSbufReadUnpadBuffer(struct HdfSBuf *sbuf, size_t length);
/**
* @brief Reads a 64-bit unsigned integer from a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the pointer to the 64-bit unsigned integer read, which is requested by the caller.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufReadUint64(struct HdfSBuf *sbuf, uint64_t *value);
/**
* @brief Reads a 32-bit unsigned integer from a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the pointer to the 32-bit unsigned integer read, which is requested by the caller.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufReadUint32(struct HdfSBuf *sbuf, uint32_t *value);
/**
* @brief Reads a 16-bit unsigned integer from a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the pointer to the 16-bit unsigned integer read, which is requested by the caller.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufReadUint16(struct HdfSBuf *sbuf, uint16_t *value);
/**
* @brief Reads an 8-bit unsigned integer from a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the pointer to the 8-bit unsigned integer read, which is requested by the caller.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufReadUint8(struct HdfSBuf *sbuf, uint8_t *value);
/**
* @brief Reads a 64-bit signed integer from a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the pointer to the 64-bit signed integer read, which is requested by the caller.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufReadInt64(struct HdfSBuf *sbuf, int64_t *value);
/**
* @brief Reads a 32-bit signed integer from a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the pointer to the 32-bit signed integer read, which is requested by the caller.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufReadInt32(struct HdfSBuf *sbuf, int32_t *value);
/**
* @brief Reads a 16-bit signed integer from a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the pointer to the 16-bit signed integer read, which is requested by the caller.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufReadInt16(struct HdfSBuf *sbuf, int16_t *value);
/**
* @brief Reads an 8-bit signed integer from a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param value Indicates the pointer to the 8-bit signed integer read, which is requested by the caller.
* @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise.
*
* @since 1.0
*/
bool HdfSbufReadInt8(struct HdfSBuf *sbuf, int8_t *value);
/**
* @brief Reads a string from a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @return Returns the pointer to the string read if the operation is successful; returns <b>NULL</b> otherwise.
* The memory pointed to by this pointer is managed by the <b>SBuf</b> and they share the same lifecycle.
*
* @since 1.0
*/
const char *HdfSbufReadString(struct HdfSBuf *sbuf);
/**
* @brief Obtains the pointer to the data stored in a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @return Returns the pointer to the data stored in the target <b>SBuf</b> if the operation is successful;
* returns a null pointer otherwise.
*
* @since 1.0
*/
uint8_t *HdfSbufGetData(const struct HdfSBuf *sbuf);
/**
* @brief Clears the data stored in a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
*
* @since 1.0
*/
void HdfSbufFlush(struct HdfSBuf *sbuf);
/**
* @brief Obtains the capacity of a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @return Returns the <b>SBuf</b> capacity.
*
* @since 1.0
*/
size_t HdfSbufGetCapacity(const struct HdfSBuf *sbuf);
/**
* @brief Obtains the size of the data stored in a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @return Returns the data size.
*
* @since 1.0
*/
size_t HdfSbufGetDataSize(const struct HdfSBuf *sbuf);
/**
* @brief Sets the data size of a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @param size Indicates the data size to set, which cannot exceed the size obtained via {@link HdfSbufGetDataSize}.
*
* @since 1.0
*/
void HdfSbufSetDataSize(struct HdfSBuf *sbuf, size_t size);
/**
* @brief Obtains a <b>SBuf</b> instance.
*
* @param capacity Indicates the initial capacity of the <b>SBuf</b>.
* @return Returns the <b>SBuf</b> instance.
*
* @since 1.0
*/
struct HdfSBuf *HdfSBufObtain(size_t capacity);
/**
* @brief Obtains a <b>SBuf</b> instance of the default capacity (256 bytes).
*
* @return Returns the <b>SBuf</b> instance.
*
* @since 1.0
*/
struct HdfSBuf *HdfSBufObtainDefaultSize(void);
/**
* @brief Creates a <b>SBuf</b> instance with the specified data and size.
* The pointer to the data stored in the <b>SBuf</b> is released by the caller,
* and the written data size should not exceed the specified value of <b>size</b>.
*
* @param base Indicates the base of the data to use.
* @param size Indicates the size of the data to use.
* @return Returns the <b>SBuf</b> instance.
*
* @since 1.0
*/
struct HdfSBuf *HdfSBufBind(uintptr_t base, size_t size);
/**
* @brief Releases a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
*
* @since 1.0
*/
void HdfSBufRecycle(struct HdfSBuf *sbuf);
/**
* @brief Creates a <b>SBuf</b> instance with an original <b>SBuf</b>.
* This function moves the data stored in the original <b>SBuf</b> to the new one without memory copy.
*
* @param sbuf Indicates the pointer to the original <b>SBuf</b>.
* @return Returns the new <b>SBuf</b> instance.
*
* @since 1.0
*/
struct HdfSBuf *HdfSBufMove(struct HdfSBuf *sbuf);
/**
* @brief Creates a <b>SBuf</b> instance with an original <b>SBuf</b>.
* This function copies the data stored in the original <b>SBuf</b> to the new one.
*
* @param sbuf Indicates the pointer to the original <b>SBuf</b>.
* @return Returns the new <b>SBuf</b> instance.
*
* @since 1.0
*/
struct HdfSBuf *HdfSBufCopy(const struct HdfSBuf *sbuf);
/**
* @brief Transfers the data ownership to a <b>SBuf</b>. Once the <b>SBuf</b> is released,
* the bound data memory is also released. This function is used together with {@link HdfSBufBind}.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
*
* @since 1.0
*/
void HdfSbufTransDataOwnership(struct HdfSBuf *sbuf);
/**
* @brief Obtains a <b>SBuf</b> instance of a specified type.
*
* @param type Indicates the SBUF type, which is defined in {@link HdfSbufType}.
* @return Returns the <b>SBuf</b> instance.
*
* @since 1.0
*/
struct HdfSBuf *HdfSBufTypedObtain(uint32_t type);
/**
* @brief Obtains a <b>SBuf</b> instance of a specified type based on the implementation of an existing <b>SBuf</b>.
*
* @param type Indicates the SBUF type, which is defined in {@link HdfSbufType}.
* @param impl Indicates the pointer to the implementation of an existing <b>SBuf</b>.
* @return Returns the new <b>SBuf</b> instance.
*
* @since 1.0
*/
struct HdfSBuf *HdfSBufTypedObtainInplace(uint32_t type, struct HdfSbufImpl *impl);
/**
* @brief Obtains a <b>SBuf</b> instance of a specified type with the given initial capacity.
*
* @param type Indicates the SBUF type, which is defined in {@link HdfSbufType}.
* @param capacity Indicates the initial capacity of the <b>SBuf</b>.
* @return Returns the new <b>SBuf</b> instance.
*
* @since 1.0
*/
struct HdfSBuf *HdfSBufTypedObtainCapacity(uint32_t type, size_t capacity);
/**
* @brief Creates a <b>SBuf</b> instance of a specified type with the specified data and size.
* The pointer to the data stored in the <b>SBuf</b> is released by the caller,
* and the written data size should not exceed the specified value of <b>size</b>.
*
* @param type Indicates the SBUF type, which is defined in {@link HdfSbufType}.
* @param base Indicates the base of the data to use.
* @param size Indicates the size of the data to use.
* @return Returns the <b>SBuf</b> instance.
*
* @since 1.0
*/
struct HdfSBuf *HdfSBufTypedBind(uint32_t type, uintptr_t base, size_t size);
/**
* @brief Obtains the implementation of a <b>SBuf</b>.
*
* @param sbuf Indicates the pointer to the target <b>SBuf</b>.
* @return Returns the pointer to the implementation of the <b>SBuf</b>.
*
* @since 1.0
*/
struct HdfSbufImpl *HdfSbufGetImpl(struct HdfSBuf *sbuf);
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* HDF_SBUF_H */
/** @} */