C API Interface (
litePDF.h)
1 /*
2 * Copyright (C) 2017 zyx [@:] zyx gmx [dot] us
3 *
4 * The litePDF library is free software: you can redistribute it
5 * and/or modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation, the version 3
7 * of the License.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this program. If not, see <http://www.gnu.org/licenses/>.
16 */
17
18 #ifndef LITEPDF_H
19 #define LITEPDF_H
20
21 #ifdef __cplusplus
22 #define LITEPDF_BEGIN_DECLS extern "C" {
23 #define LITEPDF_END_DECLS }
24 #else
25 #define LITEPDF_BEGIN_DECLS
26 #define LITEPDF_END_DECLS
27 #endif
28
29 #ifdef LITEPDF_DLL_BUILD
30 #define LITEPDF_PUBLIC /* __declspec(dllexport) */
31 #else
32 #define LITEPDF_PUBLIC __declspec(dllimport)
33 #endif
34
35 /** @mainpage litePDF
36 litePDF is a library (DLL), which allows creating new and editing of existing PDF documents with simple API.
37 Page content is drawn with standard GDI functions through a device context (HDC or TCanvas, in case of Delphi or C++ Builder).<br>
38 <br>
39 Main features of litePDF:
40 <ul>
41 <li>create new PDF documents in memory only, or with direct write to a disk</li>
42 <li>load of existing PDF documents</li>
43 <li>modify or delete of existing pages</li>
44 <li>copy pages from other documents</li>
45 <li>incremental update of PDF documents</li>
46 <li>encryption of PDF documents</li>
47 <li>digitally sign PDF documents</li>
48 <li>draw with GDI functions both directly to a page, and to a resource/template (XObject)</li>
49 <li>draw of created resources into a page</li>
50 <li>font embedding, complete or subset</li>
51 <li>font substitution</li>
52 <li>JPEG compression for images</li>
53 <li>attach files into PDF documents</li>
54 <li>low-level PDF operations</li>
55 </ul>
56 <br>
57 litePDF uses an Open Source project <a href="http://podofo.sf.net">PoDoFo</a> for manipulation of PDF documents,
58 and offers direct PdfDocument pointer to the PoDoFo interface, thus the library users can do anything what the PoDoFo
59 offers.
60 */
61
62 /** @page units Units
63 Since litePDF 1.2.0.0 the functions which used millimeters as their measure
64 units can use also inches, or fractions of the millimeters and inches.
65 The reason for the fraction is to not use architectural dependent types
66 in the API, where the @a double type is. The unit value is rounded down
67 to unsigned integers in the API. The default unit is set to millimeters
68 (@ref LITEPDF_UNIT_MM) for backward compatibility.<br>
69 <br>
70 Call @ref litePDF_GetUnit to determine which unit is currently used. To change
71 the unit to be used call @ref litePDF_SetUnit. For example, to create a page
72 of size 8.5 inches x 11.0 inches, set the unit to @ref LITEPDF_UNIT_10TH_INCH
73 and then call the @ref litePDF_AddPage with the width 85 and height 110
74 (10-times larger, because the current unit is 1/10th of an inch).<br>
75 <br>
76 All functions use the unit set for the current context, except of
77 the @ref litePDF_DrawResource, which has an explicit argument for the unit
78 value. That's for simplicity, to not need to change the units before
79 the function is called and then set it back after the call.
80 */
81
82 /** @file litePDF.h
83 @brief C interface
84
85 This document describes a direct C interface for litePDF.dll API.
86 */
87
88 LITEPDF_BEGIN_DECLS
89
90 typedef void (__stdcall * litePDFErrorCB)(unsigned int code,
91 const char *msg,
92 void *user_data);
93 /**<
94 Error callback.
95 @param code Error code, same as GetLastError().
96 @param msg Detailed error message.
97 @param user_data User data provided in @ref litePDF_CreateMemDocument.
98 */
99
100 void * __stdcall LITEPDF_PUBLIC litePDF_CreateContext(litePDFErrorCB on_error,
101 void *on_error_user_data);
102 /**<
103 Creates a new litePDF context. This is used in other litePDF functions.
104 The returned context should be freed with @ref litePDF_FreeContext
105 when no longer needed.
106
107 @param on_error Callback called on errors. This is used to report litePDF errors and
108 is used during whole life time of the returned context.
109 @param on_error_user_data User data passed into on_error callback.
110 @return Newly created litePDF context. This should be freed with @ref litePDF_FreeContext.
111 */
112
113 void __stdcall LITEPDF_PUBLIC litePDF_FreeContext(void *pctx);
114 /**<
115 Frees litePDF context previously created with @ref litePDF_CreateContext.
116 If it contains any unsaved data, then these are discarded.
117
118 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
119 */
120
121 #define LITEPDF_UNIT_UNKNOWN (0) /**< Unknown unit; usually used to indicate an error */
122 #define LITEPDF_UNIT_MM (1) /**< Millimeters unit */
123 #define LITEPDF_UNIT_10TH_MM (2) /**< 1/10th of a millimeter unit; 5 mm is value 50 */
124 #define LITEPDF_UNIT_100TH_MM (3) /**< 1/100th of a millimeter unit; 5 mm is value 500 */
125 #define LITEPDF_UNIT_1000TH_MM (4) /**< 1/1000th of a millimeter unit; 5 mm is value 5000 */
126 #define LITEPDF_UNIT_INCH (5) /**< Inch unit */
127 #define LITEPDF_UNIT_10TH_INCH (6) /**< 1/10th of an inch unit; 5" is value 50 */
128 #define LITEPDF_UNIT_100TH_INCH (7) /**< 1/100th of an inch unit; 5" is value 500 */
129 #define LITEPDF_UNIT_1000TH_INCH (8) /**< 1/1000th of an inch unit; 5" is value 5000 */
130
131 BOOL __stdcall LITEPDF_PUBLIC litePDF_SetUnit(void *pctx,
132 unsigned int unitValue);
133 /**<
134 Sets a unit to use in functions which expect non-pixel size and position values.
135 It can be one of LITEPDF_UNIT values. The default is @ref LITEPDF_UNIT_MM.
136
137 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
138 @param unitValue One of LITEPDF_UNIT values, to set as a unit for the litePDF context.
139
140 @see @ref units, litePDF_GetUnit
141 */
142
143 unsigned int __stdcall LITEPDF_PUBLIC litePDF_GetUnit(void *pctx);
144 /**<
145 Gets the currently set unit, which is used in functions which expect
146 non-pixel size and position values. It can be one of LITEPDF_UNIT values.
147 The default is @ref LITEPDF_UNIT_MM.
148
149 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
150 @return One of LITEPDF_UNIT values, which is set as the current unit for the litePDF context.
151
152 @see @ref units, litePDF_SetUnit
153 */
154
155 #define LITEPDF_FONT_FLAG_DEFAULT 0 /**< Use the settings as specified by the draw operation */
156 #define LITEPDF_FONT_FLAG_DO_NOT_EMBED 1 /**< Do not embed the font */
157 #define LITEPDF_FONT_FLAG_EMBED_COMPLETE 2 /**< Embed complete font */
158 #define LITEPDF_FONT_FLAG_EMBED_SUBSET 3 /**< Embed the font with used characters only */
159 #define LITEPDF_FONT_FLAG_SUBSTITUTE 4 /**< Substitute the font with one of the base fonts, if possible */
160
161 typedef unsigned int (__stdcall * litePDFEvalFontFlagCB)(char *inout_faceName,
162 unsigned int faceNameBufferSize,
163 void *user_data);
164 /**<
165 A callback to evaluate what to do with the specified font. The function
166 can be also used to rename the font, without changing the font flag.
167 The size of the @a inout_faceName buffer is @a faceNameBufferSize and when
168 renaming it, the written value should not be longer than @a faceNameBufferSize,
169 including the nul-terminating character.
170
171 The returned value for one font name should be consistent. It's not possible to
172 for example once request complete font embedding and the other time to request
173 no embedding at all.
174
175 @param inout_faceName [in/out] The font face name to evaluate the flag for.
176 @param faceNameBufferSize Size of the @a inout_faceName buffer.
177 @param user_data User data provided in @ref litePDF_SetEvalFontFlagCallback.
178 @return One of @ref LITEPDF_FONT_FLAG_DEFAULT, @ref LITEPDF_FONT_FLAG_DO_NOT_EMBED, @ref LITEPDF_FONT_FLAG_EMBED_COMPLETE, @ref LITEPDF_FONT_FLAG_EMBED_SUBSET, @ref LITEPDF_FONT_FLAG_SUBSTITUTE.
179 */
180
181 BOOL __stdcall LITEPDF_PUBLIC litePDF_SetEvalFontFlagCallback (void *pctx,
182 litePDFEvalFontFlagCB callback,
183 void *callback_user_data);
184 /**<
185 Sets a callback to evaluate what to do with a font. The @a callback can
186 be NULL, to unset any previously set value. See @ref litePDFEvalFontFlagCB
187 for more information about the @a callback parameters and what it can do.
188
189 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
190 @param callback A @ref litePDFEvalFontFlagCB callback to set, or NULL.
191 @param callback_user_data A user data to pass to @a callback when called.
192 @return Whether succeeded.
193 */
194
195 #define LITEPDF_ENCRYPT_PERMISSION_NONE 0x0 /**< Nothing from the rest is allowed */
196 #define LITEPDF_ENCRYPT_PERMISSION_PRINT 0x00000004 /**< Allow printing the document */
197 #define LITEPDF_ENCRYPT_PERMISSION_EDIT 0x00000008 /**< Allow modifying the document besides annotations, form fields or changing pages */
198 #define LITEPDF_ENCRYPT_PERMISSION_COPY 0x00000010 /**< Allow text and graphic extraction */
199 #define LITEPDF_ENCRYPT_PERMISSION_EDITNOTES 0x00000020 /**< Add or modify text annotations or form fields (if ePdfPermissions_Edit is set also allow to create interactive form fields including signature) */
200 #define LITEPDF_ENCRYPT_PERMISSION_FILLANDSIGN 0x00000100 /**< Fill in existing form or signature fields */
201 #define LITEPDF_ENCRYPT_PERMISSION_ACCESSIBLE 0x00000200 /**< Extract text and graphics to support user with disabilities */
202 #define LITEPDF_ENCRYPT_PERMISSION_DOCASSEMBLY 0x00000400 /**< Assemble the document: insert, create, rotate delete pages or add bookmarks */
203 #define LITEPDF_ENCRYPT_PERMISSION_HIGHPRINT 0x00000800 /**< Print a high resolution version of the document */
204
205 #define LITEPDF_ENCRYPT_ALGORITHM_RC4V1 1 /**< RC4 Version 1 encryption using a 40bit key */
206 #define LITEPDF_ENCRYPT_ALGORITHM_RC4V2 2 /**< RC4 Version 2 encryption using a 128bit key */
207 #define LITEPDF_ENCRYPT_ALGORITHM_AESV2 4 /**< AES encryption with a 128 bit key (PDF1.6) */
208 #define LITEPDF_ENCRYPT_ALGORITHM_AESV3 8 /**< AES encryption with a 256 bit key (PDF1.7 extension 3) */
209
210 BOOL __stdcall LITEPDF_PUBLIC litePDF_PrepareEncryption(void *pctx,
211 const char *userPassword,
212 const char *ownerPassword,
213 unsigned int permissions,
214 unsigned int algorithm);
215 /**<
216 Prepares encryption for newly created documents. The litePDF
217 context should be empty. The encryption is used only with
218 @ref litePDF_CreateFileDocument and @ref litePDF_CreateMemDocument, other
219 functions ignore it. Use NULL or an empty @a ownerPassword
220 to unset any previously set encryption properties.
221 Loading an encrypted document lefts it encrypted on save too.
222
223 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
224 @param userPassword User's password, can be an empty string,
225 then the user doesn't have to write a password.
226 @param ownerPassword Owner's password. Can be NULL or an empty string, to unset
227 encryption properties.
228 @param permissions Bit-or of LITEPDF_ENCRYPT_PERMISSION flags, to set user's
229 permissions for the document.
230 @param algorithm One of LITEPDF_ENCRYPT_ALGORITHM constants, an algorithm
231 to be used to encrypt the document.
232 @return Whether was able to prepare encryption within the litePDF context.
233
234 @see litePDF_CreateFileDocument, litePDF_CreateMemDocument
235 */
236
237 BOOL __stdcall LITEPDF_PUBLIC litePDF_CreateFileDocument(void *pctx,
238 const char *fileName);
239 /**<
240 Makes the litePDF context hold a new PDF, which writes directly to a file.
241 The passed-in litePDF context should not have opened any other PDF data.
242 Call @ref litePDF_Close, to close the file, and possibly save changes to it.
243 Most of the operations require memory-based PDF, which can be created
244 with @ref litePDF_CreateMemDocument.
245
246 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
247 @param fileName File name to write the PDF result to.
248 @return Whether succeeded.
249
250 @note PoDoFo doesn't support creation of file-based documents with AES encryption,
251 thus use for it memory-based documents instead (@ref litePDF_CreateMemDocument).
252
253 @see litePDF_PrepareEncryption, litePDF_CreateFileDocumentW, litePDF_CreateMemDocument, litePDF_LoadFromFile
254 */
255
256 BOOL __stdcall LITEPDF_PUBLIC litePDF_CreateFileDocumentW(void *pctx,
257 const wchar_t *fileName);
258 /**<
259 This is the same as @ref litePDF_CreateFileDocument, the only difference is that
260 the @a fileName is a wide string.
261 */
262
263 BOOL __stdcall LITEPDF_PUBLIC litePDF_CreateMemDocument(void *pctx);
264 /**<
265 Makes the litePDF context hold a memory-based PDF. Such PDF can be
266 saved with @ref litePDF_SaveToFile or @ref litePDF_SaveToData.
267 The PDF should be closed with @ref litePDF_Close.
268
269 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
270 @return Whether succeeded.
271
272 @see litePDF_PrepareEncryption, litePDF_CreateFileDocument, litePDF_LoadFromFile
273 */
274
275 BOOL __stdcall LITEPDF_PUBLIC litePDF_LoadFromFile(void *pctx,
276 const char *fileName,
277 const char *password,
278 BOOL loadCompletely,
279 BOOL forUpdate);
280 /**<
281 Makes the litePDF context hold a memory-based PDF, which is loaded
282 from a disk file. This should be closed with @ref litePDF_Close.
283 The @a loadCompletely parameter is used to determine whether the file
284 should be loaded into memory completely, or when the file can be read
285 on demand. Using complete load requires more memory, but the disk
286 file can be changed freely in the background, while incomplete load
287 requires left the file without changes while being opened.
288 The @a forUpdate parameter specifies whether the file is being opened
289 for incremental update. In that case saving such document will result
290 in the changes being appended to the end of the original document,
291 instead of resaving whole document.
292
293 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
294 @param fileName File name to load the PDF from.
295 @param password Password to use for encrypted documents.
296 @param loadCompletely Set to TRUE when the file should be loaded completely
297 into memory, or FALSE to keep the disk file in use while working with it.
298 @param forUpdate Set to TRUE to open the file for incremental update,
299 or set to FALSE otherwise.
300 @return Whether succeeded.
301
302 @see litePDF_LoadFromFileW
303 */
304
305 BOOL __stdcall LITEPDF_PUBLIC litePDF_LoadFromFileW(void *pctx,
306 const wchar_t *fileName,
307 const char *password,
308 BOOL loadCompletely,
309 BOOL forUpdate);
310 /**<
311 This is the same as @ref litePDF_LoadFromFile, the only difference is that
312 the @a fileName is a wide string.
313 */
314
315 BOOL __stdcall LITEPDF_PUBLIC litePDF_LoadFromData(void *pctx,
316 const BYTE *data,
317 unsigned int dataLength,
318 const char *password,
319 BOOL forUpdate);
320 /**<
321 Makes the litePDF context hold a memory-based PDF, which is loaded
322 with a PDF data. This should be closed with @ref litePDF_Close.
323 The @a forUpdate parameter specifies whether the file is being opened
324 for incremental update. In that case saving such document will result
325 in the changes being appended to the end of the original document,
326 instead of resaving whole document.
327
328 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
329 @param data PDF data to load.
330 @param dataLength Length of PDF data.
331 @param password Password to use for encrypted documents.
332 @param forUpdate Set to TRUE to open the file for incremental update,
333 or set to FALSE otherwise.
334 @return Whether succeeded.
335
336 @see litePDF_CreateMemDocument, litePDF_SaveToFile, litePDF_SaveToData
337 */
338
339 BOOL __stdcall LITEPDF_PUBLIC litePDF_SaveToFile(void *pctx,
340 const char *fileName);
341 /**<
342 Saves memory-based PDF into a file. The context should hold PDF created only
343 with @ref litePDF_CreateMemDocument, @ref litePDF_LoadFromFile or @ref litePDF_LoadFromData.
344 Passing any other context results in an error.
345
346 In case the PDF document had been loaded with @ref litePDF_LoadFromFile,
347 @ref litePDF_LoadFromFileW or @ref litePDF_LoadFromData with its @a forUpdate
348 parameter being TRUE, the resulting document will contain the changes as
349 an incremental update (appended at the end of the original document), otherwise
350 the whole document is completely rewritten.
351
352 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
353 @param fileName File name to which save the memory-based PDF.
354 @return Whether succeeded.
355
356 @note The only valid operation after this is either close the document
357 with @ref litePDF_Close, or free the context with @ref litePDF_FreeContext.
358
359 @see litePDF_SaveToFileW, litePDF_SaveToData, litePDF_SaveToFileWithSign, litePDF_Close
360 */
361
362 BOOL __stdcall LITEPDF_PUBLIC litePDF_SaveToFileW(void *pctx,
363 const wchar_t *fileName);
364 /**<
365 This is the same as @ref litePDF_SaveToFile, the only difference is that
366 the @a fileName is a wide string.
367 */
368
369 BOOL __stdcall LITEPDF_PUBLIC litePDF_SaveToData(void *pctx,
370 BYTE *data,
371 unsigned int *dataLength);
372 /**<
373 Saves memory-based PDF into a data. The context should hold PDF created only
374 with @ref litePDF_CreateMemDocument, @ref litePDF_LoadFromFile or @ref litePDF_LoadFromData.
375 Passing any other context results in an error.
376
377 In case the PDF document had been loaded with @ref litePDF_LoadFromFile,
378 @ref litePDF_LoadFromFileW or @ref litePDF_LoadFromData with its @a forUpdate
379 parameter being TRUE, the resulting document will contain the changes as
380 an incremental update (appended at the end of the original document), otherwise
381 the whole document is completely rewritten.
382
383 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
384 @param data [out] Actual data to store the PDF content to. It can be NULL, in which case
385 the @a dataLength is populated with large-enough value to hold the whole data.
386 @param dataLength [in/out] Tells how many bytes can be stored in @a data. If @a data
387 is NULL, then it is set to large-enough value. Passing non-NULL @a data with no enough
388 large buffer results in a failure with no change on @a dataLength.
389 @return Whether succeeded.
390
391 @note The only valid operation after this is either call of @ref litePDF_SaveToData again,
392 to get information about necessary buffer size or data itself, close the document
393 with @ref litePDF_Close, or free the context with @ref litePDF_FreeContext.
394
395 @see litePDF_SaveToFile, litePDF_SaveToDataWithSign, litePDF_Close
396 */
397
398 void __stdcall LITEPDF_PUBLIC litePDF_Close(void *pctx);
399 /**<
400 Closes PDF data in a litePDF context, thus the context doesn't hold anything afterward,
401 aka it's like a context just created with @ref litePDF_CreateContext. Do not forget to
402 free the context itself with @ref litePDF_FreeContext, when no longer needed. The function
403 does nothing, if the context doesn't hold any data. In case of any drawing in progress,
404 the drawing is discarded, same as any unsaved changes to the memory-based PDF documents.
405 It also unsets any encryption properties, previously set by @ref litePDF_PrepareEncryption.
406
407 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
408
409 @see litePDF_AddPage, litePDF_InsertPage, litePDF_UpdatePage, litePDF_FinishPage
410 */
411
412 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetPageCount(void *pctx,
413 unsigned int *pageCount);
414 /**<
415 Returns count of pages in a PDF opened in the litePDF context.
416
417 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
418 @param pageCount [out] Count of pages.
419 @return Whether succeeded.
420 */
421
422 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetPageSize(void *pctx,
423 unsigned int pageIndex,
424 unsigned int *width_u,
425 unsigned int *height_u);
426 /**<
427 Gets size of an existing page, in the current unit.
428
429 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
430 @param pageIndex Page index for which get the page size; counts from 0.
431 @param width_u [out] Width of the page in the current unit.
432 @param height_u [out] Height of the page in the current unit.
433 @return Whether succeeded.
434
435 @see litePDF_GetUnit
436 */
437
438 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetPageRotation(void *pctx,
439 unsigned int pageIndex,
440 int *out_degrees);
441 /**<
442 Gets rotation of an existing page, in degrees. Expected values are 0, 90, 180 and 270.
443
444 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
445 @param pageIndex Page index for which get the page size; counts from 0.
446 @param out_degrees [out] Rotation of the page, in degrees.
447 @return Whether succeeded.
448
449 @see litePDF_SetPageRotation
450 */
451
452 BOOL __stdcall LITEPDF_PUBLIC litePDF_SetPageRotation(void *pctx,
453 unsigned int pageIndex,
454 int degrees);
455 /**<
456 Sets rotation of an existing page, in degrees. Expected values are 0, 90, 180 and 270.
457
458 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
459 @param pageIndex Page index for which get the page size; counts from 0.
460 @param degrees Rotation of the page to set, in degrees.
461 @return Whether succeeded.
462
463 @see litePDF_GetPageRotation
464 */
465
466 #define LITEPDF_DRAW_FLAG_NONE (0) /**< None draw flags */
467 #define LITEPDF_DRAW_FLAG_EMBED_FONTS_NONE (1 << 4) /**< Do not embed any fonts into resulting PDF.
468 @note: Fonts' subset is embeded by default, if none of the @ref LITEPDF_DRAW_FLAG_EMBED_FONTS_NONE, @ref LITEPDF_DRAW_FLAG_EMBED_FONTS_COMPLETE, @ref LITEPDF_DRAW_FLAG_EMBED_FONTS_SUBSET,
469 flags is defined; the @ref LITEPDF_DRAW_FLAG_EMBED_FONTS_NONE is to override default font embedding. The reason for this default embedding is
470 due to PDF readers not showing correct fonts when they are not part of the PDF file.
471 @see LITEPDF_DRAW_FLAG_EMBED_FONTS_COMPLETE, LITEPDF_DRAW_FLAG_EMBED_FONTS_SUBSET */
472 #define LITEPDF_DRAW_FLAG_EMBED_FONTS_COMPLETE (1 << 0) /**< Embed complete fonts into resulting PDF; @see LITEPDF_DRAW_FLAG_EMBED_FONTS_SUBSET, LITEPDF_DRAW_FLAG_EMBED_FONTS_NONE */
473 #define LITEPDF_DRAW_FLAG_EMBED_FONTS_SUBSET (1 << 1) /**< Embed only subset of the fonts, aka used letters; this flag is used before @ref LITEPDF_DRAW_FLAG_EMBED_FONTS_COMPLETE; @see LITEPDF_DRAW_FLAG_EMBED_FONTS_NONE */
474 #define LITEPDF_DRAW_FLAG_SUBSTITUTE_FONTS (1 << 2) /**< Substitute fonts with base PDF fonts, if possible */
475 #define LITEPDF_DRAW_FLAG_COMPRESS_IMAGES_WITH_JPEG (1 << 3) /**< Compress images with JPEG compression, to get smaller PDF document; this is used only for RGB images */
476 #define LITEPDF_DRAW_FLAG_RESET_GRAPHICS_STATE (1 << 5) /**< Try to reset graphics state before appending new content to the page. This covers leftover saved states and the transformation matrix */
477
478 HDC __stdcall LITEPDF_PUBLIC litePDF_AddPage(void *pctx,
479 unsigned int width_u,
480 unsigned int height_u,
481 unsigned int width_px,
482 unsigned int height_px,
483 unsigned int drawFlags);
484 /**<
485 Begins drawing into a new page into the PDF context of the given size.
486 Newly created page is added as the last page of the PDF document.
487 This cannot be called when other drawing is in progress.
488
489 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
490 @param width_u Width of the new page in the current unit.
491 @param height_u Height of the new page in the current unit.
492 @param width_px Width of the new page in pixels.
493 @param height_px Height of the new page in pixels.
494 @param drawFlags Flags for drawing functions. This is a bit-or of LITEPDF_DRAW_FLAG values
495 and influences only @ref litePDF_AddPage, @ref litePDF_InsertPage, @ref litePDF_UpdatePage
496 and @ref litePDF_AddResource functions.
497 @return Device context into which can be drawn with standard GDI functions.
498 Finish the drawing, and the page addition, with @ref litePDF_FinishPage.
499
500 @note Larger pixel page size produces more precise font mapping.
501
502 @see litePDF_GetUnit, litePDF_InsertPage, litePDF_UpdatePage, litePDF_FinishPage, litePDF_AddResource
503 */
504
505 HDC __stdcall LITEPDF_PUBLIC litePDF_InsertPage(void *pctx,
506 unsigned int pageIndex,
507 unsigned int width_u,
508 unsigned int height_u,
509 unsigned int width_px,
510 unsigned int height_px,
511 unsigned int drawFlags);
512 /**<
513 Begins drawing into a new page into the PDF context of the given size.
514 Newly created page is inserted at the given position of the PDF document.
515 This cannot be called when other drawing is in progress.
516 If the index is out of bounds, then the page is added ad the end, like with
517 @ref litePDF_AddPage.
518
519 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
520 @param pageIndex Page index where to insert the page; counts from 0.
521 @param width_u Width of the new page in the current unit.
522 @param height_u Height of the new page in the current unit.
523 @param width_px Width of the new page in pixels.
524 @param height_px Height of the new page in pixels.
525 @param drawFlags Flags for drawing functions. This is a bit-or of LITEPDF_DRAW_FLAG values
526 and influences only @ref litePDF_AddPage, @ref litePDF_InsertPage, @ref litePDF_UpdatePage
527 and @ref litePDF_AddResource functions.
528 @return Device context into which can be drawn with standard GDI functions.
529 Finish the drawing, and the page insertion, with @ref litePDF_FinishPage.
530
531 @note Larger pixel page size produces more precise font mapping.
532
533 @see litePDF_GetUnit, litePDF_GetPageCount, litePDF_AddPage, litePDF_UpdatePage,
534 litePDF_FinishPage, litePDF_AddResource
535 */
536
537 HDC __stdcall LITEPDF_PUBLIC litePDF_UpdatePage(void *pctx,
538 unsigned int pageIndex,
539 unsigned int width_px,
540 unsigned int height_px,
541 unsigned int drawFlags);
542 /**<
543 Begins drawing into an already existing page. The page size in the current unit can be
544 found by @ref litePDF_GetPageSize. The function fails, and returns NULL,
545 if the @a pageIndex is out of bounds.
546
547 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
548 @param pageIndex Page index which to update; counts from 0.
549 @param width_px Width of the new page in pixels.
550 @param height_px Height of the new page in pixels.
551 @param drawFlags Flags for drawing functions. This is a bit-or of LITEPDF_DRAW_FLAG values
552 and influences only @ref litePDF_AddPage, @ref litePDF_InsertPage, @ref litePDF_UpdatePage
553 and @ref litePDF_AddResource functions.
554 @return Device context into which can be drawn with standard GDI functions.
555 Finish the drawing, and the page update, with @ref litePDF_FinishPage.
556
557 @see litePDF_GetPageCount, litePDF_AddPage, litePDF_InsertPage,
558 litePDF_FinishPage, litePDF_AddResource
559 */
560
561 BOOL __stdcall LITEPDF_PUBLIC litePDF_FinishPage(void *pctx,
562 HDC hDC);
563 /**<
564 Tells litePDF that drawing into the page is finished and that it can
565 be processed into PDF. The @a hDC is not valid after this call any more.
566
567 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
568 @param hDC Device context previously returned by @ref litePDF_AddPage,
569 @ref litePDF_InsertPage or @ref litePDF_UpdatePage.
570 @return Whether succeeded.
571 */
572
573 HDC __stdcall LITEPDF_PUBLIC litePDF_AddResource(void *pctx,
574 unsigned int width_u,
575 unsigned int height_u,
576 unsigned int width_px,
577 unsigned int height_px,
578 unsigned int drawFlags);
579 /**<
580 Begins drawing into a new resource into the PDF context of the given size.
581 This cannot be called when other drawing is in progress.
582
583 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
584 @param width_u Width of the new page in the current unit.
585 @param height_u Height of the new page in the current unit.
586 @param width_px Width of the new page in pixels.
587 @param height_px Height of the new page in pixels.
588 @param drawFlags Flags for drawing functions. This is a bit-or of LITEPDF_DRAW_FLAG values
589 and influences only @ref litePDF_AddPage, @ref litePDF_InsertPage, @ref litePDF_UpdatePage
590 and @ref litePDF_AddResource functions.
591 @return Device context into which can be drawn with standard GDI functions.
592 Finish the drawing, and the resource addition, with @ref litePDF_FinishResource.
593
594 @note Larger pixel resource size produces more precise font mapping.
595
596 @see litePDF_GetUnit, litePDF_AddPage, litePDF_InsertPage, litePDF_UpdatePage,
597 litePDF_FinishResource, litePDF_DrawResource
598 */
599
600 unsigned int __stdcall LITEPDF_PUBLIC litePDF_FinishResource(void *pctx,
601 HDC hDC);
602 /**<
603 Tells litePDF that drawing into the resource is finished and that it can
604 be processed into PDF. The @a hDC is not valid after this call any more.
605
606 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
607 @param hDC Device context previously returned by @ref litePDF_AddResource.
608 @return Newly created resource ID, or 0 on error.
609
610 @see litePDF_AddResource, litePDF_AddPageFromAsResource, litePDF_DrawResource
611 */
612
613 BOOL __stdcall LITEPDF_PUBLIC litePDF_DeletePage(void *pctx,
614 unsigned int pageIndex);
615 /**<
616 Deletes page at given index. It doesn't delete page resources, because these can
617 be used by other pages.
618
619 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
620 @param pageIndex Page index which to update; counts from 0.
621 @return Whether succeeded.
622
623 @see litePDF_GetPageCount, litePDF_PageToResource
624 */
625
626 BOOL __stdcall LITEPDF_PUBLIC litePDF_AddPagesFrom(void *pctx,
627 void *pctx_from,
628 unsigned int pageIndex,
629 unsigned int pageCount);
630 /**<
631 Adds existing pages as the last pages from another PDF. Both contexts should
632 hold memory-based documents.
633
634 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext,
635 to which add the page.
636 @param pctx_from litePDF context, previously created with @ref litePDF_CreateContext,
637 from which add the pages.
638 @param pageIndex Page index which to add from @a pctx_from; counts from 0.
639 @param pageCount How many pages to add; 0 means whole document.
640 @return Whether succeeded.
641
642 @note The two contexts cannot be the same.
643
644 @see litePDF_GetPageCount, litePDF_InsertPageFrom, litePDF_PageToResource
645 */
646
647 BOOL __stdcall LITEPDF_PUBLIC litePDF_InsertPageFrom(void *pctx,
648 unsigned int pageIndexTo,
649 void *pctx_from,
650 unsigned int pageIndexFrom);
651 /**<
652 Inserts an existing page at the given index from another PDF. Both contexts should
653 hold memory-based documents.
654
655 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext,
656 to which add the page.
657 @param pageIndexTo Page index where to add the page; counts from 0. Adds page
658 at the end, if out of bounds.
659 @param pctx_from litePDF context, previously created with @ref litePDF_CreateContext,
660 from which add the page.
661 @param pageIndexFrom Page index which to add from @a pctx_from; counts from 0.
662 @return Whether succeeded.
663
664 @note The two contexts cannot be the same.
665
666 @see litePDF_GetPageCount, litePDF_AddPagesFrom, litePDF_PageToResource
667 */
668
669 unsigned int __stdcall LITEPDF_PUBLIC litePDF_AddPageFromAsResource(void *pctx,
670 void *pctx_from,
671 unsigned int pageIndex,
672 BOOL useTrimBox);
673 /**<
674 Adds an existing page as a resource of a given PDF. This resource can be
675 referenced multiple times by its identifier. Both contexts should
676 hold memory-based documents.
677
678 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext,
679 to which add the page resource.
680 @param pctx_from litePDF context, previously created with @ref litePDF_CreateContext,
681 from which add the page.
682 @param pageIndex Page index which to add from @a pctx_from; counts from 0.
683 @param useTrimBox If TRUE, try to use trimbox for size of the resource (XObject)
684 @return Resource identifier, or 0 on error.
685
686 @note The two contexts cannot be the same.
687
688 @see litePDF_GetPageCount, litePDF_AddPagesFrom, litePDF_PageToResource, litePDF_GetResourceSize,
689 litePDF_DrawResource
690 */
691
692 unsigned int __stdcall LITEPDF_PUBLIC litePDF_PageToResource(void *pctx,
693 unsigned int pageIndex);
694 /**<
695 Creates a resource, which will reference an existing page.
696 The page itself is not deleted after call of this.
697
698 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
699 @param pageIndex Page index for which create the resource reference; counts from 0.
700 @return Resource identifier, or 0 on error.
701
702 @see litePDF_GetPageCount, litePDF_AddPagesFrom, litePDF_AddPageFromAsResource, litePDF_GetResourceSize,
703 litePDF_DrawResource
704 */
705
706 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetResourceSize(void *pctx,
707 unsigned int resourceID,
708 unsigned int *width_u,
709 unsigned int *height_u);
710 /**<
711 Gets size of an existing resource, in the current unit. The resource ID
712 was returned from @ref litePDF_AddPageFromAsResource or @ref litePDF_FinishResource.
713
714 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
715 @param resourceID Resource ID for which get the size.
716 @param width_u [out] Width of the resource, in the current unit.
717 @param height_u [out] Height of the resource, in the current unit.
718 @return Whether succeeded.
719
720 @see litePDF_GetUnit, litePDF_AddPageFromAsResource, litePDF_DrawResource
721 */
722
723 BOOL __stdcall LITEPDF_PUBLIC litePDF_DrawResource(void *pctx,
724 unsigned int resourceID,
725 unsigned int pageIndex,
726 unsigned int unitValue,
727 int x,
728 int y,
729 int scaleX,
730 int scaleY);
731 /**<
732 Draws an existing resource at the given position. The resource ID
733 was returned from @ref litePDF_AddPageFromAsResource, @ref litePDF_PageToResource
734 or @ref litePDF_FinishResource. The @a unitValue is used for both the position
735 and the scale. In case of the scale, it defines only the ratio to the base unit.
736 For example, if the @a unitValue is either @ref LITEPDF_UNIT_1000TH_MM or
737 @ref LITEPDF_UNIT_1000TH_INCH, then the ratio for the @a scaleX and @a scaleY
738 is used 1/1000 (where 1000 means the same size as the resource is in this case).
739
740 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
741 @param resourceID Resource ID to draw.
742 @param pageIndex Page index to which draw; counts from 0.
743 @param unitValue A unit to use for the @a x and @a y, and a ratio for the @a scaleX and @a scaleY.
744 @param x Where to draw on the page, X axes, in the given @a unitValue unit,
745 with left-top corner being [0,0].
746 @param y Where to draw on the page, Y axes, in the given @a unitValue unit,
747 with left-top corner being [0,0].
748 @param scaleX Scale factor of the page for the X axes, using the @a unitValue ratio.
749 @param scaleY Scale factor of the page for the Y axes, using the @a unitValue ratio.
750 @return Whether succeeded.
751
752 @see litePDF_GetPageCount, litePDF_AddPageFromAsResource, litePDF_PageToResource, litePDF_FinishResource,
753 litePDF_GetResourceSize, litePDF_DrawResourceWithMatrix
754 */
755
756 BOOL __stdcall LITEPDF_PUBLIC litePDF_DrawResourceWithMatrix(void *pctx,
757 unsigned int resourceID,
758 unsigned int pageIndex,
759 int a,
760 int b,
761 int c,
762 int d,
763 int e,
764 int f);
765 /**<
766 Draws an existing resource with given transformation matrix. All
767 the transformation values are passed into PDF directly, without any
768 conversion. The resource ID was returned from @ref litePDF_AddPageFromAsResource
769 or @ref litePDF_FinishResource. The constructed transformation matrix
770 is a standard 3x3 matrix:<BR>
771 <CODE> | a b 0 |</CODE><BR>
772 <CODE> | c d 0 |</CODE><BR>
773 <CODE> | e f 1 |</CODE>
774
775 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
776 @param resourceID Resource ID to draw.
777 @param pageIndex Page index to which draw; counts from 0.
778 @param a Transformation matrix [ a b c d e f ] parameter 'a', in 1/1000th of PDF units.
779 @param b Transformation matrix [ a b c d e f ] parameter 'b', in 1/1000th of PDF units.
780 @param c Transformation matrix [ a b c d e f ] parameter 'c', in 1/1000th of PDF units.
781 @param d Transformation matrix [ a b c d e f ] parameter 'd', in 1/1000th of PDF units.
782 @param e Transformation matrix [ a b c d e f ] parameter 'e', in 1/1000th of PDF units.
783 @param f Transformation matrix [ a b c d e f ] parameter 'f', in 1/1000th of PDF units.
784 @return Whether succeeded.
785
786 @see litePDF_GetPageCount, litePDF_AddPageFromAsResource, litePDF_FinishResource,
787 litePDF_GetResourceSize, litePDF_DrawResource
788 */
789
790 #define LITEPDF_DOCUMENT_INFO_AUTHOR "Author" /**< an Author of the document */
791 #define LITEPDF_DOCUMENT_INFO_CREATOR "Creator" /**< a Creator of the document */
792 #define LITEPDF_DOCUMENT_INFO_KEYWORDS "Keywords" /**< the Keywords of the document */
793 #define LITEPDF_DOCUMENT_INFO_SUBJECT "Subject" /**< a Subject of the document */
794 #define LITEPDF_DOCUMENT_INFO_TITLE "Title" /**< a Title of the document */
795 #define LITEPDF_DOCUMENT_INFO_PRODUCER "Producer" /**< a Producer of the document; this key is read-only */
796 #define LITEPDF_DOCUMENT_INFO_TRAPPED "Trapped" /**< a trapping state of the document */
797 #define LITEPDF_DOCUMENT_INFO_CREATION_DATE "CreationDate" /**< a date of the creation of the document */
798 #define LITEPDF_DOCUMENT_INFO_MODIFICATION_DATE "ModDate" /**< a date of the last modification of the document */
799
800 BOOL __stdcall LITEPDF_PUBLIC litePDF_SetDocumentInfo(void *pctx,
801 const char *name,
802 const wchar_t *value);
803 /**<
804 Sets information about the document. The name can be one
805 of the LITEPDF_DOCUMENT_INFO predefined constants.
806
807 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
808 @param name Document info property name to set.
809 @param value Null-terminated Unicode value to set.
810 @return Whether succeeded.
811 */
812
813 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetDocumentInfoExists(void *pctx,
814 const char *name,
815 BOOL *pExists);
816 /**<
817 Checks whether information about the document of the given name exists.
818 The name can be one of the LITEPDF_DOCUMENT_INFO predefined constants.
819
820 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
821 @param name Document info property name to test.
822 @param pExists [out] Where to store whether the document information is set.
823 @return Whether succeeded.
824 */
825
826 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetDocumentInfo(void *pctx,
827 const char *name,
828 wchar_t *value,
829 unsigned int *valueLength);
830 /**<
831 Gets information about the document. The name can be one
832 of the LITEPDF_DOCUMENT_INFO predefined constants.
833
834 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
835 @param name Document info property name to get.
836 @param value [out] Null-terminated Unicode value. It can be NULL, in which case
837 the @a valueLength is populated with large-enough value to hold the whole string.
838 @param valueLength [in/out] Tells how many characters can be stored in @a value. If @a value
839 is NULL, then it is set to large-enough value (not including the Null-termination character).
840 Passing non-NULL @a value with no enough large buffer results in a failure with no change
841 on @a valueLength. The @a valueLength has stored count of characters written, not including
842 the Null-termination character on success.
843 @return Whether succeeded.
844 */
845
846 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetDocumentIsSigned(void *pctx,
847 BOOL *pIsSigned);
848 /**<
849 Checks whether currently opened document is already signed. Signing already
850 signed document can cause breakage of previous signatures, thus it's good
851 to test whether the loaded document is signed, before signing it.
852
853 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
854 @param pIsSigned [out] Where to store the result.
855 @return Whether succeeded.
856
857 @see litePDF_GetSignatureCount, litePDF_SaveToFileWithSign, litePDF_SaveToDataWithSign
858 */
859
860 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetSignatureCount(void *pctx,
861 unsigned int *pCount);
862 /**<
863 Provides how many signature fields the currently opened document contains.
864 It returns the count of the all fields, not only those already signed.
865
866 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
867 @param pCount [out] Where to store the result.
868 @return Whether succeeded.
869
870 @note The litePDF caches the list of the existing signature fields for performance
871 reasons and it rebuilds it whenever this function is called or when the
872 @ref litePDF_CreateSignature is called, thus if there are made any changes
873 directly with the PoDoFo API after the cache had been created, then make sure
874 you call this function again to avoid a use-after-free or an outdated information
875 being used. The litePDF will try to keep the cache up to date as needed, but
876 it cannot cover every case, especially not the one when the PoDoFo API is used.
877
878 @see litePDF_GetDocumentIsSigned, litePDF_GetSignatureHasData, litePDF_GetSignatureData
879 */
880
881 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetSignatureName(void *pctx,
882 unsigned int index,
883 char *name,
884 unsigned int *nameLength);
885 /**<
886 Gets the signature field name at the given @a index.
887
888 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
889 @param index Which signature field name to get; counts from 0. This might be less
890 than @ref litePDF_GetSignatureCount.
891 @param name [out] Null-terminated ASCII name. It can be NULL, in which case
892 the @a nameLength is populated with large-enough value to hold the whole string.
893 @param nameLength [in/out] Tells how many characters can be stored in @a name. If @a name
894 is NULL, then it is set to large-enough value (not including the Null-termination character).
895 Passing non-NULL @a name with no enough large buffer results in a failure with no change
896 on @a nameLength. The @a nameLength has stored count of characters written, not including
897 the Null-termination character, on success.
898 @return Whether succeeded.
899 */
900
901 #define LITEPDF_ANNOTATION_FLAG_NONE 0x0000 /**< Default annotation flags */
902 #define LITEPDF_ANNOTATION_FLAG_INVISIBLE 0x0001 /**< Do not show nonstandard annotation if there is no annotation handler available */
903 #define LITEPDF_ANNOTATION_FLAG_HIDDEN 0x0002 /**< Do not allow show, print or interact with the annotation */
904 #define LITEPDF_ANNOTATION_FLAG_PRINT 0x0004 /**< Print the annotation */
905 #define LITEPDF_ANNOTATION_FLAG_NOZOOM 0x0008 /**< Do not scale the annotation's appearance to match the magnification of the page */
906 #define LITEPDF_ANNOTATION_FLAG_NOROTATE 0x0010 /**< Do not rotate the annotation's appearance to match the rotation of the page */
907 #define LITEPDF_ANNOTATION_FLAG_NOVIEW 0x0020 /**< Do not display the annotation on the screen or allow it to interact with the user */
908 #define LITEPDF_ANNOTATION_FLAG_READONLY 0x0040 /**< Do not allow the annotation to interact with the user */
909 #define LITEPDF_ANNOTATION_FLAG_LOCKED 0x0080 /**< Do not allow the annotation to be deleted or its properties (including position and size) to be modified by the user */
910 #define LITEPDF_ANNOTATION_FLAG_TOGGLENOVIEW 0x0100 /**< Invert the interpretation of the NoView flag for certain events */
911 #define LITEPDF_ANNOTATION_FLAG_LOCKEDCONTENTS 0x0200 /**< Do not allow the contents of the annotation to be modified by the user */
912
913 BOOL __stdcall LITEPDF_PUBLIC litePDF_CreateSignature(void *pctx,
914 const char *name,
915 unsigned int annotationPageIndex,
916 int annotationX_u,
917 int annotationY_u,
918 int annotationWidth_u,
919 int annotationHeight_u,
920 unsigned int annotationFlags,
921 unsigned int *pAddedIndex);
922 /**<
923 Creates a new signature field named @a name. The field is created completely empty.
924 Use @ref litePDF_SetSignatureDate, @ref litePDF_SetSignatureReason,
925 @ref litePDF_SetSignatureLocation, @ref litePDF_SetSignatureCreator,
926 @ref litePDF_SetSignatureAppearance and such to populate it with required values.
927 Finally, to sign the signature field use @ref litePDF_SaveToFileWithSign family
928 functions.
929
930 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
931 @param name Signature field name to use. This should be unique.
932 @param annotationPageIndex Page index where to place the signature annotation.
933 @param annotationX_u X-origin of the annotation on the page, in the current unit.
934 @param annotationY_u Y-origin of the annotation on the page, in the current unit.
935 @param annotationWidth_u Width of the annotation on the page, in the current unit.
936 @param annotationHeight_u Height of the annotation on the page, in the current unit.
937 @param annotationFlags Bit-or of LITEPDF_ANNOTATION_FLAG_ flags.
938 @param pAddedIndex [out] Optional parameter, if not NULL, then it's populated with
939 the index of the added signature field.
940 @return Whether succeeded. The call can also fail when a signature field of the same
941 name already exists.
942
943 @see litePDF_GetSignatureCount, litePDF_GetSignatureName
944 */
945
946 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetSignatureHasData(void *pctx,
947 unsigned int index,
948 BOOL *pHasData);
949 /**<
950 Checks whether the given signature field contains any data, which
951 means whether the signature field is signed.
952
953 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
954 @param index Which signature data to get; counts from 0. This might be less
955 than @ref litePDF_GetSignatureCount.
956 @param pHasData [out] Set to TRUE, when the given signature contains any data.
957 @return Whether succeeded.
958
959 @see litePDF_GetSignatureData
960 */
961
962 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetSignatureData(void *pctx,
963 unsigned int index,
964 BYTE *data,
965 unsigned int *dataLength);
966 /**<
967 Gathers raw signature data for the given signature in the currently opened document.
968 Use @ref litePDF_GetSignatureHasData to check whether the given signature field
969 is signed or not.
970
971 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
972 @param index Which signature data to get; counts from 0. This might be less
973 than @ref litePDF_GetSignatureCount.
974 @param data [out] Actual data to store the signature content to. It can be NULL, in which case
975 the @a dataLength is populated with large-enough value to hold the whole data.
976 @param dataLength [in/out] Tells how many bytes can be stored in @a data. If @a data
977 is NULL, then it is set to large-enough value. Passing non-NULL @a data with no enough
978 large buffer results in a failure with no change on @a dataLength.
979 @return Whether succeeded.
980
981 @see litePDF_GetDocumentIsSigned, litePDF_GetSignatureCount, litePDF_GetSignatureRanges
982 */
983
984 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetSignatureRanges(void *pctx,
985 unsigned int index,
986 unsigned __int64 *pRangesArray,
987 unsigned int *pRangesArrayLength);
988 /**<
989 Gathers signature ranges, that is the actual offsets into the opened file
990 which had been used to create the signature data (@ref litePDF_GetSignatureData).
991 The array is a pair of numbers, where the first number is an offset into the file
992 from its beginning and the second number is the number of bytes being used for
993 the signature from this offset.
994
995 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
996 @param index Which signature ranges to get; counts from 0. This might be less
997 than @ref litePDF_GetSignatureCount.
998 @param pRangesArray [out] Actual array to store the signature ranges to. It can be NULL,
999 in which case the @a pRangesArrayLength is populated with large-enough value to hold
1000 the whole array.
1001 @param pRangesArrayLength [in/out] Tells how many items can be stored in @a pRangesArray.
1002 If @a pRangesArray is NULL, then it is set to large-enough value. Passing non-NULL
1003 @a pRangesArray with no enough large array results in a failure with no change
1004 on @a pRangesArrayLength.
1005 @return Whether succeeded.
1006
1007 @note This function works only for the signatures which use this kind of signature method.
1008
1009 @see litePDF_GetDocumentIsSigned, litePDF_GetSignatureCount, litePDF_GetSignatureData
1010 */
1011
1012 BOOL __stdcall LITEPDF_PUBLIC litePDF_SetSignatureDate(void *pctx,
1013 unsigned int index,
1014 __int64 dateOfSign);
1015 /**<
1016 Sets signature field date of sign.
1017
1018 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1019 @param index Which signature to use; counts from 0. This might be less
1020 than @ref litePDF_GetSignatureCount.
1021 @param dateOfSign Date of sign, like Unix time_t, when the signature was created; less than
1022 or equal to 0 means today. The value can be clamp on 32-bit systems.
1023 @return Whether succeeded.
1024
1025 @see litePDF_GetSignatureDate, litePDF_GetSignatureCount
1026 */
1027
1028 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetSignatureDate(void *pctx,
1029 unsigned int index,
1030 __int64 *pDateOfSign);
1031 /**<
1032 Gets signature field date of sign.
1033
1034 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1035 @param index Which signature to use; counts from 0. This might be less
1036 than @ref litePDF_GetSignatureCount.
1037 @param pDateOfSign [out] A variable where to store the date of sign. It's like Unix time_t,
1038 as set by the signature field creator. The value can be clamp on 32-bit systems.
1039 @return Whether succeeded.
1040
1041 @see litePDF_SetSignatureDate, litePDF_GetSignatureCount
1042 */
1043
1044 BOOL __stdcall LITEPDF_PUBLIC litePDF_SetSignatureReason(void *pctx,
1045 unsigned int index,
1046 const wchar_t *reason);
1047 /**<
1048 Sets signature reason.
1049
1050 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1051 @param index Which signature to use; counts from 0. This might be less
1052 than @ref litePDF_GetSignatureCount.
1053 @param reason The value to set.
1054 @return Whether succeeded.
1055
1056 @see litePDF_GetSignatureReason, litePDF_GetSignatureCount
1057 */
1058
1059 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetSignatureReason(void *pctx,
1060 unsigned int index,
1061 wchar_t *value,
1062 unsigned int *valueLength);
1063 /**<
1064 Gets signature reason.
1065
1066 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1067 @param index Which signature to use; counts from 0. This might be less
1068 than @ref litePDF_GetSignatureCount.
1069 @param value [out] Null-terminated Unicode value. It can be NULL, in which case
1070 the @a valueLength is populated with large-enough value to hold the whole string.
1071 @param valueLength [in/out] Tells how many characters can be stored in @a value. If @a value
1072 is NULL, then it is set to large-enough value (not including the Null-termination character).
1073 Passing non-NULL @a value with no enough large buffer results in a failure with no change
1074 on @a valueLength. The @a valueLength has stored count of characters written, not including
1075 the Null-termination character on success.
1076 @return Whether succeeded.
1077
1078 @see litePDF_SetSignatureReason, litePDF_GetSignatureCount
1079 */
1080
1081 BOOL __stdcall LITEPDF_PUBLIC litePDF_SetSignatureLocation(void *pctx,
1082 unsigned int index,
1083 const wchar_t *location);
1084 /**<
1085 Sets signature location, aka where the signature had been made. This can be left unset.
1086
1087 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1088 @param index Which signature to use; counts from 0. This might be less
1089 than @ref litePDF_GetSignatureCount.
1090 @param location The value to set.
1091 @return Whether succeeded.
1092
1093 @see litePDF_GetSignatureLocation, litePDF_GetSignatureCount
1094 */
1095
1096 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetSignatureLocation(void *pctx,
1097 unsigned int index,
1098 wchar_t *value,
1099 unsigned int *valueLength);
1100 /**<
1101 Gets signature location.
1102
1103 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1104 @param index Which signature to use; counts from 0. This might be less
1105 than @ref litePDF_GetSignatureCount.
1106 @param value [out] Null-terminated Unicode value. It can be NULL, in which case
1107 the @a valueLength is populated with large-enough value to hold the whole string.
1108 @param valueLength [in/out] Tells how many characters can be stored in @a value. If @a value
1109 is NULL, then it is set to large-enough value (not including the Null-termination character).
1110 Passing non-NULL @a value with no enough large buffer results in a failure with no change
1111 on @a valueLength. The @a valueLength has stored count of characters written, not including
1112 the Null-termination character on success.
1113 @return Whether succeeded.
1114
1115 @see litePDF_SetSignatureLocation, litePDF_GetSignatureCount
1116 */
1117
1118 BOOL __stdcall LITEPDF_PUBLIC litePDF_SetSignatureCreator(void *pctx,
1119 unsigned int index,
1120 const char *creator);
1121 /**<
1122 Sets signature creator. This can be left unset.
1123
1124 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1125 @param index Which signature to use; counts from 0. This might be less
1126 than @ref litePDF_GetSignatureCount.
1127 @param creator The value to set.
1128 @return Whether succeeded.
1129
1130 @see litePDF_GetSignatureCreator, litePDF_GetSignatureCount
1131 */
1132
1133 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetSignatureCreator(void *pctx,
1134 unsigned int index,
1135 char *value,
1136 unsigned int *valueLength);
1137 /**<
1138 Gets signature creator.
1139
1140 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1141 @param index Which signature to use; counts from 0. This might be less
1142 than @ref litePDF_GetSignatureCount.
1143 @param value [out] Null-terminated ASCII value. It can be NULL, in which case
1144 the @a valueLength is populated with large-enough value to hold the whole string.
1145 @param valueLength [in/out] Tells how many characters can be stored in @a value. If @a value
1146 is NULL, then it is set to large-enough value (not including the Null-termination character).
1147 Passing non-NULL @a value with no enough large buffer results in a failure with no change
1148 on @a valueLength. The @a valueLength has stored count of characters written, not including
1149 the Null-termination character on success.
1150 @return Whether succeeded.
1151
1152 @see litePDF_SetSignatureCreator, litePDF_GetSignatureCount
1153 */
1154
1155 #define LITEPDF_APPEARANCE_NORMAL (0) /**< Normal appearance */
1156 #define LITEPDF_APPEARANCE_ROLLOVER (1) /**< Rollover appearance; the default is the normal appearance */
1157 #define LITEPDF_APPEARANCE_DOWN (2) /**< Down appearance; the default is the normal appearance */
1158
1159 BOOL __stdcall LITEPDF_PUBLIC litePDF_SetSignatureAppearance(void *pctx,
1160 unsigned int index,
1161 unsigned int appearanceType,
1162 unsigned int resourceID,
1163 int offsetX_u,
1164 int offsetY_u);
1165 /**<
1166 Sets the signature appearance.
1167
1168 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1169 @param index Which signature to use; counts from 0. This might be less
1170 than @ref litePDF_GetSignatureCount.
1171 @param appearanceType One of the @ref LITEPDF_APPEARANCE_NORMAL, @ref LITEPDF_APPEARANCE_ROLLOVER
1172 and @ref LITEPDF_APPEARANCE_DOWN constants. At least the @ref LITEPDF_APPEARANCE_NORMAL type
1173 should be set, if the appearance of the signature is requested.
1174 @param resourceID An existing resource ID of the annotation content, as shown to the user.
1175 @param offsetX_u X-offset of the resource inside the annotation of the signature, in the current unit.
1176 @param offsetY_u Y-offset of the resource inside the annotation of the signature, in the current unit.
1177 @return Whether succeeded.
1178
1179 @note The resource position offset is from [left, top] corner of the annotation rectangle.
1180
1181 @see litePDF_GetUnit, litePDF_AddResource, litePDF_GetSignatureCount, litePDF_CreateSignature
1182 */
1183
1184 #define LITEPDF_CERTIFICATION_PERMISSION_NO_PERMS (1) /**< No changes to the document are permitted; any change to the document invalidates the signature. */
1185 #define LITEPDF_CERTIFICATION_PERMISSION_FORM_FILL (2) /**< Permitted changes are filling in forms, instantiating page templates, and signing; other changes invalidate the signature. */
1186 #define LITEPDF_CERTIFICATION_PERMISSION_ANNOTATIONS (3) /**< Permitted changes are the same as for @ref LITEPDF_CERTIFICATION_PERMISSION_FORM_FILL, as well as annotation creation, deletion, and modification; other changes invalidate the signature. */
1187
1188 BOOL __stdcall LITEPDF_PUBLIC litePDF_SetSignatureCertification(void *pctx,
1189 unsigned int index,
1190 unsigned int permission);
1191 /**<
1192 Sets the signature certification. This is used to detect modifications relative to a signature
1193 field that is signed by the author of a document (the person applying the first signature). A document
1194 can contain only one signature field that contains the access permissions; it should be the first
1195 signed field in the document. It enables the author to specify what changes are permitted to be
1196 made the document and what changes invalidate the author’s signature.
1197
1198 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1199 @param index Which signature to use; counts from 0. This might be less
1200 than @ref litePDF_GetSignatureCount.
1201 @param permission One of the @ref LITEPDF_CERTIFICATION_PERMISSION_NO_PERMS, @ref LITEPDF_CERTIFICATION_PERMISSION_FORM_FILL
1202 and @ref LITEPDF_CERTIFICATION_PERMISSION_ANNOTATIONS constants.
1203
1204 @see litePDF_CreateSignature
1205 */
1206
1207 BOOL __stdcall LITEPDF_PUBLIC litePDF_SetSignatureSize(void *pctx,
1208 unsigned int requestBytes);
1209 /**<
1210 Sets how many bytes the signature may require. The default value is 4096 bytes
1211 and it is automatically adjusted when the @ref litePDF_SaveToFileWithSign or
1212 @ref litePDF_SaveToDataWithSign are used. The manual signing functions
1213 require this value to be set before signing, if the final hash with the certificate
1214 exceeds the default size.
1215
1216 This value is remembered in general, not for any signature in particular.
1217
1218 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1219 @param requestBytes How many bytes the signature will require.
1220 @return Whether succeeded.
1221
1222 @see litePDF_SetSignatureHash, litePDF_SaveToFileWithSignManual, litePDF_SaveToFileWithSignManualW, litePDF_SaveToDataWithSignManual
1223 */
1224
1225 #define LITEPDF_SIGNATURE_HASH_SHA1 1 /**< Use SHA1 hash algorithm */
1226 #define LITEPDF_SIGNATURE_HASH_SHA256 2 /**< Use SHA256 hash algorithm */
1227 #define LITEPDF_SIGNATURE_HASH_SHA384 3 /**< Use SHA384 hash algorithm */
1228 #define LITEPDF_SIGNATURE_HASH_SHA512 4 /**< Use SHA512 hash algorithm */
1229
1230 BOOL __stdcall LITEPDF_PUBLIC litePDF_SetSignatureHash(void *pctx,
1231 unsigned int signatureHash);
1232 /**<
1233 Sets the signature hash algorithm to be used. The default value is @ref LITEPDF_SIGNATURE_HASH_SHA512.
1234 It is used only when the @ref litePDF_SaveToFileWithSign or
1235 @ref litePDF_SaveToDataWithSign are used. The supported
1236 values are @ref LITEPDF_SIGNATURE_HASH_SHA1, @ref LITEPDF_SIGNATURE_HASH_SHA256,
1237 @ref LITEPDF_SIGNATURE_HASH_SHA384 and @ref LITEPDF_SIGNATURE_HASH_SHA512.
1238
1239 This value is remembered in general, not for any signature in particular.
1240
1241 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1242 @param signatureHash The hash algorithm to use.
1243 @return Whether succeeded.
1244
1245 @see litePDF_SetSignatureSize, litePDF_SaveToFileWithSignManual, litePDF_SaveToFileWithSignManualW, litePDF_SaveToDataWithSignManual
1246 */
1247
1248 BOOL __stdcall LITEPDF_PUBLIC litePDF_AddSignerPFX(void *pctx,
1249 const BYTE *pfxData,
1250 unsigned int pfxDataLength,
1251 const char *pfxPassword);
1252 /**<
1253 Adds a signer to be used when digitally signing the document with
1254 @ref litePDF_SaveToFileWithSign or @ref litePDF_SaveToDataWithSign.
1255 The passed-in certificate is in the PFX format and should include
1256 the private key.
1257
1258 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1259 @param pfxData A certificate with private key in the PFX format.
1260 @param pfxDataLength A length of the @a pfxData.
1261 @param pfxPassword A password to use to open the PFX certificate; can be NULL.
1262 @return Whether succeeded.
1263
1264 @see litePDF_AddSignerPEM
1265 */
1266
1267 BOOL __stdcall LITEPDF_PUBLIC litePDF_AddSignerPEM(void *pctx,
1268 const BYTE *pemData,
1269 unsigned int pemDataLength,
1270 const BYTE *pkeyData,
1271 unsigned int pkeyDataLength,
1272 const char *pkeyPassword);
1273 /**<
1274 Adds a signer to be used when digitally signing the document with
1275 @ref litePDF_SaveToFileWithSign or @ref litePDF_SaveToDataWithSign.
1276 The passed-in certificate and private key are in the PEM format.
1277
1278 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1279 @param pemData A certificate in the PEM format.
1280 @param pemDataLength A length of the @a pemData.
1281 @param pkeyData A private key for the certificate, in the PEM format.
1282 @param pkeyDataLength A length of the @a pkeyData.
1283 @param pkeyPassword A password to use to open the private key; can be NULL.
1284 @return Whether succeeded.
1285
1286 @see litePDF_AddSignerPFX
1287 */
1288
1289 BOOL __stdcall LITEPDF_PUBLIC litePDF_SaveToFileWithSign(void *pctx,
1290 const char *fileName,
1291 unsigned int signatureIndex);
1292 /**<
1293 Digitally signs a PDF document opened at the litePDF context. The caller is
1294 responsible to set at least one signer with either @ref litePDF_AddSignerPFX
1295 or @ref litePDF_AddSignerPEM first. An alternative @ref litePDF_SaveToFileWithSignManual
1296 is provided when it's required to compute the signature hash manually by the caller.
1297
1298 In case the document had been loaded with @ref litePDF_LoadFromFile,
1299 @ref litePDF_LoadFromFileW or @ref litePDF_LoadFromData with its @a forUpdate
1300 parameter being TRUE, the resulting document will contain the changes as
1301 an incremental update (appended at the end of the original document), otherwise
1302 the whole document is completely rewritten.
1303
1304 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1305 @param fileName A file name where to save signed PDF document.
1306 @param signatureIndex Which signature to use; counts from 0. This might be less
1307 than @ref litePDF_GetSignatureCount.
1308 @return Whether succeeded.
1309
1310 @note The only valid operation after this is either close the document
1311 with @ref litePDF_Close, or free the context with @ref litePDF_FreeContext.
1312
1313 @note Signing already signed document can cause breakage of previous signatures, thus
1314 check whether the loaded document is already signed with @ref litePDF_GetDocumentIsSigned.
1315 Load the document with its @a forUpdate parameter set to TRUE, to sign an existing document.
1316
1317 @see litePDF_SaveToFileWithSignW, litePDF_SaveToDataWithSign
1318 */
1319
1320 BOOL __stdcall LITEPDF_PUBLIC litePDF_SaveToFileWithSignW(void *pctx,
1321 const wchar_t *fileName,
1322 unsigned int signatureIndex);
1323 /**<
1324 This is the same as @ref litePDF_SaveToFileWithSign, the only difference is that
1325 the @a fileName is a wide string.
1326 */
1327
1328 BOOL __stdcall LITEPDF_PUBLIC litePDF_SaveToDataWithSign(void *pctx,
1329 unsigned int signatureIndex,
1330 BYTE *data,
1331 unsigned int *dataLength);
1332 /**<
1333 Digitally signs a PDF document opened at the litePDF context. The caller is
1334 responsible to set at least one signer with either @ref litePDF_AddSignerPFX
1335 or @ref litePDF_AddSignerPEM first. An alternative @ref litePDF_SaveToDataWithSignManual
1336 is provided when it's required to compute the signature hash manually by the caller.
1337
1338 In case the document had been loaded with @ref litePDF_LoadFromFile,
1339 @ref litePDF_LoadFromFileW or @ref litePDF_LoadFromData with its @a forUpdate
1340 parameter being TRUE, the resulting document will contain the changes as
1341 an incremental update (appended at the end of the original document), otherwise
1342 the whole document is completely rewritten.
1343
1344 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1345 @param signatureIndex Which signature to use; counts from 0. This might be less
1346 than @ref litePDF_GetSignatureCount.
1347 @param data [out] Actual data to store the PDF content to. It can be NULL, in which case
1348 the @a dataLength is populated with large-enough value to hold the whole data.
1349 @param dataLength [in/out] Tells how many bytes can be stored in @a data. If @a data
1350 is NULL, then it is set to large-enough value. Passing non-NULL @a data with no enough
1351 large buffer results in a failure with no change on @a dataLength.
1352 @return Whether succeeded.
1353
1354 @note The only valid operation after this is either call of @ref litePDF_SaveToDataWithSign again,
1355 to get information about necessary buffer size or data itself, close the document
1356 with @ref litePDF_Close, or free the context with @ref litePDF_FreeContext.
1357
1358 @note Signing already signed document can cause breakage of previous signatures, thus
1359 check whether the loaded document is already signed with @ref litePDF_GetDocumentIsSigned.
1360 Load the document with its @a forUpdate parameter set to TRUE, to sign an existing document.
1361
1362 @see litePDF_SaveToFileWithSign
1363 */
1364
1365 typedef void (__stdcall *litePDF_appendSignatureDataFunc)(const char *bytes,
1366 unsigned int bytes_len,
1367 void *user_data);
1368 /**<
1369 The function is used within @ref litePDF_SaveToFileWithSignManual and @ref litePDF_SaveToDataWithSignManual.
1370 It is called called when more data should be added to hash computation.
1371 */
1372
1373 typedef void (__stdcall *litePDF_finishSignatureFunc)(char *signature,
1374 unsigned int *signature_len,
1375 void *user_data);
1376 /**<
1377 The function is used within @ref litePDF_SaveToFileWithSignManual and @ref litePDF_SaveToDataWithSignManual.
1378 It is called when all the data are processed and the signature value is required.
1379 The @a signature_len contains size of the @a signature buffer. The callback is
1380 responsible to populate @a signature and @a signature_len with correct values.
1381 Set @a signature_len to zero on any error. Note the callback is called only once.
1382 */
1383
1384 BOOL __stdcall LITEPDF_PUBLIC litePDF_SaveToFileWithSignManual(void *pctx,
1385 const char *fileName,
1386 unsigned int signatureIndex,
1387 litePDF_appendSignatureDataFunc appendSignatureData,
1388 void *append_user_data,
1389 litePDF_finishSignatureFunc finishSignature,
1390 void *finish_user_data);
1391 /**<
1392 Digitally signs a PDF document opened at the litePDF context. The caller is
1393 responsible for a detached hash computations and related certificate management.
1394
1395 In case the document had been loaded with @ref litePDF_LoadFromFile,
1396 @ref litePDF_LoadFromFileW or @ref litePDF_LoadFromData with its @a forUpdate
1397 parameter being TRUE, the resulting document will contain the changes as
1398 an incremental update (appended at the end of the original document), otherwise
1399 the whole document is completely rewritten.
1400
1401 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1402 @param fileName A file name where to save signed PDF document.
1403 @param signatureIndex Which signature to use; counts from 0. This might be less
1404 than @ref litePDF_GetSignatureCount.
1405 @param appendSignatureData Called when more data should be added to hash computation.
1406 The function cannot be NULL, even when called the second time, to get actual data.
1407 @param append_user_data User data value for the @a appendSignatureData callback.
1408 @param finishSignature Called when all the data are processed, and the signature
1409 value is required. The @a signature_len contains size of the @a signature buffer.
1410 The callback is responsible to populate @a signature and @a signature_len with
1411 correct values. Set @a signature_len to zero on any error.
1412 Note the callback is called only once.
1413 The function cannot be NULL, even when called the second time, to get actual data.
1414 @param finish_user_data User data value for the @a finishSignature callback.
1415 @return Whether succeeded.
1416
1417 @note The only valid operation after this is either close the document
1418 with @ref litePDF_Close, or free the context with @ref litePDF_FreeContext.
1419
1420 @note Signing already signed document can cause breakage of previous signatures, thus
1421 check whether the loaded document is already signed with @ref litePDF_GetDocumentIsSigned.
1422 Load the document with its @a forUpdate parameter set to TRUE, to sign an existing document.
1423
1424 @see litePDF_SaveToFileWithSign, litePDF_SaveToFileWithSignManualW, litePDF_SaveToDataWithSignManual
1425 */
1426
1427 BOOL __stdcall LITEPDF_PUBLIC litePDF_SaveToFileWithSignManualW(void *pctx,
1428 const wchar_t *fileName,
1429 unsigned int signatureIndex,
1430 litePDF_appendSignatureDataFunc appendSignatureData,
1431 void *append_user_data,
1432 litePDF_finishSignatureFunc finishSignature,
1433 void *finish_user_data);
1434 /**<
1435 This is the same as @ref litePDF_SaveToFileWithSignManual, the only difference is that
1436 the @a fileName is a wide string.
1437 */
1438
1439 BOOL __stdcall LITEPDF_PUBLIC litePDF_SaveToDataWithSignManual(void *pctx,
1440 unsigned int signatureIndex,
1441 litePDF_appendSignatureDataFunc appendSignatureData,
1442 void *append_user_data,
1443 litePDF_finishSignatureFunc finishSignature,
1444 void *finish_user_data,
1445 BYTE *data,
1446 unsigned int *dataLength);
1447 /**<
1448 Digitally signs a PDF document opened at the litePDF context. The caller is
1449 responsible for a detached hash computations and related certificate management.
1450
1451 In case the document had been loaded with @ref litePDF_LoadFromFile,
1452 @ref litePDF_LoadFromFileW or @ref litePDF_LoadFromData with its @a forUpdate
1453 parameter being TRUE, the resulting document will contain the changes as
1454 an incremental update (appended at the end of the original document), otherwise
1455 the whole document is completely rewritten.
1456
1457 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1458 @param signatureIndex Which signature to use; counts from 0. This might be less
1459 than @ref litePDF_GetSignatureCount.
1460 @param appendSignatureData Called when more data should be added to hash computation.
1461 The function cannot be NULL, even when called the second time, to get actual data.
1462 @param append_user_data User data value for the @a appendSignatureData callback.
1463 @param finishSignature Called when all the data are processed, and the signature
1464 value is required. The @a signature_len contains size of the @a signature buffer.
1465 The callback is responsible to populate @a signature and @a signature_len with
1466 correct values. Set @a signature_len to zero on any error.
1467 Note the callback is called only once.
1468 The function cannot be NULL, even when called the second time, to get actual data.
1469 @param finish_user_data User data value for the @a finishSignature callback.
1470 @param data [out] Actual data to store the PDF content to. It can be NULL, in which case
1471 the @a dataLength is populated with large-enough value to hold the whole data.
1472 @param dataLength [in/out] Tells how many bytes can be stored in @a data. If @a data
1473 is NULL, then it is set to large-enough value. Passing non-NULL @a data with no enough
1474 large buffer results in a failure with no change on @a dataLength.
1475 @return Whether succeeded.
1476
1477 @note The only valid operation after this is either call of @ref litePDF_SaveToDataWithSignManual again,
1478 to get information about necessary buffer size or data itself, close the document
1479 with @ref litePDF_Close, or free the context with @ref litePDF_FreeContext.
1480
1481 @note Signing already signed document can cause breakage of previous signatures, thus
1482 check whether the loaded document is already signed with @ref litePDF_GetDocumentIsSigned.
1483 Load the document with its @a forUpdate parameter set to TRUE, to sign an existing document.
1484
1485 @see litePDF_SaveToFileWithSignManual, litePDF_SaveToFileWithSign
1486 */
1487
1488 BOOL __stdcall LITEPDF_PUBLIC litePDF_EmbedFile(void *pctx,
1489 const char *fileName);
1490 /**<
1491 Embeds a file into a PDF document.
1492
1493 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1494 @param fileName File name of the file to be attached.
1495 @return Whether succeeded.
1496
1497 @note Files can be embed only to memory-based documents.
1498
1499 @note The path is stripped from the @a fileName. The @a fileName is used as a key,
1500 aka it's not possible to embed two files of the same name into a PDF document.
1501
1502 @see litePDF_EmbedFileW, litePDF_EmbedData, litePDF_CreateMemDocument
1503 */
1504
1505 BOOL __stdcall LITEPDF_PUBLIC litePDF_EmbedFileW(void *pctx,
1506 const wchar_t *fileName);
1507 /**<
1508 This is the same as @ref litePDF_EmbedFile, the only difference is that
1509 the @a fileName is a wide string.
1510 */
1511
1512 BOOL __stdcall LITEPDF_PUBLIC litePDF_EmbedData(void *pctx,
1513 const char *fileName,
1514 const BYTE *data,
1515 unsigned int dataLength);
1516 /**<
1517 Embeds a data (file) into a PDF document.
1518
1519 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1520 @param fileName File name to be used for the data identification.
1521 @param data Actual data to be attached.
1522 @param dataLength Length of the data.
1523 @return Whether succeeded.
1524
1525 @note Data can be embed only to memory-based documents.
1526
1527 @note The path is stripped from the @a fileName. The @a fileName is used as a key,
1528 aka it's not possible to embed two files of the same name into a PDF document.
1529
1530 @see litePDF_EmbedDataW, litePDF_EmbedFile, litePDF_CreateMemDocument
1531 */
1532
1533 BOOL __stdcall LITEPDF_PUBLIC litePDF_EmbedDataW(void *pctx,
1534 const wchar_t *fileName,
1535 const BYTE *data,
1536 unsigned int dataLength);
1537 /**<
1538 This is the same as @ref litePDF_EmbedData, the only difference is that
1539 the @a fileName is a wide string.
1540 */
1541
1542
1543 INT __stdcall LITEPDF_PUBLIC litePDF_GetEmbeddedFileCount(void *pctx);
1544 /**<
1545 Gets count of embedded files stored in a PDF document.
1546
1547 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1548 @return Count of found embedded files, or -1 on error.
1549
1550 @see litePDF_EmbedFile, litePDF_EmbedData, litePDF_GetEmbeddedFileName,
1551 litePDF_GetEmbeddedFileData
1552 */
1553
1554 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetEmbeddedFileName(void *pctx,
1555 unsigned int index,
1556 char *fileName,
1557 unsigned int *fileNameLength);
1558 /**<
1559 Gets embedded file's name, as stored in a PDF document.
1560
1561 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1562 @param index Index of the embedded file; returns failure, if out of range.
1563 @param fileName [out] Buffer to store the embedded file's name to. It can be NULL,
1564 in which case the @a fileNameLength is populated with large-enough value to hold
1565 the whole string.
1566 @param fileNameLength [in/out] Tells how many characters can be stored in @a fileName.
1567 If @a fileName is NULL, then it is set to large-enough value. Passing
1568 non-NULL @a fileName with no enough large buffer results in a failure with
1569 no change on @a fileNameLength. The set length is without the Null-terminate character.
1570 @return Whether succeeded.
1571
1572 @see litePDF_GetEmbeddedFileNameW, litePDF_EmbedFile, litePDF_EmbedData, litePDF_GetEmbeddedFileCount,
1573 litePDF_GetEmbeddedFileData
1574 */
1575
1576 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetEmbeddedFileNameW(void *pctx,
1577 unsigned int index,
1578 wchar_t *fileName,
1579 unsigned int *fileNameLength);
1580 /**<
1581 This is the same as @ref litePDF_GetEmbeddedFileName, the only difference is that
1582 the @a fileName is a wide string.
1583 */
1584
1585 BOOL __stdcall LITEPDF_PUBLIC litePDF_GetEmbeddedFileData(void *pctx,
1586 unsigned int index,
1587 BYTE *data,
1588 unsigned int *dataLength);
1589 /**<
1590 Gets embedded file's data, as stored in a PDF document. There are no data returned,
1591 if the file was not embed.
1592
1593 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext.
1594 @param index Index of the embedded file; returns failure, if out of range.
1595 @param data [out] Actual embedded file's data, as stored in the PDF. It can be NULL, in which case
1596 the @a dataLength is populated with large-enough value to hold the whole data.
1597 @param dataLength [in/out] Tells how many bytes can be stored in @a data. If @a data
1598 is NULL, then it is set to large-enough value. Passing non-NULL @a data with no enough
1599 large buffer results in a failure with no change on @a dataLength.
1600 @return Whether succeeded.
1601
1602 @see litePDF_EmbedFile, litePDF_EmbedData, litePDF_GetEmbeddedFileCount,
1603 litePDF_GetEmbeddedFileName
1604 */
1605
1606 void * __stdcall LITEPDF_PUBLIC litePDF_GetPoDoFoDocument(void *pctx);
1607 /**<
1608 Gets a pointer to PoDoFo::PdfDocument document, which is currently opened.
1609 The returned pointer is owned by litePDF, do not free it. It is valid until
1610 the document is closed.
1611
1612 @return Pointer to currently opened PoDoFo::PdfDocument.
1613
1614 @see litePDF_Close
1615 */
1616
1617 BOOL __stdcall LITEPDF_PUBLIC litePDF_DrawDebugPage(void *pctx,
1618 const char *filename);
1619 /**<
1620 Draws saved debugPage as a new page into the PDF file. There should not be
1621 running any drawing when calling this function (like no page can be opened
1622 for drawing).
1623
1624 @param pctx litePDF context, previously created with @ref litePDF_CreateContext.
1625 @param filename File name with full path for litePDF debug page.
1626 */
1627
1628 BOOL __stdcall LITEPDF_PUBLIC litePDF_CreateLinkAnnotation(void *pctx,
1629 unsigned int annotationPageIndex,
1630 int annotationX_u,
1631 int annotationY_u,
1632 int annotationWidth_u,
1633 int annotationHeight_u,
1634 unsigned int annotationFlags,
1635 unsigned int annotationResourceID,
1636 unsigned int destinationPageIndex,
1637 unsigned int destinationX_u,
1638 unsigned int destinationY_u,
1639 const wchar_t *destinationDescription);
1640 /**<
1641 Creates a link annotation at the given page and position, which will target the given
1642 destination page and the position in it. The context should hold a memory-based document.
1643 Note, the link annotation can be created only when the document is not drawing, to
1644 have all the document pages available.
1645
1646 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext,
1647 to which add the link annotation.
1648 @param annotationPageIndex Page index where to place the link annotation.
1649 @param annotationX_u X-origin of the annotation on the page, in the current unit.
1650 @param annotationY_u Y-origin of the annotation on the page, in the current unit.
1651 @param annotationWidth_u Width of the annotation on the page, in the current unit.
1652 @param annotationHeight_u Height of the annotation on the page, in the current unit.
1653 @param annotationFlags Bit-or of LITEPDF_ANNOTATION_FLAG_ flags.
1654 @param annotationResourceID Optional resource ID of the annotation content, as shown
1655 to the user. 0 means do not add additional visualization on the page, but the annotation
1656 can be still clicked.
1657 @param destinationPageIndex Page index where the link points to.
1658 @param destinationX_u X-origin of the destination on the page, in the current unit.
1659 @param destinationY_u Y-origin of the destination on the page, in the current unit.
1660 @param destinationDescription Optional destination description, which can be used
1661 for accessibility reasons by the viewer.
1662 @return Whether succeeded.
1663
1664 @see litePDF_GetUnit, litePDF_GetPageCount, litePDF_AddResource, litePDF_CreateBookmarkRoot
1665 */
1666
1667 BOOL __stdcall LITEPDF_PUBLIC litePDF_CreateURIAnnotation(void *pctx,
1668 unsigned int annotationPageIndex,
1669 int annotationX_u,
1670 int annotationY_u,
1671 int annotationWidth_u,
1672 int annotationHeight_u,
1673 unsigned int annotationFlags,
1674 unsigned int annotationResourceID,
1675 const char *destinationURI,
1676 const wchar_t *destinationDescription);
1677 /**<
1678 Creates a URI annotation at the given page and position, which will reference the given
1679 destination URI. The context should hold a memory-based document.
1680 Note, the URI annotation can be created only when the document is not drawing, to
1681 have all the document pages available.
1682
1683 @param pctx a litePDF context, previously created with @ref litePDF_CreateContext,
1684 to which add the URI annotation.
1685 @param annotationPageIndex Page index where to place the URI annotation.
1686 @param annotationX_u X-origin of the annotation on the page, in the current unit.
1687 @param annotationY_u Y-origin of the annotation on the page, in the current unit.
1688 @param annotationWidth_u Width of the annotation on the page, in the current unit.
1689 @param annotationHeight_u Height of the annotation on the page, in the current unit.
1690 @param annotationFlags Bit-or of LITEPDF_ANNOTATION_FLAG_ flags.
1691 @param annotationResourceID Optional resource ID of the annotation content, as shown
1692 to the user. 0 means do not add additional visualization on the page, but the annotation
1693 can be still clicked.
1694 @param destinationURI The URI the annotation points to.
1695 @param destinationDescription Optional destination description, which can be used
1696 for accessibility reasons by the viewer.
1697 @return Whether succeeded.
1698
1699 @see litePDF_GetUnit, litePDF_GetPageCount, litePDF_AddResource
1700 */
1701
1702 #define LITEPDF_BOOKMARK_FLAG_NONE 0x0000 /**< Default bookmark flags */
1703 #define LITEPDF_BOOKMARK_FLAG_ITALIC 0x0001 /**< Show bookmark title as an italic text */
1704 #define LITEPDF_BOOKMARK_FLAG_BOLD 0x0002 /**< Show bookmark title as a bold text */
1705
1706 unsigned int __stdcall LITEPDF_PUBLIC litePDF_CreateBookmarkRoot(void *pctx,
1707 const wchar_t *title,
1708 unsigned int flags,
1709 unsigned char titleColor_red,
1710 unsigned char titleColor_green,
1711 unsigned char titleColor_blue,
1712 unsigned int destinationPageIndex,
1713 unsigned int destinationX_u,
1714 unsigned int destinationY_u);
1715 /**<
1716 Creates a new root (top-level) bookmark, which will target the given destination
1717 page and the position in it. The context should hold a memory-based document.
1718 Note, the bookmarks can be created only when the document is not drawing, to
1719 have all the document pages available.
1720
1721 @param pctx A litePDF context, previously created with @ref litePDF_CreateContext,
1722 to which add the link annotation.
1723 @param title Title of the bookmark.
1724 @param flags Bit-or of LITEPDF_BOOKMARK_FLAG_ flags.
1725 @param titleColor_red RGB red value of the title text color.
1726 @param titleColor_green RGB green value of the title text color.
1727 @param titleColor_blue RGB blue value of the title text color.
1728 @param destinationPageIndex Page index where the link points to.
1729 @param destinationX_u X-origin of the destination on the page, in the current unit.
1730 @param destinationY_u Y-origin of the destination on the page, in the current unit.
1731 @return Created bookmark ID or 0, when the bookmark could not be created.
1732
1733 @see litePDF_GetUnit, litePDF_CreateBookmarkChild, litePDF_CreateBookmarkSibling, litePDF_CreateLinkAnnotation
1734 */
1735
1736 unsigned int __stdcall LITEPDF_PUBLIC litePDF_CreateBookmarkChild(void *pctx,
1737 unsigned int parentBookmarkID,
1738 const wchar_t *title,
1739 unsigned int flags,
1740 unsigned char titleColor_red,
1741 unsigned char titleColor_green,
1742 unsigned char titleColor_blue,
1743 unsigned int destinationPageIndex,
1744 unsigned int destinationX_u,
1745 unsigned int destinationY_u);
1746 /**<
1747 Creates a new child bookmark, which will target the given destination
1748 page and the position in it. The context should hold a memory-based document.
1749 Note, the bookmarks can be created only when the document is not drawing, to
1750 have all the document pages available.
1751
1752 @param pctx A litePDF context, previously created with @ref litePDF_CreateContext,
1753 to which add the link annotation.
1754 @param parentBookmarkID Bookmark ID of the parent bookmark. The child will be
1755 created under this bookmark.
1756 @param title Title of the bookmark.
1757 @param flags Bit-or of LITEPDF_BOOKMARK_FLAG_ flags.
1758 @param titleColor_red RGB red value of the title text color.
1759 @param titleColor_green RGB green value of the title text color.
1760 @param titleColor_blue RGB blue value of the title text color.
1761 @param destinationPageIndex Page index where the link points to.
1762 @param destinationX_u X-origin of the destination on the page, in the current unit.
1763 @param destinationY_u Y-origin of the destination on the page, in the current unit.
1764 @return Created bookmark ID or 0, when the bookmark could not be created.
1765
1766 @see litePDF_GetUnit, litePDF_CreateBookmarkRoot, litePDF_CreateBookmarkSibling, litePDF_CreateLinkAnnotation
1767 */
1768
1769 unsigned int __stdcall LITEPDF_PUBLIC litePDF_CreateBookmarkSibling(void *pctx,
1770 unsigned int previousBookmarkID,
1771 const wchar_t *title,
1772 unsigned int flags,
1773 unsigned char titleColor_red,
1774 unsigned char titleColor_green,
1775 unsigned char titleColor_blue,
1776 unsigned int destinationPageIndex,
1777 unsigned int destinationX_u,
1778 unsigned int destinationY_u);
1779 /**<
1780 Creates a new sibling (next) bookmark, which will target the given destination
1781 page and the position in it. The context should hold a memory-based document.
1782 Note, the bookmarks can be created only when the document is not drawing, to
1783 have all the document pages available.
1784
1785 @param pctx A litePDF context, previously created with @ref litePDF_CreateContext,
1786 to which add the link annotation.
1787 @param previousBookmarkID Bookmark ID of the previous bookmark. The sibling will be
1788 created as the next of this bookmark.
1789 @param title Title of the bookmark.
1790 @param flags Bit-or of LITEPDF_BOOKMARK_FLAG_ flags.
1791 @param titleColor_red RGB red value of the title text color.
1792 @param titleColor_green RGB green value of the title text color.
1793 @param titleColor_blue RGB blue value of the title text color.
1794 @param destinationPageIndex Page index where the link points to.
1795 @param destinationX_u X-origin of the destination on the page, in the current unit.
1796 @param destinationY_u Y-origin of the destination on the page, in the current unit.
1797 @return Created bookmark ID or 0, when the bookmark could not be created.
1798
1799 @see litePDF_GetUnit, litePDF_CreateBookmarkRoot, litePDF_CreateBookmarkChild, litePDF_CreateLinkAnnotation
1800 */
1801
1802 LITEPDF_END_DECLS
1803
1804 #endif /* LITEPDF_H */