Foxit PDF SDK

Class Methods | List of all members
FSLibrary Class Reference

Inherits NSObject.

## Class Methods
(BOOL) | + addExternalFontPath:
| Add external font path. More...
(void) | + destroy
| Release all resource allocated by Foxit PDF SDK Library. More...
(BOOL) | + enableJavaScript:
| Enable or disable javascript for PDF. More...
(void) | + enableThreadSafety:
| Enable thread safety. More...
(NSString *) | + executeJavaScript:
| Execute javascript. More...
(FSErrorCode) | + flushLog
| Flush the log file. More...
(FSRenderConfig *) | + getRenderConfig
| Get the rendering configuration. More...
(NSString *) | + getVersion
| Get the version of current Foxit PDF SDK library. More...
(BOOL) | + hasModuleLicenseRight:
| Check if user has right to use a specified module of Foxit PDF SDK in current used license information (which is used to initialize Foxit PDF SDK). More...
(FSErrorCode) | + initialize:key:
| Initialize Foxit PDF SDK Library, with valid license information. More...
(FSErrorCode) | + initializeWithJSXFAThreadsafety:key:is_optimize_memory:enable_js_xfa_threadsafety:
| Initialize Foxit PDF SDK Library, with valid license information. More...
(void) | + matchExternalFontsOnly:
| Specify whether to match fonts only from external fonts. More...
(BOOL) | + registerSecurityCallback:callback:
| Register a FSSecurityCallback object to Foxit PDF SDK for decryption of the PDFs with special encryption filters. More...
(BOOL) | + registerSignatureCallback:sub_filter:signature_callback:
| Register a third-party FSSignatureCallback object to Foxit PDF SDK for signing and verifying signature, along with the filter and sub filter name of the callback. More...
(void) | + registerXFAAppProviderCallback:
| Register an FSAppProviderCallback object to Foxit PDF SDK. More...
(FSErrorCode) | + reinitialize
| Re-initialize Foxit PDF SDK Library. More...
(BOOL) | + setActionCallback:
| Set a FSActionCallback object to Foxit PDF SDK, in aid of performing PDF actions. More...
(BOOL) | + setAnnotIconProviderCallback:
| Set a customized FSIconProviderCallback object to Foxit PDF SDK. More...
(BOOL) | + setCacheSize:
| Set the upper limit of PDF library cache size. More...
(void) | + setDefaultICCProfilesPath:
| Set path of folder which contains default ICC profile files. More...
(BOOL) | + setDocEventCallback:
| Set a object to Foxit PDF SDK. More...
(BOOL) | + setFontMapperCallback:
| Set a object to Foxit PDF SDK. More...
(void) | + setLogFile:
| Set the log file path. More...
(void) | + setLogFileWithStreamCallback:
| Set the log file stream. More...
(BOOL) | + setNotifierCallback:
| Set a object to Foxit PDF SDK. More...
(void) | + setRenderConfig:
| Set the rendering configuration. More...
(void) | + setRenderTextGamma:
| Set gamma value for text rendering. More...
(BOOL) | + setTimeStampCallback:
| Set a FSTimeStampCallback object to Foxit PDF SDK, in aid of interacting with time stamp server. More...
(BOOL) | + unregisterSecurityCallback:
| Unregister a FSSecurityCallback object from Foxit PDF SDK. More...
(void) | + unregisterSignatureCallback:sub_filter:
| Unregister the third-party FSSignatureCallback object, which is associated with a specific filter and sub-filter, from the Foxit PDF SDK. If a default signature is available, it will be restored together with its filter and sub-filter values. More...

## Detailed Description

This class represents the library management. It contains functions to initialize/re-initialize/release Foxit PDF SDK library, and also contains functions for global use.
Any application should load Foxit PDF SDK by function FSLibrary::initialize:key: before calling any other Foxit PDF SDK functions. When there is no need to use Foxit PDF SDK any more, please call function FSLibrary::destroy.
Functions in Foxit PDF SDK may throw exception when some error occurs. User can catch these exceptions and check the error code with values starting from FSErrFile to know more about what error occurs.

Note
  During the life-cycle of an application, FSLibrary::initialize:key: and FSLibrary::destroy should be called in pair and can only be called once. Once FSLibrary::destroy is called during the life-cycle of an application, Foxit PDF SDK cannot be initialized any more in the life-cycle of the application. Before FSLibrary::destroy is called, if user wants to re-initialize Foxit PDF SDK, please refer to function FSLibrary::reinitialize.

## Method Documentation

## ◆ addExternalFontPath:()

+ (BOOL) addExternalFontPath: |  | (NSString *) | font_path |

