Skip to content
DemoFAQ

PDF 生成模板编辑器

开源可视化 PDF 生成引擎,支持自定义模板,并提供面向开发者的 API,灵活构建文档生成流程。

查看 GitHub

应用许可证密钥 — C ​

应用许可证密钥 ​

如果您还没有获取许可证密钥,请查看如何获取许可证密钥。

ComPDFKit 转换 SDK 目前支持离线认证的方式验证许可证密钥。

了解关于:

 复制许可证密钥

正确获取许可证密钥,是许可证应用的关键。

  1. 在您收到的邮件中,找到包含许可证密钥的XML文件
  2. 打开 XML 文件,通过 <type> 字段判断许可证类型,如果是 <type>online</type> 则为在线许可证, <type>offline</type> 或无该字段则为离线许可证。

在线许可证:

xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<license version="1">
    <platform>windows</platform>
    <starttime>xxxxxxxx</starttime>
    <endtime>xxxxxxxx</endtime>
    <type>online</type>
    <key>LICENSE_KEY</key>
</license>

离线许可证:

xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<license version="1">
    <platform>windows</platform>
    <starttime>xxxxxxxx</starttime>
    <endtime>xxxxxxxx</endtime>
    <key>LICENSE_KEY</key>
</license>
  1. 复制<key>LICENSE_KEY</key>字段中的LICENSE_KEY

 应用许可证密钥

在您的项目中使用 ComPDFKit Conversion SDK 的类和方法之前,您需要先应用 License(许可证密钥)初始化该 SDK。

c
// 引入头文件。
#include "compdf_common_c.h"
#include "compdf_conversion_c.h"

// 验证 license。
const char* license = "LICENSE_KEY";
CSDKErrorCode code = CPDF_LicenseVerify(license, "device_id", "app_id");
if (code != e_CErrSuccess) {
    return code;
}

// 初始化转档资源,参数为 SDK 包内 resource 目录的路径。
CPDF_Initialize(CPDF_TEXT("ComPDF_Conversion_SDK/resource"));

 查询授权类型

授权验证成功后,可以调用 CPDF_GetLicenseType 查询当前已验证的授权类型。该接口不会重新验证授权,也不消耗页数额度。

返回值含义
e_CLicenseUnknown(0)尚未验证授权、验证失败,或 SDK 正在释放
e_CLicenseTrial(1)试用授权
e_CLicenseFormal(2)正式授权
c
CLicenseType type = CPDF_GetLicenseType();
if (type == e_CLicenseTrial) {
    // 试用授权。
}

 C 接口约定

头文件

头文件说明
compdf_common_c.h许可证验证、初始化、资源释放、页数、版本以及 DocumentAI 模型配置。
compdf_conversion_c.h文档转换接口。
compdf_basictypes_c.h错误码、转换选项、图片类型、OCR 语言等公共 C 类型。

路径字符串类型

大部分文件路径参数的类型为 COMPDFKIT_STRING:Windows 上为 const wchar_t*(例如 L"input.pdf"),Linux 和 macOS 上为 UTF-8 编码的 const char*。为便于跨平台,本指南的示例使用以下辅助宏(由本指南定义,不是 SDK 提供的接口,可按需复制到您的工程中):

c
#if defined(_WIN32)
#define CPDF_TEXT(text) L##text
#else
#define CPDF_TEXT(text) text
#endif

CPDF_LicenseVerify 例外:其 license、device_id、app_id 参数始终为 const char*。

转换选项初始化

CConvertOption 是普通的 C 结构体,没有构造函数,使用前必须初始化。推荐直接使用头文件提供的默认值宏:

c
CConvertOption option = CPDF_CONVERT_OPTION_DEFAULT;

本指南的示例使用以下辅助函数(由本指南定义,不是 SDK 提供的接口),它返回与 CPDF_CONVERT_OPTION_DEFAULT 相同的默认值:

c
static CConvertOption CPDF_DefaultConvertOption(void)
{
    CConvertOption option = CPDF_CONVERT_OPTION_DEFAULT;
    return option;
}

