Resumable Transfer

Last Updated on : 2025-07-21 02:54:30download

Features

Network exceptions or other issues might cause event reporting failures. To mitigate such problems as much as possible, the new version v3.10.12 introduces a resumable transfer feature.

Principle

The core principle of this feature is to monitor the event upload process and track the reporting status of events. When an exception occurs during reporting, the event is recorded in the resumable transfer module. Once the network is restored, the system retrieves these failed records one by one and attempts to upload them until the upload is successful. The records are deleted after successful retransfer.

  • Enabling this feature requires additional storage space (such as a TF card) to record data. The occupied space is directly proportional to the number of failed upload events.
  • The stored data is only accessible and functional on the same device.

Development guide

Header file

tuya_ipc_breakpoint_resume.h

API description

  • Initialization

    typedef struct {
        INT_T breakpoint_resume_enable;                         ///< 1: breakpoint resume enable
        INT_T pic_event_enable;                                 ///< 1: pic & event resume enable
        CHAR_T folder_path[BREAKPOINT_RESUME_BASE_PATH_LEN];    ///< Node of storage card is mounted
        FLOAT_T max_record_hours;                               ///< Maximum record hours for breakpoint events (0: default 12 hours)
        INT_T data_file_need_backup;                            ///< Whether to enable a backup policy
        UINT_T max_record_num;                                  ///< Max number of offline records (0: default 4000 records)
        INT_T enable_intelli_resume;                            ///< Implement smart control of upload depending on the upload network status
        UINT_T max_time_for_upload_to_cloud;                    ///< Max time for upload single video to cloud (0: default 10 seconds)
        BREAKPOINT_RESUME_UPLOAD_SPEED_CTRL_E speed_control_upload_enable;     ///< Speed control upload
        BREAKPOINT_RESUME_CHECK_UPLOAD_CONDITIONS_CB check_upload_cb;          ///< Check whether the start conditions for uploading data are met. 0: ok/other: not ok
        BREAKPOINT_RESUME_IS_NETWORK_NORMAL_CB network_normal_cb;              ///< Whether network status is normal. 0: ok/other: not ok
        BREAKPOINT_RESUME_UPLOAD_CLOUD_DATA_CB cloud_data_upload_cb;           ///< Upload cloud storage
        BREAKPOINT_RESUME_GET_OTHER_CLIENT_USER_NUM_CB get_other_client_num_cb;
    } TUYA_IPC_BREAKPOINT_RESUME_T;
    
    /**
    * @brief Initialize tuya ipc breakpoint resume
    * @param[in] pbreakpoint_resume_var: init para
    * @return OPERATE_RET
    */
    OPERATE_RET tuya_ipc_breakpoint_resume_init(IN TUYA_IPC_BREAKPOINT_RESUME_T *pbreakpoint_resume_var);
    
    Parameter Description
    breakpoint_resume_enable Enable the entire module.
    pic_event_enable Enable resumable transfer of events and images.
    folder_path The storage path of the resumable data table.
    max_record_hours This is a reserved parameter, and its configuration will be enabled in future versions.
    data_file_need_backup Specifies whether to enable the backup feature for the resumable transfer table. Enabling this will increase the CPU usage. It is disabled by default.
    max_record_num The maximum number of resumable transfer data records.
    enable_intelli_resume Enable smart resumable transfer mode. The upload rate can be automatically adjusted based on actual conditions. It is disabled by default.
    max_time_for_upload_to_cloud The maximum time for uploading a single piece of data. After enable_intelli_resume is enabled, if the uploaded data exceeds this limit, it will be identified as a network error, and the upload will be automatically paused.
    speed_control_upload_enable After this parameter is enabled, the system will automatically pause uploading during active periods if other streaming or upload tasks are detected.
    check_upload_cb This callback checks whether the resumable transfer task can currently be executed.
    network_normal_cb The callback invoked when the network status is obtained. You are recommended to implement this important callback.
    cloud_data_upload_cb The callback invoked when the video is uploaded to cloud storage. You can choose not to implement this callback now.
    get_other_client_num_cb The callback invoked when the number of other streaming tasks (such as RTSP) is obtained. You can decide whether to implement it.

    Once enabled after initialization, the SDK automatically monitors and adds offline records internally. There is no need for external parties to be aware of the record-adding process.

  • Deinitialize

    /**
    * @brief Deinitialize Tuya IPC resumable transfer
    *
    * @return OPERATE_RET
    */
    OPERATE_RET tuya_ipc_breakpoint_resume_uninit();
    
  • Suspend resumable transfer

    /**
    * @brief Suspend resumable transfer service
    *
    * @return OPRT_OK on success. Others on error
    */
    OPERATE_RET tuya_ipc_breakpoint_resume_suspend();
    

    This feature can be used in scenarios such as formatting or low-power sleep mode. It suspends all tasks of the resumable transfer module and quickly writes cached data to storage.

  • Recover resumable transfer

    /**
    * @brief Recover resumable transfer service
    *
    * @return OPRT_OK on success. Others on error
    */
    OPERATE_RET tuya_ipc_breakpoint_resume_recovery();
    

    This feature must be used in conjunction with tuya_ipc_breakpoint_resume_suspend.

Things to note

  • This feature serves as a remedial measure when a device encounters network errors or upload failures. Once the network is restored, it will make every effort to upload data to the cloud. However, if the device remains in a prolonged state of network instability, the overall user experience might still be affected.
  • Enabling this feature will slightly increase read/write pressure on the storage card.
  • Its functionality is also dependent on the storage card’s condition. In cases such as storage card exceptions, data integrity cannot be guaranteed.

FAQs

What happens if the breakpoint data exceeds the set limit?

If the maximum number of breakpoint records is exceeded, the oldest data records will be overwritten.