Add external font path.

Parameters

  [in] | font_path | The external font path.

Returns
  YES means success, while NO means failure.

## ◆ destroy()

+ (void) destroy |  |  |

Release all resource allocated by Foxit PDF SDK Library.

User should call this function to release all memory blocks allocated by the library.
Once this fucntion is called, Foxit PDF SDK library cannot be initialized any more in the life-cycle of the application.

Returns
  None.

## ◆ enableJavaScript:()

+ (BOOL) enableJavaScript: |  | (BOOL) | enable_javascript |

Enable or disable javascript for PDF.

Javascript for PDF is enabled by default.

Parameters

  [in] | enable_javascript | YES means to enable javascript, and NO means to disable javascript. If this function is not called, javascript for PDF is enabled by default.

Returns
  YES means success, while NO means failure.

## ◆ enableThreadSafety:()

+ (void) enableThreadSafety: |  | (BOOL) | is_enable_thread_safety |

Enable thread safety.

From Foxit PDF SDK 11.0, document level thread safety is enabled by default except Javascript and xfa module without calling this function. This function will be deprecated in future version. And users need to ensure that one pdf document is only operated by one thread at a time. If users want to enable thread safety for javascript and xfa module, please pass the YES to the enable_js_xfa_threadsafety during calling function FSLibrary::initialize:key:.

Currently, module "OCR" does not support thread safety.

Parameters

  [in] | is_enable_thread_safety | Enable thread safety.YES means to enable thread safety, while NO means to disable thread safety.

Returns
  None.

## ◆ executeJavaScript:()

+ (NSString *) executeJavaScript: |  | (NSString *) | java_script |

Execute javascript.

Parameters

  [in] | java_script | The javascript which needs to be executed.

Returns
  The result error information, such as syntax error warning, unsupported warning, and other error messages.

## ◆ flushLog()

+ (FSErrorCode) flushLog |  |  |

Flush the log file.

Returns
  Error code.

## ◆ getRenderConfig()

+ (FSRenderConfig *) getRenderConfig |  |  |

Get the rendering configuration.

Returns
  A rendering configuration object which shows current configuration.

## ◆ getVersion()

+ (NSString *) getVersion |  |  |

Get the version of current Foxit PDF SDK library.

Returns
  Version string.

## ◆ hasModuleLicenseRight:()

+ (BOOL) hasModuleLicenseRight: |  | (FSModuleName) | module_name |

Check if user has right to use a specified module of Foxit PDF SDK in current used license information (which is used to initialize Foxit PDF SDK).

In Foxit PDF SDK, once the library is initialized successfully, most feature can be used. But for some special features, they can be used only when specified modules are defined in license information. This function can be used to check if user has right for these special modules before using these feature.

Parameters

  [in] | module_name | Name of the module whose right is to be checked. Please refer to values starting from FSModuleNameConnectedPDF and this should be one of these values.

Returns
  YES means user has right to use the specified module, while NO means user does not have right to use the specified module.

## ◆ initialize:key:()

+ (FSErrorCode) initialize: |  | (NSString *) | sn
key: |  | (NSString *) | key

Initialize Foxit PDF SDK Library, with valid license information.

During the life-cycle of an application, this function can only be called once and should be called first before any other functions in Foxit PDF SDK can be called.
Once function FSLibrary::destroy is called, Foxit PDF SDK library cannot be initialized any more in the life-cycle of the application.

Parameters

  [in] | sn | String of sn information, which can be retrieved from "SN=" part in key file "gsdk_sn.txt" or "rdk_sn.txt".
  [in] | key | String of key information, which can be retrieved from "Sign=" part in key file "gsdk_key.txt" or "rdk_key.txt".

Returns
  FSErrSuccess means success.
  FSErrInvalidLicense means input license information is invalid.
  FSErrParam means parameter sn or key is an empty string.
  For more information about error code values, please refer to values starting from FSErrSuccess.

## ◆ initializeWithJSXFAThreadsafety:key:is_optimize_memory:enable_js_xfa_threadsafety:()

+ (FSErrorCode) initializeWithJSXFAThreadsafety: |  | (NSString *) | sn
key: |  | (NSString *) | key
is_optimize_memory: |  | (BOOL) | is_optimize_memory
enable_js_xfa_threadsafety: |  | (BOOL) | enable_js_xfa_threadsafety

Initialize Foxit PDF SDK Library, with valid license information.

During the life-cycle of an application, this function can only be called once and should be called first before any other functions in Foxit PDF SDK can be called.
Once function FSLibrary::destroy is called, Foxit PDF SDK library cannot be initialized any more in the life-cycle of the application.

