Loading...
Searching...
No Matches
pdftron::PDFNet Class Reference

`#include <PDFNet.h>`

## Classes
class | SecurityDescriptor

## Public Types
enum | CMSType { e_lcms , e_icm , e_no_cms }
enum | FlateCompressionLevel { e_Z_DEFAULT_COMPRESSION = -1 , e_Z_NO_COMPRESSION = 0 , e_Z_BEST_SPEED = 1 , e_Z_BEST_COMPRESSION = 9 }
enum | CharacterOrdering { e_Identity = 0 , e_Japan1 = 1 , e_Japan2 = 2 , e_GB1 = 3 , e_CNS1 = 4 , e_Korea1 = 5 }
enum | ConnectionErrorHandlingMode { e_continue , e_continue_unless_switching_to_demo , e_stop }
typedef TRN_PDFNetCreateSecurityHandler | CreateSecurityHandler
typedef Common::Iterator< SecurityDescriptor > | SecurityDescriptorIterator
typedef void(* | ConnectionErrorProc) (const char *message, const int error_code, UChar switch_to_demo, void *user_data)

## Static Public Member Functions
static void | Initialize (const char *license_key=0)
static void | Terminate (const int termination_level)
static void | EnableJavaScript (bool enable)
static bool | IsJavaScriptEnabled ()
static void | Terminate ()
static bool | SetResourcesPath (const UString &path)
static UString | GetResourcesPath ()
static void | AddResourceSearchPath (const UString &path)
static double | GetVersion ()
static void | SetColorManagement (CMSType t=e_lcms)
static void | SetDefaultDeviceCMYKProfile (const UString &icc_filename)
static void | SetDefaultDeviceCMYKProfile (Filters::Filter stream)
static void | SetDefaultDeviceRGBProfile (const UString &icc_filename)
static void | SetDefaultDeviceRGBProfile (Filters::Filter stream)
static void | SetDefaultDiskCachingEnabled (bool use_disk)
static void | SetDefaultFlateCompressionLevel (int level)
static void | SetViewerCache (size_t max_cache_size, bool on_disk)
static bool | AddFontSubst (const char *fontname, const UString &fontpath)
static bool | AddFontSubst (CharacterOrdering ordering, const UString &fontpath)
static void | SetTempPath (const UString &temp_path)
static void | SetPersistentCachePath (const UString &persistent_path)
static UString | GetSystemFontList ()
static void | RegisterSecurityHandler (const char *handler_name, const char *gui_name, CreateSecurityHandler factory_method)
static SecurityDescriptorIterator | GetSecHdlrInfoIterator ()
static void | SetNumberWriteProc (char *(*WriteProc)(double num, char *in_buf, int in_buf_size))
static void | SetNumberReadProc (TRN_Bool(*ReadProc)(const TRN_UChar *buf, double *output))
static void | AddPDFTronCustomHandler (UInt32 custom_id)
static const char * | GetVersionString ()
static void | SetWriteAPIUsageLocally (bool write_usage)
static void | SetConnectionErrorHandlingMode (ConnectionErrorHandlingMode mode)
static void | SetConnectionErrorProc (ConnectionErrorProc error_proc, void *data)

## Detailed Description

PDFNet contains global library initialization, registration, configuration, and termination methods.

Note
  there is only a single, static instance of PDFNet class. Initialization and termination methods need to be called only once per application session.

Definition at line 24 of file PDFNet.h.

## Member Typedef Documentation

## ◆ ConnectionErrorProc

typedef void(* pdftron::PDFNet::ConnectionErrorProc) (const char *message, const int error_code, UChar switch_to_demo, void *user_data)

Error handler for PWS server connection. A type of callback function (or a delegate in .NET terminology) that is called in case an error is encountered when connection fails.

Parameters

  message | The reason for the connection failure.
  error_code | The error code from the connection failure.
  switch_to_demo | Is 1 if continuing in the current situation requires a change from a production key to demo mode (where watermarks will be applied) and 0 otherwise
  user_data | Custom data.

Definition at line 464 of file PDFNet.h.

## ◆ CreateSecurityHandler

typedef TRN_PDFNetCreateSecurityHandler pdftron::PDFNet::CreateSecurityHandler

