API参考

本文档提供了 CPP StreamDock SDK的完整API参考。

DeviceManager类

设备管理器，用于枚举和管理StreamDock设备。

静态方法

instance()

static DeviceManager& instance();

获取DeviceManager的单例实例。

返回值: DeviceManager的引用

实例方法

enumerator()

void enumerator();

枚举当前连接的StreamDock设备。

listen()

void listen(std::function<void(std::shared_ptr<StreamDock>)> connect_and_run = nullptr);

启动后台线程监听设备插拔事件。

参数:

  • connect_and_run: 可选的回调函数，当新设备连接时执行

stopListen()

void stopListen();

停止设备监听线程。

getStreamDocks()

std::unordered_map<std::string, std::shared_ptr<StreamDock>>& getStreamDocks();

获取当前所有连接的StreamDock设备。

返回值: 设备映射表，key为设备路径，value为设备对象

StreamDock类

StreamDock设备的基类，提供设备控制的基本功能。

初始化方法

init()

void init();

初始化StreamDock设备和所有内部组件。

initImgHelper()

void initImgHelper();

初始化内部图像助手（背景、按键、第二屏幕等）。

设备信息方法

getFirmwareVersion()

std::string getFirmwareVersion();

获取设备固件版本。

返回值: 固件版本字符串

info()

StreamDockInfo* info();

获取设备元数据。

返回值: StreamDockInfo指针

feature()

FeatureOption* feature();

获取支持的功能选项。

返回值: FeatureOption指针

屏幕控制方法

wakeupScreen()

virtual void wakeupScreen();

唤醒设备屏幕。

setKeyBrightness()

virtual void setKeyBrightness(uint8_t brightness);

设置设备按键亮度。

参数:

  • brightness: 亮度级别（通常0-100）

sleep()

virtual void sleep();

使设备进入睡眠模式。

refresh()

virtual void refresh();

刷新显示。

按键控制方法

clearAllKeys()

virtual void clearAllKeys();

清空所有按键图像。

clearKey()

virtual void clearKey(uint8_t keyValue);

清空指定按键的图像。

参数:

  • keyValue: 按键索引

图像设置方法

setKeyImgFile()

virtual void setKeyImgFile(const std::string& filePath, uint8_t keyValue);

从文件设置按键图像。

参数:

  • filePath: 图像文件路径
  • keyValue: 目标按键索引

setKeyImgFileStream()

virtual void setKeyImgFileStream(const std::string& stream, uint8_t keyValue);

从数据流设置按键图像。

参数:

  • stream: 图像数据流
  • keyValue: 目标按键索引

setBackgroundImgFile()

virtual void setBackgroundImgFile(const std::string& filePath, uint32_t timeoutMs = 3000);

从文件设置背景图像。

参数:

  • filePath: 图像文件路径
  • timeoutMs: 超时时间（毫秒）

setBackgroundImgStream()

virtual void setBackgroundImgStream(const std::string& stream, uint32_t timeoutMs = 3000);

从数据流设置背景图像。

参数:

  • stream: 图像数据流
  • timeoutMs: 超时时间（毫秒）

连接管理方法

disconnected()

virtual void disconnected();

断开设备连接。

heartbeat()

virtual void heartbeat();

发送心跳信号。

功能控制器方法

reader()

IReadController* reader();

获取输入读取控制器。

返回值: IReadController指针

rgber()

IRGBController* rgber();

获取RGB控制器。

返回值: IRGBController指针

gifer()

IGifController* gifer();

获取GIF动画控制器。

返回值: IGifController指针

configer()

IConfiger* configer();

获取配置控制器。

返回值: IConfiger指针

heartbeater()

IHeartBeat* heartbeater();

获取心跳控制器。

返回值: IHeartBeat指针

图像处理方法

setEncoder()

void setEncoder(std::shared_ptr<IImageEncoder> encoder);

设置图像编码器。

参数:

  • encoder: 图像编码器共享指针

getBgImgHelper()

std::shared_ptr<ImgHelper> getBgImgHelper() const;

获取背景图像助手。

返回值: ImgHelper共享指针

getKyImgHelper()

std::shared_ptr<ImgHelper> getKyImgHelper(uint16_t keyValue = 0) const;

获取按键图像助手。

参数:

  • keyValue: 按键索引

返回值: ImgHelper共享指针

静态工具方法

readImgToString()

static std::string readImgToString(const std::string& jpgPath);

读取图像文件并返回为字节流。

参数:

  • jpgPath: JPEG图像路径

返回值: 图像数据的字节字符串

isStreamDockHidDevice()

static bool isStreamDockHidDevice(const hid_device_info& device);

检查设备是否为有效的StreamDock HID设备。

参数:

  • device: HID设备信息

返回值: 如果是StreamDock设备返回true

isJpegData()

static bool isJpegData(const std::string& originData);

检查给定数据是否为JPEG编码。

参数:

  • originData: 原始数据