Parameters

  [in] | sn | String of sn information, which can be retrieved from "SN=" part in key file "gsdk_sn.txt" or "rdk_sn.txt".
  [in] | key | String of key information, which can be retrieved from "Sign=" part in key file "gsdk_key.txt" or "rdk_key.txt".
  [in] | is_optimize_memory | The flag is used to attempt to optimize memory by cleaning up memory fragments. YES means to clean up memory fragments, and NO means not.
  [in] | enable_js_xfa_threadsafety | The flag is used to enable javascript and XFA module threadsafety. YES means to enable, and NO means not. Default value is NO. Users need to ensure that one pdf document is only operated by one thread at a time.

Returns
  FSErrSuccess means success.
  FSErrInvalidLicense means input license information is invalid.
  FSErrParam means parameter sn or key is an empty string.
  For more information about error code values, please refer to values starting from FSErrSuccess.

## ◆ matchExternalFontsOnly:()

+ (void) matchExternalFontsOnly: |  | (BOOL) | only_match |

Specify whether to match fonts only from external fonts.

Parameters

  [in] | only_match | YES means only match external fonts which are added by function FSLibrary::addExternalFontPath:. NO means match system fonts when external fonts not found. Default value is NO.

Returns
  None.

## ◆ registerSecurityCallback:callback:()

+ (BOOL) registerSecurityCallback: |  | (NSString *) | filter
callback: |  | (id<FSSecurityCallback>) | callback

Register a FSSecurityCallback object to Foxit PDF SDK for decryption of the PDFs with special encryption filters.

When this function is successful, Foxit PDF SDK will take over the input security callback object and user should not release this callback object directly anymore; otherwise unexpected crash may occurs later.

Parameters

  [in] | filter | The filter name of the security callback object. This should not be nil or an empty string. When users implement security callback of FSCustomSecurityCallback, users could specified their own custom filter string, but need to follow the PDF name conventions. When users implement security callback of FSCertificateSecurityCallback, the filter value must be set to "Adobe.PubSec". When users implement security callback of FSDRMSecurityCallback, the filter value must be set to "FoxitDRM", or some error may occur later. When users implement security callback of FSRMSSecurityCallback, the filter value must be set to "MicrosoftIRMServices" or "FoxitRMS", or some error may occur later.
  [in] | callback | A FSSecurityCallback object, which is implemented by user and based on callback class FSSecurityCallback. User should not inherit FSSecurityCallback directly, but inherit its derived class, such as FSCustomSecurityCallback, FSCertificateSecurityCallback, etc.

Returns
  YES means success, while NO means failure.

Note
  If module "RMS" is not defined in the license information which is used in function FSLibrary::initialize:key:, that means user has no right in using RMS related functions and this function will throw exception FSErrNoRMSModuleRight.

## ◆ registerSignatureCallback:sub_filter:signature_callback:()

+ (BOOL) registerSignatureCallback: |  | (NSString *) | filter
sub_filter: |  | (NSString *) | sub_filter
signature_callback: |  | (id<FSSignatureCallback>) | signature_callback

Register a third-party FSSignatureCallback object to Foxit PDF SDK for signing and verifying signature, along with the filter and sub filter name of the callback.

Foxit PDF SDK has default signature callbacks defined with filter and sub filter:

- filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.detached"
- filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.sha1"
- filter: "Adobe.PPKLite" and sub filter: "ETSI.CAdES.detached"
- filter: "Adobe.PPKLite" and sub filter: "ETSI.RFC3161"

If user wants to use a third-party signature callback, please call this function before signing or verifying signature process.
If user register a customized signature callback with the same filter and sub filter as default ones by this function, and the value of parameter is not nil, the default signature callback in Foxit PDF SDK will not have effect. If user register a customized signature callback with the same filter and sub filter as default ones by this function, and the value of parameter is nil,
the default signature callback in Foxit PDF SDK will have effect again.

Parameters

  [in] | filter | The filter name of the signature callback, in ASCII encoding. This should not be an empty string. Filter name is the name of the signature callback.
  [in] | sub_filter | The sub filter name of the signature callback, in ASCII encoding. Sub filter is to describe the encoding of signature value and key information in the signature dictionary.
  [in] | signature_callback | A customized FSSignatureCallback object, which is implemented by user and based on callback class FSSignatureCallback. User should ensure all the callback functions have been implemented in application level and should also ensure this signature callback object valid until Foxit PDF SDK is released by function FSLibrary::destroy. If this is nil, that means the registered third-party callback is to be removed from Foxit PDF SDK.

