PDF Settings Application Programming Interfaces

The following Application Programming Interface functions to Image to PDF all control what can be done with the PDF document. These items notify the PDF viewer what activity has been allowed by the author, and whether outlines/bookmarks have been enabled.

Note: A PDF viewer may choose to ignore any or all of these settings.

  I2PDF_SetDPI
Parameters: dpi - integer between 9 and 2880 inclusive, specify 0 to use the actual DPI recorded in the image file
Return Value: 0 - success
1 - invalid parameter - dpi specified is less than 9
2 - invalid parameter - dpi specified is greater than 2880
Notes:
  • PDF documents use a default resolution setting of 72 DPI. Images created for screen display under Windows will probably have a resolution of 96 DPI. If you have created images for printing then you will probably need to use 300 or 600 DPI. If you do not adjust the default resolution setting then when displayed within a PDF document on screen a 96 DPI image will appear 25% larger than expected. This gets much worse for a 300 DPI image which will appear 416% larger than expected.
  • Please note that if you use the actual DPI recorded in the image file (by using a value of 0) that where an image format does not explicitly record a DPI value a default one will be used that is appropriate to that image format (this will most likely be either 72 DPI or the current DPI of the main display on your PC).
  • We recommend that you use a value of 0 so that the actual DPI is always used.

  •   I2PDF_SetOutline
    Parameters: format - must be one of the following:
    OUTLINE_FORMAT_FILENAME (1) - this is the name of the image file including the image extension but not including the full filepath)
    OUTLINE_FORMAT_NAME (2) - same as filename but without the image extension.
    style - must be one of the following: STYLE_LOWERCASE (1), STYLE_UPPERCASE (2), STYLE_CAPITALISE (3) or STYLE_NONE (0)
    Return Value: 0 - success
    1 - invalid format parameter
    2 - invalid style parameter
    Notes:
  • This turns on the generation of a bookmark for each image that is in the output PDF document.

  •   I2PDF_SetOutlineTitle
    Parameters: title - of the outline root node which can be up to 256 characters long.
    Return Value: 0 - success
    1 - title not specified
    2 - title too long
    Notes:
  • If an outline is produced (either using I2PDF_SetOutline or I2PDF_AddImageBookmark) this sets the outline root title rather than the default that is shown by the PDF viewer application (eg "OutlineRoot").

  •   I2PDF_SetOwnerPassword
    Parameters: password - string between 1 and 32 characters.
    Return Value: 0 - success
    1 - invalid parameter
    Notes:
  • The owner of a PDF document would enter this password in order to view it and make changes and perform actions that may be restricted to a normal user.
  • Please note that the owner and user passwords cannot be the same.
  • The PDF document will be encrypted using the default encryption level of 40 bits. You can use an encryption level of 128 bits if you use the I2PDF_EncryptionLevel API below.

  •   I2PDF_SetUserPassword
    Parameters: password - string between 1 and 32 characters.
    Return Value: 0 - success
    1 - invalid parameter
    Notes:
  • In order that only the intended user can view the PDF document, they must type in this password, otherwise the user is not allowed to access the PDF document.
  • Please note that you cannot have a user password without an owner one - if you do not specify an owner password your license code will be used as the owner password. If you are evaluating this utility then a default owner password of "evaluation" is used instead.
  • Please note that he owner and user passwords cannot be the same.
  • The PDF document will be encrypted using the default encryption level of 40 bits. You can use an encryption level of 128 bits if you use the I2PDF_EncryptionLevel API below.

  •   I2PDF_EncryptionLevel
    Parameters: level - integer which must be either 40 (low) or 128 (high)
    force - integer which must be 1 to force the encryption (see note below) or 0
    Return Value: 0 - success
    1 - invalid parameter
    Notes:
  • Specifies the level of encryption that is to be used on the PDF document. If not specified the default level of 40 bits is used.
  • Normally, a PDF can only be encrypted if the owner and user passwords are specified as these form the basis for the encryption key. However, it may be required to force the encryption of the document without supplying either of these passwords and this command will ensure that this takes place.
  • WARNING: A PDF document that has been force encrypted in this way is NOT secure - it just prevents simple eavesdropping during electronic transmission.

  •   I2PDF_SetPermissionEdit
    Parameters: None
    Return Value: None
    Notes:
  • Allows editing/changing of the PDF document but NOT adding or changing of text notes and AcroForm fields.

  •   I2PDF_SetPermissionEditExtra
    Parameters: None
    Return Value: None
    Notes:
  • Allows the adding and changing of text notes and AcroForm fields within a PDF document.

  •   I2PDF_SetPermissionCopy
    Parameters: None
    Return Value: None
    Notes:
  • Allows the copying of text and graphics from the PDF document.

  •   I2PDF_SetPermissionPrint
    Parameters: None
    Return Value: None
    Notes:
  • Allows printing of the PDF document.

  •   I2PDF_SetPermissions
    Parameters: permissions - must be one or more of the following: PDF_PERMISSION_READ_ONLY (0), PDF_PERMISSION_EDIT (1), PDF_PERMISSION_EDIT_EXTRA (2), PDF_PERMISSION_COPY (4), PDF_PERMISSION_PRINT (8)
    Return Value: 0 - success
    1 - invalid permissions
    Notes:
  • This is an alternative to using the individual permission APIs above and allows the setting of all the permissions that are required in one go.