返回值: 如果是JPEG数据返回true

isPngData()

static bool isPngData(const std::string& originData);

检查给定数据是否为PNG编码。

参数:

  • originData: 原始数据

返回值: 如果是PNG数据返回true

readGifToStream()

static std::vector<std::vector<uint8_t>> readGifToStream(const std::string& filePath, 
                                                        std::shared_ptr<IImageEncoder> encoder, 
                                                        const ImgHelper& helper);

读取GIF文件并分割为编码的图像帧。

参数:

  • filePath: GIF文件路径
  • encoder: 图像编码器
  • helper: 图像助手

返回值: 图像帧字节数组的向量

IReadController接口

输入读取控制器，用于处理设备输入事件。

方法

read()

virtual std::vector<uint8_t> read(int32_t timeoutMs = -1) = 0;

从设备读取数据。

参数:

  • timeoutMs: 超时时间（毫秒），-1表示阻塞读取

返回值: 读取的数据向量

registerReadCallback()

virtual void registerReadCallback(uint8_t realValue, ReadCallback callback, 
                               RegisterEvent event = RegisterEvent::EveryThing, 
                               bool callbackAsync = false) = 0;

注册按键事件回调。

参数:

  • realValue: 实际按键值
  • callback: 回调函数
  • event: 事件类型
  • callbackAsync: 是否异步执行回调

unregisterReadCallback()

virtual void unregisterReadCallback(uint8_t realValue, RegisterEvent event) = 0;

取消注册按键事件回调。

参数:

  • realValue: 实际按键值
  • event: 事件类型

registerRawReadCallback()

virtual void registerRawReadCallback(RawReadCallback callback, bool callbackAsync = false) = 0;

注册原始读取回调。

参数:

  • callback: 回调函数
  • callbackAsync: 是否异步执行回调

unregisterRawReadCallback()

virtual void unregisterRawReadCallback() = 0;

取消注册原始读取回调。

startReadLoop()

virtual void startReadLoop() = 0;

启动读取循环。

stopReadLoop()

virtual void stopReadLoop() = 0;

停止读取循环。

IRGBController接口

RGB控制器，用于控制设备的LED灯光。

方法

setLedBrightness()

virtual void setLedBrightness(uint8_t brightness) = 0;

设置LED亮度。

参数:

  • brightness: 亮度级别（通常0-100）

setLedColor()

virtual void setLedColor(uint8_t red, uint8_t green, uint8_t blue) = 0;

设置LED颜色。

参数:

  • red: 红色分量（0-255）
  • green: 绿色分量（0-255）
  • blue: 蓝色分量（0-255）

resetLedColor()

virtual void resetLedColor() = 0;

重置LED颜色。

IGifController接口

GIF动画控制器，用于处理GIF动画。

方法

setKeyGifFile()

virtual void setKeyGifFile(const std::string& gifPath, uint8_t keyValue, uint16_t gifDelay = 100) = 0;

设置按键GIF文件。

参数:

  • gifPath: GIF文件路径
  • keyValue: 目标按键索引
  • gifDelay: GIF延迟（毫秒）

setKeyGifStream()

virtual void setKeyGifStream(const std::vector<std::string>& gifStream, uint8_t keyValue, uint16_t gifDelay = 100) = 0;
virtual void setKeyGifStream(const std::vector<std::vector<uint8_t>>& gifStream, uint8_t keyValue, uint16_t gifDelay = 100) = 0;

设置按键GIF数据流。

参数:

  • gifStream: GIF数据流
  • keyValue: 目标按键索引
  • gifDelay: GIF延迟（毫秒）

setBackgroundGifFile()

virtual void setBackgroundGifFile(const std::string& gifPath, int16_t background_place_x = 0, 
                                int16_t background_place_y = 0, uint16_t gifDelay = 100, 
                                uint8_t FBlayer = 0x00) = 0;

设置背景GIF文件。

参数:

  • gifPath: GIF文件路径
  • background_place_x: 背景X位置
  • background_place_y: 背景Y位置
  • gifDelay: GIF延迟（毫秒）
  • FBlayer: 帧缓冲层

startGifLoop()

virtual void startGifLoop() = 0;

启动GIF循环。

stopGifLoop()

virtual void stopGifLoop() = 0;

停止GIF循环。

TransportCWrapper类

传输层C++封装，提供HID设备操作的C++接口。

构造和析构

TransportCWrapper()

explicit TransportCWrapper(const hid_device_info& device_info);

使用设备信息初始化连接。

参数:

  • device_info: HID设备信息

~TransportCWrapper()

~TransportCWrapper();

析构函数，自动释放资源。

基础通信方法

canWrite()

bool canWrite() const;

检查设备是否可写。

返回值: 如果可写返回true

read()

void read(uint8_t* response, size_t* length, int32_t timeoutMs = -1) const;

从设备读取数据。

参数:

  • response: 输出缓冲区
  • length: 输入时为缓冲区大小，输出时为实际读取字节数
  • timeoutMs: 超时时间（毫秒）

