文档转码功能

通过阅读本章节,您将了解文档转码的相关功能与使用方法。文档转码功能可以实现将PPT、PPTX、PDF等文档格式转码为png及jpg格式,借助互动白板进行实时翻页、标注与共享展示,支持在 Web端、PC 端提交文件转码任务,将 ppt 和 pdf 等文档转码为各种清晰度的图片存储在云端,再在各客户端获取、下载使用或者删除转码后的文档。SDK提供文档上传(PC/Web)、下载、删除、查询等文档使用中的各类功能接口。

注册文档转码通知回调

API介绍

注册文档转换的结果的回调通知。服务器转码完成或有结果时,会通知客户端,通过此接口得到文档转码结果。

API原型

参数说明

参数 类型 说明
cb function 回调函数
参数 类型 说明
cb function 回调函数
code int 结果错误码
info object 文档信息
参数 类型 说明
cb function 回调函数
json_extension string 无效扩展字段
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理

返回值说明

无返回值。

回调结果:带错误码及文档信息。

枚举定义 说明
kNIMDocTransFailFlagSuccess 0 正常
kNIMDocTransFailFlagNotExist 2 找不到文件
kNIMDocTransFailFlagFileTypeErr 3 文件类型错误
kNIMDocTransFailFlagRequstErr 4 转码请求出现异常
kNIMDocTransFailFlagLinkErr 5 转码服务器连接错误
kNIMDocTransFailFlagServerErr 6 转码服务器内部错误
kNIMDocTransFailFlagPicErr 7 文档转码图片出错
kNIMDocTransFailFlagQualityErr 8 图片质量处理错误
kNIMDocTransFailFlagPageLimit 9 页数超限
kNIMDocTransFailFlagNosErr 10 nos回调错误
kNIMDocTransFailFlagDocParseErr 11 文档解析出错
kNIMDocTransFailFlagUnknown 100 表示未知错误

示例

文档上传

API介绍

转码文档上传接口。通过扩展的上传文件上传转码文件到服务器。如果上传成功,则等待结果通知。

API原型

参数说明