Returns
  YES means success, while NO means failure.

## ◆ registerXFAAppProviderCallback:()

+ (void) registerXFAAppProviderCallback: |  | (id<FSAppProviderCallback>) | callback |

Register an FSAppProviderCallback object to Foxit PDF SDK.

This function should be called first before processing XFA document.

Parameters

  [in] | callback | An FSAppProviderCallback object, which is implemented by user and based on callback class FSAppProviderCallback. User should ensure all the callback functions have been implemented in application level and should also ensure this XFA application provider callback object valid until Foxit PDF SDK is released by function FSLibrary::destroy.

Returns
  None.

Note
  If module "XFA" is not defined in the license information which is used in function FSLibrary::initialize:key:, that means user has no right in using XFA related functions and this function will throw exception FSErrNoXFAModuleRight.

## ◆ reinitialize()

+ (FSErrorCode) reinitialize |  |  |

Re-initialize Foxit PDF SDK Library.

When user meets out-of-memory error or user wants to re-initialize Foxit PDF SDK library before function FSLibrary::destroy is called, user can call this function to re-initialize Foxit PDF SDK Library.
Once function FSLibrary::destroy is called, Foxit PDF SDK library cannot be initialized any more in the life-cycle of the application.

Returns
  FSErrSuccess means success. For more information about error code values, please refer to values starting from FSErrSuccess.

## ◆ setActionCallback:()

+ (BOOL) setActionCallback: |  | (id<FSActionCallback>) | action_callback |

Set a FSActionCallback object to Foxit PDF SDK, in aid of performing PDF actions.

User should implement an action callback object and call this function to set the action callback object to Foxit PDF SDK if PDF actions need to be performed, such as filling a PDF form.

Parameters

  [in] | action_callback | A customized FSActionCallback object. nil means not use any action callback object. User should ensure all the callback functions have been implemented in application level. If this is a valid action callback object, Foxit PDF SDK will take over the management of this callback object and user should not release it directly.

Returns
  YES means success, while NO means failure.

## ◆ setAnnotIconProviderCallback:()

+ (BOOL) setAnnotIconProviderCallback: |  | (id<FSIconProviderCallback>) | annot_icon_provider |

Set a customized FSIconProviderCallback object to Foxit PDF SDK.

User can call this function to set a customized icon provider for annotation. If this function has been called several times, Foxit PDF SDK will only keep the last icon provider. If this function has not been called even once, Foxit PDF SDK will use the default standard icon provider.

Parameters

  [in] | annot_icon_provider | A customized annotation icon provider, which is implemented based on callback class FSIconProviderCallback. If this is nil, customized annotation icon provider will be removed from Foxit PDF SDK and default standard icon provider will be used instead. Application should ensure this icon provider object valid until it has been removed from Foxit PDF SDK or function FSLibrary::destroy is called.

Returns
  YES means success, while NO means failure.

Note
  Icon provider's ID and version are treated as the name of the icon provider, so please offer different "ID + version" for different icon providers by callback functions FSIconProviderCallback::getProviderID and FSIconProviderCallback::getProviderVersion.

## ◆ setCacheSize:()

+ (BOOL) setCacheSize: |  | (unsigned int) | size |

Set the upper limit of PDF library cache size.

If no cache size limit is set by application, the cache size will be set to 200 MegaBytes internally by default.

Parameters

  [in] | size | The upper limit of the cache, in MegaBytes, 0~4096. If set to 0, that means not to use limit of cache size.

Returns
  YES means success, while NO means failure.

## ◆ setDefaultICCProfilesPath:()

+ (void) setDefaultICCProfilesPath: |  | (NSString *) | icc_profile_folder_path |

Set path of folder which contains default ICC profile files.

Default ICC profile files are offered in "res" folder Foxit PDF SDK package. Default ICC profile files are "sRGB Color Space Profile.icm", "sGray.icc", and "USWebCoatedSWOP.icc". Foxit PDF SDK will load these default ICC profile files from input folder path.
If input folder path does not exist or default ICC profile files are not all in the specified folder, this function will throw FSErrFilePathNotExist.

Parameters

  [in] | icc_profile_folder_path | A valid path of a folder which contains default ICC profile files.

Returns
  None.

## ◆ setDocEventCallback:()

+ (BOOL) setDocEventCallback: |  | (id<FSDocEventCallback>) | callback |

Set a object to Foxit PDF SDK.

Parameters

  [in] | callback | A object. nil means not use any document event callback object.

Returns
  YES means success, while NO means failure.

## ◆ setFontMapperCallback:()

+ (BOOL) setFontMapperCallback: |  | (id<FSFontMapperCallback>) | callback |

