libharu维基页面

安装

LibHaru 是一个用于生成 PDF 文件的库，可以在多种操作系统上进行安装。以下是对不同操作系统上安装 LibHaru 的方法的总结：

Linux/UNIX:

1. 解压缩下载的 LibHaru 包：

   tar -xvzf libharu-X.X.X.tar.gz
   

2. 创建构建目录并进入：

   mkdir build
   cd build
   

3. 使用 CMake 生成构建文件：

   cmake ../libharu-X.X.X
   

4. 清理、构建库并安装到默认路径（通常是 /usr/local/include 和 /usr/local/lib 目录）：

   make clean
   make
   sudo make install
   

macOS:

使用 Homebrew 包管理器安装 LibHaru：

brew install libharu

Windows (非 Cygwin/MSYS):

LibHaru 使用 CMake 构建系统。可以通过以下方式安装：

使用 VCPKG 依赖管理器:

1. 克隆 VCPKG 仓库：

   git clone https://github.com/Microsoft/vcpkg.git
   

2. 进入 VCPKG 目录并初始化：

   cd vcpkg
   ./bootstrap-vcpkg.sh
   

3. 集成 VCPKG 到当前开发环境：

   ./vcpkg integrate install
   

4. 安装 LibHaru：

   ./vcpkg install libharu
   

注意：

• VCPKG 中的 LibHaru 端口由 Microsoft 团队成员和社区贡献者保持最新。如果发现版本过时，可以在 VCPKG 仓库中创建 issue 或 pull request。

Cygwin/MSYS:

对于 Cygwin/MSYS 环境，可以参照 Linux/UNIX 的通用方法进行安装。

通过这些步骤，用户可以在不同操作系统上安装 LibHaru，进而在项目中生成和操作 PDF 文件。

使用

在LibHaru库中，创建和操作PDF文档的基本流程如下：

1. 初始化文档对象：
   使用HPDF_New()或HPDF_NewEx()创建一个HPDF_Doc类型的“文档对象”。如果需要自定义内存管理，则使用HPDF_NewEx()。这些函数返回的句柄将用于后续步骤。

2. 设置错误处理：
   可以在创建文档对象后指定一个用户定义的错误处理函数（这里称为“error_handler”）。使用setjmp()进行异常处理。

3. 设置文档属性：
   根据需要设置压缩模式、加密、页面模式和密码。

4. 创建新页面：
   调用HPDF_AddPage()向文档添加一个新页面。返回的页面句柄将用于后续的页面操作。

5. 插入页面：
   如果要在现有页面前插入新页面，可调用HPDF_InsertPage()。

6. 设置页面对象：
   根据需要设置页面对象的属性，例如页面大小和方向。

7. 页面描述：
   执行绘图操作，将文本放置在页面上。具体细节请参考“图形”章节。

8. 保存文档：
   使用HPDF_SaveToFile()将文档保存到文件，或使用HPDF_SaveToStream()将文档保存到临时流。通过调用HPDF_ReadFromStream()可以获取保存的数据，并可输出到标准输出。

9. 创建下一个文档：
   如果需要创建另一个文档，调用HPDF_NewDoc()。这个函数会在撤销当前文档后创建一个新文档。

10. 最终化和清理：
    所有处理完成后，调用HPDF_Free()释放文档对象所占用的所有资源。

以下是使用LibHaru创建PDF文档的示例代码的总结：

#include "hpdf.h"

// 创建PDF文档对象
HPDF_Doc pdf = HPDF_New(error_handler, NULL);
if (!pdf) {
   
   
    printf("ERROR: cannot create pdf object.\n");
    return 1;
}

// 异常处理
if (setjmp(env)) {
   
   
    HPDF_Free(pdf);
    return 1;
}

// 设置文档属性，如压缩、加密、页面模式和密码
HPDF_SetCompressionMode(pdf, HPDF_COMP_ALL);
HPDF_SetPageMode(pdf, HPDF_PAGE_MODE_USE_OUTLINE);
HPDF_SetPassword(pdf, "owner", "user");

// 创建和插入页面
HPDF_Page page_1 = HPDF_AddPage(pdf);
// HPDF_Page page_0 = HPDF_InsertPage(pdf, page_1); // 如果需要在特定页面前插入页面

// 设置页面属性，如大小和方向
HPDF_Page_SetSize(page_1, HPDF_PAGE_SIZE_B5, HPDF_PAGE_LANDSCAPE);

// 在页面上执行绘图操作和放置文本

// 保存文档到文件或流
HPDF_SaveToFile(pdf, "test.pdf");
// 或者保存到流并输出
HPDF_SaveToStream(pdf);
// ...（省略流操作代码）

// 如果需要，创建新的文档
// HPDF_NewDoc(pdf);

// 清理并释放资源
HPDF_Free(pdf);

这个流程提供了使用LibHaru库创建PDF文档的完整步骤，从初始化文档对象到最终的清理工作。

错误处理

函数类型

在Haru中，根据出错时的返回值，有三种类型的函数：

1. 返回 HPDF_STATUS 的函数：出错时返回错误代码。
2. 返回对象句柄的函数：出错时返回 NULL。
3. 返回其他值的函数：出错时返回初始值。

错误处理

当发生错误时，首先返回函数的返回值，然后在文档对象中存储一个错误代码，最后（如果定义了）调用用户自定义的错误处理函数。

• HPDF_GetError() 用于返回错误代码。但如果函数的第一个参数无效，则错误代码不会设置（因此无法检索）。
• 一些函数还设置了详细的错误代码，HPDF_GetErrorDetail() 用于返回详细错误代码。可以使用 strerror() 或平台等价物来了解失败的底层系统调用。
• 注意：一旦设置了错误代码，某些I/O处理函数将被阻塞。因此，必须调用 HPDF_ResetError() 来恢复程序。

用户自定义错误处理函数

可以定义一个在发生错误时调用的用户自定义错误处理函数，其定义如下：

typedef void (*HPDF_Error_Handler) (HPDF_STATUS error_no, HPDF_STATUS detail_no, void *user_data);

在Windows环境中，如果将Haru构建为共享库，错误处理函数的定义需要使用 __stdcall 调用约定。

使用用户自定义错误处理函数

可以通过使用错误处理函数有效地进行错误处理：

C语言中的错误处理

C语言不支持直接的异常处理，但通过使用 setjmp / longjmp 来模拟异常处理，错误处理变得简单。

void error_handler(HPDF_STATUS error_no, HPDF_STATUS detail_no, void *user_data) {
   
   
    printf("ERROR: error_no=%04X, detail_no=%d\n", (unsigned int)error_no, (int)detail_no);
    longjmp(env, 1); // 发生错误时调用 longjmp()
}

int main() {
   
   
    HPDF_Doc pdf;
    pdf = HPDF_New(error_handler, NULL); // 设置错误处理函数
    if (!pdf) {
   
   
        printf("error: cannot create PdfDoc object\n");
        return 1;
    }

    if (setjmp(env)) {
   
   
        HPDF_Free(pdf);
        return 1;
    }

    // 执行页面描述过程（不需要检查函数返回代码）

    HPDF_SaveToFile(pdf, fname);
    HPDF_Free(pdf);
    return 0;
}

C++中的错误处理

C++直接支持异常处理。在发生错误时抛出异常，错误处理变得简单。

void error_handler(HPDF_STATUS error_no, HPDF_STATUS detail_no, void *user_data) {