pdftron::PDFNet Class Reference

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

#include <PDFNet.h>

List of all members.

Classes

class  SecurityDescriptor
 SecurityDescriptor is a class describing SecurityHandler. More...

Public Types

enum  CMSType { e_lcms, e_icm, e_no_cms }
enum  CharacterOrdering {
  e_Identity = 0, e_Japan1 = 1, e_Japan2 = 2, e_GB1 = 3,
  e_CNS1 = 4, e_Korea1 = 5
}
 Standard character orderings. More...
typedef
TRN_PDFNetCreateSecurityHandler 
CreateSecurityHandler
 CreateSecurityHandler is a function pointer and a factory method used to create new instances of SecurityHandler.
typedef Common::Iterator
< SecurityDescriptor
SecurityDescriptorIterator

Static Public Member Functions

static void Initialize (const char *license_key=0)
 Initializes PDFNet library.
static void Terminate ()
 Terminates PDFNet library.
static bool SetResourcesPath (const UString &path)
 Sets the location of PDFNet resource file.
static UString GetResourcesPath ()
static double GetVersion ()
static void SetColorManagement (CMSType t=e_lcms)
 Used to set a specific Color Management System (CMS) for use during color conversion operators, image rendering, etc.
static void SetDefaultDeviceCMYKProfile (const UString &icc_filename)
 Sets the default ICC color profile for DeviceCMYK color space.
static void SetDefaultDeviceRGBProfile (const UString &icc_filename)
 Sets the default ICC color profile for DeviceRGB color space.
static bool AddFontSubst (const char *fontname, const UString &fontpath)
 AddFontSubst functions can be used to create font substitutes that can override default PDFNet font selection algorithm.
static bool AddFontSubst (CharacterOrdering ordering, const UString &fontpath)
static bool SetTempPath (const UString &temp_path)
 Set the location of temporary folder.
static void RegisterSecurityHandler (const char *handler_name, const char *gui_name, CreateSecurityHandler factory_method)
 Registers a new type of SecurityHandler.
static SecurityDescriptorIterator GetSecHdlrInfoIterator ()
static void SetNumberWriteProc (char *(*WriteProc)(double num, char *in_buf, int in_buf_size))
 Sets a callback function used to override the default PDFNet number serialization routine.
static void SetNumberReadProc (TRN_Bool(*ReadProc)(const TRN_UChar *buf, double *output))
 Sets a callback function used to override the default PDFNet number parsing function.


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.

Member Typedef Documentation

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.


Member Enumeration Documentation

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.

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.


Member Function Documentation

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

Initializes PDFNet library.

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

Note:
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 the demo mode.
Exceptions:
If the license_key is invalid, the function will throw an exception.

static 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.

static bool pdftron::PDFNet::SetResourcesPath ( const UString path  )  [static]

Sets the location of PDFNet resource file.

Note:
Starting with v.4.5 PDFNet does not require a separate resource file (pdfnet.res) on all desktop/server platforms. As a result, this function is not longer required for proper PDFNet initialization. The function is still available on embedded systems and for backwards compatibility. The function can be also used 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.

static UString pdftron::PDFNet::GetResourcesPath (  )  [static]

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

static double pdftron::PDFNet::GetVersion (  )  [static]

Returns:
PDFNet version number.

static 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.

static 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.

static 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.

static 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.

These 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.

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 these functions 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");
         
 // 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");
 ...

static bool pdftron::PDFNet::AddFontSubst ( CharacterOrdering  ordering,
const UString fontpath 
) [static]

static bool 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.

static 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.

static SecurityDescriptorIterator pdftron::PDFNet::GetSecHdlrInfoIterator (  )  [static]

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

static void pdftron::PDFNet::SetNumberWriteProc ( char *(*)(double num, char *in_buf, int in_buf_size)  WriteProc  )  [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.

static void pdftron::PDFNet::SetNumberReadProc ( TRN_Bool(*)(const TRN_UChar *buf, double *output)  ReadProc  )  [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:
WriteProc A pointer to a function that will serialize a floating-point number in PDF number format.


© 2002-2010 PDFTron Systems Inc.