CreateSecurityHandler is a function pointer and a factory method used to create new instances of SecurityHandler. The function pointer is used to register a new type of SecurityHandler with PDFNet.

Definition at line 345 of file PDFNet.h.

## ◆ SecurityDescriptorIterator

typedef Common::Iterator<SecurityDescriptor> pdftron::PDFNet::SecurityDescriptorIterator

Definition at line 367 of file PDFNet.h.

## Member Enumeration Documentation

## ◆ CharacterOrdering

enum pdftron::PDFNet::CharacterOrdering

Standard character orderings. PDFNet.AddFontSubst() can be used to associate a specific font with a given character ordering and to override default font mapping algorithm.

Enumerator
e_Identity | Generic/Unicode.
e_Japan1 | Japanese.
e_Japan2 | Japanese.
e_GB1 | Chinese; Simplified.
e_CNS1 | Chinese; Traditional.
e_Korea1 | Korean.

Definition at line 244 of file PDFNet.h.

## ◆ CMSType

enum pdftron::PDFNet::CMSType

Enumerator
e_lcms | Use LittleCMS (available on all supported platforms).
e_icm | Use Windows ICM2 (available only on Windows platforms).
e_no_cms | No ICC color management.

Definition at line 134 of file PDFNet.h.

## ◆ ConnectionErrorHandlingMode

enum pdftron::PDFNet::ConnectionErrorHandlingMode

Enumerator
e_continue |
e_continue_unless_switching_to_demo |
e_stop |

Definition at line 437 of file PDFNet.h.

## ◆ FlateCompressionLevel

enum pdftron::PDFNet::FlateCompressionLevel

Enumerator
e_Z_DEFAULT_COMPRESSION |
e_Z_NO_COMPRESSION |
e_Z_BEST_SPEED |
e_Z_BEST_COMPRESSION |

Definition at line 206 of file PDFNet.h.

## Member Function Documentation

## ◆ AddFontSubst() [1/2]

bool pdftron::PDFNet::AddFontSubst | ( | CharacterOrdering | ordering,
|  | const UString & | fontpath )
| static

AddFontSubst functions can be used to create font substitutes that can override default PDFNet font selection algorithm.

AddFontSubst functions are useful in situations where referenced fonts are not present in the document and PDFNet font substitution algorithm is not producing desired results.

AddFontSubst(ordering, fontpath) maps the given character ordering (see Ordering entry in CIDSystemInfo dictionary; Section 5.6.2 in PDF Reference) to a font file. This method is less specific that the former variant of AddFontSubst, and can be used to override a range of missing fonts (or any missing font) with a predefined substitute.

The following is an example of using this function to provide user defined font substitutes:

PDFNet::Initialize();
PDFNet::SetResourcesPath("c:/myapp/resources");
// Specify more general font mappings...
PDFNet::AddFontSubst(PDFNet::e_Identity, "c:/myfonts/arialuni.ttf"); // Arial Unicode MS
PDFNet::AddFontSubst(PDFNet::e_Japan1, "c:/myfonts/KozMinProVI-Regular.otf");
PDFNet::AddFontSubst(PDFNet::e_Japan2, "c:/myfonts/KozMinProVI-Regular.otf");
PDFNet::AddFontSubst(PDFNet::e_Korea1, "c:/myfonts/AdobeSongStd-Light.otf");
PDFNet::AddFontSubst(PDFNet::e_CNS1, "c:/myfonts/AdobeMingStd-Light.otf");
PDFNet::AddFontSubst(PDFNet::e_GB1, "c:/myfonts/AdobeMyungjoStd-Medium.otf");
...
PDFDoc doc("c:/my.pdf");
...
pdftron::PDFNet::SetResourcesPath
static bool SetResourcesPath(const UString &path)
pdftron::PDFNet::Initialize
static void Initialize(const char *license_key=0)
pdftron::PDFNet::AddFontSubst
static bool AddFontSubst(const char *fontname, const UString &fontpath)
pdftron::PDFNet::e_Identity
@ e_Identity
Generic/Unicode.
Definition PDFNet.h:245
pdftron::PDFNet::e_Korea1
@ e_Korea1
Korean.
Definition PDFNet.h:250
pdftron::PDFNet::e_Japan1
@ e_Japan1
Japanese.
Definition PDFNet.h:246
pdftron::PDFNet::e_GB1
@ e_GB1
Chinese; Simplified.
Definition PDFNet.h:248
pdftron::PDFNet::e_Japan2
@ e_Japan2
Japanese.
Definition PDFNet.h:247
pdftron::PDFNet::e_CNS1
@ e_CNS1
Chinese; Traditional.
Definition PDFNet.h:249

## ◆ AddFontSubst() [2/2]

bool pdftron::PDFNet::AddFontSubst | ( | const char * | fontname,
|  | const UString & | fontpath )
| static

AddFontSubst functions can be used to create font substitutes that can override default PDFNet font selection algorithm.

AddFontSubst functions are useful in situations where referenced fonts are not present in the document and PDFNet font substitution algorithm is not producing desired results.

AddFontSubst(fontname, fontpath) maps the given font name (i.e. 'BaseFont' entry from the font dictionary) to a font file.

The following is an example of using this function to provide user defined font substitutes:

PDFNet::Initialize();
PDFNet::SetResourcesPath("c:/myapp/resources");
// Specify specific font mappings...
PDFNet::AddFontSubst("MinionPro-Regular", "c:/myfonts/MinionPro-Regular.otf");
PDFNet::AddFontSubst("Times-Roman", "c:/windows/fonts/times.ttf");
PDFNet::AddFontSubst("Times-Italic", "c:/windows/fonts/timesi.ttf");
...
PDFDoc doc("c:/my.pdf");
...

## ◆ AddPDFTronCustomHandler()

void pdftron::PDFNet::AddPDFTronCustomHandler | ( | UInt32 | custom_id | ) |
| static

Add PDFTron Custom Security handler

Parameters

  custom_id | The user's custom id. The id should match what was used to create PDFTronCustomSecurityHandler when encrypting the document.

Note
  calling this function is a requirement to load files encrypted with PDFTronCustomSecurityHandler.

## ◆ AddResourceSearchPath()

void pdftron::PDFNet::AddResourceSearchPath | ( | const UString & | path | ) |
| static

Sets the location of PDFNet resource file.

Note
  Starting with v.4.5 PDFNet no longer requires a seperate resource file, and so this function is not required for proper PDFNet initialization. The function can be used on all platforms to specify search paths for ICC profiles, fonts, and other user defined resources.

Parameters

  path | - The resource directory path to add to the search list.

## ◆ EnableJavaScript()

void pdftron::PDFNet::EnableJavaScript | ( | bool | enable | ) |
| static

A switch that can be used to turn on/off JavaScript engine

Parameters

  enable | true to enable JavaScript engine, false to disable.

## ◆ GetResourcesPath()

UString pdftron::PDFNet::GetResourcesPath | ( |  | ) |
| static

Returns
  the location of PDFNet resources folder. Empty string means that resources are located in your application folder.

## ◆ GetSecHdlrInfoIterator()

SecurityDescriptorIterator pdftron::PDFNet::GetSecHdlrInfoIterator | ( |  | ) |
| static

Returns
  iterator to the first SecurityDescriptor in the list of currently registered SecurityHandler types.

## ◆ GetSystemFontList()

UString pdftron::PDFNet::GetSystemFontList | ( |  | ) |
| static

Get available fonts on the system.

Returns
  A JSON list of fonts accessible to PDFNet

## ◆ GetVersion()

double pdftron::PDFNet::GetVersion | ( |  | ) |
| static

Returns
  PDFNet version number.

## ◆ GetVersionString()

const char * pdftron::PDFNet::GetVersionString | ( |  | ) |
| static

Returns
  PDFNet version as a string.

## ◆ Initialize()

void pdftron::PDFNet::Initialize | ( | const char * | license_key = 0 | ) |
| static

Initializes PDFNet library. Initialize() is usually called once, during process initialization.

Note
  With the exception of SetPersistentCache and SetTempPath, it is unsafe to call any other PDFNet API without first initializing the library

Parameters

  license_key | Optional license key used to activate the product. If the license_key is not specified or is null, the product will work in demo mode.

Exceptions

  If | the license_key is invalid, the function will throw an exception.

## ◆ IsJavaScriptEnabled()

bool pdftron::PDFNet::IsJavaScriptEnabled | ( |  | ) |
| static

Test whether JavaScript is enabled

