Miscellaneous Application Programming Interfaces

The following Application Programming Interface functions to Image to PDF are optional:

  I2PDF_DeleteImagesOnConvert
Parameters: None
Return Value: None
Notes:
  • When the PDF document has been successfully produced all of the images that have been converted to PDF are deleted.
    Use this with caution - if this is accidentally used you may be unable to recover any images deleted.

  •   I2PDF_Log
    Parameters: logFilename - specifies the name and location of the log file.
    logLevel - any combination of the following: 0 (normal logging), 1 (include image information), 2 (include font matching information), 4 (include filename wildcard matching information), 8 (include Bates number information)
    Return Value: 0 - success
    1 - invalid logFilename parameter
    Notes:
  • All information and error messages are appended to the end of the file specified (with a timestamp).
  • This provides a complete audit log of any failures plus additional information including image and font information (if required).
  • When the I2PDF_MetaToNativePDF API is used it can be useful to see the results of the font matching that is performed when it is necessary to convert a font reference in the meta image file to an actual font that is available for inclusion in the PDF.
  • If a font cannot be matched then a default Helvetica font is used.
  • You can log one or more items of information by combining the options you want, eg a log level of 5 is the sum of 1 (image information) + 4 (filename wildcard matching information).
  • If you are logging wildcard matching information then this command must be used before the first wildcarded image file is specified otherwise the record of the wildcard matching will not be logged.

  •   I2PDF_WildcardFilenameUse
    Parameters: flags - must be one of the following: 0 (default of one PDF produced per image with no recursion), 1 (one PDF per directory), 2 (recurse down sub-directories), 3 (both one PDF per directory and recursion)
    Return Value: 0 - success
    1 - images have already been added
    Notes:
  • This can only be specified if the PDF filename is *.pdf AND only one wildcarded image name is used.
  • This must be set BEFORE I2PDF_AddImage is used.

  •   I2PDF_TreatImageNumericExtensionAs
    I2PDF_TreatImageNumericExtAs
    Parameters: imageExtension - must be a valid image file extension: ".jpg", ".tif", ".png", ".gif", ".bmp", ".wmf", ".emf", ".tga" or ".pcx"
    Return Value: 0 - success
    1 - invalid imageExtension parameter
    2 - imageExtension does not start with a "."
    3 - imageExtension is not 4 characters long
    Notes:
  • If images are produced using a process which generates sequenced images with numbered extensions eg image.001, image.002 etc this command allows the processing of these images by specifying a valid image extension which should be used in their place.

  •   I2PDF_TreatImageTmpExtensionAs
    I2PDF_TreatImageTmpExtAs
    Parameters: imageExtension - must be a valid image file extension: ".jpg", ".tif", ".png", ".gif", ".bmp", ".wmf", ".emf", ".tga" or ".pcx"
    Return Value: 0 - success
    1 - invalid imageExtension parameter
    2 - imageExtension does not start with a "."
    3 - imageExtension is not 4 characters long
    Notes:
  • If images are produced using a process which generates images with a TMP file extension this command allows the processing of these images by specifying a valid image extension which should be used in their place.

  •   I2PDF_TreatImageExtensionAs
    I2PDF_TreatImageExtAs
    Parameters: sourceExtension - must be a file extension starting with "." - can be up to 10 characters long.
    targetExtension - must be a valid image file extension: ".jpg", ".tif", ".png", ".gif", ".bmp", ".wmf", ".emf", ".tga" or ".pcx"
    Return Value: 0 - success
    1 - invalid sourceExtension parameter
    2 - sourceExtension does not start with a "."
    3 - invalid targetExtension parameter
    4 - targetExtension does not start with a "."
    5 - targetExtension is not 4 characters long
    6 - max image extension mappings already defined
    Notes:
  • If images are produced using a process which generates images with non-standard image file extensions this command allows the processing of these images by specifying a valid image extension which should be used in their place.
  • Up to 100 extension mappings may be defined.

  •   I2PDF_Reset
    Parameters: None
    Return Value: None
    Notes:
  • Reset all settings including the list of images added.
  • This can be useful as an alternative/as well as using the reset option in I2PDF_MakePDF as you can abandon your settings mid-way through setting everything up.

  •   I2PDF_GetDLLVersion
    Parameters: None
    Return Value: Version number of the dll multiplied by one hundred, eg a value of 100 is equivalent to version 1.00.
    Notes:
  • This allows the support of multiple versions of a DLL so that functions that might only be available in a later version can then only be called if the returned version currently being used is one that supports those functions.

  •   I2PDF_SilentRunning
    Parameters: None
    Return Value: None
    Notes:
  • Prevents information from being printed to the console window.

  •   I2PDF_PreventPDFOverwrite
    Parameters: None
    Return Value: None
    Notes:
  • Prevents an existing PDF from being overwritten.

  •   I2PDF_SaveFailureBackupPDF
    Parameters: filename - specifies the name and location of the backup PDF document.
    Return Value: 0 - success
    1 - invalid filename parameter
    Notes:
  • Will save the PDF to a backup filename if the required file cannot be written (perhaps because another application has the target PDF currently open).
  • This actually creates the PDF as the backup filename first, then deletes the target PDF (if it exists) and renames the backup PDF file as the required target PDF.

  •   I2PDF_IncludeTIFFOCRText
    Parameters: None
    Return Value: None
    Notes:
  • If a TIFF file has had it's image OCR'd using Microsoft Document Imaging then the OCR'd text is stored with the image inside the TIFF file.
  • Using this API any such OCR'd text can be included in the output PDF as "invisible" text that allows the PDF to be searchable.

  •   I2PDF_SaveTIFFOCRText
    Parameters: text - can either be the set value FilePerPage which will save the OCR'd text in a file numbered per page or it is the additional text (maximum of 256 characters) between the default two blank lines that are output between pages of text. If spaces are required in the text then enclose it within quotes. Use \n in the text to force a newline to be output.
    Return Value: None
    Notes:
  • If a TIFF file has had it's image OCR'd using Microsoft Document Imaging then the OCR'd text is stored with the image inside the TIFF file.
  • Using this API any such OCR'd text can be output to a file for external indexing/reference.
  • This file is in the same location as the output PDF and has the same name but with a different file extension. Instead of a .pdf extension it will have a .txt one.
  • Sometimes it is useful to have a more visual separator between page text - try using "\n********** PAGE BREAK **********\n\n" instead of ""

  •   I2PDF_LoadImageFailureSkip
    I2PDF_LoadImageFailSkip
    Parameters: None
    Return Value: None
    Notes:
  • If an image fails to be converted for any reason, then the default action is to abandon the production of the PDF. This does mean that any other images that have already been converted into the PDF or are still to be converted are effectively lost until they are converted in the future. This API allows images that fail to be skipped over so that all valid images are still converted and a PDF produced.
  • However, the only way that you would know about a failure is by an ERROR entry in the log file (see I2PDF_Log API) or through the use of the I2PDF_LoadImageFailureCopyTo or I2PDF_LoadImageFailurePage_Real/Int/Web APIs below.

  •   I2PDF_LoadImageFailureCopyTo
    I2PDF_LoadImageFailCopyTo
    Parameters: directory - specifies the name and location of the directory to hold copied images.
    Return Value: 0 - success
    1 - invalid directory
    Notes:
  • If an image fails to be converted for any reason, then the default action is to abandon the production of the PDF. This does mean that any other images that have already been converted into the PDF or are still to be converted are effectively lost until they are converted in the future. This API allows images that fail to be copied to the specified directory (for a manual or monitoring process to deal with) and this would normally be used in conjunction with I2PDF_LoadImageFailureSkip or I2PDF_LoadImageFailurePage_Real/Int/Web so that the image conversion process will continue so that all valid images are still converted and a PDF produced.
  • If the directory does not exist it is created.
  • Image files that are copied will overwrite any existing files with the same filename.

  •   I2PDF_LoadImageFailurePage_Real
    I2PDF_LoadImageFailPg_Real
    Parameters: width - specifies the page width. Must be a value between 100 and 2000 points inclusive.
    height - specifies the page height. Must be a value between 100 and 2000 points inclusive.
    backgroundRed - specifies the red component of the background color. Value must be between 0.0 and 1.0 inclusive.
    backgroundGreen - specifies the green component of the background color. Value must be between 0.0 and 1.0 inclusive.
    backgroundBlue - specifies the blue component of the background color. Value must be between 0.0 and 1.0 inclusive.
    message - text (up to 500 characters) with any combination of special formatting markup characters:
  • FN-NAME inserts the filename of the image.
  • Return Value: 0 - success
    1 - invalid width
    2 - invalid height
    3 - invalid backgroundRed
    4 - invalid backgroundGreen
    5 - invalid backgroundBlue
    6 - invalid message
    Notes:
  • If an image fails to be converted for any reason, then the default action is to abandon the production of the PDF. This does mean that any other images that have already been converted into the PDF or are still to be converted are effectively lost until they are converted in the future. This API allows images that fail to still have a page in the PDF but with the required message.
  • The message text is displayed approximately one third of the way down the page and is centered.
  • If outlines have been specified (see I2PDF_Outline) then the image filename is used as the outline name.
  • This uses the default font of 10 point Times-Roman black normal text. To change this use the I2PDF_LoadImageFailurePageFont_Real/Int/Web APIs below.
  • Click here for more information and examples of real colors.
  • 1 point is 1/72 inch.

  •   I2PDF_LoadImageFailurePage_Int
    I2PDF_LoadImageFailPg_Int
    Parameters: width - specifies the page width. Must be a value between 100 and 2000 points inclusive.
    height - specifies the page height. Must be a value between 100 and 2000 points inclusive.
    backgroundRed - specifies the red component of the background color. Value must be between 0 and 255 inclusive.
    backgroundGreen - specifies the green component of the background color. Value must be between 0 and 255 inclusive.
    backgroundBlue - specifies the blue component of the background color. Value must be between 0 and 255 inclusive.
    message - text (up to 500 characters) with any combination of special formatting markup characters:
  • FN-NAME inserts the filename of the image.
  • Return Value: 0 - success
    1 - invalid width
    2 - invalid height
    3 - invalid backgroundRed
    4 - invalid backgroundGreen
    5 - invalid backgroundBlue
    6 - invalid message
    Notes:
  • If an image fails to be converted for any reason, then the default action is to abandon the production of the PDF. This does mean that any other images that have already been converted into the PDF or are still to be converted are effectively lost until they are converted in the future. This API allows images that fail to still have a page in the PDF but with the required message.
  • The message text is displayed approximately one third of the way down the page and is centered.
  • If outlines have been specified (see I2PDF_Outline) then the image filename is used as the outline name.
  • This uses the default font of 10 point Times-Roman black normal text. To change this use the I2PDF_LoadImageFailurePageFont_Real/Int/Web APIs below.
  • Click here for more information and examples of integer colors.
  • 1 point is 1/72 inch.

  •   I2PDF_LoadImageFailurePage_Web
    I2PDF_LoadImageFailPg_Web
    Parameters: width - specifies the page width. Must be a value between 100 and 2000 points inclusive.
    height - specifies the page height. Must be a value between 100 and 2000 points inclusive.
    backgroundColor - specified as a hexadecimal string (from #000000 to #FFFFFF).
    message - text (up to 500 characters) with any combination of special formatting markup characters:
  • FN-NAME inserts the filename of the image.
  • Return Value: 0 - success
    1 - invalid width
    2 - invalid height
    3 - invalid backgroundColor
    4 - invalid message
    Notes:
  • If an image fails to be converted for any reason, then the default action is to abandon the production of the PDF. This does mean that any other images that have already been converted into the PDF or are still to be converted are effectively lost until they are converted in the future. This API allows images that fail to still have a page in the PDF but with the required message.
  • The message text is displayed approximately one third of the way down the page and is centered.
  • If outlines have been specified (see I2PDF_Outline) then the image filename is used as the outline name.
  • This uses the default font of 10 point Times-Roman black normal text. To change this use the I2PDF_LoadImageFailurePageFont_Real/Int/Web APIs below.
  • Click here for more information and examples of web colors.
  • 1 point is 1/72 inch.

  •   I2PDF_LoadImageFailurePageFont_Real
    I2PDF_LoadImageFailPgFnt_Real
    Parameters: size - must be between 1 and 300 points inclusive.
    font - must be one of the following standard PDF fonts (which are also known as base14 fonts): Courier, Courier-Bold, Courier-BoldOblique, Courier-Oblique, Helvetica, Helvetica-Bold, Helvetica-BoldOblique, Helvetica-Oblique, Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic
    fillRed - specifies the red component of the fill color. Value must be between 0.0 and 1.0 inclusive.
    fillGreen - specifies the green component of the fill color. Value must be between 0.0 and 1.0 inclusive.
    fillBlue - specifies the blue component of the fill color. Value must be between 0.0 and 1.0 inclusive.
    style - must be one of the following:
    TEXT_STYLE_NORMAL (1) - text is filled in with the required fill color
    TEXT_STYLE_STROKE (2) - text is filled in with the required fill color and the outline of each letter is "stroked" in the other color
    otherRed - specifies the red component of the "other" color. Value must be between 0.0 and 1.0 inclusive.
    otherGreen - specifies the green component of "other" color. Value must be between 0.0 and 1.0 inclusive.
    otherBlue - specifies the blue component of "other" color. Value must be between 0.0 and 1.0 inclusive.
    Return Value: 0 - success
    1 - invalid size
    2 - invalid font
    3 - invalid fillRed
    4 - invalid fillGreen
    5 - invalid fillBlue
    6 - invalid style
    7 - invalid otherRed
    8 - invalid otherGreen
    9 - invalid otherBlue
    Notes:
  • This is optional and controls the display of the failure message text specified in I2PDF_LoadImageFailurePage_Real/Int/Web above.
  • If not specified a default of 10 point Times-Roman black normal text is used.
  • Click here for more information and examples of real colors.

  •   I2PDF_LoadImageFailurePageFont_Int
    I2PDF_LoadImageFailPgFnt_Int
    Parameters: size - must be between 1 and 300 points inclusive.
    font - must be one of the following standard PDF fonts (which are also known as base14 fonts): Courier, Courier-Bold, Courier-BoldOblique, Courier-Oblique, Helvetica, Helvetica-Bold, Helvetica-BoldOblique, Helvetica-Oblique, Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic
    fillRed - specifies the red component of the fill color. Value must be between 0 and 255 inclusive.
    fillGreen - specifies the green component of the fill color. Value must be between 0 and 255 inclusive.
    fillBlue - specifies the blue component of the fill color. Value must be between 0 and 255 inclusive.
    style - must be one of the following:
    TEXT_STYLE_NORMAL (1) - text is filled in with the required fill color
    TEXT_STYLE_STROKE (2) - text is filled in with the required fill color and the outline of each letter is "stroked" in the other color
    otherRed - specifies the red component of the "other" color. Value must be between 0 and 255 inclusive.
    otherGreen - specifies the green component of "other" color. Value must be between 0 and 255 inclusive.
    otherBlue - specifies the blue component of "other" color. Value must be between 0 and 255 inclusive.
    Return Value: 0 - success
    1 - invalid size
    2 - invalid font
    3 - invalid fillRed
    4 - invalid fillGreen
    5 - invalid fillBlue
    6 - invalid style
    7 - invalid otherRed
    8 - invalid otherGreen
    9 - invalid otherBlue
    Notes:
  • This is optional and controls the display of the failure message text specified in I2PDF_LoadImageFailurePage_Real/Int/Web above.
  • If not specified a default of 10 point Times-Roman black normal text is used.
  • Click here for more information and examples of integer colors.

  •   I2PDF_LoadImageFailurePageFont_Web
    I2PDF_LoadImageFailPgFnt_Web
    Parameters: size - must be between 1 and 300 points inclusive.
    font - must be one of the following standard PDF fonts (which are also known as base14 fonts): Courier, Courier-Bold, Courier-BoldOblique, Courier-Oblique, Helvetica, Helvetica-Bold, Helvetica-BoldOblique, Helvetica-Oblique, Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic
    fillColor - specified as a hexadecimal string (from #000000 to #FFFFFF)
    style - must be one of the following:
    TEXT_STYLE_NORMAL (1) - text is filled in with the required fill color
    TEXT_STYLE_STROKE (2) - text is filled in with the required fill color and the outline of each letter is "stroked" in the other color
    otherColor - specified as a hexadecimal string (from #000000 to #FFFFFF)
    Return Value: 0 - success
    1 - invalid size
    2 - invalid font
    3 - invalid fillColor
    4 - invalid style
    5 - invalid otherColor
    Notes:
  • This is optional and controls the display of the failure message text specified in I2PDF_LoadImageFailurePage_Real/Int/Web above.
  • If not specified a default of 10 point Times-Roman black normal text is used.
  • Click here for more information and examples of web colors.

  •   I2PDF_MinImageSize
    Parameters: width - specifies the minimum image width required for an image to be converted. height - specifies the minimum image height required for an image to be converted.
    Notes:
  • Images whose width and/or height are less than the values specified are skipped during the conversion process.
  • This is useful if you have multi-image files (such as TIFFs) that have thumbnail images as well as full-size images within the file and you want to skip over the thumbnail images.
  • The default value is 1.