Skip to content

J
jensen
Commit 3e0e948c authored by martin hou's avatar martin hou
Browse files
Options

docs: 增加API功能说明

parent fc068882
Hide whitespace changes
Inline Side-by-side
Showing with 164 additions and 34 deletions
jensen.d.ts
View file @ 3e0e948c
// 设备信息
export type DeviceInfo = {
sn: string;
versionNumber: number;
versionCode: string;
sn: string; // 设备SN号
versionNumber: number; // 固件版本号数字表示，如1.2.3的值就是0x010203
versionCode: string; // 固件版本号的字符串表示，如1.2.3
};
// 常规指令的应答结构，表示指令的结果是成功或是失败
export type ReturnStruct = {
common: { result: 'failed' | 'success' };
};
// 提示音更新应答
export type ToneUpdateResponse = {
code: number;
result: string;
code: number; // 错误码，0表示成功，1/2/3/4分别表示length-mismatch/busy/card-full/card-error
result: string; // 错误码的文本表示，与上面的0/1/2/3/4一一对应
}
// UAC更新应答
export type UACUpdateResponse = {
code: number;
result: string;
code: number; // 错误码，0表示成功，1/2/3/4分别表示length-mismatch/busy/card-full/card-error
result: string; // 错误码的文本表示，与上面的0/1/2/3/4一一对应
}
// 文件信息
export type FileInfo = {
name: string;
createDate: string;
createTime: string;
time: Date;
duration: number;
length: number;
signature: string;
name: string; // 文件名称
createDate: string; // 录音日期，yyyy-MM-dd部分
createTime: string; // 录音时间，HH:mm:ss部分
time: Date; // 录音时间
duration: number; // 持续时长，单位为毫秒
length: number; // 文件长度，单位为字节
signature: string; // 文件签名，0长度的文件或是录音中的文件的值为000000000000000000000000000000000
};
// 蓝牙状态
export type BluetoothStatus = {
status: string;
mac?: string;
name?: string;
a2dp?: boolean;
hfp?: boolean;
avrcp?: boolean;
battery?: number;
status: string; // 状态，connected或者disconnected表示是否有连接的设备
mac?: string; // 当前连接的设备MAC地址
name?: string; // 当前连接的设备名称
a2dp?: boolean; // 是否支持A2DP特性
hfp?: boolean; // 是否支持HFP
avrcp?: boolean; // 是否支持AVRCP
battery?: number; // 被连接上的蓝牙耳机的电池电量
};
// 蓝牙设备信息
export type BluetoothDevice = {
name: string;
mac: string;
name: string; // 设备名称
mac: string; // 设备MAC地址
};
// 操作系统枚举
export const enum OS {
Windows = 'Windows',
Linux = 'Linux',
Mac = 'Mac'
}
// 会议平台枚举
export const enum Platform {
zoom = 'zoom',
teams = 'teams',
......@@ -62,97 +71,218 @@ export const enum Platform {
discord = 'discord'
}
// 日历行程信息
export type ScheduleInfo = {
startDate: Date;
endDate: Date;
os: OS;
platform: Platform;
startDate: Date; // 开始时间(注意是时间)
endDate: Date; // 结束时间
os: OS; // 操作系统
platform: Platform; // 会议软件平台
};
// 日志级别枚举
export enum Level {
debug = 'debug',
info = 'info',
error = 'error'
}
// 日志条目信息
export type Log = {
level: Level;
module: string;
procedure: string;
message: string;
time: number;
level: Level; // 级别，如info/debug/error
module: string; // 日志发生时所处的模块
procedure: string; // 日志发生时所处的过程
message: string; // 日志详情
time: number; // 日志发生时间的时间戳
};
// 日志记录管理
export type Logger = {
// 历史日志条目，有最大保留数量上限
messages: Log[];
// 是否开启控制台输出
consoleOutput: boolean;
// 分级日志记录
info(module: string, procedure: string, message: string): void;
debug(module: string, procedure: string, message: string): void;
error(module: string, procedure: string, message: string): void;
_append(level: Level, module: string, procedure: string, message: string): void;
_print(log: Log): void;
// 过滤查找
filter(module: string, procedure: string): void;
// 启停控制台输出
enableConsoleOutput(): void;
disableConsoleOutput(): void;
// 查看最后rows条记录
peek(rows: number): void;
// 按照module和procedure、keyword搜索日志
search(module: string, procedure: string, keyword: string): Log[];
};
// HiDock连接及协议交互类实现
// 构造方法增加了conn参数，用于兼容单设备连接和多设备连接时的过渡
// 以后会只保留多设备连接，也就是USBDevice实例由外部的代码进行管理，Jensen类只负责收发消息和消息的处理
declare class Jensen {
// 构造方法，logger为外部传入的全局共用的Logger实例；如果传入了conn，就表示连接管理交由外部代码管理
constructor(log?: Logger, conn?: USBDevice);
// 连接初始化，不需要显式调用
init: () => Promise<boolean>;
// 连接初始化（多连接时适用）
initialize: () => Promise<boolean>;
// 发起连接设备请求（单连接时适用）
connect: () => Promise<void>;
// 事件：当连接完成时触发
onconnect: () => void;
// 主动断开连接（单连接时适用）
disconnect: () => void;
// 事件：当连接断开时触发
ondisconnect?: () => void;
// 连接重置（多连接时适用）
reconnect: () => Promise<boolean>;
// 是否停止连接检查（OTA更新时使用）
isStopConnectionCheck: boolean;
// 是否已连接
isConnected: () => boolean;
// 获取当前连接的设备型号，如hidock-h1/hidock-h1e/hidock-p1/hidock-p1:mini等
getModel: () => string;
// 尝试自动连接（单连接时适用）
tryconnect: (disableOnConnect?: boolean) => Promise<boolean>;
// ----------------------------------------------------------------------------
// 从此处往下全部是与设备通信的消息指令实现
// 获取设备信息
getDeviceInfo: (time?: number) => Promise<DeviceInfo>;
// 列出设备录音文件
listFiles: (time?: number) => Promise<FileInfo[]>;
// 获取录音文件内容
// #fileName 为文件名称
// #length 文件长度
// #on 回调为当数据准备好时调用，如果传输失败会传递fail过来
// #onprogress 回调为传输时进度发生变化时调用
// 注意：文件传输进度和数据并不是同时到达的，在文件传输到100%时才会开始调用on回调进行转移数据
getFile: (fileName: string, length: number, on?: (msg: Uint8Array | 'fail') => void, onprogress?: (size: number) => void) => void;
// 获取指定长度的录音文件内容，length参数可以小于或等于文件的原始长度，其它参数与getFile()方法一致
getFilePart: (fileName: string, length: number, on?: (msg: Uint8Array | 'fail') => void, onprogress?: (size: number) => void) => void;
// 暂不使用
getFileBlock: (fileName: string, length: number, on?: (msg: Uint8Array | 'fail') => void) => Promise<ReturnStruct['common']>;
requestFirmwareUpgrade: (vn: number, length: number, time?: number) => Promise<{ result: 'accepted' | 'fail' }>;
// 请求固件更新
// #versionNumber 新固件的版本号
// #length 新固件的内容长度
// #time 超时时长
requestFirmwareUpgrade: (versionNumber: number, length: number, time?: number) => Promise<{ result: 'accepted' | 'fail' }>;
// 发送新固件内容到设备端
// #data 为固件数据内容
// #seconds 为超时时长
// #onProgress 为进度回调
uploadFirmware: (data: number[], seconds?: number, onProgress?: (cur: number, total: number) => void) => Promise<ReturnStruct['common']>;
// 开始BNC体验
beginBNC: (time?: number) => Promise<ReturnStruct['common']>;
// 停止BNC体验
endBNC: (time?: number) => Promise<ReturnStruct['common']>;
// 设置设备时间
setTime: (date: Date, timeout?: number) => Promise<ReturnStruct['common']>;
// 删除文件
deleteFile: (fileName: string) => Promise<{ result: 'failed' | 'success' | 'not-exists' }>;
uploadFirmware: (data: number[], seconds?: number, onProgress?: (cur: number, total: number) => void) => Promise<ReturnStruct['common']>;
// 获取设备时间
getTime: (time?: number) => Promise<{ time: string }>;
// 获取设备设置项，注意：不同型号的设备有不同的设置项
getSettings: (time?: number) => Promise<{ autoRecord: boolean; autoPlay: boolean; notification?: boolean } | null>;
// 设备Auto Record开关
setAutoRecord: (enable: boolean, time?: number) => Promise<ReturnStruct['common']>;
// 设置Recording Notification提示音开关，录音开始时是否播放Start Recording
setAutoPlay: (enable: boolean, time?: number) => Promise<ReturnStruct['common']>;
// 设置WebUSB设备接入提示（Windows电脑右下角的弹窗）
setNotification: (state: boolean, time?: number) => Promise<ReturnStruct['common']>;
// 获取录音中的文件信息，当它从null -> non-null -> null转变时就表示已经有一个新的录音产生了
getRecordingFile: () => Promise<{ recording: null | string; createTime: string; createDate: string }>;
// 获取内部存储卡信息
// used：已使用，capacity：总容量（单位为M），status：900表示正常，其它表示异常
getCardInfo: (seconds?: number) => Promise<{ used: number; capacity: number; status: string }>;
// 内部存储卡格式化
formatCard: (seconds?: number) => Promise<ReturnStruct['common']>;
// 恢复出厂设置，MTT阶段添加，不建议使用
factoryReset: (seconds?: number) => Promise<ReturnStruct['common']>;
// 恢复出厂设置，内部存储格式化，设置项恢复默认值，蓝牙配对信息清空等
restoreFactorySettings: (seconds?: number) => Promise<ReturnStruct['common']>;
// 获取设备录音文件数量
getFileCount: (seconds?: number) => Promise<{ count: number } | null>;
// 录音测试，MTT阶段使用，不应该在HiNotes上使用
recordTestStart: (type: number, seconds?: number) => Promise<ReturnStruct['common']>;
recordTestEnd: (type: number, seconds?: number) => Promise<ReturnStruct['common']>;
// 测试消息，用于确定是否能够正常通信，已作废
test: (seconds?: number) => Promise<ReturnStruct['common']>;
// 设置蓝牙提示音开关
setBluetoothPromptPlay: (state: boolean, seconds?: number) => Promise<ReturnStruct['common']>;
// 写入/更新设备内SN号
writeSerialNumber: (sn: string) => Promise<ReturnStruct['common']>;
// 发送会议日程信息，设备将在指定的时间上去模拟会议软件的按键，来实现对接听和挂断的兼容
sendScheduleInfo: (info: ScheduleInfo[]) => Promise<ReturnStruct['common']>;
// 扫描蓝牙设备，此方法大约需要30秒才有返回，需要做好等待提示
scanDevices: (seconds?: number) => Promise<BluetoothDevice[]>;
// 连接到指定的蓝牙设备
connectBTDevice: (mac: string, seconds?: number) => Promise<ReturnStruct['common']>;
// 断开已连接的蓝牙设备
disconnectBTDevice: (seconds?: number) => Promise<ReturnStruct['common']>;
// 获取蓝牙连接状态
getBluetoothStatus: (seconds?: number) => Promise<BluetoothStatus>;
// 获取实时音频流的设置信息，主要是确定设备端的实时音频的编码信息
getRealtimeSettings: () => Promise<any>;
// 开始实时音频流传输
startRealtime: () => Promise<ReturnStruct['common']>;
// 暂停实时音频流传输
pauseRealtime: () => Promise<ReturnStruct['common']>;
// 停止/结束实时音频流传输
stopRealtime: () => Promise<ReturnStruct['common']>;
// 获取实时音频流数据
getRealtime: (frames: number) => Promise<{ data: Uint8Array; rest: number }>;
// 录音文件随机读取，从指定位置起读取指定数量个字节
readFile: (fname: string, offset: number, length: number) => Promise<Uint8Array>;
// 请求设备提示音更新
requestToneUpdate: (signature: string, size: number, seconds?: number) => Promise<ToneUpdateResponse>;
// 更新设备提示音
updateTone: (data: Uint8Array, seconds?: number) => Promise<ReturnStruct['common']>;
// 请求设备UAC固件更新
requestUACUpdate: (signature: string, size: number, seconds?: number) => Promise<UACUpdateResponse>;
// 更新设备UAC固件
updateUAC: (data: Uint8Array, seconds?: number) => Promise<ReturnStruct['common']>;
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment