C API Interface (litePDF.h)

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