From 30cd13ca154cd90c23845fabae107da6db7b031d Mon Sep 17 00:00:00 2001
From: assertsu <subenhui@huawei.com>
Date: Tue, 4 Jun 2024 04:22:51 +0000
Subject: [PATCH 1/2] =?UTF-8?q?=E5=90=8C=E6=AD=A5hdc=E5=92=8Cbeta=E6=8E=A5?=
 =?UTF-8?q?=E5=8F=A3=E6=8F=8F=E8=BF=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: assertsu <subenhui@huawei.com>
---
 multimedia/media_foundation/native_avbuffer.h |  38 +++--
 multimedia/media_foundation/native_averrors.h |  22 +--
 multimedia/player_framework/avplayer.h        | 147 +++++++++++-------
 3 files changed, 127 insertions(+), 80 deletions(-)

diff --git a/multimedia/media_foundation/native_avbuffer.h b/multimedia/media_foundation/native_avbuffer.h
index 19ec2be46..391fc0691 100644
--- a/multimedia/media_foundation/native_avbuffer.h
+++ b/multimedia/media_foundation/native_avbuffer.h
@@ -34,6 +34,8 @@ typedef struct OH_NativeBuffer OH_NativeBuffer;
  * @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
+ * Possible failure causes: 1. capacity <= 0. 2. create allocator failed. 3. create OH_AVBuffer failed.
+ * 4. created buffer memory is nullptr. 5. created buffer memory's addr is nullptr. 6. failed to new OH_AVBuffer.
  * @since 11
  */
 OH_AVBuffer *OH_AVBuffer_Create(int32_t capacity);
@@ -42,8 +44,10 @@ OH_AVBuffer *OH_AVBuffer_Create(int32_t capacity);
  * @brief Clear the internal resources of the buffer and destroy the buffer instance.
  * @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 buffer's magic error.
+ *         {@link AV_ERR_OPERATE_NOT_PERMIT} if input buffer is not user created.
  * @since 11
  */
 OH_AVErrCode OH_AVBuffer_Destroy(OH_AVBuffer *buffer);
@@ -54,8 +58,10 @@ OH_AVErrCode OH_AVBuffer_Destroy(OH_AVBuffer *buffer);
  * @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} if input buffer is nullptr, buffer's magic error,
+ *         input buffer's buffer is nulllptr or attr is nullptr.
  * @since 11
  */
 OH_AVErrCode OH_AVBuffer_GetBufferAttr(OH_AVBuffer *buffer, OH_AVCodecBufferAttr *attr);
@@ -66,8 +72,10 @@ OH_AVErrCode OH_AVBuffer_GetBufferAttr(OH_AVBuffer *buffer, OH_AVCodecBufferAttr
  * @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} if input buffer is nullptr, buffer's magic error,
+ *         input buffer's buffer is nulllptr, attr is nullptr, 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);
@@ -78,7 +86,8 @@ OH_AVErrCode OH_AVBuffer_SetBufferAttr(OH_AVBuffer *buffer, const OH_AVCodecBuff
  * @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. buffer's magic error.
+ * 3. input buffer's buffer is nulllptr. 4. buffer's meta is nullptr.
  * @since 11
  */
 OH_AVFormat *OH_AVBuffer_GetParameter(OH_AVBuffer *buffer);
@@ -88,8 +97,10 @@ OH_AVFormat *OH_AVBuffer_GetParameter(OH_AVBuffer *buffer);
  * @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} if input buffer is nullptr, buffer's magic error,
+ *         input buffer's buffer is nulllptr, input format is nullptr or input meta is nullptr.
  * @since 11
  */
 OH_AVErrCode OH_AVBuffer_SetParameter(OH_AVBuffer *buffer, const OH_AVFormat *format);
