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