Returns
  true if it is enabled, false otherwise

## ◆ RegisterSecurityHandler()

void pdftron::PDFNet::RegisterSecurityHandler | ( | const char * | handler_name,
|  | const char * | gui_name,
|  | CreateSecurityHandler | factory_method )
| static

Registers a new type of SecurityHandler. If a handler with the same name was already registered, the new SecurityHandler will replace the old handler.

Parameters

  handler_name | - SecurityHandler's document name (as it appears in Encrypt dictionary).
  factory_method | - a function pointer and a factory method used to create new instances of SecurityHandler.

## ◆ SetColorManagement()

void pdftron::PDFNet::SetColorManagement | ( | CMSType | t = e_lcms | ) |
| static

Used to set a specific Color Management System (CMS) for use during color conversion operators, image rendering, etc.

Parameters

  t | identifies the type of color management to use.

## ◆ SetConnectionErrorHandlingMode()

void pdftron::PDFNet::SetConnectionErrorHandlingMode | ( | ConnectionErrorHandlingMode | mode | ) |
| static

Sets the connection error handling behaviour for Apryse SDK The default for this method is e_continue

Parameters

  mode | Rules that Apryse SDK will follow after a connection error.

## ◆ SetConnectionErrorProc()

void pdftron::PDFNet::SetConnectionErrorProc | ( | ConnectionErrorProc | error_proc,
|  | void * | data )
| static

Sets the error handling function to be called when an error is encountered when connecting to PDFTron Web Services.

Parameters

  error_proc | Connection error handling callback function (or delegate in .NET)
  data | Custom data to be passed as the fourth parameter to 'error_proc'.

## ◆ SetDefaultDeviceCMYKProfile() [1/2]

void pdftron::PDFNet::SetDefaultDeviceCMYKProfile | ( | const UString & | icc_filename | ) |
| static

Sets the default ICC color profile for DeviceCMYK color space.

Note
  You can use this method to override default PDFNet settings. For more information on default color spaces please refer to section 'Default Color Spaces' in Chapter 4.5.4 of PDF Reference Manual.

Exceptions

  the | function will throw Exception if the ICC profile can't be found or if it fails to open.

## ◆ SetDefaultDeviceCMYKProfile() [2/2]

void pdftron::PDFNet::SetDefaultDeviceCMYKProfile | ( | Filters::Filter | stream | ) |
| static

Sets the default ICC color profile for DeviceCMYK color space.

Note
  You can use this method to override default PDFNet settings. For more information on default color spaces please refer to section 'Default Color Spaces' in Chapter 4.5.4 of PDF Reference Manual.

Exceptions

  the | function will throw Exception if the ICC profile fails to open.

## ◆ SetDefaultDeviceRGBProfile() [1/2]

void pdftron::PDFNet::SetDefaultDeviceRGBProfile | ( | const UString & | icc_filename | ) |
| static

Sets the default ICC color profile for DeviceRGB color space.

Note
  You can use this method to override default PDFNet settings. For more information on default color spaces please refer to section 'Default Color Spaces' in Chapter 4.5.4 of PDF Reference Manual.

Exceptions

  the | function will throw Exception if the ICC profile can't be found or if it fails to open.

## ◆ SetDefaultDeviceRGBProfile() [2/2]

void pdftron::PDFNet::SetDefaultDeviceRGBProfile | ( | Filters::Filter | stream | ) |
| static

Sets the default ICC color profile for DeviceRGB color space.

Note
  You can use this method to override default PDFNet settings. For more information on default color spaces please refer to section 'Default Color Spaces' in Chapter 4.5.4 of PDF Reference Manual.

Exceptions

  the | function will throw Exception if the ICC profile fails to open.

## ◆ SetDefaultDiskCachingEnabled()

void pdftron::PDFNet::SetDefaultDiskCachingEnabled | ( | bool | use_disk | ) |
| static

Sets the default policy on using temporary files.

@use_disk if parameter is true then new documents are allowed to create temporary files; otherwise all document contents will be stored in memory.

## ◆ SetDefaultFlateCompressionLevel()

void pdftron::PDFNet::SetDefaultFlateCompressionLevel | ( | int | level | ) |
| static

Sets the default compression level for Flate (ZLib).