getFirmwareVesion()

std::string getFirmwareVesion() const;

获取固件版本。

返回值: 固件版本字符串

屏幕控制方法

wakeupScreen()

void wakeupScreen() const;

唤醒屏幕。

setKeyBrightness()

void setKeyBrightness(uint8_t brightness) const;

设置按键亮度。

参数:

  • brightness: 亮度级别

refresh()

void refresh() const;

刷新显示。

sleep()

void sleep() const;

使设备进入睡眠模式。

按键控制方法

clearAllKeys()

void clearAllKeys() const;

清空所有按键。

clearKey()

void clearKey(uint8_t key_value) const;

清空指定按键。

参数:

  • key_value: 按键值

图像传输方法

setKeyImgFileStream()

void setKeyImgFileStream(const std::string& jpegData, uint8_t keyValue) const;

设置按键图像流。

参数:

  • jpegData: JPEG图像数据
  • keyValue: 目标按键索引

setBackgroundImgStream()

void setBackgroundImgStream(const std::string& jpegData, int32_t timeoutMs = 3000) const;

设置背景图像流。

参数:

  • jpegData: JPEG图像数据
  • timeoutMs: 超时时间（毫秒）

setBackgroundBitmap()

void setBackgroundBitmap(const std::string& bitmapStream, int32_t timeoutMs = 5000) const;

设置背景位图。

参数:

  • bitmapStream: 位图数据流
  • timeoutMs: 超时时间（毫秒）

LED控制方法

setLedBrightness()

void setLedBrightness(uint8_t brightness) const;

设置LED亮度。

参数:

  • brightness: 亮度级别

setLedColor()

void setLedColor(uint16_t count, uint8_t r, uint8_t g, uint8_t b) const;

设置LED颜色。

参数:

  • count: LED数量
  • r: 红色分量
  • g: 绿色分量
  • b: 蓝色分量

resetLedColor()

void resetLedColor() const;

重置LED颜色。

K1 Pro 键盘控制方法

以下方法专用于 K1 Pro 设备的键盘控制功能：

setKeyboardBacklightBrightness()

void setKeyboardBacklightBrightness(uint8_t brightness) const;

设置键盘背光亮度。

参数:

  • brightness: 亮度值 (0-6)

setKeyboardLightingEffects()

void setKeyboardLightingEffects(uint8_t effect) const;

设置键盘灯光效果。

参数:

  • effect: 效果模式标识符 (0-9)，0 为静态灯光

setKeyboardLightingSpeed()

void setKeyboardLightingSpeed(uint8_t speed) const;

设置键盘灯光效果速度。

参数:

  • speed: 灯光效果速度值 (0-7)

setKeyboardRgbBacklight()

void setKeyboardRgbBacklight(uint8_t r, uint8_t g, uint8_t b) const;

设置键盘RGB背光颜色。

参数:

  • r: 红色分量 (0-255)
  • g: 绿色分量 (0-255)
  • b: 蓝色分量 (0-255)

keyboardOsModeSwitch()

void keyboardOsModeSwitch(uint8_t osMode) const;

设置键盘OS模式。

参数:

  • osMode: OS模式标识符（Windows/Mac）

连接管理方法

disconnected()

void disconnected() const;

断开连接。

heartbeat()

void heartbeat() const;

发送心跳包。

静态方法

disableOutput()

static void disableOutput(bool isDisable = true);

禁用底层输出。

参数:

  • isDisable: 是否禁用输出

枚举类型

RegisterEvent

注册事件类型，用于指定回调函数触发的事件类型。

enum class RegisterEvent {
    EveryThing,    // 所有事件
    KeyPress,      // 按键按下
    KeyRelease,    // 按键释放
    KnobLeft,      // 旋钮左转
    KnobRight,     // 旋钮右转
    KnobPress,     // 旋钮按下
    KnobRelease,   // 旋钮释放
    SwipeLeft,     // 左滑
    SwipeRight,    // 右滑
    ToggleUp,      // 开关向上
    ToggleDown     // 开关向下
};

DeviceOriginType

设备原始类型，用于标识不同的StreamDock设备型号。

enum class DeviceOriginType {
    SD293,         // StreamDock 293
    SD293s,        // StreamDock 293s
    SDN1,          // StreamDock N1
    SDN3,          // StreamDock N3
    SDN4,          // StreamDock N4
    SDN4Pro,       // StreamDock N4Pro
    SDM3,          // StreamDock M3
    SDM18,         // StreamDock M18
    SDXL,          // StreamDock XL
    SDK1Pro        // K1 Pro
};

回调函数类型

ReadCallback

按键事件回调函数类型。

using ReadCallback = std::function<void()>;

RawReadCallback

原始读取回调函数类型。

using RawReadCallback = std::function<void(const std::vector<uint8_t>&)>;
Last Updated:
Contributors: JKWTCN