注意: 如果使用 memset 或 {0} 将 CConvertOption 清零,table_recognition_accuracy 会是 0,即 e_CHighAccuracy,而默认值为 e_CBalanced。清零初始化时请显式设置您依赖的每个选项。

接口一览

compdf_common_c.h:

接口说明
CSDKErrorCode CPDF_LicenseVerify(const char* license, const char* device_id, const char* app_id)验证许可证,返回 e_CErrSuccess 表示成功。见 2.4.2 应用许可证密钥。
CLicenseType CPDF_GetLicenseType(void)查询当前已验证的授权类型,不重新验证、不消耗额度。见 2.4.4 查询授权类型。
void CPDF_Initialize(COMPDFKIT_STRING resource_path)初始化 SDK,resource_path 为 SDK 包内 resource 目录的路径。须在调用转换接口之前调用。
void CPDF_SetLogger(bool enable_info, bool enable_warning)设置日志级别:enable_info 为 true 时输出 info、warning 和 error 日志;否则 enable_warning 为 true 时输出 warning 和 error 日志;两者均为 false 时只输出 error 日志。
CSDKErrorCode CPDF_SetDocumentAIModel(COMPDFKIT_STRING model_path, int gpu_id)加载 DocumentAI 模型包,并与已加载的能力合并。gpu_id 为使用的 GPU 编号,-1 表示不使用 GPU。model_path 为空时返回 e_CErrInvalidArg;转换任务进行中或释放尚未完成时返回 e_CErrConverting。见 3.7.4。
void CPDF_SetDocumentAIModelCount(int layout_model_count, int table_model_count)设置版面分析模型与表格识别模型的实例数。请在开始转换之前调用;转换任务进行中或释放尚未完成时调用会被忽略。
void CPDF_ReleaseDocumentAIModel(void)释放已加载的全部 DocumentAI 模型。之后再使用 AI 功能需要重新调用 CPDF_SetDocumentAIModel。
int CPDF_GetPageCount(COMPDFKIT_STRING file_path, COMPDFKIT_STRING password)返回 PDF 文件的页数。文件无法打开(例如密码错误)时返回 0;库资源正在释放或配置时返回 -1。
int CPDF_GetRemainingPageQuota(void)返回剩余页数配额:>= 0 为剩余页数,-1 表示未初始化,-2 表示不限制,-3 表示配额文件已损坏。
void CPDF_GetVersion(char* version)将 SDK 版本号字符串(例如 "4.3.0")写入调用方分配的缓冲区,缓冲区需足够容纳该字符串(例如 32 字节)。
void CPDF_Release(void)释放 SDK 占用的全部资源。见 3.18 释放库资源。

compdf_conversion_c.h:除 Word 转 PDF 外,所有转换接口的签名相同:

c
CSDKErrorCode CPDF_StartPDFToXxx(
    COMPDFKIT_STRING file_path,    // 输入文件路径
    COMPDFKIT_STRING password,     // 打开 PDF 的密码,无密码时传空字符串
    COMPDFKIT_STRING output_path,  // 输出路径
    CConvertOption options,        // 转换选项
    CConvertCallback* callback);   // 可选回调,不需要时传 NULL
接口输出格式章节
CPDF_StartPDFToWordWord (.docx)3.8
CPDF_StartPDFToExcelExcel (.xlsx) / CSV3.9、3.12
CPDF_StartPDFToPptPowerPoint (.pptx)3.10
CPDF_StartPDFToHtmlHTML (.html)3.11
CPDF_StartPDFToImage图片3.13
CPDF_StartPDFToRtfRTF (.rtf)3.14
CPDF_StartPDFToTxt文本 (.txt)3.15
CPDF_StartPDFToSearchablePDF可搜索 PDF (.pdf)3.16
CPDF_StartPDFToOfdOFD (.ofd)3.16.1
CPDF_StartPDFToJsonJSON (.json)4.1
CPDF_StartPDFToMarkdownMarkdown (.md)4.2
CPDF_StartWordToPDFPDF(输入为 Word 文档,签名不同)3.17

CConvertCallback(progress、cancel、handle 以及自定义 AI 回调)见 3.1、3.2 与 3.7.2。

CConvertOption 字段

下表的默认值即 CPDF_CONVERT_OPTION_DEFAULT 中的初始值:

字段类型默认说明
enable_ai_layoutbooltrue是否启用 AI 版面分析。开启 OCR 时版面分析自动启用。
enable_ai_table_recognitionbooltrue是否启用 AI 表格识别,仅在版面分析启用时生效。
contain_imagebooltrue是否在输出中包含图片,仅在 enable_ocr 为 false 时生效。
contain_page_background_imagebooltrue是否在输出中包含页面背景图,仅在 enable_ocr 为 true 时生效。
json_contain_tablebooltruePDF 转 JSON 时是否提取表格。
contain_annotationbooltrue是否包含注释。
excel_all_contentboolfalsePDF 转 Excel 时是否写入表格以外的文本、图片等内容。
excel_csv_formatboolfalsePDF 转 Excel 时是否以 CSV 格式保存表格。
enable_ocrboolfalse是否启用 OCR。
transparent_textbooltrue输出文档中的文本层是否透明(用于可搜索 PDF、OFD)。
txt_table_formatbooltruePDF 转 TXT 时是否按表格结构写入表格文本。
image_path_enhanceboolfalsePDF 转图片时是否增强路径的显示效果。
formula_to_imagebooltrue是否将公式转换为图片。
auto_create_folderbooltrue输出多个文件时,是否自动创建文件夹存放。
output_document_per_pageboolfalse是否每页输出一个文件。
language_countint0languages 数组中的语言数量。
image_scalingfloat4.0输出图片的缩放比例,1.0 为原始页面大小。
page_layout_modeCPageLayoutModee_PageLayoutModeFlow页面布局模式,见 3.5。
excel_worksheet_optionCExcelWorksheetOptione_CForTableExcel 工作表的创建方式,见 3.9。
html_optionCHtmlOptione_CSinglePageHTML 输出方式,见 3.11。
ocr_optionCOCROptione_CAllOCR 识别范围,见 3.6。
image_color_modeCImageColorModee_CColor输出图片的色彩模式。
image_typeCImageTypee_CJPG输出图片的格式。
font_namechar[256]空输出文档使用的字体名称,例如 "Arial",见 3.7.3。
page_rangeschar[256]空转换的页码范围,例如 "1-3,5,7-9";空表示全部页面。
languagesCOCRLanguage*NULLOCR 语言数组,共 language_count 个,最多使用 32 个。开启 OCR 但未指定语言时使用英文。
enable_document_orientation_classificationboolfalseOCR 识别前是否识别并矫正文档方向。仅在 enable_ocr 为 true 时生效,需要加载 document_process.model。
enable_document_dewarpboolfalseOCR 识别前是否进行文档矫正。仅在 enable_ocr 为 true 时生效,需要加载 document_process.model。
enable_auto_page_sizeboolfalse输入为图片文件时,按图片分辨率匹配最接近的标准纸张,见 3.13。
custom_page_widthfloat0输入为图片文件时指定输出页宽,单位为点,0 表示不指定。
custom_page_heightfloat0输入为图片文件时指定输出页高,单位为点。
table_recognition_accuracyCTableRecognitionAccuracye_CBalanced表格识别模型档位,见 3.7.1。
word_pdf_bookmark_modeCWordPdfBookmarkModee_CWordPdfBookmarkNone如何生成 PDF 书签,仅对 Word 转 PDF 生效,见 3.17。

枚举取值

