1# VideoEncoder 2 3 4## Overview 5 6The VideoEncoder module provides the APIs for video encoding. 7 8You can refer to the corresponding development guide and samples based on your development requirements. 9 10- [Video Encoding](../../media/avcodec/video-encoding.md) 11- [Temporal Layered Video Encoding](../../media/avcodec/video-encoding-temporal-scalability.md) 12 13**System capability**: SystemCapability.Multimedia.VideoEncoder 14 15**Since**: 9 16 17The following figures show the APIs supported by each version and the APIs that can be called in different states. 18 19 20 21 22 23## Summary 24 25 26### Files 27 28| Name| Description| 29| -------- | -------- | 30| [native_avcodec_videoencoder.h](native__avcodec__videoencoder_8h.md) | Declares the APIs used for video encoding. | 31 32 33### Types 34 35| Name| Description| 36| -------- | -------- | 37| typedef void(\* [OH_VideoEncoder_OnNeedInputParameter](#oh_videoencoder_onneedinputparameter)) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index, OH_AVFormat \*parameter, void \*userData) | Defines the pointer to the function that is called when new input parameters are required for a frame with the specified index. It takes effect only in surface mode. | 38 39### Enums 40 41| Name| Description| 42| -------- | -------- | 43| [OH_VideoEncodeBitrateMode](#oh_videoencodebitratemode) { CBR = 0, VBR = 1, CQ = 2 } | Enumerates the bit rate modes of a video encoder. (It is deprecated from API version 14.) | 44 45 46### Functions 47 48| Name| Description| 49| -------- | -------- | 50| [OH_AVCodec](_codec_base.md#oh_avcodec) \* [OH_VideoEncoder_CreateByMime](#oh_videoencoder_createbymime) (const char \*mime) | Creates a video encoder instance based on a [MIME](_codec_base.md#media-codec-formats) type. This function is recommended. | 51| [OH_AVCodec](_codec_base.md#oh_avcodec) \* [OH_VideoEncoder_CreateByName](#oh_videoencoder_createbyname) (const char \*name) | Creates a video encoder instance based on an encoder name. | 52| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Destroy](#oh_videoencoder_destroy) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Clears the internal resources of a video encoder and destroys the encoder instance. | 53| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_SetCallback](#oh_videoencoder_setcallback) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md) callback, void \*userData) | Sets an OH_AVCodecCallback callback so that your application can respond to events generated by a video encoder. (It is deprecated from API version 11.) | 54| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_RegisterCallback](#oh_videoencoder_registercallback) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_AVCodecCallback](_o_h___a_v_codec_callback.md) callback, void \*userData) | Registers an OH_AVCodecCallback callback so that your application can respond to events generated by a video encoder. | 55| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_RegisterParameterCallback](#oh_videoencoder_registerparametercallback) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_VideoEncoder_OnNeedInputParameter](#oh_videoencoder_onneedinputparameter) onInputParameter, void \*userData) | Registers an OH_AVCodecCallback input parameter callback so that your application can respond to events generated by a video encoder. | 56| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Configure](#oh_videoencoder_configure) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, OH_AVFormat \*format) | Configures a video encoder. Typically, you need to configure the description information about the video track to be encoded, such as the width, height, and pixel format. | 57| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Prepare](#oh_videoencoder_prepare) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Prepares internal resources for a video encoder. | 58| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Start](#oh_videoencoder_start) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Starts a video encoder. This function should be called after a successful call of **OH_VideoEncoder_Prepare**. | 59| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Stop](#oh_videoencoder_stop) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Stops a video encoder and releases the input and output buffers. | 60| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Flush](#oh_videoencoder_flush) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Clears the input and output data and parameters, for example, H.264 PPS/SPS, cached in a video encoder. | 61| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Reset](#oh_videoencoder_reset) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Resets a video encoder. The encoder returns to the initial state. | 62| OH_AVFormat \* [OH_VideoEncoder_GetOutputDescription](#oh_videoencoder_getoutputdescription) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Obtains the OH_AVFormat information about the output data of a video encoder. | 63| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_SetParameter](#oh_videoencoder_setparameter) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, OH_AVFormat \*format) | Sets the encoder parameter when a video encoder is running. | 64| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_GetSurface](#oh_videoencoder_getsurface) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OHNativeWindow](_codec_base.md#ohnativewindow) \*\*window) | Obtains the input surface from a video encoder. | 65| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_FreeOutputData](#oh_videoencoder_freeoutputdata) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Frees an output buffer of a video encoder. (It is deprecated from API version 11.) | 66| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_NotifyEndOfStream](#oh_videoencoder_notifyendofstream) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Notifies a video encoder that input streams end. | 67| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_PushInputData](#oh_videoencoder_pushinputdata) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index, [OH_AVCodecBufferAttr](_o_h___a_v_codec_buffer_attr.md) attr) | Pushes the input buffer filled with data to a video encoder. (It is deprecated from API version 11.) | 68| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_PushInputBuffer](#oh_videoencoder_pushinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Pushes the OH_AVBuffer corresponding to the index to a video encoder in buffer mode. | 69| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_PushInputParameter](#oh_videoencoder_pushinputparameter) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Pushes the parameter configured for a frame with the given index to a video encoder in surface mode. | 70| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_FreeOutputBuffer](#oh_videoencoder_freeoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Returns the processed OH_AVBuffer corresponding to the index to a video encoder. | 71| OH_AVFormat \* [OH_VideoEncoder_GetInputDescription](#oh_videoencoder_getinputdescription) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Obtains the description of the image received by a video encoder. | 72| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_IsValid](#oh_videoencoder_isvalid) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, bool \*isValid) | Checks whether a video encoder instance is valid. | 73| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_QueryInputBuffer](#oh_videoencoder_queryinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t *index, int64_t timeoutUs) | Obtains the index of the next available input buffer.| 74| [OH_AVBuffer](_core.md#oh_avbuffer) [OH_VideoEncoder_GetInputBuffer](#oh_videoencoder_getinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Obtains the instance of the available input buffer.| 75| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_QueryOutputBuffer](#oh_videoencoder_queryoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t *index, int64_t timeoutUs) | Obtains the index of the next available output buffer.| 76| [OH_AVBuffer](_core.md#oh_avbuffer) [OH_VideoEncoder_GetOutputBuffer](#oh_videoencoder_getoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Obtains the instance of the available output buffer.| 77 78## Type Description 79 80### OH_VideoEncoder_OnNeedInputParameter 81 82``` 83typedef void(* OH_VideoEncoder_OnNeedInputParameter) (OH_AVCodec *codec, uint32_t index, OH_AVFormat *parameter, void *userData) 84``` 85 86**Description** 87 88Defines the pointer to the function that is called when new input parameters are required for a frame with the specified index. 89 90This callback can be used only in surface mode after it is registered by calling OH_VideoEncoder_RegisterParameterCallback. 91 92In buffer mode, OH_AVBuffer can directly carry the encoding parameter associated with each frame. Currently, it can manage parameters, including **QPMin**, **QPMax**, and reference frames for Long Term Reference (LTR), on a per-frame basis. 93 94**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 95 96**Since**: 12 97 98**Parameters** 99 100| Name| Description| 101| -------- | -------- | 102| codec | Pointer to a video encoder instance. | 103| index | Index of the frame to encode. | 104| parameter | Pointer to the encoding parameter | 105| userData | Pointer to the data on which the caller depends when executing the callback. | 106 107 108## Enum Description 109 110 111### OH_VideoEncodeBitrateMode 112 113``` 114enum OH_VideoEncodeBitrateMode 115``` 116 117**Description** 118 119Enumerates the bit rate modes of a video encoder. 120 121**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 122 123**Since**: 9 124 125**Deprecated from**: 14 126 127**Substitute**: [OH_BitrateMode](_codec_base.md#oh_bitratemode-1) 128 129| Value| Description| 130| -------- | -------- | 131| CBR | Constant bit rate. | 132| VBR | Variable bit rate. | 133| CQ | Constant quality. | 134 135 136## Function Description 137 138 139### OH_VideoEncoder_Configure() 140 141``` 142OH_AVErrCode OH_VideoEncoder_Configure (OH_AVCodec *codec, OH_AVFormat *format ) 143``` 144 145**Description** 146 147Configures a video encoder. Typically, you need to configure the description information about the video track to be encoded, such as the width, height, and pixel format. This function must be called prior to **OH_VideoEncoder_Prepare**. 148 149This function is used to verify the validity of configuration parameters. Some invalid parameters are not forcibly verified. The default values are used or discarded. Some invalid parameters are forcibly verified. The rules are as follows: 150 151The value ranges of the following parameters can be obtained from [Capability Query](../../media/avcodec/obtain-supported-codecs.md). All the values of **OH_MD_KEY_I_FRAME_INTERVAL** are supported. 152 153If the current platform does not support **OH_MD_KEY_VIDEO_ENCODER_ENABLE_TEMPORAL_SCALABILITY** or **OH_MD_KEY_VIDEO_ENCODER_LTR_FRAME_COUNT**, no error is reported and the normal encoding process is used. 154 155Parameter verification rules are as follows: 156 157| Key | Value Within the Range| Value Out of Range| No Value Configured| 158| ------------------------------------------------------------------------- | -------- | -------- | ------ | 159| OH_MD_KEY_WIDTH | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL | 160| OH_MD_KEY_HEIGHT | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL | 161| OH_MD_KEY_PIXEL_FORMAT<br>For details, see [OH_AVPixelFormat](_core.md#oh_avpixelformat-1).| AV_ERR_OK | AV_ERR_UNSUPPORT | AV_ERR_OK | 162| OH_MD_KEY_FRAME_RATE | AV_ERR_OK | AV_ERR_INVALID_VAL |AV_ERR_OK | 163| OH_MD_KEY_PROFILE<br>For details, see [OH_MD_KEY_PROFILE](_codec_base.md#oh_md_key_profile). | AV_ERR_OK | AV_ERR_INVALID_VAL |AV_ERR_OK | 164| OH_MD_KEY_I_FRAME_INTERVAL | AV_ERR_OK | \\ | AV_ERR_OK | 165 166| OH_MD_KEY_<br>BITRATE | OH_MD_KEY_<br>QUALITY | OH_MD_KEY_<br>VIDEO_ENCODER_BITRATE_MODE | Return Value| Description | 167| :-------------------- | :-------------------- | :--------------------------------------- | ---- | ---------------------- | 168| \\ | \\ | \\ | AV_ERR_OK | The default value of the encoder is used. | 169| Out of range | Out of range | Unsupported mode | AV_ERR_INVALID_VAL | An error is reported for all abnormal values. | 170| Normal value | Normal value | \\ | AV_ERR_INVALID_VAL | The bit rate conflicts with the quality. | 171| Normal value | \\ | \\ | AV_ERR_OK | The default bit rate control mode is enabled. | 172| Normal value | \\ | BITRATE_MODE_VBR and BITRATE_MODE_CBR | AV_ERR_OK | | 173| Normal value | \\ | BITRATE_MODE_CQ | AV_ERR_INVALID_VAL | The bit rate conflicts with the CQ mode. | 174| \\ | Normal value | \\ | AV_ERR_OK | The CQ mode is enabled. | 175| \\ | Normal value | BITRATE_MODE_CQ | AV_ERR_OK | | 176| \\ | Normal value | BITRATE_MODE_VBR and BITRATE_MODE_CBR | AV_ERR_INVALID_VAL | The quality conflicts with the VBR or CBR mode.| 177| \\ | \\ | BITRATE_MODE_VBR and BITRATE_MODE_CBR | AV_ERR_OK | The default bit rate of the encoder is used. | 178| \\ | \\ | BITRATE_MODE_CQ | AV_ERR_OK | The default quality is used. | 179 180 181**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 182 183**Since**: 9 184 185**Parameters** 186 187| Name| Description| 188| -------- | -------- | 189| codec | Pointer to a video encoder instance. | 190| format | Pointer to an OH_AVFormat instance, which provides the description information about the video track to be encoded. | 191 192**Returns** 193 194One of the following result codes: 195 196**AV_ERR_OK**: The operation is successful. 197 198**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, an unexpected nullptr. 199 200**AV_ERR_INVALID_VAL**: 201 202 1. The value of **codec** is nullptr or does not point to an encoder instance. 203 2. The format is not supported. 204 205**AV_ERR_UNKNOWN**: An unknown error occurs. 206 207**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 208 209**AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoEncoder_Prepare**. 210 211**AV_ERR_UNSUPPORT**: The feature is not supported. 212 213 214### OH_VideoEncoder_CreateByMime() 215 216``` 217OH_AVCodec* OH_VideoEncoder_CreateByMime (const char *mime) 218``` 219 220**Description** 221 222Creates a video encoder instance based on a MIME type. This function is recommended. 223 224**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 225 226**Since**: 9 227 228**Parameters** 229 230| Name| Description| 231| -------- | -------- | 232| mime | Pointer to a string that describes the MIME type. For details, see [AVCODEC_MIMETYPE](_codec_base.md#variables).| 233 234**Returns** 235 236Pointer to the video encoder instance created. If the encoder type is not supported or the memory is insufficient, NULL is returned. 237 238 239### OH_VideoEncoder_CreateByName() 240 241``` 242OH_AVCodec* OH_VideoEncoder_CreateByName (const char *name) 243``` 244 245**Description** 246 247Creates a video encoder instance based on an encoder name. Tho use this function, you must know the exact name of the encoder. The encoder name can be obtained through capability query. 248 249For details, see [Obtaining Supported Codecs](../../media/avcodec/obtain-supported-codecs.md#creating-a-codec-with-the-specified-name). 250 251**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 252 253**Since**: 9 254 255**Parameters** 256 257| Name| Description| 258| -------- | -------- | 259| name | Pointer to a video encoder name. | 260 261**Returns** 262 263Pointer to the video encoder instance created. If the encoder name is not supported or the memory is insufficient, NULL is returned. 264 265 266### OH_VideoEncoder_Destroy() 267 268``` 269OH_AVErrCode OH_VideoEncoder_Destroy (OH_AVCodec *codec) 270``` 271 272**Description** 273 274Clears the internal resources of a video encoder and destroys the encoder instance. You only need to call the function once. 275 276**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 277 278**Since**: 9 279 280**Parameters** 281 282| Name| Description| 283| -------- | -------- | 284| codec | Pointer to a video encoder instance. | 285 286**Returns** 287 288One of the following result codes: 289 290**AV_ERR_OK**: The operation is successful. 291 292**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, an unexpected nullptr. 293 294**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 295 296**AV_ERR_UNKNOWN**: An unknown error occurs. 297 298**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 299 300 301### OH_VideoEncoder_Flush() 302 303``` 304OH_AVErrCode OH_VideoEncoder_Flush (OH_AVCodec *codec) 305``` 306 307**Description** 308 309Clears the input and output data and parameters, for example, H.264 PPS/SPS, cached in a video encoder. 310 311This function invalidates the indexes of all buffers previously reported through the asynchronous callback. Therefore, before calling this function, ensure that the buffers with the specified indexes are no longer required. This function cannot be called consecutively. 312 313**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 314 315**Since**: 9 316 317**Parameters** 318 319| Name| Description| 320| -------- | -------- | 321| codec | Pointer to a video encoder instance. | 322 323**Returns** 324 325One of the following result codes: 326 327**AV_ERR_OK**: The operation is successful. 328 329**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, an unexpected nullptr. 330 331**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 332 333**AV_ERR_UNKNOWN**: An unknown error occurs. 334 335**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 336 337**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 338 339 340### OH_VideoEncoder_FreeOutputBuffer() 341 342``` 343OH_AVErrCode OH_VideoEncoder_FreeOutputBuffer (OH_AVCodec *codec, uint32_t index ) 344``` 345 346**Description** 347 348Returns the processed OH_AVBuffer corresponding to the index to a video encoder. You need to call this function to release the output buffer in a timely manner. Otherwise, the encoding process is blocked. 349 350For details, see step 13 in surface mode or step 11 in buffer mode in [Video Encoding](../../media/avcodec/video-encoding.md). 351 352**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 353 354**Since**: 11 355 356**Parameters** 357 358| Name| Description| 359| -------- | -------- | 360| codec | Pointer to a video encoder instance. | 361| index | Index of the output buffer. The index is obtained from [OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer).| 362 363**Returns** 364 365One of the following result codes: 366 367**AV_ERR_OK**: The operation is successful. 368 369**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, an unexpected nullptr. 370 371**AV_ERR_INVALID_VAL**: 372 373 1. The value of **codec** is nullptr or does not point to an encoder instance. 374 2. The format is not supported. 375 3. The index is invalid or the same index is used consecutively. This error does not affect the subsequent encoding process. 376 377**AV_ERR_UNKNOWN**: An unknown error occurs. 378 379**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 380 381**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 382 383 384### OH_VideoEncoder_GetInputDescription() 385 386``` 387OH_AVFormat* OH_VideoEncoder_GetInputDescription (OH_AVCodec *codec) 388``` 389 390**Description** 391 392Obtains the description of the image received by a video encoder. This function must be called after [OH_VideoEncoder_Configure](#oh_videoencoder_configure) is called. 393 394You must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to manually release the OH_AVFormat instance in the return value. 395 396**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 397 398**Since**: 10 399 400**Parameters** 401 402| Name| Description| 403| -------- | -------- | 404| codec | Pointer to a video encoder instance. | 405 406**Returns** 407 408Pointer to an OH_AVFormat instance. If the value of **codec** is nullptr or does not point to an encoder instance, NULL is returned. 409 410 411### OH_VideoEncoder_GetOutputDescription() 412 413``` 414OH_AVFormat* OH_VideoEncoder_GetOutputDescription (OH_AVCodec *codec) 415``` 416 417**Description** 418 419Obtains the OH_AVFormat information about the output data of a video encoder. 420 421You must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to release the OH_AVFormat instance in the return value. 422 423**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 424 425**Since**: 9 426 427**Parameters** 428 429| Name| Description| 430| -------- | -------- | 431| codec | Pointer to a video encoder instance. | 432 433**Returns** 434 435Pointer to an OH_AVFormat instance. If the value of **codec** is nullptr or does not point to an encoder instance, NULL is returned. 436 437 438### OH_VideoEncoder_GetSurface() 439 440``` 441OH_AVErrCode OH_VideoEncoder_GetSurface (OH_AVCodec *codec, OHNativeWindow ** window ) 442``` 443 444**Description** 445 446Obtains the input surface from a video encoder. This function must be called after **OH_VideoEncoder_Configure** but before **OH_VideoEncoder_Prepare**. 447 448**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 449 450**Since**: 9 451 452**Parameters** 453 454| Name| Description| 455| -------- | -------- | 456| codec | Pointer to a video encoder instance. | 457| window | Double pointer to an OHNativeWindow instance. For details, see [OHNativeWindow](_codec_base.md#ohnativewindow). The application manages the lifecycle of the window and calls **OH_NativeWindow_DestroyNativeWindow** to release the window when the lifecycle ends. | 458 459**Returns** 460 461One of the following result codes: 462 463**AV_ERR_OK**: The operation is successful. 464 465**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 466 467**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 468 469 470### OH_VideoEncoder_IsValid() 471 472``` 473OH_AVErrCode OH_VideoEncoder_IsValid (OH_AVCodec *codec, bool *isValid ) 474``` 475 476**Description** 477 478Checks whether the encoder service is valid when an encoder instance exists. 479 480**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 481 482**Since**: 10 483 484**Parameters** 485 486| Name| Description| 487| -------- | -------- | 488| codec | Pointer to a video encoder instance. | 489| isValid | Pointer of the Boolean type. The value indicates the validity of the encoder service only when the function returns **AV_ERR_OK**. The value **true** means that the encoder service is valid, and **false** means the opposite. It is recommended that you initialize **isValid** to **false**. | 490 491**Returns** 492 493One of the following result codes: 494 495**AV_ERR_OK**: The operation is successful. 496 497**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 498 499 500### OH_VideoEncoder_NotifyEndOfStream() 501 502``` 503OH_AVErrCode OH_VideoEncoder_NotifyEndOfStream (OH_AVCodec *codec) 504``` 505 506**Description** 507 508Notifies a video encoder that input streams end. You are advised to use this function for notification. This function is used only in surface mode. In buffer mode, OH_AVBuffer is used to carry the EOS information to notify the end of the input stream. 509 510**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 511 512**Since**: 9 513 514**Parameters** 515 516| Name| Description| 517| -------- | -------- | 518| codec | Pointer to a video encoder instance. | 519 520**Returns** 521 522One of the following result codes: 523 524**AV_ERR_OK**: The operation is successful. 525 526**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, an unexpected nullptr. 527 528**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 529 530**AV_ERR_UNKNOWN**: An unknown error occurs. 531 532**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 533 534**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 535 536 537### OH_VideoEncoder_Prepare() 538 539``` 540OH_AVErrCode OH_VideoEncoder_Prepare (OH_AVCodec *codec) 541``` 542 543**Description** 544 545Prepares internal resources for a video encoder. This function must be called after **OH_VideoEncoder_Configure**. 546 547**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 548 549**Since**: 9 550 551**Parameters** 552 553| Name| Description| 554| -------- | -------- | 555| codec | Pointer to a video encoder instance. | 556 557**Returns** 558 559One of the following result codes: 560 561**AV_ERR_OK**: The operation is successful. 562 563**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 564 565**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 566 567 568### OH_VideoEncoder_PushInputBuffer() 569 570``` 571OH_AVErrCode OH_VideoEncoder_PushInputBuffer (OH_AVCodec *codec, uint32_t index ) 572``` 573 574**Description** 575 576Pushes the OH_AVBuffer corresponding to the index to a video encoder in buffer mode. 577 578**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 579 580**Since**: 11 581 582**Parameters** 583 584| Name| Description| 585| -------- | -------- | 586| codec | Pointer to a video encoder instance. | 587| index | Index of the input buffer. The index is obtained from [OH_AVCodecOnNeedInputBuffer](_codec_base.md#oh_avcodeconneedinputbuffer).| 588 589**Returns** 590 591One of the following result codes: 592 593**AV_ERR_OK**: The operation is successful. 594 595**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, an unexpected nullptr. 596 597**AV_ERR_INVALID_VAL**: 598 599 1. The value of **codec** is nullptr or does not point to an encoder instance. 600 2. The format is not supported. 601 602**AV_ERR_UNKNOWN**: An unknown error occurs. 603 604**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 605 606**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 607 608 609### OH_VideoEncoder_PushInputParameter() 610 611``` 612OH_AVErrCode OH_VideoEncoder_PushInputParameter (OH_AVCodec *codec, uint32_t index) 613``` 614 615**Description** 616 617Pushes the parameter configured for a frame with the given index to a video encoder in surface mode. 618 619**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 620 621**Since**: 12 622 623**Parameters** 624 625| Name| Description| 626| -------- | -------- | 627| codec | Pointer to a video encoder instance. | 628| index | Index of the input parameter buffer. The index is obtained from [OH_VideoEncoder_OnNeedInputParameter](#oh_videoencoder_onneedinputparameter). | 629 630**Returns** 631 632One of the following result codes: 633 634**AV_ERR_OK**: The operation is successful. 635 636**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, an unexpected nullptr. 637 638**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 639 640**AV_ERR_UNKNOWN**: An unknown error occurs. 641 642**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 643 644**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 645 646 647### OH_VideoEncoder_RegisterCallback() 648 649``` 650OH_AVErrCode OH_VideoEncoder_RegisterCallback (OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData ) 651``` 652 653**Description** 654 655Registers an OH_AVCodecCallback callback so that your application can respond to events generated by a video encoder. This function must be called prior to **OH_VideoEncoder_Prepare**. 656 657**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 658 659**Since**: 11 660 661**Parameters** 662 663| Name| Description| 664| -------- | -------- | 665| codec | Pointer to a video encoder instance. | 666| callback | Callback function to set. For details, see [OH_AVCodecCallback](_o_h___a_v_codec_callback.md). | 667| userData | Pointer to the data on which the caller depends when executing the callback. | 668 669**Returns** 670 671One of the following result codes: 672 673**AV_ERR_OK**: The operation is successful. 674 675**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, an unexpected nullptr. 676 677**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 678 679**AV_ERR_UNKNOWN**: An unknown error occurs. 680 681**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 682 683**AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoEncoder_Prepare**. 684 685 686### OH_VideoEncoder_RegisterParameterCallback() 687 688``` 689OH_AVErrCode OH_VideoEncoder_RegisterParameterCallback (OH_AVCodec *codec, OH_VideoEncoder_OnNeedInputParameter onInputParameter, void *userData) 690``` 691 692**Description** 693 694Registers an OH_AVCodecCallback input parameter callback so that your application can respond to events generated by a video encoder. In surface encoding mode, this function must be called when frame parameters need to be set, and it must be called before [OH_VideoEncoder_Configure](#oh_videoencoder_configure). 695 696**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 697 698**Since**: 12 699 700**Parameters** 701 702| Name| Description| 703| -------- | -------- | 704| codec | Pointer to a video encoder instance. | 705| onInputParameter | Pointer to the input parameter callback. For details, see [OH_VideoEncoder_OnNeedInputParameter](#oh_videoencoder_onneedinputparameter). | 706| userData | Pointer to the data on which the caller depends when executing the callback. | 707 708**Returns** 709 710One of the following result codes: 711 712**AV_ERR_OK**: The operation is successful. 713 714**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, an unexpected nullptr. 715 716**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 717 718**AV_ERR_UNKNOWN**: An unknown error occurs. 719 720**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 721 722**AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoEncoder_Prepare**. 723 724 725### OH_VideoEncoder_Reset() 726 727``` 728OH_AVErrCode OH_VideoEncoder_Reset (OH_AVCodec *codec) 729``` 730 731**Description** 732 733Resets a video encoder. The encoder returns to the initial state. To continue encoding, you must call **OH_VideoEncoder_Configure** to configure the encoder again. 734 735**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 736 737**Since**: 9 738 739**Parameters** 740 741| Name| Description| 742| -------- | -------- | 743| codec | Pointer to a video encoder instance. | 744 745**Returns** 746 747One of the following result codes: 748 749**AV_ERR_OK**: The operation is successful. 750 751**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, an unexpected nullptr. 752 753**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 754 755**AV_ERR_UNKNOWN**: An unknown error occurs. 756 757**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 758 759 760### OH_VideoEncoder_SetParameter() 761 762``` 763OH_AVErrCode OH_VideoEncoder_SetParameter (OH_AVCodec *codec, OH_AVFormat *format ) 764``` 765 766**Description** 767 768Sets the encoder parameter when a video encoder is running. 769 770This function can be called only after the encoder is started. Incorrect parameter settings may cause encoding failure. 771 772**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 773 774**Since**: 9 775 776**Parameters** 777 778| Name| Description| 779| -------- | -------- | 780| codec | Pointer to a video encoder instance. | 781| format | Pointer to an OH_AVFormat instance. | 782 783**Returns** 784 785One of the following result codes: 786 787**AV_ERR_OK**: The operation is successful. 788 789**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, an unexpected nullptr. 790 791**AV_ERR_INVALID_VAL**: 792 793 1. The value of **codec** is nullptr or does not point to an encoder instance. 794 2. The format is not supported. 795 796**AV_ERR_UNKNOWN**: An unknown error occurs. 797 798**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 799 800**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 801 802 803### OH_VideoEncoder_Start() 804 805``` 806OH_AVErrCode OH_VideoEncoder_Start (OH_AVCodec *codec) 807``` 808 809**Description** 810 811Starts a video encoder. This function should be called after a successful call of **OH_VideoEncoder_Prepare**. After being started, the encoder starts to report the registered event. 812 813In surface mode, when there is a correct input on the surface, **OnNewOutputBuffer** is triggered each time a frame is encoded. 814 815In buffer mode, the encoder immediately triggers the input callback. Each time the caller completes an input, the encoder performs encoding. **OnNewOutputBuffer** is triggered each time a frame is encoded. 816 817**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 818 819**Since**: 9 820 821**Parameters** 822 823| Name| Description| 824| -------- | -------- | 825| codec | Pointer to a video encoder instance. | 826 827**Returns** 828 829One of the following result codes: 830 831**AV_ERR_OK**: The operation is successful. 832 833**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, an unexpected nullptr. 834 835**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 836 837**AV_ERR_UNKNOWN**: An unknown error occurs. 838 839**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 840 841**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 842 843 844### OH_VideoEncoder_Stop() 845 846``` 847OH_AVErrCode OH_VideoEncoder_Stop (OH_AVCodec *codec) 848``` 849 850**Description** 851 852Stops a video encoder and releases the input and output buffers. After the video encoder is stopped, you can call **OH_VideoEncoder_Start** to enter the running state again. 853 854**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 855 856**Since**: 9 857 858**Parameters** 859 860| Name| Description| 861| -------- | -------- | 862| codec | Pointer to a video encoder instance. | 863 864**Returns** 865 866One of the following result codes: 867 868**AV_ERR_OK**: The operation is successful. 869 870**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, an unexpected nullptr. 871 872**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 873 874**AV_ERR_UNKNOWN**: An unknown error occurs. 875 876**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 877 878**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 879 880 881### OH_VideoEncoder_QueryInputBuffer() 882 883``` 884OH_AVErrCode OH_VideoEncoder_QueryInputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs); 885``` 886 887**Description** 888 889Obtains the index of the next available input buffer. 890 891After calling this function, you must call [OH_VideoEncoder_GetInputBuffer](#oh_videoencoder_getinputbuffer) to obtain the buffer instance and call [OH_VideoEncoder_PushInputBuffer](#oh_videoencoder_pushinputbuffer) to pass the buffer instance to the encoder. 892 893Note that the preceding operations are supported only in synchronous mode. 894 895**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 896 897**Since**: 20 898 899**Parameters** 900 901| Name| Description| 902| -------- | -------- | 903| codec | Pointer to a video encoder instance. | 904| index | Pointer to the index of the input buffer.| 905| timeoutUs | Timeout duration, in microseconds. A negative value means to wait infinitely. The value **0** means to return immediately. A positive value means to wait for the specified time before exiting. | 906 907**Returns** 908 909One of the following result codes: 910 911**AV_ERR_OK**: The operation is successful. 912 913**AV_ERR_NO_MEMORY**: The encoder instance has been destroyed. 914 915**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 916 917**AV_ERR_UNKNOWN**: An unknown error occurs. 918 919**AV_ERR_SERVICE_DIED**: The codec service has been terminated. 920 921**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 922 923**AV_ERR_OPERATE_NOT_PERMIT**: This function is called in asynchronous mode. 924 925**AV_ERR_TRY_AGAIN_LATER**: The query fails. Try again after a short interval. 926 927 928### OH_VideoEncoder_GetInputBuffer() 929 930``` 931OH_AVBuffer *OH_VideoEncoder_GetInputBuffer(struct OH_AVCodec *codec, uint32_t index); 932``` 933 934**Description** 935 936Obtains the instance of the available input buffer. 937 938Note that this function works only in synchronous mode. 939 940**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 941 942**Since**: 20 943 944**Parameters** 945 946| Name| Description| 947| -------- | -------- | 948| codec | Pointer to a video encoder instance. | 949| index | Index of the input buffer. It can be obtained by calling [OH_VideoEncoder_QueryInputBuffer](#oh_videoencoder_queryinputbuffer).| 950 951**Returns** 952 953Pointer to the OH_AVBuffer instance created. If the operation fails, NULL is returned. 954 955 956### OH_VideoEncoder_QueryOutputBuffer() 957 958``` 959OH_AVErrCode OH_VideoEncoder_QueryOutputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs); 960``` 961 962**Description** 963 964Obtains the index of the next available output buffer. 965 966Through the buffer instance obtained via [OH_VideoEncoder_GetOutputBuffer](#oh_videoencoder_getoutputbuffer), you can return the processed output buffer to the encoder by calling [OH_VideoEncoder_FreeOutputBuffer](#oh_videoencoder_freeoutputbuffer). 967 968Note that the preceding operations are supported only in synchronous mode. 969 970**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 971 972**Since**: 20 973 974**Parameters** 975 976| Name| Description| 977| -------- | -------- | 978| codec | Pointer to a video encoder instance. | 979| index | Pointer to the index of the output buffer.| 980| timeoutUs | Timeout duration, in microseconds. A negative value means to wait infinitely. The value **0** means to return immediately. A positive value means to wait for the specified time before exiting. | 981 982**Returns** 983 984One of the following result codes: 985 986**AV_ERR_OK**: The operation is successful. 987 988**AV_ERR_NO_MEMORY**: The encoder instance has been destroyed. 989 990**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 991 992**AV_ERR_UNKNOWN**: An unknown error occurs. 993 994**AV_ERR_SERVICE_DIED**: The codec service has been terminated. 995 996**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 997 998**AV_ERR_OPERATE_NOT_PERMIT**: This function is called in asynchronous mode. 999 1000**AV_ERR_STREAM_CHANGED**: The stream format has changed. You can call **OH_VideoEncoder_GetOutputDescription** to obtain the new stream information. 1001 1002**AV_ERR_TRY_AGAIN_LATER**: The query fails. Try again after a short interval. 1003 1004 1005### OH_VideoEncoder_GetOutputBuffer() 1006 1007``` 1008OH_AVBuffer *OH_VideoEncoder_GetOutputBuffer(struct OH_AVCodec *codec, uint32_t index); 1009``` 1010 1011**Description** 1012 1013Obtains the instance of the available output buffer. 1014 1015Note that this function works only in synchronous mode. 1016 1017**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 1018 1019**Since**: 20 1020 1021**Parameters** 1022 1023| Name| Description| 1024| -------- | -------- | 1025| codec | Pointer to a video encoder instance. | 1026| index | Index of the output buffer. It can be obtained by calling [OH_VideoEncoder_QueryOutputBuffer](#oh_videoencoder_queryoutputbuffer).| 1027 1028**Returns** 1029 1030Pointer to the OH_AVBuffer instance created. If the operation fails, NULL is returned. 1031 1032 1033## Description of Deprecated Functions 1034 1035 1036### OH_VideoEncoder_SetCallback() 1037 1038``` 1039OH_AVErrCode OH_VideoEncoder_SetCallback (OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData ) 1040``` 1041 1042**Description** 1043 1044Sets an OH_AVCodecCallback callback so that your application can respond to events generated by a video encoder. This function must be called prior to **OH_VideoEncoder_Prepare**. 1045 1046**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 1047 1048**Since**: 9 1049 1050**Deprecated from**: 11 1051 1052**Substitute API**: [OH_VideoEncoder_RegisterCallback](#oh_videoencoder_registercallback) 1053 1054**Parameters** 1055 1056| Name| Description| 1057| -------- | -------- | 1058| codec | Pointer to a video encoder instance. | 1059| callback | Callback function to set. For details, see [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md). | 1060| userData | Pointer to the data on which the caller depends when executing the callback. | 1061 1062**Returns** 1063 1064One of the following result codes: 1065 1066**AV_ERR_OK**: The operation is successful. 1067 1068**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, an unexpected nullptr. 1069 1070**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 1071 1072**AV_ERR_UNKNOWN**: An unknown error occurs. 1073 1074**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 1075 1076**AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoEncoder_Prepare**. 1077 1078 1079### OH_VideoEncoder_PushInputData() 1080 1081``` 1082OH_AVErrCode OH_VideoEncoder_PushInputData (OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr ) 1083``` 1084 1085**Description** 1086 1087Pushes the input buffer filled with data to a video encoder. 1088 1089**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 1090 1091**Since**: 10 1092 1093**Deprecated from**: 11 1094 1095**Substitute API**: [OH_VideoEncoder_PushInputBuffer](#oh_videoencoder_pushinputbuffer) 1096 1097**Parameters** 1098 1099| Name| Description| 1100| -------- | -------- | 1101| codec | Pointer to a video encoder instance. | 1102| index | Index of the input buffer. The index is obtained from [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata). | 1103| attr | Description of the data contained in the buffer. | 1104 1105**Returns** 1106 1107One of the following result codes: 1108 1109**AV_ERR_OK**: The operation is successful. 1110 1111**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, an unexpected nullptr. 1112 1113**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 1114 1115**AV_ERR_UNKNOWN**: An unknown error occurs. 1116 1117**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 1118 1119**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 1120 1121 1122### OH_VideoEncoder_FreeOutputData() 1123 1124``` 1125OH_AVErrCode OH_VideoEncoder_FreeOutputData (OH_AVCodec *codec, uint32_t index ) 1126``` 1127 1128**Description** 1129 1130Frees an output buffer of a video encoder. 1131 1132**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 1133 1134**Since**: 9 1135 1136**Deprecated from**: 11 1137 1138Substitute API: [OH_VideoEncoder_FreeOutputBuffer](#oh_videoencoder_freeoutputbuffer) 1139 1140**Parameters** 1141 1142| Name| Description| 1143| -------- | -------- | 1144| codec | Pointer to a video encoder instance. | 1145| index | Index of the output buffer. The index is obtained from [OH_AVCodecOnNewOutputData](_codec_base.md#oh_avcodeconnewoutputdata). | 1146 1147**Returns** 1148 1149One of the following result codes: 1150 1151**AV_ERR_OK**: The operation is successful. 1152 1153**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, an unexpected nullptr. 1154 1155**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to an encoder instance. 1156 1157**AV_ERR_UNKNOWN**: An unknown error occurs. 1158 1159**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 1160 1161**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 1162