参数 类型 说明
local_file string 本地文件的完整路径,路径名必须是utf-8
json_extension string Json 扩展参数
callback_result function 上传的结果回调函数
callback_progress function 上传进度的回调函数
callback_speed function 上传速度的回调函数
callback_transfer function 返回最终上传信息的回调函数
参数 类型 说明
localFile string 本地文件的完整路径,路径名必须是utf-8
param string 扩展参数
resCb function 上传的结果回调函数
resData IntPtr APP的自定义用户数据,SDK只负责传回给回调函数resCb,不做任何处理!
prgCb function 上传进度的回调函数
prgData IntPtr APP的自定义用户数据,SDK只负责传回给回调函数prgCb,不做任何处理!
speedCb function 上传速度的回调函数
speedData IntPtr APP的自定义用户数据,SDK只负责传回给回调函数speedCb,不做任何处理!
infoCb function 返回最终上传信息的回调函数
infoData IntPtr APP的自定义用户数据,SDK只负责传回给回调函数infoCb,不做任何处理!
参数 类型 说明
local_file string 本地文件的完整路径,路径名必须是utf-8
json_extension string Json 扩展参数
res_cb function 上传的结果回调函数
res_user_data IntPtr APP的自定义用户数据,SDK只负责传回给回调函数res_cb,不做任何处理!
prg_cb function 上传进度的回调函数
prg_user_data IntPtr APP的自定义用户数据,SDK只负责传回给回调函数prg_cb,不做任何处理!
speed_cb function 上传速度的回调函数
speed_user_data IntPtr APP的自定义用户数据,SDK只负责传回给回调函数speed_cb,不做任何处理!
info_cb function 返回最终上传信息的回调函数
info_user_data IntPtr APP的自定义用户数据,SDK只负责传回给回调函数info_cb,不做任何处理!
键常量名 键常量值 值类型 说明
kNIMNosLowLimit low_limit int HTTP通用配置,传输速度,每秒字节数(默认10)
kNIMNosLowTime low_time int HTTP通用配置,传输过程中当low_time秒时间内传输速度小于low_limit时(字节每秒),下载任务会返回超时而取消(默认60)
kNIMNosTimeout timeout int HTTP通用配置,超时时间,单位ms,下载时最小10000,上传时最小30000,不设置默认30000
kNIMNosTaskId task_id string HTTP通用配置,任务ID,上传下载断点续传必填,如果传入的ID是曾经未完成的需要续传功能的传输任务的ID,则会开始续传(用户需要保证ID的唯一性)
kNIMNosNeedContinueTrans continue_trans bool HTTP通用配置,任务是否需要续传功能
kNIMNosFileSize download_filesize int64 HTTP下载任务的文件大小,需要续传功能必填,单位Byte,其他情况不需要填
kNIMNosSaveAsFilePath saveas_filepath string HTTP下载任务的文件存放本地路径,不填则默认路径回调中返回
kNIMNosUploadType upload_type int NIMNosUploadType HTTP上传任务的类型
kNIMNosDocTransName name string (HTTP上传转码文档使用)名称
kNIMNosDocTransSourceType source_type int NIMDocTranscodingFileType (HTTP上传转码文档使用)转码源文档的文件类型
kNIMNosDocTransPicType pic_type int NIMDocTranscodingImageType (HTTP上传转码文档使用)转码目标图片的文件类型
kNIMNosDocTransExt doc_trans_ext string (HTTP上传转码文档使用)文档转换时的扩展参数,在成功后能查询到
kNIMNosResId res_id string 上传文件的id,如果是文档转换则为服务器的文档id
kNIMNosCallId call_id string 上传文件的会话id
枚举定义 说明
kNIMDocTranscodingFileTypePPT 1 ppt文档
kNIMDocTranscodingFileTypePPTX 2 pptx文档
kNIMDocTranscodingFileTypePDF 3 pdf文档
枚举定义 说明
kNIMDocTranscodingImageTypeJPG 10 转码为 jpg 图片
kNIMDocTranscodingImageTypePNG 11 转码为 png 图片
枚举定义 说明
kNIMDocTranscodingQualityHigh 1 高清转码质量
kNIMDocTranscodingQualityMedium 2 中等转码质量
kNIMDocTranscodingQualityLow 3 低清转码质量

返回值说明

返回接口调用结果。

无返回值

示例

        NIM.Nos.NosAPI.UploadEx(filePath,params, ResultCb, Marshal.StringToHGlobalAnsi("UploadResult"),
        ReportPrg, Marshal.StringToHGlobalAnsi("UploadProgress"),
        ReportSpeed, Marshal.StringToHGlobalAnsi("UploadSpeed"),
        ReportInfo, Marshal.StringToHGlobalAnsi("UploadInfo"));
    }

    private void ReportInfo(long actual_upload_size, long upload_speed, string json_extension, IntPtr user_data)
    {
        //TODO:上传信息
    }

    private void ReportPrg(long uploaded_size, long file_size, string json_extension, IntPtr user_data)
    {
        //TODO:上传进度    
    }

    private void ReportSpeed(long upload_speed, string json_extension, IntPtr user_data)
    {
        //TODO:上传速度
    }

    private void ResultCb(int rescode, string url, string json_extension, IntPtr user_data)
    {
        //TODO:上传结果
    }

    //停止上传,taskId 为调用 UploadEx 时传入的参数,参考 HttpExtendedParameters
    NIM.Nos.NosAPI.StopUploadEx(string taskId, string ext = null)
    //发起上传任务
    void foo_start_http_download(const std::string& task_uuid)
    {
        Json::FastWriter writer;
        Json::Value value;
        value[kNIMNosLowLimit] = ; //int(选填) HTTP通用配置,传输速度,每秒字节数(默认10)
        value[kNIMNosLowTime] = ;  //int(选填) HTTP通用配置,传输过程中当low_time秒时间内传输速度小于low_limit时(字节每秒),下载任务会返回超时而取消(默认60)
        value[kNIMNosTimeout] = ;  //int(选填) HTTP通用配置,超时时间,单位ms,下载时最小10000,上传时最小30000,不设置默认30000
        value[kNIMNosNeedContinueTrans] = ; //bool 需要支持断点续传True
        value[kNIMNosTaskId] = task_uuid;   //string(断点续传必填) HTTP通用配置,任务ID,如果传入的ID是曾经未完成的传输任务,则会开始续传(用户需要保证ID的唯一性)
        //文档传输独有
        value[nim::kNIMNosUploadType] = nim::kNIMNosUploadTypeDocTrans;
        value[nim::kNIMNosDocTransName] = file_name;
        value[nim::kNIMNosDocTransSourceType] = (nim::NIMDocTranscodingFileType)file_type;
        value[nim::kNIMNosDocTransPicType] = nim::kNIMDocTranscodingImageTypePNG;
        value[nim::kNIMNosDocTransExt] = "";

        nim_nos_upload_ex func = (nim_nos_upload_ex) GetProcAddress(hInst, "nim_nos_upload_ex");
        func(local_file.c_str(), writer.write(value).c_str(), &CallbackUploadEx, callback_result_userdata, &CallbackProgressEx, callback_progress_pointer, &CallbackSpeed, callback_speed_pointer, &CallbackTransferInfo, callback_transfer_pointer);
    }    

    //暂停上传任务
    void foo_pause_http_upload(const std::string& task_uuid)
    {
        nim_nos_stop_upload_ex func = (nim_nos_stop_upload_ex) GetProcAddress(hInst, "nim_nos_stop_upload_ex");
        func(task_uuid.c_str(), nullptr);
    }