@@ -99,6 +110,8 @@ OH_AVErrCode OH_AVBuffer_SetParameter(OH_AVBuffer *buffer, const OH_AVFormat *fo
  * @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
+ * Possible failure causes: 1. input buffer is nullptr. 2. buffer's magic error.
+ * 3. input buffer's buffer is nulllptr. 4. buffer's memory is nullptr.
  * @since 11
  */
 uint8_t *OH_AVBuffer_GetAddr(OH_AVBuffer *buffer);
@@ -108,6 +121,8 @@ uint8_t *OH_AVBuffer_GetAddr(OH_AVBuffer *buffer);
  * @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
+ * Possible failure causes: 1. input buffer is nullptr. 2. buffer's magic error.
+ * 3. input buffer's buffer is nulllptr. 4. buffer's memory is nullptr.
  * @since 11
  */
 int32_t OH_AVBuffer_GetCapacity(OH_AVBuffer *buffer);
@@ -117,8 +132,9 @@ int32_t OH_AVBuffer_GetCapacity(OH_AVBuffer *buffer);
  * instance pointed to by the return value * needs to be manually 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 nullptr
+ * Possible failure causes: 1. input buffer is nullptr. 2. buffer's magic error.
+ * 3. input buffer's buffer is nulllptr. 4. buffer's memory is nullptr. 5. surfaceBuffer is nullptr.
  * @since 11
  */
 OH_NativeBuffer *OH_AVBuffer_GetNativeBuffer(OH_AVBuffer *buffer);
diff --git a/multimedia/media_foundation/native_averrors.h b/multimedia/media_foundation/native_averrors.h
index eb2ad2039..081af5f91 100644
--- a/multimedia/media_foundation/native_averrors.h
+++ b/multimedia/media_foundation/native_averrors.h
@@ -27,47 +27,47 @@ extern "C" {
  */
 typedef enum OH_AVErrCode {
     /**
-     * the operation completed successfully.
+     * @error the operation completed successfully.
      */
     AV_ERR_OK = 0,
     /**
-     * no memory.
+     * @error no memory.
      */
     AV_ERR_NO_MEMORY = 1,
     /**
-     * opertation not be permitted.
+     * @error opertation not be permitted.
      */
     AV_ERR_OPERATE_NOT_PERMIT = 2,
     /**
-     * invalid argument.
+     * @error invalid argument.
      */
     AV_ERR_INVALID_VAL = 3,
     /**
-     * IO error.
+     * @error IO error.
      */
     AV_ERR_IO = 4,
     /**
-     * network timeout.
+     * @error network timeout.
      */
     AV_ERR_TIMEOUT = 5,
     /**
-     * unknown error.
+     * @error unknown error.
      */
     AV_ERR_UNKNOWN = 6,
     /**
-     * media service died.
+     * @error media service died.
      */
     AV_ERR_SERVICE_DIED = 7,
     /**
-     * the state is not support this operation.
+     * @error the state is not support this operation.
      */
     AV_ERR_INVALID_STATE = 8,
     /**
-     * unsupport interface.
+     * @error unsupport interface.
      */
     AV_ERR_UNSUPPORT = 9,
     /**
-     * extend err start.
+     * @error extend err start.
      */
     AV_ERR_EXTEND_START = 100,
     /** drm error base.
diff --git a/multimedia/player_framework/avplayer.h b/multimedia/player_framework/avplayer.h
index 0939a6516..bdf9025a7 100644
--- a/multimedia/player_framework/avplayer.h
+++ b/multimedia/player_framework/avplayer.h
@@ -65,7 +65,7 @@ typedef struct DRM_MediaKeySystemInfo DRM_MediaKeySystemInfo;
  * @brief Call back will be invoked when updating DRM information.
  * @param player Player instance.
  * @param mediaKeySystemInfo DRM information.
- * @return DRM_ERR_INVALID_VAL when the params checked failure, return DRM_ERR_OK when function called successfully.
+ * @return void
  * @since 12
  * @version 1.0
  */
@@ -74,7 +74,8 @@ typedef void (*Player_MediaKeySystemInfoCallback)(OH_AVPlayer *player, DRM_Media
 /**
  * @brief Create a player
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
- * @return Returns a pointer to an OH_AVPlayer instance
+ * @return Returns a pointer to an OH_AVPlayer instance for success, nullptr for failure
+ * Possible failure causes: 1. failed to PlayerFactory::CreatePlayer. 2. failed to new PlayerObject.
  * @since 11
  * @version 1.0
 */
@@ -85,8 +86,9 @@ OH_AVPlayer *OH_AVPlayer_Create(void);
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
  * @param url Indicates the playback source.
- * @return Returns {@link AV_ERR_OK} if the url is set successfully; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr, url is null or player setUrlSource failed.
  * @since 11
  * @version 1.0
  */
@@ -99,8 +101,9 @@ OH_AVErrCode OH_AVPlayer_SetURLSource(OH_AVPlayer *player, const char *url);
  * @param fd Indicates the file descriptor of media source.
  * @param offset Indicates the offset of media source in file descriptor.
  * @param size Indicates the size of media source.
- * @return Returns {@link AV_ERR_OK} if the fd source is set successfully; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player setFdSource failed.
  * @since 11
  * @version 1.0
  */
@@ -113,8 +116,9 @@ OH_AVErrCode OH_AVPlayer_SetFDSource(OH_AVPlayer *player, int32_t fd, int64_t of
  *
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
- * @return Returns {@link AV_ERR_OK} if {@link Prepare} is successfully added to the task queue;
- * returns an error code defined in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player Prepare failed.
  * @since 11
  * @version 1.0
  */
@@ -128,8 +132,9 @@ OH_AVErrCode OH_AVPlayer_Prepare(OH_AVPlayer *player);
  *
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
- * @return Returns {@link AV_ERR_OK} if the playback is started; otherwise returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player Play failed.
  * @since 11
  * @version 1.0
  */
@@ -139,8 +144,9 @@ OH_AVErrCode OH_AVPlayer_Play(OH_AVPlayer *player);
  * @brief Pauses playback.
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
- * @return Returns {@link AV_ERR_OK} if {@link Pause} is successfully added to the task queue;
- * returns an error code defined in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player Pause failed.
  * @since 11
  * @version 1.0
  */
@@ -150,8 +156,9 @@ OH_AVErrCode OH_AVPlayer_Pause(OH_AVPlayer *player);
  * @brief Stop playback.
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
- * @return Returns {@link AV_ERR_OK} if {@link Stop} is successfully added to the task queue;
- * returns an error code defined in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player Stop failed.
  * @since 11
  * @version 1.0
  */
@@ -165,8 +172,9 @@ OH_AVErrCode OH_AVPlayer_Stop(OH_AVPlayer *player);
  *
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
- * @return Returns {@link AV_ERR_OK} if {@link Reset} is successfully added to the task queue;
- * returns an error code defined in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player Reset failed.
  * @since 11
  * @version 1.0
  */
@@ -181,8 +189,9 @@ OH_AVErrCode OH_AVPlayer_Reset(OH_AVPlayer *player);
  *
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
- * @return Returns {@link AV_ERR_OK} if {@link Release} is successfully added to the task queue;
- * returns an error code defined in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player Release failed.
  * @since 11
  * @version 1.0
  */
@@ -197,8 +206,9 @@ OH_AVErrCode OH_AVPlayer_Release(OH_AVPlayer *player);
  *
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
- * @return Returns {@link AV_ERR_OK} if the playback is released; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player ReleaseSync failed.
  * @since 11
  * @version 1.0
  */
@@ -217,8 +227,9 @@ OH_AVErrCode OH_AVPlayer_ReleaseSync(OH_AVPlayer *player);
  *        ranging from 0 to 1. each step is 0.01.
  * @param rightVolume Indicates the target volume of the right audio channel to set,
  *        ranging from 0 to 1. each step is 0.01.
- * @return Returns {@link AV_ERR_OK} if the volume is set; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player SetVolume failed.
  * @since 11
  * @version 1.0
  */
@@ -233,8 +244,9 @@ OH_AVErrCode OH_AVPlayer_SetVolume(OH_AVPlayer *player, float leftVolume, float
  * @param player Pointer to an OH_AVPlayer instance
  * @param mSeconds Indicates the target playback position, accurate to milliseconds.
  * @param mode Indicates the player seek mode. For details, see {@link AVPlayerSeekMode}.
- * @return Returns {@link AV_ERR_OK} if the seek is done; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player Seek failed.
  * @since 11
  * @version 1.0
 */
@@ -245,8 +257,9 @@ OH_AVErrCode OH_AVPlayer_Seek(OH_AVPlayer *player, int32_t mSeconds, AVPlayerSee
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
  * @param currentTime Indicates the playback position.
- * @return Returns {@link AV_ERR_OK} if the current position is get; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player GetCurrentTime failed.
  * @since 11
  * @version 1.0
  */
@@ -257,8 +270,9 @@ OH_AVErrCode OH_AVPlayer_GetCurrentTime(OH_AVPlayer *player, int32_t *currentTim
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
  * @param videoWidth The video width
- * @return Returns {@link AV_ERR_OK} if the current position is get; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr.
  * @since 11
  * @version 1.0
  */
@@ -269,8 +283,9 @@ OH_AVErrCode OH_AVPlayer_GetVideoWidth(OH_AVPlayer *player, int32_t *videoWidth)
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
  * @param videoHeight The video height
- * @return Returns {@link AV_ERR_OK} if the current position is get; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr.
  * @since 11
  * @version 1.0
  */
@@ -281,8 +296,9 @@ OH_AVErrCode OH_AVPlayer_GetVideoHeight(OH_AVPlayer *player, int32_t *videoHeigh
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
  * @param speed the rate mode {@link AVPlaybackSpeed} which can set.
- * @return Returns {@link AV_ERR_OK} if the playback rate is set successful; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player SetPlaybackSpeed failed.
  * @since 11
  * @version 1.0
  */
@@ -293,8 +309,9 @@ OH_AVErrCode OH_AVPlayer_SetPlaybackSpeed(OH_AVPlayer *player, AVPlaybackSpeed s
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
  * @param speed the rate mode {@link AVPlaybackSpeed} which can get.
- * @return Returns {@link AV_ERR_OK} if the current player playback rate is get; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player GetPlaybackSpeed failed.
  * @since 11
  * @version 1.0
  */
@@ -313,8 +330,9 @@ OH_AVErrCode OH_AVPlayer_GetPlaybackSpeed(OH_AVPlayer *player, AVPlaybackSpeed *
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
  * @param bitRate the bit rate, The unit is bps.
- * @return Returns {@link AV_ERR_OK} if the bit rate is set successfully; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player SelectBitRate failed.
  * @since 11
  * @version 1.0
  */
@@ -325,8 +343,10 @@ OH_AVErrCode OH_AVPlayer_SelectBitRate(OH_AVPlayer *player, uint32_t bitRate);
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
  * @param window A pointer to a OHNativeWindow instance, see {@link OHNativeWindow}
- * @return Returns {@link AV_ERR_OK} if the surface is set; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr, input window is nullptr,
+ *          or player SetVideoSurface failed.
  * @since 11
  * @version 1.0
  */
@@ -337,8 +357,9 @@ OH_AVErrCode  OH_AVPlayer_SetVideoSurface(OH_AVPlayer *player, OHNativeWindow *w
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
  * @param duration Indicates the total duration of media files.
- * @return Returns {@link AV_ERR_OK} if the current duration is get; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player GetDuration failed.
  * @since 11
  * @version 1.0
  */
@@ -349,8 +370,9 @@ OH_AVErrCode OH_AVPlayer_GetDuration(OH_AVPlayer *player, int32_t *duration);
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
  * @param state the current playback state
- * @return Returns {@link AV_ERR_OK} if the current duration is get; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr.
  * @since 11
  * @version 1.0
  */
@@ -360,7 +382,7 @@ OH_AVErrCode OH_AVPlayer_GetState(OH_AVPlayer *player, AVPlayerState *state);
  * @brief Checks whether the player is playing.
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
- * @return Returns true if the playback is playing; false otherwise.
+ * @return Returns true if the playback is playing; Return false if not or input player is nullptr.
  * @since 11
  * @version 1.0
  */
@@ -370,7 +392,7 @@ bool OH_AVPlayer_IsPlaying(OH_AVPlayer *player);
  * @brief Returns the value whether single looping is enabled or not .
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
- * @return Returns true if the playback is single looping; false otherwise.
+ * @return Returns true if the playback is single looping; Return false if not or input player is nullptr.
  * @since 11
  * @version 1.0
  */
@@ -393,8 +415,9 @@ OH_AVErrCode OH_AVPlayer_SetLooping(OH_AVPlayer *player, bool loop);
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
  * @param callback object pointer.
- * @return Returns {@link AV_ERR_OK} if the playercallback is set; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player SetLooping failed.
  * @since 11
  * @version 1.0
  */
@@ -410,8 +433,10 @@ OH_AVErrCode OH_AVPlayer_SetPlayerCallback(OH_AVPlayer *player, AVPlayerCallback
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
  * @param index Track index
- * @return Returns {@link AV_ERR_OK} if selected successfully; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr, callback.onInfo or callback.onError is null,
+ *         or player SetPlayerCallback failed.
  * @since 11
  * @version 1.0
 */
@@ -427,8 +452,9 @@ OH_AVErrCode OH_AVPlayer_SelectTrack(OH_AVPlayer *player, int32_t index);
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
  * @param index Track index
- * @return Returns {@link AV_ERR_OK} if selected successfully; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player DeselectTrack failed.
  * @since 11
  * @version 1.0
 */
@@ -443,8 +469,9 @@ OH_AVErrCode OH_AVPlayer_DeselectTrack(OH_AVPlayer *player, int32_t index);
  * @param player Pointer to an OH_AVPlayer instance
  * @param trackType Media type.
  * @param index Track index
- * @return Returns {@link AV_ERR_OK} if the track index is get; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player GetCurrentTrack failed.
  * @since 11
  * @version 1.0
  */
@@ -455,8 +482,10 @@ OH_AVErrCode OH_AVPlayer_GetCurrentTrack(OH_AVPlayer *player, int32_t trackType,
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
  * @param callback object pointer.
- * @return Returns {@link AV_ERR_OK} if the drm info callback is set; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr, MediaKeySystemInfoCallback is null
+ *         player SetDrmSystemInfoCallback failed, SetDrmSystemInfoCallback failed or SetDrmSystemInfoCallback failed.
  * @since 12
  * @version 1.0
  */
@@ -468,8 +497,9 @@ OH_AVErrCode OH_AVPlayer_SetMediaKeySystemInfoCallback(OH_AVPlayer *player,
  * @syscap SystemCapability.Multimedia.Media.AVPlayer
  * @param player Pointer to an OH_AVPlayer instance
  * @param mediaKeySystemInfo Media key system info.
- * @return Returns {@link AV_ERR_OK} if the current position is get; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or no memory.
  * @since 12
  * @version 1.0
  */
@@ -482,8 +512,9 @@ OH_AVErrCode OH_AVPlayer_GetMediaKeySystemInfo(OH_AVPlayer *player, DRM_MediaKey
  * @param player Pointer to an OH_AVPlayer instance
  * @param mediaKeySession A media key session instance with decryption function.
  * @param secureVideoPath Require secure decoder or not.
- * @return Returns {@link AV_ERR_OK} if set successfully; returns an error code defined
- * in {@link native_averrors.h} otherwise.
+ * @return Function result code.
+ *         {@link AV_ERR_OK} if the execution is successful.
+ *         {@link AV_ERR_INVALID_VAL} if input player is nullptr or player SetDecryptConfig failed.
  * @since 12
  * @version 1.0
 */
-- 
Gitee


From 3e753f6f71e001408fd688746ab518603211fb1c Mon Sep 17 00:00:00 2001
From: assertsu <subenhui@huawei.com>
Date: Tue, 4 Jun 2024 04:22:56 +0000
Subject: [PATCH 2/2] =?UTF-8?q?=E5=90=8C=E6=AD=A5hdc=E5=92=8Cbeta=E6=8E=A5?=
 =?UTF-8?q?=E5=8F=A3=E6=8F=8F=E8=BF=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: assertsu <subenhui@huawei.com>
---
 multimedia/av_codec/native_avmuxer.h          | 21 +++++++++++++
 multimedia/media_foundation/native_avformat.h | 30 +++++++++++++++++--
 multimedia/media_foundation/native_avmemory.h | 11 +++++--
 3 files changed, 56 insertions(+), 6 deletions(-)

diff --git a/multimedia/av_codec/native_avmuxer.h b/multimedia/av_codec/native_avmuxer.h
index 2e622508c..e88f992c8 100644
--- a/multimedia/av_codec/native_avmuxer.h
+++ b/multimedia/av_codec/native_avmuxer.h
@@ -44,6 +44,8 @@ OH_AVMuxer *OH_AVMuxer_Create(int32_t fd, OH_AVOutputFormat format);
  * @param rotation The supported angles are 0, 90, 180, and 270 degrees.
  * @return Returns AV_ERR_OK if the execution is successful,
  * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
+ * {@link AV_ERR_INVALID_VAL}, the muxer or rotation invalid.
+ * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permit to call the interface, it was called in invalid state.
  * @since 10
  */
 OH_AVErrCode OH_AVMuxer_SetRotation(OH_AVMuxer *muxer, int32_t rotation);
@@ -59,6 +61,11 @@ OH_AVErrCode OH_AVMuxer_SetRotation(OH_AVMuxer *muxer, int32_t rotation);
  * @param trackFormat OH_AVFormat handle pointer contain track format
  * @return Returns AV_ERR_OK if the execution is successful,
  * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
+ * {@link AV_ERR_INVALID_VAL}, the muxer or trackIndex or trackFormat invalid.
+ * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permit to call the interface, it was called in invalid state.
+ * {@link AV_ERR_UNSUPPORT}, the mime type is not supported.
+ * {@link AV_ERR_NO_MEMORY}, failed to malloc memory.
+ * {@link AV_ERR_UNKNOWN}, unknown error.
  * @since 10
  */
 OH_AVErrCode OH_AVMuxer_AddTrack(OH_AVMuxer *muxer, int32_t *trackIndex, OH_AVFormat *trackFormat);
@@ -70,6 +77,9 @@ OH_AVErrCode OH_AVMuxer_AddTrack(OH_AVMuxer *muxer, int32_t *trackIndex, OH_AVFo
  * @param muxer Pointer to an OH_AVMuxer instance
  * @return Returns AV_ERR_OK if the execution is successful,
  * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
+ * {@link AV_ERR_INVALID_VAL}, the muxer invalid.
+ * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permit to call the interface, it was called in invalid state.
+ * {@link AV_ERR_UNKNOWN}, unknown error.
  * @since 10
  */
 OH_AVErrCode OH_AVMuxer_Start(OH_AVMuxer *muxer);
@@ -86,6 +96,10 @@ OH_AVErrCode OH_AVMuxer_Start(OH_AVMuxer *muxer);
  * @param info The buffer information related to this sample {@link OH_AVCodecBufferAttr}
  * @return Returns AV_ERR_OK if the execution is successful,
  * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
+ * {@link AV_ERR_INVALID_VAL}, the muxer or trackIndex or sample or info invalid.
+ * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permit to call the interface, it was called in invalid state.
+ * {@link AV_ERR_NO_MEMORY}, failed to request memory.
+ * {@link AV_ERR_UNKNOWN}, unknown error.
  * @deprecated since 11
  * @useinstead OH_AVMuxer_WriteSampleBuffer
  * @since 10
@@ -104,6 +118,10 @@ OH_AVErrCode OH_AVMuxer_WriteSample(OH_AVMuxer *muxer, uint32_t trackIndex,
  * @param sample The encoded or demuxer sample, which including data and buffer information
  * @return Returns AV_ERR_OK if the execution is successful,
  * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
+ * {@link AV_ERR_INVALID_VAL}, the muxer or trackIndex or sample invalid.
+ * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permit to call the interface, it was called in invalid state.
+ * {@link AV_ERR_NO_MEMORY}, failed to request memory.
+ * {@link AV_ERR_UNKNOWN}, unknown error.
  * @since 11
  */
 OH_AVErrCode OH_AVMuxer_WriteSampleBuffer(OH_AVMuxer *muxer, uint32_t trackIndex,
@@ -116,6 +134,8 @@ OH_AVErrCode OH_AVMuxer_WriteSampleBuffer(OH_AVMuxer *muxer, uint32_t trackIndex
  * @param muxer Pointer to an OH_AVMuxer instance
  * @return Returns AV_ERR_OK if the execution is successful,
  * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
+ * {@link AV_ERR_INVALID_VAL}, the muxer invalid.
+ * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permit to call the interface, it was called in invalid state.
  * @since 10
  */
 OH_AVErrCode OH_AVMuxer_Stop(OH_AVMuxer *muxer);
@@ -126,6 +146,7 @@ OH_AVErrCode OH_AVMuxer_Stop(OH_AVMuxer *muxer);
  * @param muxer Pointer to an OH_AVMuxer instance
  * @return Returns AV_ERR_OK if the execution is successful,
  * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
+ * {@link AV_ERR_INVALID_VAL}, the muxer invalid.
  * @since 10
  */
 OH_AVErrCode OH_AVMuxer_Destroy(OH_AVMuxer *muxer);
diff --git a/multimedia/media_foundation/native_avformat.h b/multimedia/media_foundation/native_avformat.h
index 4335cee33..6868ce4de 100644
--- a/multimedia/media_foundation/native_avformat.h
+++ b/multimedia/media_foundation/native_avformat.h
@@ -70,7 +70,8 @@ struct OH_AVFormat *OH_AVFormat_Create(void);
  * @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
  */
@@ -84,7 +85,8 @@ struct OH_AVFormat *OH_AVFormat_CreateAudioFormat(const char *mimeType,
  * @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
  */
@@ -108,6 +110,7 @@ void OH_AVFormat_Destroy(struct OH_AVFormat *format);
  * @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 format is nullptr. 2. input format's magic error.
  * @since 9
  * @version 1.0
  */
@@ -120,6 +123,7 @@ bool OH_AVFormat_Copy(struct OH_AVFormat *to, struct OH_AVFormat *from);
  * @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. input format's magic error. 3. key is nullptr.
  * @since 9
  * @version 1.0
  */
@@ -132,6 +136,7 @@ bool OH_AVFormat_SetIntValue(struct OH_AVFormat *format, const char *key, int32_
  * @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. input format's magic error. 3. key is nullptr.
  * @since 9
  * @version 1.0
  */
@@ -144,6 +149,7 @@ bool OH_AVFormat_SetLongValue(struct OH_AVFormat *format, const char *key, int64
  * @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. input format's magic error. 3. key is nullptr.
  * @since 9
  * @version 1.0
  */
@@ -156,6 +162,7 @@ bool OH_AVFormat_SetFloatValue(struct OH_AVFormat *format, const char *key, floa
  * @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. input format's magic error. 3. key is nullptr.
  * @since 9
  * @version 1.0
  */
@@ -168,6 +175,8 @@ bool OH_AVFormat_SetDoubleValue(struct OH_AVFormat *format, const char *key, dou
  * @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. input format's magic error. 3. key is nullptr.
+ * 4. value is nullptr.
  * @since 9
  * @version 1.0
  */
@@ -181,6 +190,8 @@ bool OH_AVFormat_SetStringValue(struct OH_AVFormat *format, const char *key, con
  * @param addr written data addr
  * @param size written data length
  * @return The return value is TRUE for success, FALSE for failure
+ * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr.
+ * 4. addr is nullptr. 5. size is zero.
  * @since 9
  * @version 1.0
  */
@@ -193,6 +204,8 @@ bool OH_AVFormat_SetBuffer(struct OH_AVFormat *format, const char *key, const ui
  * @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. input format's magic error. 3. key is nullptr.
+ * 4. out is nullptr.
  * @since 9
  * @version 1.0
  */
@@ -205,6 +218,8 @@ bool OH_AVFormat_GetIntValue(struct OH_AVFormat *format, const char *key, int32_
  * @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. input format's magic error. 3. key is nullptr.
+ * 4. out is nullptr.
  * @since 9
  * @version 1.0
  */
@@ -217,6 +232,8 @@ bool OH_AVFormat_GetLongValue(struct OH_AVFormat *format, const char *key, int64
  * @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. input format's magic error. 3. key is nullptr.
+ * 4. out is nullptr.
  * @since 9
  * @version 1.0
  */
@@ -229,6 +246,8 @@ bool OH_AVFormat_GetFloatValue(struct OH_AVFormat *format, const char *key, floa
  * @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. input format's magic error. 3. key is nullptr.
+ * 4. out is nullptr.
  * @since 9
  * @version 1.0
  */
@@ -242,6 +261,8 @@ bool OH_AVFormat_GetDoubleValue(struct OH_AVFormat *format, const char *key, dou
  * @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. input format's magic error. 3. key is nullptr.
+ * 4. out is nullptr. 5. malloc out string nullptr.
  * @since 9
  * @version 1.0
  */
@@ -256,6 +277,8 @@ bool OH_AVFormat_GetStringValue(struct OH_AVFormat *format, const char *key, con
  * if the caller needs to hold it for a long time, it must copy the memory
  * @param size Length of read and write data
  * @return The return value is TRUE for success, FALSE for failure
+ * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr.
+ * 4. addr is nullptr. 5. size is nullptr.
  * @since 9
  * @version 1.0
  */
@@ -265,7 +288,8 @@ bool OH_AVFormat_GetBuffer(struct OH_AVFormat *format, const char *key, uint8_t
  * @brief Output the information contained in OH_AVFormat as a string.
  * @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, nullptr for failure
+ * Possible failure causes: 1. input format is nullptr. 2. malloc dump info nullptr.
  * @since 9
  * @version 1.0
  */
diff --git a/multimedia/media_foundation/native_avmemory.h b/multimedia/media_foundation/native_avmemory.h
index 489a4ff49..e4457d835 100644
--- a/multimedia/media_foundation/native_avmemory.h
+++ b/multimedia/media_foundation/native_avmemory.h
@@ -29,7 +29,9 @@ 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 nullptr. Possible failure causes: 1. size <= 0. 2. create OH_AVMemory failed.
+ * 3.failed to new OH_AVMemory.
  * @deprecated since 11
  * @useinstead OH_AVBuffer_Create
  * @since 10
@@ -41,6 +43,7 @@ OH_AVMemory *OH_AVMemory_Create(int32_t size);
  * @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.
+ * Possible failure causes: 1. input mem is nullptr. 2. mem's magic error. 3. mem's memory is nullptr.
  * @deprecated since 11
  * @useinstead OH_AVBuffer_GetAddr
  * @since 9
@@ -53,6 +56,7 @@ 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. mem's magic error. 3. mem's memory is nullptr.
  * @deprecated since 11
  * @useinstead OH_AVBuffer_GetCapacity
  * @since 9
@@ -65,8 +69,9 @@ 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} if input mem is nullptr, mem's magic error or input mem is not user created.
  * @deprecated since 11
  * @useinstead OH_AVBuffer_Destroy
  * @since 10
-- 
Gitee