API参考&文档一致性整改

Signed-off-by: Leal <lealtan@163.com>

security/device_certificate/certmanager/include/cm_native_api.h

@@ -4,7 +4,7 @@
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- *     http://www.apache.org/licenses/LICENSE-2.0
+ * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
@@ -12,27 +12,25 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
-/**
- * @file cm_native_api.h
- *
- * @brief Defines the Certificate Manager APIs.
- *
- * @library libohcert_manager.so
- * @kit DeviceCertificateKit
- * @syscap SystemCapability.Security.CertificateManager
- * @since 22
- */
-
 /**
  * @addtogroup CertManager
  * @{
  *
  * @brief Describes the OpenHarmony Certificate Manager capabilities, including certificate and credential management
- *    operations, provided for applications.
+ * operations, provided for applications.
  *
  * @since 22
  */
+/**
+ * @file cm_native_api.h
+ *
+ * @brief Declares the APIs used to obtain details of specific certificates.
+ * 
+ * @library libohcert_manager.so
+ * @kit DeviceCertificateKit
+ * @syscap SystemCapability.Security.CertificateManager
+ * @since 22
+ */
 
 #ifndef CM_NATIVE_API_H
 #define CM_NATIVE_API_H
@@ -43,22 +41,26 @@
 extern "C" {
 #endif
 
+
 /**
- * @brief Get the detail of USB key certificate.
- *
- * @param keyUri Indicates the USB key certificate uri.
- * @param ukeyInfo Indicates USB key certificate attribute information.
- * @param certificateList Indicates the detail information of USB key certificate.
- * @return {@link OH_CM_ErrorCode#OH_CM_SUCCESS} 0 - The operation is successful.
- *         {@link OH_CM_ErrorCode#OH_CM_HAS_NO_PERMISSION} 201 - Permission verification failed.
- *         {@link OH_CM_ErrorCode#OH_CM_CAPABILITY_NOT_SUPPORTED} 801 - Capability not supported.
- *         {@link OH_CM_ErrorCode#OH_CM_PARAMETER_VALIDATION_FAILED} 17500011 - Indicates that the
- *    input parameters validation failed. for example, the parameter format is incorrect or the value range is invalid.
- *         {@link OH_CM_ErrorCode#OH_CM_INNER_FAILURE} 17500001 - Internal error. Possible causes:
- *    1. IPC communication failed; 2. Memory operation error; 3. File operation error.
- *         {@link OH_CM_ErrorCode#OH_CM_NOT_FOUND} 17500002 - Indicates that the certificate does not exist.
- *         {@link OH_CM_ErrorCode#OH_CM_ACCESS_UKEY_SERVICE_FAILED} 17500010 - Indicates that
- *    access USB key service failed.
+ * @brief Obtains the detail list of USB certificate credentials.
+ * 
+ * @param keyUri Pointer to the URI that stores the USB certificate credentials, in string format.
+ * @param ukeyInfo Pointer to the property information of the USB certificate credential.
+ * @param certificateList Pointer to the USB certificate credential detail list obtained.
+ * @return {@link OH_CM_ErrorCode}:
+ * **OH_CM_SUCCESS = 0**: Operation successful.
+ * **OH_CM_HAS_NO_PERMISSION = 201**: Permission verification failed.
+ * **OH_CM_CAPABILITY_NOT_SUPPORTED = 801**: The device is not supported.
+ * **OH_CM_PARAMETER_VALIDATION_FAILED = 17500011**: Input parameter verification failed. Possible causes:
+ * 1. Incorrect parameter format.
+ * 2. Invalid parameter value range.
+ * **OH_CM_INNER_FAILURE = 17500001**: Internal error. Possible causes:
+ * 1. IPC failure.
+ * 2. Memory operation error.
+ * 3. File operation error.
+ * **OH_CM_NOT_FOUND = 17500002**: The certificate does not exist.
+ * **OH_CM_ACCESS_UKEY_SERVICE_FAILED = 17500010**: Failed to access the USB certificate credential.
  * @permission ohos.permission.ACCESS_CERT_MANAGER
  * @since 22
  */
@@ -66,52 +68,60 @@ int32_t OH_CertManager_GetUkeyCertificate(const OH_CM_Blob *keyUri,
     const OH_CM_UkeyInfo *ukeyInfo, OH_CM_CredentialDetailList *certificateList);
 
 /**
- * @brief Get the detail of application private certificate.
- *
- * @param keyUri Indicates the private certificate uri.
- * @param certificate Indicates the detail information of private certificate.
- * @return {@link OH_CM_ErrorCode#OH_CM_SUCCESS} 0 - The operation is successful.
- *         {@link OH_CM_ErrorCode#OH_CM_HAS_NO_PERMISSION} 201 - Permission verification failed.
- *         {@link OH_CM_ErrorCode#OH_CM_PARAMETER_VALIDATION_FAILED} 17500011 - Indicates that the input
- *    parameters validation failed. for example, the parameter format is incorrect or the value range is invalid.
- *         {@link OH_CM_ErrorCode#OH_CM_INNER_FAILURE} 17500001 - Internal error. Possible causes:
- *    1. IPC communication failed; 2. Memory operation error; 3. File operation error.
- *         {@link OH_CM_ErrorCode#OH_CM_NOT_FOUND} 17500002 - Indicates that the certificate does not exist.
+ * @brief Obtains the details of a private certificate credential of a specific application.
+ * 
+ * @param keyUri Pointer to the URI that stores the application's private certificate credentials, in string format.
+ * @param certificate Pointer to the details of the application's private credentials obtained.
+ * @return {@link OH_CM_ErrorCode}:
+ * **OH_CM_SUCCESS = 0**: Operation successful.
+ * **OH_CM_HAS_NO_PERMISSION = 201**: Permission verification failed.
+ * **OH_CM_PARAMETER_VALIDATION_FAILED = 17500011**: Input parameter verification failed. Possible causes:
+ * 1. Incorrect parameter format.
+ * 2. Invalid parameter value range.
+ * **OH_CM_INNER_FAILURE = 17500001**: Internal error. Possible causes:
+ * 1. IPC failure.
+ * 2. Memory operation error.
+ * 3. File operation error.
+ * **OH_CM_NOT_FOUND = 17500002**: The certificate does not exist.
  * @permission ohos.permission.ACCESS_CERT_MANAGER
  * @since 22
  */
 int32_t OH_CertManager_GetPrivateCertificate(const OH_CM_Blob *keyUri, OH_CM_Credential *certificate);
 
 /**
- * @brief Get the detail of user public certificate.
- *
- * @param keyUri Indicates the private certificate uri.
- * @param certificate Indicates the detail information of public certificate.
- * @return {@link OH_CM_ErrorCode#OH_CM_SUCCESS} 0 - The operation is successful.
- *         {@link OH_CM_ErrorCode#OH_CM_HAS_NO_PERMISSION} 201 - Permission verification failed.
- *         {@link OH_CM_ErrorCode#OH_CM_PARAMETER_VALIDATION_FAILED} 17500011 - Indicates that the input
- *    parameters validation failed. for example, the parameter format is incorrect or the value range is invalid.
- *         {@link OH_CM_ErrorCode#OH_CM_INNER_FAILURE} 17500001 - Internal error. Possible causes:
- *    1. IPC communication failed; 2. Memory operation error; 3. File operation error.
- *         {@link OH_CM_ErrorCode#OH_CM_NOT_FOUND} 17500002 - Indicates that the certificate does not exist.
- *         {@link OH_CM_ErrorCode#OH_CM_NO_AUTHORIZATION} 17500005 - The application is not authorized by the user.
+ * @brief Obtains the details of a public certificate credential of a specific user.
+ * 
+ * @param keyUri Pointer to the URI that stores the user's public certificate credentials, in string format.
+ * @param certificate Pointer to the details of the user's public certificate credential obtained.
+ * @return {@link OH_CM_ErrorCode}:
+ * **OH_CM_SUCCESS = 0**: Operation successful.
+ * **OH_CM_HAS_NO_PERMISSION = 201**: Permission verification failed.
+ * **OH_CM_PARAMETER_VALIDATION_FAILED = 17500011**: Input parameter verification failed. Possible causes:
+ * 1. Incorrect parameter format.
+ * 2. Invalid parameter value range.
+ * **OH_CM_INNER_FAILURE = 17500001**: Internal error. Possible causes:
+ * 1. IPC failure.
+ * 2. Memory operation error.
+ * 3. File operation error.
+ * **OH_CM_NOT_FOUND = 17500002**: The certificate does not exist.
+ * **OH_CM_NO_AUTHORIZATION = 17500005**: The application is not authorized.
  * @permission ohos.permission.ACCESS_CERT_MANAGER
  * @since 22
  */
 int32_t OH_CertManager_GetPublicCertificate(const OH_CM_Blob *keyUri, OH_CM_Credential *certificate);
 
 /**
- * @brief Destroys a credential detail list.
- *
- * @param certificateList Indicates the pointer to the credential detail list to destroy.
+ * @brief Destroys the certificate detail list.
+ * 
+ * @param certificateList Pointer to the certificate credential detail list to be destroyed.
  * @since 22
  */
 void OH_CertManager_FreeUkeyCertificate(OH_CM_CredentialDetailList *certificateList);
 
 /**
- * @brief Destroys a credential detail.
- *
- * @param certificate Indicates the pointer to the credential detail to destroy.
+ * @brief Destroys the certificate details.
+ * 
+ * @param certificate Pointer to the certificate credential details to be destroyed.
  * @since 22
  */
 void OH_CertManager_FreeCredential(OH_CM_Credential *certificate);
@@ -121,4 +131,4 @@ void OH_CertManager_FreeCredential(OH_CM_Credential *certificate);
 #endif
 
 /** @} */
-#endif /* CM_NATIVE_API_H */
+#endif /* CM_NATIVE_API_H */

security/device_certificate/certmanager/include/cm_native_type.h

@@ -4,7 +4,7 @@
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- *     http://www.apache.org/licenses/LICENSE-2.0
+ * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
@@ -12,27 +12,25 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
-/**
- * @file cm_native_type.h
- *
- * @brief Defines the structure and enumeration.
- *
- * @library libohcert_manager.so
- * @kit DeviceCertificateKit
- * @syscap SystemCapability.Security.CertificateManager
- * @since 22
- */
-
 /**
  * @addtogroup CertManagerType
  * @{
  *
  * @brief Defines the macros, enumerated values, data structures,
- *    and error codes used by OpenHarmony Certificate Manager APIs.
+ * and error codes used by OpenHarmony Certificate Manager APIs.
  *
  * @since 22
  */
+/**
+ * @file cm_native_type.h
+ *
+ * @brief Provides the enums, structs, macros, and error codes used by **CertManager** APIs.
+ * 
+ * @library libohcert_manager.so
+ * @kit DeviceCertificateKit
+ * @syscap SystemCapability.Security.CertificateManager
+ * @since 22
+ */
 
 #ifndef CM_NATIVE_TYPE_H
 #define CM_NATIVE_TYPE_H
@@ -47,94 +45,92 @@ extern "C" {
 
 #define OH_CM_MAX_LEN_CERTIFICATE_CHAIN   24588
 #define OH_CM_MAX_LEN_URI              256
-#define OH_CM_MAX_LEN_CERT_ALIAS       129
-#define OH_CM_MAX_LEN_TYPE_NAME       1025
+#define OH_CM_MAX_LEN_CERT_ALIAS       129 
+#define OH_CM_MAX_LEN_TYPE_NAME       1025 
 
 /**
- * @brief Enumerates the error codes.
- *
+ * @brief Enumerates error codes.
+ * 
  * @since 22
  */
 typedef enum {
     /**
-     * The operation is successful.
+     * Operation succeeded.
      */
     OH_CM_SUCCESS = 0,
     /**
-     *  Indicates that the application has no permission to call the API.
+     * Permission verification failed.
      */
     OH_CM_HAS_NO_PERMISSION = 201,
     /**
-     * Capability not supported.
+     * Not supported by the device.
      */
     OH_CM_CAPABILITY_NOT_SUPPORTED = 801,
     /**
-     * Indicates that internal error. Possible causes: 1. IPC communication failed;
-     * 2. Memory operation error; 3. File operation error.
+     * Internal error. Possible causes: 1. IPC failure. 2. Memory operation error. 3. File operation error.
      */
     OH_CM_INNER_FAILURE = 17500001,
     /**
-     * Indicates that the certificate does not exist.
+     * The certificate does not exist.
      */
     OH_CM_NOT_FOUND = 17500002,
     /**
-     * Indicates that the keystore is in an invalid format or the keystore password is incorrect.
+     * The keystore format is invalid or the keystore password is incorrect.
      */
     OH_CM_INVALID_CERT_FORMAT = 17500003,
     /**
-     * Indicates that the number of certificates or credentials reaches the maximum allowed.
+     * The number of certificates or credentials reaches the upper limit.
      */
     OH_CM_MAX_CERT_COUNT_REACHED = 17500004,
     /**
-     *  Indicates that the application is not authorized by the user.
+     * The application is not authorized.
      */
     OH_CM_NO_AUTHORIZATION = 17500005,
     /**
-     * Indicates that the device enters advanced security mode.
+     * The device enters the advanced security mode.
      */
     OH_CM_DEVICE_ENTER_ADVSECMODE = 17500007,
     /**
-     * Indicates that the device does not support the specified certificate store path.
+     * The device does not support the specified certificate storage path.
      */
     OH_CM_STORE_PATH_NOT_SUPPORTED = 17500009,
     /**
-     * Indicates that access USB key service failed.
+     * Failed to access the USB certificate credential.
      */
     OH_CM_ACCESS_UKEY_SERVICE_FAILED = 17500010,
     /**
-     * Indicates that the input parameters validation failed.
-     * for example, the parameter format is incorrect or the value range is invalid.
+     * Parameter verification fails. For example, the parameter format or range is invalid.
      */
-    OH_CM_PARAMETER_VALIDATION_FAILED = 17500011
+    OH_CM_PARAMETER_VALIDATION_FAILED = 17500011,
 } OH_CM_ErrorCode;
 
 /**
- * @brief Enumerates the certificate purpose.
- *
+ * @brief Enumerates the certificate credential purposes.
+ * 
  * @since 22
  */
 typedef enum {
     /**
-     * Indicates the default purpose.
+     * Default purpose, which is used for credential signing.
      */
     OH_CM_CERT_PURPOSE_DEFAULT = 0,
     /**
-     * Indicates all certificate purpose, used for query certificates function.
+     * All purposes, which are used to query credential functionalities.
      */
     OH_CM_CERT_PURPOSE_ALL = 1,
     /**
-     * Indicates certificate for signature.
+     * Signing purpose.
      */
     OH_CM_CERT_PURPOSE_SIGN = 2,
     /**
-     *  Indicates certificate for encrypt.
+     * Encryption purpose.
      */
-    OH_CM_CERT_PURPOSE_ENCRYPT = 3
+    OH_CM_CERT_PURPOSE_ENCRYPT = 3,
 } OH_CM_CertificatePurpose;
 
 /**
- * @brief Defines the structure for storing data.
- *
+ * @brief Defines a struct for a binary large object (BLOB).
+ * 
  * @since 22
  */
 typedef struct {
@@ -143,19 +139,19 @@ typedef struct {
      */
     uint32_t size;
     /**
-     * Pointer to the memory in which the data is stored.
+     * Pointer to the memory in which the data is stored. 
      */
     uint8_t *data;
 } OH_CM_Blob;
 
 /**
- * @brief Defines the structure for certificate detail of credential .
- *
+ * @brief Defines a struct for the certificate credential details.
+ * 
  * @since 22
  */
 typedef struct {
     /**
-     * Indicates whether the credential contains certificate data.
+     * Whether a certificate data exists.
      */
     uint32_t isExist;
     /**
@@ -167,58 +163,60 @@ typedef struct {
      */
     char alias[OH_CM_MAX_LEN_CERT_ALIAS];
     /**
-     * Indicates the uri of Credential.
+     * Indicates the uri of Credential. 
      */
     char keyUri[OH_CM_MAX_LEN_URI];
     /**
-     * Indicates the number of certificates included in the credential.
+     * Number of certificates contained in the credential.
      */
     uint32_t certNum;
     /**
-     * Indicates the number of key included in the credential.
+     * Number of keys contained in the credential.
      */
     uint32_t keyNum;
     /**
-     * Indicates the certificate binary data which max length is defined by OH_CM_MAX_LEN_CERTIFICATE_CHAIN.
+     * Binary data of a credential. The value contains up to 20480 bytes.
      */
     OH_CM_Blob credData;
     /**
-     * Indicates the certificate purpose.
+     * Purpose of a certificate credential.
      */
     OH_CM_CertificatePurpose certPurpose;
 } OH_CM_Credential;
 
 /**
- * @brief Defines credential detail list .
- *
+ * @brief Defines a struct for the certificate credential detail list.
+ * 
  * @since 22
  */
 typedef struct {
     /**
-     * Indicates the credential count.
+     * Number of certificate credential details.
      */
     uint32_t credentialCount;
     /**
-     * Indicates the credential data.
+     * Indicates the credential data. 
      */
     OH_CM_Credential *credential;
 } OH_CM_CredentialDetailList;
 
 /**
- * @brief Defines the USB key certificate attribute information.
- *
+ * @brief Defines a struct for the USB certificate credential information.
+ * 
  * @since 22
  */
 typedef struct {
     /**
-     * Indicates the purpose of certificate.
+     * Purpose of a certificate credential.
      */
     OH_CM_CertificatePurpose certPurpose;
 } OH_CM_UkeyInfo;
 
+
+
 #ifdef __cplusplus
 }
 #endif
 
 /** @} */
-#endif /* CM_NATIVE_TYPE_H */
+#endif /* CM_NATIVE_TYPE_H */