文档下载

API介绍

文件下载接口。通过拼接得到的页面或者源文件的url,下载文件。

API原型

参数说明

参数 类型 说明
nos_url string 文件的下载链接
json_extension string Json 扩展参数
callback_result function 下载的结果回调函数
callback_progress function 下载进度的回调函数
callback_speed function 下载速度的回调函数
callback_transfer function 返回最终下载信息的回调函数
参数 类型 说明
nosUrl string 文件的下载链接
param string 扩展参数
resCb function 下载的结果回调函数
resData IntPtr APP的自定义用户数据,SDK只负责传回给回调函数resCb,不做任何处理!
prgCb function 下载进度的回调函数
prgData IntPtr APP的自定义用户数据,SDK只负责传回给回调函数prgCb,不做任何处理!
speedCb function 下载速度的回调函数
speedData IntPtr APP的自定义用户数据,SDK只负责传回给回调函数speedCb,不做任何处理!
infoCb function 返回最终下载信息的回调函数
infoData IntPtr APP的自定义用户数据,SDK只负责传回给回调函数infoCb,不做任何处理!
参数 类型 说明
nos_url string 文件的下载链接
json_extension string Json 扩展参数
res_cb function 下载的结果回调函数
res_user_data IntPtr APP的自定义用户数据,SDK只负责传回给回调函数res_cb,不做任何处理!
prg_cb function 下载进度的回调函数
prg_user_data IntPtr APP的自定义用户数据,SDK只负责传回给回调函数prg_cb,不做任何处理!
speed_cb function 下载速度的回调函数
speed_user_data IntPtr APP的自定义用户数据,SDK只负责传回给回调函数speed_cb,不做任何处理!
info_cb function 返回最终下载信息的回调函数
info_user_data IntPtr APP的自定义用户数据,SDK只负责传回给回调函数info_cb,不做任何处理!

返回值说明

无返回值。

示例

拉取文档转码信息列表

API介绍

获取自己的文档列表信息。

API原型

参数说明