Parameters

  level | An integer in range 0-9 representing the compression value to use as a default for any Flate streams (e.g used to compress content streams, PNG images, etc). The library normally uses the default compression level (Z_DEFAULT_COMPRESSION). For most images, compression values in the range 3-6 compress nearly as well as higher levels, and do so much faster. For on-line applications it may be desirable to have maximum speed Z_BEST_SPEED = 1). You can also specify no compression (Z_NO_COMPRESSION = 0).

@default Z_DEFAULT_COMPRESSION (-1).

## ◆ SetNumberReadProc()

void pdftron::PDFNet::SetNumberReadProc | ( | TRN_Bool(* | ReadProc )(const TRN_UChar *buf, double *output) | ) |
| static

Sets a callback function used to override the default PDFNet number parsing function. Applications that require advanced control over PDF number processing can provide a custom handler.

Parameters

  ReadProc | A pointer to a function that will parse a floating-point number in PDF number format.

## ◆ SetNumberWriteProc()

void pdftron::PDFNet::SetNumberWriteProc | ( | char *(* | WriteProc )(double num, char *in_buf, int in_buf_size) | ) |
| static

Sets a callback function used to override the default PDFNet number serialization routine. Applications that require advanced control over PDF number processing can provide a custom handler.

Parameters

  WriteProc | A pointer to a function that will serialize a floating-point number in PDF number format. The following parameters describe the callback function:
  num | The number to be converted to decimal.
  in_buf | the buffer used to serialize the number.
  in_buf_size | the size of input buffer.

Returns
  A pointer within in_buf array where the number string starts.

## ◆ SetPersistentCachePath()

void pdftron::PDFNet::SetPersistentCachePath | ( | const UString & | persistent_path | ) |
| static

Set the location of persistent cache files.

This method is provided for applications that require tight control of the location where temporary files are created.

## ◆ SetResourcesPath()

bool pdftron::PDFNet::SetResourcesPath | ( | const UString & | path | ) |
| static

Sets the location of PDFNet resource file.

Note
  Starting with v.4.5 PDFNet no longer requires a seperate resource file, and so this function is not required for proper PDFNet initialization. It remains available for backward compatibility. On mobile systems (iOS, Android, etc.) this method is required for proper initialization starting with version 6.0. (This helps reduce overall app size.) The function can be used on all platforms to specify a default search path for ICC profiles, fonts, and other user defined resources.

Parameters

  path | - The default resource directory path.

Returns
  true if path is found, false otherwise.

## ◆ SetTempPath()

void pdftron::PDFNet::SetTempPath | ( | const UString & | temp_path | ) |
| static

Set the location of temporary folder.

This method is provided for applications that require tight control of the location where temporary files are created.

## ◆ SetViewerCache()

void pdftron::PDFNet::SetViewerCache | ( | size_t | max_cache_size,
|  | bool | on_disk )
| static

Sets the default parameters for the viewer cache. Any subsequently created documents will use these parameters.

Parameters

  max_cache_size | - The maximum size, in bytes, of the entire document's page cache. Set to zero to disable the viewer cache.
  on_disk | - If set to 'true', cache will be stored on the local filesystem. If set to 'false', cache will be stored in heap memory.

@default Desktop: max_cache_size = 512 MB, on_disk = true | Mobile: max_cache_size = 100 MB, on_disk = false

## ◆ SetWriteAPIUsageLocally()

void pdftron::PDFNet::SetWriteAPIUsageLocally | ( | bool | write_usage | ) |
| static

Enable writing API usage locally.

Parameters

  write_usage | if parameter is true API usage will be written to local JSON files in the persistent cache path otherwise no API usage is saved.

## ◆ Terminate() [1/2]

void pdftron::PDFNet::Terminate | ( |  | ) |
| static

Terminates PDFNet library. Terminate() is usually called once, when the process is terminated.

Note
  it is unsafe to call any other PDFNet API after you terminate the library.

## ◆ Terminate() [2/2]

void pdftron::PDFNet::Terminate | ( | const int | termination_level | ) |
| static

Terminates PDFNet library. Terminate() is usually called once, when the process is terminated.

Parameters

  termination_level | Optional termination level used to decide what operations need to be included

Note
  it is unsafe to call any other PDFNet API after you terminate the library.

The documentation for this class was generated from the following file:

- PDF/PDFNet.h