hikvision-isup-client/include/playback.h

#ifndef PLAYBACK_H
#define PLAYBACK_H

/**
 * @file playback.h
 * @brief 录像回放管理头文件
 * 
 * 本文件定义录像回放相关的功能接口，
 * 包括回放开始、停止、数据接收等。
 */

#include "common.h"
#include "config.h"
#include "stream.h"

/* 回放状态 */
typedef enum {
    PLAYBACK_STATE_IDLE = 0,
    PLAYBACK_STATE_STARTING,
    PLAYBACK_STATE_PLAYING,
    PLAYBACK_STATE_PAUSED,
    PLAYBACK_STATE_STOPPING,
    PLAYBACK_STATE_ERROR
} PlaybackState;

/* 回放会话结构 */
typedef struct {
    int      playback_id;         /* 回放ID */
    char     device_id[MAX_DEVICE_ID]; /* 设备ID */
    int      channel;             /* 通道号 */
    PlaybackState state;          /* 回放状态 */
    
    time_t   start_time;          /* 回放开始时间 */
    time_t   end_time;            /* 回放结束时间 */
    
    int      speed;               /* 回放速度(1=正常, 2=2倍, 4=4倍...) */
    int      frame_count;         /* 已接收帧数 */
    
    StreamSession* stream;        /* 关联的流会话 */
    
    pthread_mutex_t lock;         /* 线程锁 */
    int      is_running;          /* 是否运行中 */
    
    void*    internal_handle;     /* 内部句柄 */
} PlaybackSession;

/* 回放数据回调 */
typedef void (*PlaybackDataCB)(PlaybackSession* session, StreamFrame* frame, void* user_data);

/* 回放状态回调 */
typedef void (*PlaybackStatusCB)(PlaybackSession* session, PlaybackState state, void* user_data);

/**
 * @brief 初始化回放模块
 * @return 成功返回SUCCESS, 失败返回FAILURE
 */
int playback_init(void);

/**
 * @brief 反初始化回放模块
 */
void playback_cleanup(void);

/**
 * @brief 开始录像回放
 * @param device_id 设备ID
 * @param channel 通道号
 * @param start_time 开始时间
 * @param end_time 结束时间
 * @param speed 回放速度
 * @param data_cb 回放数据回调
 * @param status_cb 回放状态回调
 * @param user_data 用户数据
 * @return 成功返回回放会话指针, 失败返回NULL
 * 
 * 说明: 发起录像回放请求。内部流程:
 *       1. 调用NET_ESTREAM_StartListenPlayBack开启SMS回放监听
 *       2. 调用NET_ECMS_StartPlayBack向设备发送回放开始请求
 *       3. 接收设备回放码流数据
 *       4. 可选: 将回放流转发到RTMP服务器
 */
PlaybackSession* playback_start(const char* device_id, int channel,
                                 time_t start_time, time_t end_time,
                                 int speed,
                                 PlaybackDataCB data_cb,
                                 PlaybackStatusCB status_cb,
                                 void* user_data);

/**
 * @brief 停止录像回放
 * @param session 回放会话指针
 * @return 成功返回SUCCESS, 失败返回FAILURE
 * 
 * 说明: 停止回放并释放资源。内部流程:
 *       1. 调用NET_ESTREAM_StopPlayBack停止码流转发
 *       2. 调用NET_ECMS_StopPlayBack向设备发送停止请求
 *       3. 调用NET_ESTREAM_StopListenPlayBack停止监听
 */
int playback_stop(PlaybackSession* session);

/**
 * @brief 暂停回放
 * @param session 回放会话指针
 * @return 成功返回SUCCESS, 失败返回FAILURE
 */
int playback_pause(PlaybackSession* session);

/**
 * @brief 恢复回放
 * @param session 回放会话指针
 * @return 成功返回SUCCESS, 失败返回FAILURE
 */
int playback_resume(PlaybackSession* session);

/**
 * @brief 获取录像文件列表
 * @param device_id 设备ID
 * @param channel 通道号
 * @param start_time 开始时间
 * @param end_time 结束时间
 * @param files 输出文件列表
 * @param max_files 最大文件数
 * @return 返回录像文件数量
 * 
 * 说明: 查询指定时间段内的录像文件列表。
 */
int playback_get_file_list(const char* device_id, int channel,
                           time_t start_time, time_t end_time,
                           char files[][MAX_PATH_SIZE], int max_files);

/**
 * @brief 下载录像文件
 * @param device_id 设备ID
 * @param channel 通道号
 * @param file_name 文件名
 * @param save_path 保存路径
 * @return 成功返回SUCCESS, 失败返回FAILURE
 */
int playback_download_file(const char* device_id, int channel,
                           const char* file_name, const char* save_path);

/**
 * @brief 获取所有活跃回放会话
 * @param sessions 输出会话指针数组
 * @param max_sessions 最大会话数
 * @return 返回活跃会话数量
 */
int playback_get_active_sessions(PlaybackSession* sessions[], int max_sessions);

/**
 * @brief 停止所有回放
 */
void playback_stop_all(void);

/**
 * @brief 按回放ID查找会话
 */
PlaybackSession* playback_get_session(int playback_id);

/**
 * @brief 获取回放会话状态
 * @param session 回放会话指针
 * @return 回放状态枚举值
 */
PlaybackState playback_get_state(PlaybackSession* session);

#endif /* PLAYBACK_H */