枚举类型取值
CPageLayoutModee_PageLayoutModeBox(框排)、e_PageLayoutModeFlow(流排)
COCROptione_CInvalidCharacter、e_CScanPage、e_CInvalidCharacterAndScanPage、e_CAll,含义见 3.6
CExcelWorksheetOptione_CForTable、e_CForPage、e_CForDocument,含义见 3.9
CHtmlOptione_CSinglePage、e_CSinglePageWithBookmark、e_CMultiPage、e_CMultiPageWithBookmark,含义见 3.11
CImageColorModee_CColor(彩色)、e_CGray(灰度)、e_CBinary(黑白)
CImageTypee_CJPG、e_CJPEG、e_CJPEG2000、e_CPNG、e_CBMP、e_CTIFF、e_CTGA、e_CGIF、e_CWEBP
CTableRecognitionAccuracye_CHighAccuracy(0,高精度)、e_CBalanced(1,均衡)
CWordPdfBookmarkModee_CWordPdfBookmarkNone、e_CWordPdfBookmarkHeadings、e_CWordPdfBookmarkWordBookmarks,含义见 3.17
COCRLanguagee_CUNKNOWN(未知)、e_CCHINESE(简体中文)、e_CCHINESE_TRA(繁体中文)、e_CENGLISH(英文)、e_CKOREAN(韩文)、e_CJAPANESE(日文)、e_CLATIN(拉丁字母语言)、e_CDEVANAGARI(天城文)、e_CCYRILLIC(西里尔字母语言)、e_CARABIC(阿拉伯文)、e_CTAMIL(泰米尔文)、e_CTELUGU(泰卢固文)、e_CKANNADA(卡纳达文)、e_CTHAI(泰文)、e_CGREEK(希腊文)、e_CEslav(斯拉夫语)、e_CAUTO(自动选择语言)

错误码

大部分接口返回 CSDKErrorCode,e_CErrSuccess 表示成功。调用转换接口后请检查返回值。

错误码值含义
e_CErrSuccess0成功。
e_CErrCancel1转换被取消。
e_CErrFile2文件不存在或无法打开。
e_CErrPDFPassword3密码错误。
e_CErrPDFPage4PDF 页面加载失败。
e_CErrPDFFormat5格式无效,文件可能已损坏。
e_CErrPDFSecurity6PDF 使用了不支持的加密方式。
e_CErrOutOfMemory7内存不足;Word 转 PDF 时也表示诊断缓冲区放不下完整诊断信息。
e_CErrIO8系统 I/O 错误。
e_CErrCompress9文件夹压缩失败。
e_CErrLicenseInvalid20许可证无效。
e_CErrLicenseExpire21许可证已过期。
e_CErrLicenseUnsupportedPlatform22许可证不支持当前平台。
e_CErrLicenseUnsupportedID23许可证不支持该应用 ID。
e_CErrLicenseUnsupportedDevice24许可证不支持该设备 ID。
e_CErrLicensePermissionDeny25许可证不包含该功能权限。
e_CErrLicenseUninitialized26许可证未初始化。
e_CErrLicenseIllegalAccess27非法访问接口。
e_CErrLicenseFileReadFailed28读取许可证文件失败。
e_CErrLicenseOCRPermissionDeny29许可证不包含 OCR 权限。
e_CErrLicenseConcurrencyExceeded30当前转换并发数超过许可证限制。
e_CErrLicensePageLimitExceeded31转换页数超过许可证限制。
e_CErrLicenseQuotaCorrupted32配额持久化文件被篡改。
e_CErrNoTable40源文件中没有表格。
e_CErrOCRFailure41OCR 识别调用失败。
e_CErrConverting60正在执行转换任务(例如转换进行中加载模型)。
e_CErrInvalidArg80参数无效。
e_CErrInvalidHandle81句柄无效,可能未初始化或已释放。
e_CErrModelInvalidFormat82模型文件格式无效或已损坏。
e_CErrModelFunctionUnsupported83模型不支持所请求的功能。
e_CErrModelFormatUnsupported84不支持该模型格式。
e_CErrModelSDKMismatch85模型与当前 SDK 版本不配套。
e_CErrImageDataEmpty86图像数据为空。
e_CErrImageWHError87图像宽高无效。
e_CErrImageUnsupportedFormat88不支持该图像格式。
e_CErrImageInvalid89图像无效或已损坏。
e_CErrExpire90资源(例如许可证)已过期。
e_CErrMissingArg91缺少必需的参数。
e_CErrLicenseUnsupportedAPI92当前许可证不支持调用该接口。
e_CErrLicenseMismatch93许可证与设备、模块或版本不匹配。
e_CErrInvalidTable94表格数据无效或为空。
e_CErrUnsupportedFeature95输入包含无法完全还原的特性,或目标格式无法承载输入内容。可能仍有可用输出(Word 转 PDF 通常仍会生成 PDF),见 3.13 与 3.17。
e_CErrUnknown100未知错误。