参数 类型 说明
id string 查询的起始docId,若为空,表示从头开始查找,按照文档转码的发起时间降序排列
limit int 查询的文档的最大数目,有最大值限制,目前为30
json_extension string 无效扩展字段
cb function 回调函数
参数 类型 说明
id string 查询的起始docId,若为空,表示从头开始查找,按照文档转码的发起时间降序排列
limit int 查询的文档的最大数目,有最大值限制,目前为30
cb function 回调函数
参数 类型 说明
id string 查询的起始docId,若为空,表示从头开始查找,按照文档转码的发起时间降序排列
limit int 查询的文档的最大数目,有最大值限制,目前为30
cb function 回调函数
json_extension string 无效扩展字段
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理
键常量名 键常量值 值类型 说明
kNIMDocTransCount count int 计数
kNIMDocTransInfos infos key 分页获取时文档信息列表的key
kNIMDocTransId id string 标识ID
kNIMDocTransName name string 转码文档名称
kNIMDocTransSourceType source_type int 转码源文档的文件类型NIMDocTranscodingFileType
kNIMDocTransSize size int64 文件大小
kNIMDocTransPicType pic_type int 转码目标图片的文件类型NIMDocTranscodingImageType
kNIMDocTransState state int 转码过程状态NIMDocTranscodingState
kNIMDocTransUrlPrefix url_prefix string 转码后的下载地址前缀
kNIMDocTransPageNum page_num int 转码文档总页数
kNIMDocTransExt ext string 发起文档转码时的附带信息
kNIMDocTransFlag flag int 错误原因NIMDocTranscodingFailFlag,kNIMDocTranscodingStateFailed时有效
kNIMDocTransPicInfo pic_info key 图片信息的key;用于描述各个分辨率的信息
kNIMDocTransQuality quality int 转码图像清晰度
kNIMDocTransWidth width int 图片宽度
kNIMDocTransHeight height int 图片宽度
kNIMDocTransFilePath file_path string 上传文件的路径
kNIMDocTransUploadStatus upload_status int 文件续传状态NIMDocContinueUploadState
枚举定义 说明
kNIMDocContinueUploadNone 0 没有进行过上传
kNIMDocContinueUploading 1 文件续传中
kNIMDocContinueUploadFailed 2 文件续传失败
kNIMDocContinueUploadCompleted 3 文件续传完成
枚举定义 说明
kNIMDocTranscodingStatePreparing = 1 转码准备中
kNIMDocTranscodingStateOngoing = 2 转码进行中
kNIMDocTranscodingStateTimeout = 3 转码超时
kNIMDocTranscodingStateCompleted = 4 转码完成
kNIMDocTranscodingStateFailed = 5 转码失败

返回值说明

无返回值。

示例

查询文档转码信息

API介绍

查询文档信息接口。通过此接口可以得到文档的状态,已经转码成功的文档,可以在信息中得到详细信息,并通过拼接接口得到某一页的链接地址。

API原型

参数说明

参数 类型 说明
id string 查询的docId
limit int 查询的文档的最大数目,有最大值限制,目前为30
json_extension string 无效扩展字段
cb function 回调函数
参数 类型 说明
id string 查询的docId
cb function 回调函数
参数 类型 说明
id string 查询的docId
limit int 查询的文档的最大数目,有最大值限制,目前为30
cb function 回调函数
json_extension string 无效扩展字段
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理

返回值说明

无返回值。

示例

拼接文档源的下载地址

API介绍

获取文档源文件链接地址接口。通过查询得到的文档信息,可以用此接口拼接得到文档源的链接地址。

API原型

参数说明

参数 类型 说明
url_prefix string 文档信息中的url前缀
file_type int 文档类型NIMDocTranscodingFileType

返回值说明

返回文档源的下载地址,C接口需要上层调用nim_global.h提供的内存释放接口释放。

示例

拼接文档图片的下载地址

API介绍

获取文档页链接地址接口。通过查询得到的文档信息,可以用此接口拼接得到文档页的链接地址。

API原型

参数说明

参数 类型 说明
url_prefix string 文档信息中的url前缀
imgType enum 图片类型NIMDocTranscodingImageType
quality int 清晰度等级NIMDocTranscodingQuality
pageNum int 文档类型页码
参数 类型 说明
url_prefix string 文档信息中的url前缀
img_type int 图片类型NIMDocTranscodingImageType
quality int 清晰度等级NIMDocTranscodingQuality
page_num int 文档类型页码

返回值说明

返回文档页的下载地址,C接口需要上层调用nim_global.h提供的内存释放接口释放。

示例

删除云端的转码文档

API介绍

删除云端转码文档接口。

API原型

参数说明

参数 类型 说明
id string 文档id
json_extension string 无效扩展
cb function 回调函数
参数 类型 说明
id string 文档id
cb function 回调函数
参数 类型 说明
id string 文档id
json_extension string 无效扩展
cb function 回调函数
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理

返回值说明

无返回值。

示例