diff --git a/interface/kits/c/native_audio_channel_layout.h b/interface/kits/c/native_audio_channel_layout.h index 4fc7c56168e7a82d4763336db2e50a2119506b4f..307f0a7913ed24283858b040aea5e652909e6f12 100644 --- a/interface/kits/c/native_audio_channel_layout.h +++ b/interface/kits/c/native_audio_channel_layout.h @@ -14,8 +14,7 @@ */ /** - * @brief The channel layout indicates the appearance and order of the speakers - * for recording or playback. + * @brief The channel layout during recording and playback. * * @library NA * @syscap SystemCapability.Multimedia.Media.Core diff --git a/interface/kits/c/native_avbuffer.h b/interface/kits/c/native_avbuffer.h index ce24df936cb8d1c3a514ea9f56f5df66846b17b4..615a21e08a51c35f9e6d10e55cebffac60806158 100644 --- a/interface/kits/c/native_avbuffer.h +++ b/interface/kits/c/native_avbuffer.h @@ -29,67 +29,88 @@ typedef struct OH_AVBuffer OH_AVBuffer; typedef struct OH_NativeBuffer OH_NativeBuffer; /** - * @brief Create an OH_AVBuffer instance, It should be noted that the life cycle of the OH_AVBuffer instance pointed - * to by the return value * needs to be manually released by {@link OH_AVBuffer_Destroy}. + * @brief Create an OH_AVBuffer instance, It should be noted that the OH_AVBuffer instance pointed + * to by the return value * needs to be released by {@link OH_AVBuffer_Destroy}. * @syscap SystemCapability.Multimedia.Media.Core * @param capacity the buffer's capacity, bytes - * @return Returns a pointer to an OH_AVBuffer instance if the execution is successful, otherwise returns nullptr + * @return Returns a pointer to an OH_AVBuffer instance if the execution is successful, otherwise returns NULL. + * Possible failure causes: + * 1. capacity <= 0; + * 2. internal error occurred, the system has no resources. * @since 11 */ OH_AVBuffer *OH_AVBuffer_Create(int32_t capacity); /** * @brief Clear the internal resources of the buffer and destroy the buffer instance. + * The same buffer can not be destroyed repeatedly. * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer - * @return Returns AV_ERR_OK if the execution is successful, otherwise returns a specific error code, refer to - * {@link OH_AVErrCode} + * @return Function result code. + * {@link AV_ERR_OK} if the execution is successful. + * {@link AV_ERR_INVALID_VAL} if input buffer is nullptr or structure verification failed of the buffer. + * {@link AV_ERR_OPERATE_NOT_PERMIT} if input buffer is not user created. * @since 11 */ OH_AVErrCode OH_AVBuffer_Destroy(OH_AVBuffer *buffer); /** - * @brief Get the buffer's attribute. + * @brief Get the buffer's attribute, such as pts, size, offset, and flags. * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer * @param attr Encapsulate OH_AVCodecBufferAttr structure instance pointer, please refer to * {@link OH_AVCodecBufferAttr} - * @return Returns AV_ERR_OK if the execution is successful, otherwise returns a specific error code, refer to - * {@link OH_AVErrCode} + * @return Function result code. + * {@link AV_ERR_OK} if the execution is successful. + * {@link AV_ERR_INVALID_VAL} + * 1. input buffer or attr is nullptr; + * 2. structure verification failed of the buffer. * @since 11 */ OH_AVErrCode OH_AVBuffer_GetBufferAttr(OH_AVBuffer *buffer, OH_AVCodecBufferAttr *attr); /** - * @brief Set the buffer's attribute. + * @brief Set the buffer's attribute, such as pts, size, offset, and flags. * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer * @param attr Encapsulate OH_AVCodecBufferAttr structure instance pointer, please refer to * {@link OH_AVCodecBufferAttr} - * @return Returns AV_ERR_OK if the execution is successful, otherwise returns a specific error code, refer to - * {@link OH_AVErrCode} + * @return Function result code. + * {@link AV_ERR_OK} if the execution is successful. + * {@link AV_ERR_INVALID_VAL} + * 1. input buffer or attr is nullptr; + * 2. structure verification failed of the buffer; + * 3. the size or offset of input buffer's memory is invalid. * @since 11 */ OH_AVErrCode OH_AVBuffer_SetBufferAttr(OH_AVBuffer *buffer, const OH_AVCodecBufferAttr *attr); /** - * @brief Get the buffer's parameter. It should be noted that the life cycle of the OH_AVFormat instance pointed to - * by the return value * needs to be manually released by {@link OH_AVFormat_Destroy}. + * @brief Get parameters except basic attributes, the information is carried in OH_AVFormat. + * It should be noted that the OH_AVFormat instance pointed to + * by the return value * needs to be released by {@link OH_AVFormat_Destroy}. * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer * @return Returns Encapsulate OH_AVFormat structure instance pointer if the execution is successful, - * otherwise returns nullptr + * otherwise returns nullptr. Possible failure causes: + * 1. input buffer is nullptr; + * 2. structure verification failed of the buffer; + * 3. buffer's meta is nullptr. * @since 11 */ OH_AVFormat *OH_AVBuffer_GetParameter(OH_AVBuffer *buffer); /** - * @brief Set the buffer's parameter. + * @brief Set parameters except basic attributes, the information is carried in OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer * @param format Encapsulate OH_AVFormat structure instance pointer - * @return Returns AV_ERR_OK if the execution is successful, otherwise returns a specific error code, refer to - * {@link OH_AVErrCode} + * @return Function result code. + * {@link AV_ERR_OK} if the execution is successful. + * {@link AV_ERR_INVALID_VAL} + * 1. input buffer or format is nullptr; + * 2. structure verification failed of the buffer; + * 3. input meta is nullptr. * @since 11 */ OH_AVErrCode OH_AVBuffer_SetParameter(OH_AVBuffer *buffer, const OH_AVFormat *format); @@ -98,27 +119,38 @@ OH_AVErrCode OH_AVBuffer_SetParameter(OH_AVBuffer *buffer, const OH_AVFormat *fo * @brief Get the buffer's virtual address. * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer - * @return the buffer's virtual address if the buffer is valid, otherwise nullptr + * @return the buffer's virtual address if the buffer is valid, otherwise NULL + * Possible failure causes: + * 1. input buffer is nullptr; + * 2. structure verification failed of the OH_AVBuffer; + * 3. internal error has occurred. * @since 11 */ uint8_t *OH_AVBuffer_GetAddr(OH_AVBuffer *buffer); /** - * @brief Get the buffer's capacity + * @brief Get the buffer's capacity(byte). * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer - * @return the buffer's capacity if the buffer is valid, otherwise -1 + * @return The buffer's capacity if the buffer is valid, otherwise -1 + * Possible failure causes: + * 1. input buffer is nullptr; + * 2. structure verification failed of the OH_AVBuffer; + * 3. internal error has occurred. * @since 11 */ int32_t OH_AVBuffer_GetCapacity(OH_AVBuffer *buffer); /** - * @brief Get the OH_NativeBuffer instance pointer,It should be noted that the life cycle of the OH_AVBuffer - * instance pointed to by the return value * needs to be manually released by {@link OH_NativeBuffer_Unreference}. + * @brief Get the OH_NativeBuffer instance pointer. It should be noted that the OH_AVBuffer + * instance pointed to by the return value * needs to be released by {@link OH_NativeBuffer_Unreference}. * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer - * @return Returns Encapsulate OH_NativeBuffer structure instance pointer is successful, - * otherwise returns nullptr + * @return Returns Encapsulate OH_NativeBuffer structure instance pointer is successful, otherwise returns NULL + * Possible failure causes: + * 1. input buffer is nullptr; + * 2. structure verification failed of the OH_AVBuffer; + * 3. internal error has occurred. * @since 11 */ OH_NativeBuffer *OH_AVBuffer_GetNativeBuffer(OH_AVBuffer *buffer); diff --git a/interface/kits/c/native_avformat.h b/interface/kits/c/native_avformat.h index 4335cee3370160b09cf5cf5d9b866ed699bc82c7..c5a006d05ed3f2a5e80a5b84aa13e5026f1a2754 100644 --- a/interface/kits/c/native_avformat.h +++ b/interface/kits/c/native_avformat.h @@ -65,12 +65,13 @@ typedef enum OH_AVPixelFormat { struct OH_AVFormat *OH_AVFormat_Create(void); /** - * @briefCreate an audio OH_AVFormat handle pointer to read and write data + * @brief Create an audio OH_AVFormat handle pointer to read and write data. * @syscap SystemCapability.Multimedia.Media.Core * @param mimeType mime type * @param sampleRate sample rate * @param channelCount channel count - * @return Returns a pointer to an OH_AVFormat instance + * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise nullptr + * Possible failure causes: 1. mimeType is nullptr; 2. new format is nullptr. * @since 10 * @version 1.0 */ @@ -79,12 +80,13 @@ struct OH_AVFormat *OH_AVFormat_CreateAudioFormat(const char *mimeType, int32_t channelCount); /** - * @briefCreate an video OH_AVFormat handle pointer to read and write data + * @brief Create an video OH_AVFormat handle pointer to read and write data. * @syscap SystemCapability.Multimedia.Media.Core * @param mimeType mime type * @param width width * @param height height - * @return Returns a pointer to an OH_AVFormat instance + * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise nullptr + * Possible failure causes: 1. mimeType is nullptr; 2. new format is nullptr. * @since 10 * @version 1.0 */ @@ -93,7 +95,7 @@ struct OH_AVFormat *OH_AVFormat_CreateVideoFormat(const char *mimeType, int32_t height); /** - * @brief Destroy the specified OH_AVFormat handle resource + * @brief Destroy the OH_AVFormat instance, can not be destoryed repeatedly. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @return void @@ -103,145 +105,212 @@ struct OH_AVFormat *OH_AVFormat_CreateVideoFormat(const char *mimeType, void OH_AVFormat_Destroy(struct OH_AVFormat *format); /** - * @brief Copy OH_AVFormat handle resource + * @brief Copy OH_AVFormat handle resource. * @syscap SystemCapability.Multimedia.Media.Core * @param to OH_AVFormat handle pointer to receive data * @param from pointer to the OH_AVFormat handle of the copied data * @return The return value is TRUE for success, FALSE for failure + * Possible failure causes: + * 1. input parameter is nullptr; + * 2. structure verification failed of the input OH_AVFormat. * @since 9 * @version 1.0 */ bool OH_AVFormat_Copy(struct OH_AVFormat *to, struct OH_AVFormat *from); /** - * @brief Write Int data to OH_AVFormat + * @brief Set a value of Int type to the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key key to write data * @param value written data * @return The return value is TRUE for success, FALSE for failure + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification failed of the input format; + * 3. input key is nullptr; + * 4. value type corresponding to the key is incorrect. * @since 9 * @version 1.0 */ bool OH_AVFormat_SetIntValue(struct OH_AVFormat *format, const char *key, int32_t value); /** - * @brief Write Long data to OH_AVFormat + * @brief Set a value of Long type to the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key key to write data * @param value written data * @return The return value is TRUE for success, FALSE for failure + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification failed of the input format; + * 3. input key is nullptr; + * 4. value type corresponding to the key is incorrect. * @since 9 * @version 1.0 */ bool OH_AVFormat_SetLongValue(struct OH_AVFormat *format, const char *key, int64_t value); /** - * @brief Write Float data to OH_AVFormat + * @brief Set a value of Float type to the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key key to write data * @param value written data * @return The return value is TRUE for success, FALSE for failure + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification failed of the input format; + * 3. input key is nullptr; + * 4. value type corresponding to the key is incorrect. * @since 9 * @version 1.0 */ bool OH_AVFormat_SetFloatValue(struct OH_AVFormat *format, const char *key, float value); /** - * @brief Write Double data to OH_AVFormat + * @brief Set a value of Double type to the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key key to write data * @param value written data * @return The return value is TRUE for success, FALSE for failure + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification failed of the input format; + * 3. input key is nullptr; + * 4. value type corresponding to the key is incorrect. * @since 9 * @version 1.0 */ bool OH_AVFormat_SetDoubleValue(struct OH_AVFormat *format, const char *key, double value); /** - * @brief Write String data to OH_AVFormat + * @brief Set a value of String type to the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key key to write data * @param value written data * @return The return value is TRUE for success, FALSE for failure + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification failed of the input format; + * 3. input key is nullptr; + * 4. input value is nullptr; + * 5. value type corresponding to the key is incorrect; * @since 9 * @version 1.0 */ bool OH_AVFormat_SetStringValue(struct OH_AVFormat *format, const char *key, const char *value); /** - * @brief Write a block of data of a specified length to OH_AVFormat + * @brief Write a block of data of a specified length to OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key key to write data - * @param addr written data addr - * @param size written data length + * @param addr written data addr, the lifecycle is managed by the invoker + * @param size written data length, range is(0, 1)MB * @return The return value is TRUE for success, FALSE for failure + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification failed of the input format; + * 3. input key is nullptr; + * 4. input addr is nullptr; + * 5. size is 0 or exceeds the upper limit, which is 1MB; + * 6. value type corresponding to the key is incorrect. * @since 9 * @version 1.0 */ bool OH_AVFormat_SetBuffer(struct OH_AVFormat *format, const char *key, const uint8_t *addr, size_t size); /** - * @brief Read Int data from OH_AVFormat + * @brief Get the Int value from the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key read key value * @param out read data * @return The return value is TRUE for success, FALSE for failure + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification failed of the input format; + * 3. input key is nullptr; + * 4. input out is nullptr; + * 5. the obtained key does not exist or is not set. * @since 9 * @version 1.0 */ bool OH_AVFormat_GetIntValue(struct OH_AVFormat *format, const char *key, int32_t *out); /** - * @brief Read Long data from OH_AVFormat + * @brief Get the Long value from the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key read key value * @param out read data * @return The return value is TRUE for success, FALSE for failure + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification failed of the input format; + * 3. input key is nullptr; + * 4. input out is nullptr; + * 5. the obtained key does not exist or is not set. * @since 9 * @version 1.0 */ bool OH_AVFormat_GetLongValue(struct OH_AVFormat *format, const char *key, int64_t *out); /** - * @brief Read Float data from OH_AVFormat + * @brief Get the Float value from the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key read key value * @param out read data * @return The return value is TRUE for success, FALSE for failure + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification failed of the input format; + * 3. input key is nullptr; + * 4. input out is nullptr; + * 5. the obtained key does not exist or is not set. * @since 9 * @version 1.0 */ bool OH_AVFormat_GetFloatValue(struct OH_AVFormat *format, const char *key, float *out); /** - * @brief Read Double data from OH_AVFormat + * @brief Get the Double value from the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key read key value * @param out read data * @return The return value is TRUE for success, FALSE for failure + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification failed of the input format; + * 3. input key is nullptr; + * 4. input out is nullptr; + * 5. the obtained key does not exist or is not set. * @since 9 * @version 1.0 */ bool OH_AVFormat_GetDoubleValue(struct OH_AVFormat *format, const char *key, double *out); /** - * @brief Read String data from OH_AVFormat + * @brief Get the String value from the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key read key value * @param out The read string pointer, the data life cycle pointed to is updated with GetString, * and Format is destroyed. If the caller needs to hold it for a long time, it must copy the memory * @return The return value is TRUE for success, FALSE for failure + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification failed of the input format; + * 3. input key is nullptr; + * 4. input out is nullptr; + * 5. the resources of out string generated by malloc is insufficient; + * 6. the obtained key does not exist or is not set. * @since 9 * @version 1.0 */ @@ -251,21 +320,31 @@ bool OH_AVFormat_GetStringValue(struct OH_AVFormat *format, const char *key, con * @brief Read a block of data of specified length from OH_AVFormat * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance - * @param key Key value for reading and writing data + * @param key Key value for reading data * @param addr The life cycle is held by the format, with the destruction of the format, * if the caller needs to hold it for a long time, it must copy the memory - * @param size Length of read and write data + * @param size Length of read data * @return The return value is TRUE for success, FALSE for failure + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification failed of the input format; + * 3. input key is nullptr; + * 4. input addr is nullptr; + * 5. input size is nullptr; + * 6. the obtained key does not exist or is not set. * @since 9 * @version 1.0 */ bool OH_AVFormat_GetBuffer(struct OH_AVFormat *format, const char *key, uint8_t **addr, size_t *size); /** - * @brief Output the information contained in OH_AVFormat as a string. + * @brief Return a string consisting of key and values contained in OH_AVFormat. + * the max string that can be returned is 1024 bytes, + * and the string pointer is released when the format is destroyed. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance - * @return Returns a string consisting of key and data + * @return Returns a string consisting of key and data for success, NULL for failure + * Possible failure causes: 1. input format is nullptr; 2. system resources are insufficient. * @since 9 * @version 1.0 */ diff --git a/interface/kits/c/native_avmemory.h b/interface/kits/c/native_avmemory.h index 489a4ff49c3493e94dda7ed35772c061e156a7da..b0ef26562239f71e0288b6c6a20663988aa315e9 100644 --- a/interface/kits/c/native_avmemory.h +++ b/interface/kits/c/native_avmemory.h @@ -29,7 +29,8 @@ typedef struct OH_AVMemory OH_AVMemory; * @brief Create an OH_AVMemory instance * @syscap SystemCapability.Multimedia.Media.Core * @param size the memory's size, bytes. - * @return Returns a pointer to an OH_AVMemory instance, needs to be freed by OH_AVMemory_Destroy. + * @return Returns a pointer to an OH_AVMemory instance for success, needs to be freed by OH_AVMemory_Destroy, + * otherwise returns NULL. * @deprecated since 11 * @useinstead OH_AVBuffer_Create * @since 10 @@ -40,7 +41,11 @@ OH_AVMemory *OH_AVMemory_Create(int32_t size); * @brief Get the memory's virtual address * @syscap SystemCapability.Multimedia.Media.Core * @param mem Encapsulate OH_AVMemory structure instance pointer - * @return the memory's virtual address if the memory is valid, otherwise nullptr. + * @return the memory's virtual address if the memory is valid, otherwise NULL. + * Possible failure causes: + * 1. input mem is nullptr; + * 2. structure verification failed of the mem; + * 3. mem's memory is nullptr. * @deprecated since 11 * @useinstead OH_AVBuffer_GetAddr * @since 9 @@ -53,6 +58,10 @@ uint8_t *OH_AVMemory_GetAddr(struct OH_AVMemory *mem); * @syscap SystemCapability.Multimedia.Media.Core * @param mem Encapsulate OH_AVMemory structure instance pointer * @return the memory's size if the memory is valid, otherwise -1. + * Possible failure causes: + * 1. input mem is nullptr; + * 2. structure verification failed of the mem; + * 3. mem's memory is nullptr. * @deprecated since 11 * @useinstead OH_AVBuffer_GetCapacity * @since 9 @@ -65,8 +74,12 @@ int32_t OH_AVMemory_GetSize(struct OH_AVMemory *mem); * instance * @syscap SystemCapability.Multimedia.Media.Core * @param mem Encapsulate OH_AVMemory structure instance pointer - * @return Returns AV_ERR_OK if the execution is successful, - * otherwise returns a specific error code, refer to {@link OH_AVErrCode} + * @return Function result code. + * {@link AV_ERR_OK} if the execution is successful. + * {@link AV_ERR_INVALID_VAL} + * 1. input mem is nullptr; + * 2. structure verification failed of the mem; + * 3. mem's memory is nullptr. * @deprecated since 11 * @useinstead OH_AVBuffer_Destroy * @since 10