Set a object to Foxit PDF SDK.

Once a valid custom font mapper callback is set to Foxit PDF SDK, Foxit PDF SDK will first use this callback when mapping a font.

Parameters

  [in] | callback | A object. nil means not use any custom font mapper callback object.

Returns
  YES means success, while NO means failure.

## ◆ setLogFile:()

+ (void) setLogFile: |  | (NSString *) | log_file_path |

Set the log file path.

After a log file path is set to Foxit PDF SDK, all the logs will be written to the log file. Currently, the log information in Foxit PDF SDK is simple; this will be improved in future version.

Parameters

  [in] | log_file_path | A log file path.

Returns
  None.

## ◆ setLogFileWithStreamCallback:()

+ (void) setLogFileWithStreamCallback: |  | (id<FSFileStreamCallback>) | log_file |

Set the log file stream.

After a log file is set to Foxit PDF SDK, all the logs will be written to the log file stream. Currently, the log information in Foxit PDF SDK is simple; this will be improved in future version.

Parameters

  [in] | log_file | A log file stream.

Returns
  None.

## ◆ setNotifierCallback:()

+ (BOOL) setNotifierCallback: |  | (id<FSNotifierCallback>) | notifier |

Set a object to Foxit PDF SDK.

User can call this function to set a notifier callback object to Foxit PDF SDK, so that when events (such as OOM) happens, user would be notified.

Parameters

  [in] | notifier | A object. User should ensure all the callback functions have been implemented in application level.

Returns
  YES means success, while NO means failure.

## ◆ setRenderConfig:()

+ (void) setRenderConfig: |  | (FSRenderConfig*) | render_config |

Set the rendering configuration.

Parameters

  [in] | render_config | A rendering configuration object to be set.

Returns
  None.

## ◆ setRenderTextGamma:()

+ (void) setRenderTextGamma: |  | (float) | gamma |

Set gamma value for text rendering.

If this function is not called to set gamma value, Foxit PDF SDK will use 2.2 as the default value.

Parameters

  [in] | gamma | Gamma value. It should be greater than 0.

Returns
  None.

## ◆ setTimeStampCallback:()

+ (BOOL) setTimeStampCallback: |  | (id<FSTimeStampCallback>) | timestamp_callback |

Set a FSTimeStampCallback object to Foxit PDF SDK, in aid of interacting with time stamp server.

When this function is successful, Foxit PDF SDK will take over the default time stamp interaction during signing and user should not release this callback object directly anymore; otherwise unexpected crash may occurs later.

Parameters

  [in] | timestamp_callback | A customized FSTimeStampCallback object, which is implemented by user and based on callback class FSTimeStampCallback. User should ensure all the callback functions have been implemented in application level and should also ensure this time stamp callback object valid until Foxit PDF SDK is released by function FSLibrary::destroy. If this is nil, that means the registered third-party callback is to be removed from Foxit PDF SDK.

Returns
  YES means success, while NO means failure.

## ◆ unregisterSecurityCallback:()

+ (BOOL) unregisterSecurityCallback: |  | (NSString *) | filter |

Unregister a FSSecurityCallback object from Foxit PDF SDK.

Parameters

  [in] | filter | The filter name which is used for registering a security callback object. Please refer to comment of parameter filter in function FSLibrary::registerSecurityCallback:callback:.

Returns
  YES means success, while NO means failure.

Note
  If module "RMS" is not defined in the license information which is used in function FSLibrary::initialize:key:, that means user has no right in using RMS related functions and this function will throw exception FSErrNoRMSModuleRight.

## ◆ unregisterSignatureCallback:sub_filter:()

+ (void) unregisterSignatureCallback: |  | (NSString *) | filter
sub_filter: |  | (NSString *) | sub_filter

Unregister the third-party FSSignatureCallback object, which is associated with a specific filter and sub-filter, from the Foxit PDF SDK. If a default signature is available, it will be restored together with its filter and sub-filter values.

Foxit PDF SDK has default signature callbacks defined with filter and sub filter:

- filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.detached"
- filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.sha1"
- filter: "Adobe.PPKLite" and sub filter: "ETSI.CAdES.detached"
- filter: "Adobe.PPKLite" and sub filter: "ETSI.RFC3161"

Parameters

  [in] | filter | The filter name of the signature callback, in ASCII encoding. This should not be an empty string. Filter name is the name of the signature callback.
  [in] | sub_filter | The sub filter name of the signature callback, in ASCII encoding. Sub filter is to describe the encoding of signature value and key information in the signature dictionary.

Returns
  None.