PDFEdit Component

Properties   Methods   Events   Config Settings   Errors  

The PDFEdit component provides text and document editing capabilities for PDFs.

Syntax

nsoftware.SecurePDF.PDFEdit

Remarks

The PDFEdit component can be used to automate search and replace operations, text extraction, content composition, and document merging and splitting.

To begin, provide the input document as a file (InputFile), byte array (InputData), or stream (SetInputStream) and call the Open method. When finished editing the document, call the Close method to close it and save the changes to either OutputFile, OutputData, or the stream set in SetOutputStream.

Search, Replace, and Extract Text

Use the ReplacePageText and ReplaceDocumentText methods to iterate through the page or document content and replace all the text elements that match the specified pattern with the provided text. The component will fire the ReplaceText event during this operation, providing the flexibility of skipping certain text blocks or updating the replacement string on the fly. For example: pdfedit.InputFile = "invoice.pdf"; pdfedit.OutputFile = "invoice_filled.pdf"; pdfedit.OnReplaceText += (s, e) => { if (e.Substitute == "/n software") { e.Substitute = "my company"; } }; pdfedit.Open(); int occurrences = pdfedit.ReplacePageText(0, "SELLER_NAME", "/n software"); pdfedit.Close(); Additionally, the GetPageText and GetDocumentText methods let you extract all the text residing on a specific page or in the entire document.

Content Composition

With PDFEdit, you can also create documents from scratch or add text or images to existing documents using the editing API. This consists of the following four methods:

The above methods are complemented by a set of formatting methods that let you choose the parameters of the added text or image (where, what color, how big, or how skewed):

  • SetPosition sets the page to work with and places the cursor at a specific position on the page.
  • SetFont sets the font to use, including its size, style, and color.
  • SetAlignment sets the block alignment (left/center/right, top/center/bottom).
  • SetTransform sets the transformation matrix, which alters positioning, scaling, rotation angle, and skew.

Document Merging and Splitting

Document-level operations can be performed with the AppendPage, InsertPage, RemovePage, and RemovePages methods.

To copy pages from one document to another, open each document in an individual PDFEdit object. Then, using the SelectPage method, select the page of document 1 that you want to add to document 2, and assign the PDFPage object populated in its SelectedPage property to the NewPage property of the recipient document. Finally, commit the page to the recipient document using the AppendPage or InsertPage method. dest.InputFile = "recipient.pdf"; dest.Open(); src.InputFile = "donor.pdf"; src.Open(); src.SelectPage(0); dest.NewPage = src.SelectedPage; dest.AppendPage(); dest.Close(); src.Close(); To split the document in two, use the RemovePages method to remove the respective subsets of pages from the document, then save each remaining part. For example: pdfedit.InputFile = "input_4_pages.pdf"; pdfedit.Open(); // Remove the pages after page 1, and save the first part (pages 0-1) pdfedit.OutputFile = "input_first.pdf"; pdfedit.RemovePages(2, 2); pdfedit.Close(); // Remove the pages up to and including page 1, and save the second part (pages 2-3) pdfedit.OutputFile = "input_second.pdf"; pdfedit.Open(); pdfedit.RemovePages(0, 2); pdfedit.Close();

Property List


The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

AttachmentsA collection of all attached files found in the document.
DecryptionCertThe decryption certificate.
FontThe currently set font.
InputDataA byte array containing the PDF document to process.
InputFileThe PDF file to process.
MediaA collection of all media objects found in the document.
NewPageA placeholder for a page object to be added to the document.
OutputDataA byte array containing the PDF document after processing.
OutputFileThe path to a local file where the output will be written.
OverwriteWhether or not the component should overwrite files.
PasswordThe password to decrypt the document with.
PositionThe currently set position.
SelectedPageThe currently selected page.

Method List


The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

AddAttachmentAdds an attachment to the document.
AddBitmapAdds a bitmap image to the document.
AddDrawingAdds a vector drawing to the document.
AddTextBlockAdds a block of text to the document.
AppendPageAppends a page to the end of the document.
CloseCloses the opened document.
ConfigSets or retrieves a configuration setting.
ConvertConverts the document to a different format.
CreateNewCreates a new PDF document.
EncryptedChecks whether the document is encrypted.
GetDocumentPropertyReturns the value of a document property.
GetDocumentTextReturns the entire text content contained in the document.
GetPagePropertyReturns the value of a page property.
GetPageTextReturns the text content residing on a specific page.
InsertPageInserts a page into the document.
OpenOpens the document for processing.
RemoveAttachmentRemoves an attachment from the document.
RemovePageRemoves a page from the document.
RemovePagesRemoves a subset of pages from the document.
ReplaceDocumentTextReplaces text in the document.
ReplacePageTextReplaces text on a page.
ResetResets the component.
SaveAttachmentSaves a PDF attachment to a file.
SaveMediaSaves a media object to a file.
SelectPageSelects a page.
SetAlignmentSets the object alignment for subsequent insertion operations.
SetDocumentPropertySets the value of a document property.
SetFontSets the font properties to be applied to text.
SetInputStreamSets the stream containing the PDF document to process.
SetOutputStreamSets the stream to write the processed document to.
SetPositionSets the page and position for new text blocks or images.
SetTransformSets the object transformation parameters for subsequent insertion operations.

Event List


The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

DocumentInfoFired when the document has been loaded into memory.
ErrorFired when information is available about errors during data delivery.
LogFired once for each log message.
PasswordFired when the component detects that the document is encrypted with a password.
RecipientInfoFired for each recipient certificate of the encrypted document.
ReplaceTextFired when a substring in the document is due to be replaced.

Config Settings


The following is a list of config settings for the component with short descriptions. Click on the links for further details.

AFRelationship[Key]The value of the AFRelationship key for the attachment.
AutoTurnPagesWhether to change the page automatically upon exceeding the upper or lower page boundary.
CloseInputStreamAfterProcessingWhether to close the input stream after processing.
CloseOutputStreamAfterProcessingWhether to close the output stream after processing.
CompressStreamsWhether to compress stream objects.
DefaultPageHeightThe default height for newly added pages.
DefaultPageWidthThe default width for newly added pages.
EnforcePDFAWhether to enforce PDF/A compliance.
FallbackFontThe fallback font.
FontPathsThe font search paths.
KeepPositionOnInsertWhether to keep the current position after inserting an element.
LoadMediaWhether to load images from the document.
LogLevelThe level of detail that is logged.
OwnerPasswordThe owner password to decrypt the document with.
PageCopyByRefElementsThe names of page elements to be copied by reference.
PDFALevelThe PDF/A conformance level to enforce.
PDFAPolicyThe PDF/A policy to follow.
RightPaddingThe width of the whitespace gap to the right of newly added elements.
SaveChangesWhether to save changes made to the document.
SystemFontNamesThe system font names.
TempPathThe location where temporary files are stored.
BuildInfoInformation about the product's build.
GUIAvailableWhether or not a message loop is available for processing events.
LicenseInfoInformation about the current license.
MaskSensitiveDataWhether sensitive data is masked in log messages.
UseInternalSecurityAPIWhether or not to use the system security libraries or an internal implementation.

Attachments Property (PDFEdit Component)

A collection of all attached files found in the document.

Syntax

public PDFAttachmentList Attachments { get; }
Public Property Attachments As PDFAttachmentList

Remarks

This property is used to access the details of all the attached files identified in the document. Use the AddAttachment, RemoveAttachment, and SaveAttachment methods to add, remove, and save attachments to/from this collection respectively.

This property is not available at design time.

Please refer to the PDFAttachment type for a complete list of fields.

DecryptionCert Property (PDFEdit Component)

The decryption certificate.

Syntax

public Certificate DecryptionCert { get; set; }
Public Property DecryptionCert As Certificate

Remarks

This property is used to provide the certificate used for decryption. Note that this certificate must have a private key associated with it.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

Font Property (PDFEdit Component)

The currently set font.

Syntax

public PDFFont Font { get; }
Public ReadOnly Property Font As PDFFont

Remarks

This property is used to access the font details specified using the SetFont method.

This property is read-only and not available at design time.

Please refer to the PDFFont type for a complete list of fields.

InputData Property (PDFEdit Component)

A byte array containing the PDF document to process.

Syntax

public byte[] InputData { get; set; }
Public Property InputData As Byte()

Remarks

This property is used to assign a byte array containing the PDF document to be processed.

This property is not available at design time.

InputFile Property (PDFEdit Component)

The PDF file to process.

Syntax

public string InputFile { get; set; }
Public Property InputFile As String

Default Value

""

Remarks

This property is used to provide a path to the PDF document to be processed.

Media Property (PDFEdit Component)

A collection of all media objects found in the document.

Syntax

public PDFMediaList Media { get; }
Public Property Media As PDFMediaList

Remarks

This property is used to access the details of all the media objects identified in the document. The only media type that is currently supported is bitmap (a fixed-size image).

Use the AddBitmap method to add images to this collection, and use the SaveMedia method to extract the embedded media object to a local file.

This property is not available at design time.

Please refer to the PDFMedia type for a complete list of fields.

NewPage Property (PDFEdit Component)

A placeholder for a page object to be added to the document.

Syntax

public PDFPage NewPage { get; set; }
Public Property NewPage As PDFPage

Remarks

This property is used to specify a page object from another document to be added to the current document using the AppendPage or InsertPage methods.

This property is not available at design time.

Please refer to the PDFPage type for a complete list of fields.

OutputData Property (PDFEdit Component)

A byte array containing the PDF document after processing.

Syntax

public byte[] OutputData { get; }
Public ReadOnly Property OutputData As Byte()

Remarks

This property is used to read the byte array containing the produced output after the operation has completed. It will only be set if an output file and output stream have not been assigned via OutputFile and SetOutputStream respectively.

This property is read-only and not available at design time.

OutputFile Property (PDFEdit Component)

The path to a local file where the output will be written.

Syntax

public string OutputFile { get; set; }
Public Property OutputFile As String

Default Value

""

Remarks

This property is used to provide a path where the resulting PDF document will be saved after the operation has completed.

Overwrite Property (PDFEdit Component)

Whether or not the component should overwrite files.

Syntax

public bool Overwrite { get; set; }
Public Property Overwrite As Boolean

Default Value

False

Remarks

This property indicates whether or not the component will overwrite OutputFile, OutputData, or the stream set in SetOutputStream. If set to false, an error will be thrown whenever OutputFile, OutputData, or the stream set in SetOutputStream exists before an operation.

Password Property (PDFEdit Component)

The password to decrypt the document with.

Syntax

public string Password { get; set; }
Public Property Password As String

Default Value

""

Remarks

This property is used to provide the user password for decryption. Though it may be different from OwnerPassword, most implementations use the same value for both.

Position Property (PDFEdit Component)

The currently set position.

Syntax

public PDFPagePosition Position { get; }
Public ReadOnly Property Position As PDFPagePosition

Remarks

This property is used to access the position details specified using the SetPosition method.

This property is read-only and not available at design time.

Please refer to the PDFPagePosition type for a complete list of fields.

SelectedPage Property (PDFEdit Component)

The currently selected page.

Syntax

public PDFPage SelectedPage { get; }
Public ReadOnly Property SelectedPage As PDFPage

Remarks

This property is used to access the page object that corresponds to the page selected using the SelectPage method. Use page selection to copy a page from one document to another.

This property is read-only and not available at design time.

Please refer to the PDFPage type for a complete list of fields.

AddAttachment Method (PDFEdit Component)

Adds an attachment to the document.

Syntax

public void AddAttachment(string fileName, string description);

Async Version
public async Task AddAttachment(string fileName, string description);
public async Task AddAttachment(string fileName, string description, CancellationToken cancellationToken);
Public Sub AddAttachment(ByVal FileName As String, ByVal Description As String)

Async Version
Public Sub AddAttachment(ByVal FileName As String, ByVal Description As String) As Task
Public Sub AddAttachment(ByVal FileName As String, ByVal Description As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to add an attachment (embedded file) to the document and to the Attachments collection.

The FileName and Description parameters specify the filename and description of the attachment respectively.

Example: component.InputFile = "input.pdf"; component.OutputFile = "input_with_attachment.pdf"; component.Open(); component.AddAttachment("foo.txt", "desc"); // Alternatively, create a PDFAttachment object and add it to Attachments manually: PDFAttachment attachment = new PDFAttachment(); attachment.FileName = "foo.txt"; // or attachment.DataB = new byte[] { ... }; // or attachment.InputStream = new FileStream(...); attachment.Description = "desc"; component.Attachments.Add(attachment); // Or using one of the constructors: component.Attachments.Add(new PDFAttachment("foo.txt", "desc")); component.Close(); The full list of attachments is contained in the Attachments collection.

NOTE: If the document is not already opened, this method will open it, perform the operation, then close it.

AddBitmap Method (PDFEdit Component)

Adds a bitmap image to the document.

Syntax

public void AddBitmap(string format, byte[] bitmapBytes, int width, int height);

Async Version
public async Task AddBitmap(string format, byte[] bitmapBytes, int width, int height);
public async Task AddBitmap(string format, byte[] bitmapBytes, int width, int height, CancellationToken cancellationToken);
Public Sub AddBitmap(ByVal Format As String, ByVal BitmapBytes As Byte(), ByVal Width As Integer, ByVal Height As Integer)

Async Version
Public Sub AddBitmap(ByVal Format As String, ByVal BitmapBytes As Byte(), ByVal Width As Integer, ByVal Height As Integer) As Task
Public Sub AddBitmap(ByVal Format As String, ByVal BitmapBytes As Byte(), ByVal Width As Integer, ByVal Height As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method is used to add a bitmap image to the document at the current Position and to the Media collection.

The Format and BitmapBytes parameters specify the format and raw data of the serialized image respectively. The former can take one of the following values:

  • JPEG2000
  • JPEG
  • Custom
The Width and Height parameters specify the original width and height of the bitmap in pixels.

The full list of images is contained in the Media collection. Use the following methods to adjust new image parameters:

AddDrawing Method (PDFEdit Component)

Adds a vector drawing to the document.

Syntax

public void AddDrawing(string format, byte[] drawingBytes);

Async Version
public async Task AddDrawing(string format, byte[] drawingBytes);
public async Task AddDrawing(string format, byte[] drawingBytes, CancellationToken cancellationToken);
Public Sub AddDrawing(ByVal Format As String, ByVal DrawingBytes As Byte())

Async Version
Public Sub AddDrawing(ByVal Format As String, ByVal DrawingBytes As Byte()) As Task
Public Sub AddDrawing(ByVal Format As String, ByVal DrawingBytes As Byte(), cancellationToken As CancellationToken) As Task

Remarks

This method is used to add a vector drawing to the document at the current Position.

The Format and DrawingBytes parameters specify the format and raw data (as an encoded PDF appearance stream) of the drawing respectively. The former is reserved for future use.

AddTextBlock Method (PDFEdit Component)

Adds a block of text to the document.

Syntax

public void AddTextBlock(string text);

Async Version
public async Task AddTextBlock(string text);
public async Task AddTextBlock(string text, CancellationToken cancellationToken);
Public Sub AddTextBlock(ByVal Text As String)

Async Version
Public Sub AddTextBlock(ByVal Text As String) As Task
Public Sub AddTextBlock(ByVal Text As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to insert a block of Text into the document at the current Position. Use the following methods to adjust new text block parameters:

AppendPage Method (PDFEdit Component)

Appends a page to the end of the document.

Syntax

public void AppendPage();

Async Version
public async Task AppendPage();
public async Task AppendPage(CancellationToken cancellationToken);
Public Sub AppendPage()

Async Version
Public Sub AppendPage() As Task
Public Sub AppendPage(cancellationToken As CancellationToken) As Task

Remarks

This method is used to append the page specified in the NewPage property to the end of the opened document. If NewPage is not set, the component will append a new blank page.

Note that when this method returns, the Position will not be automatically moved to the newly appended page.

Close Method (PDFEdit Component)

Closes the opened document.

Syntax

public void Close();

Async Version
public async Task Close();
public async Task Close(CancellationToken cancellationToken);
Public Sub Close()

Async Version
Public Sub Close() As Task
Public Sub Close(cancellationToken As CancellationToken) As Task

Remarks

This method is used to close the previously opened document. It should always be preceded by a call to the Open method.

Example: component.InputFile = "input.pdf"; component.Open(); // Some operation component.Close(); If any changes are made to the document, they will be saved automatically to OutputFile, OutputData, or the stream set in SetOutputStream when this method is called. To configure this saving behavior, set the SaveChanges configuration setting.

Config Method (PDFEdit Component)

Sets or retrieves a configuration setting.

Syntax

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);
Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Convert Method (PDFEdit Component)

Converts the document to a different format.

Syntax

public void Convert(string format);

Async Version
public async Task Convert(string format);
public async Task Convert(string format, CancellationToken cancellationToken);
Public Sub Convert(ByVal Format As String)

Async Version
Public Sub Convert(ByVal Format As String) As Task
Public Sub Convert(ByVal Format As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to convert the document to the format specified by the Format parameter, which can take one of the following values:

Format Description
CompressedPDF All data streams included in the document are compressed.
UncompressedPDF All data streams included in the document are decompressed.

CreateNew Method (PDFEdit Component)

Creates a new PDF document.

Syntax

public void CreateNew();

Async Version
public async Task CreateNew();
public async Task CreateNew(CancellationToken cancellationToken);
Public Sub CreateNew()

Async Version
Public Sub CreateNew() As Task
Public Sub CreateNew(cancellationToken As CancellationToken) As Task

Remarks

This method is used to create a blank PDF document with one empty page. Use the DefaultPageWidth and DefaultPageHeight configuration settings to adjust the new page dimensions. Having created the baseline document, use the component's methods to add objects to it.

Encrypted Method (PDFEdit Component)

Checks whether the document is encrypted.

Syntax

public bool Encrypted();

Async Version
public async Task<bool> Encrypted();
public async Task<bool> Encrypted(CancellationToken cancellationToken);
Public Function Encrypted() As Boolean

Async Version
Public Function Encrypted() As Task(Of Boolean)
Public Function Encrypted(cancellationToken As CancellationToken) As Task(Of Boolean)

Remarks

This method is used to determine whether or not the document is encrypted. It will return false if the document is pseudo-encrypted with an empty password.

Example: component.InputFile = "input.pdf"; if (component.Encrypted()) { // Set Password or DecryptionCert } component.Open(); // Some operation component.Close(); NOTE: If the document is not already opened, this method will open it, perform the operation, then close it.

GetDocumentProperty Method (PDFEdit Component)

Returns the value of a document property.

Syntax

public string GetDocumentProperty(string documentProperty);

Async Version
public async Task<string> GetDocumentProperty(string documentProperty);
public async Task<string> GetDocumentProperty(string documentProperty, CancellationToken cancellationToken);
Public Function GetDocumentProperty(ByVal DocumentProperty As String) As String

Async Version
Public Function GetDocumentProperty(ByVal DocumentProperty As String) As Task(Of String)
Public Function GetDocumentProperty(ByVal DocumentProperty As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

This method is used to obtain the value of a document property. Together with SetDocumentProperty, this method provides an extensible way of managing the document settings that are not available through other means. The list of settings below may be extended in the future.

The DocumentProperty parameter specifies the document property to read and can take one of the following values:

Document property Default value Description
Xmp "" The XML body of the XMP metadata embedded in the document.
Xmp[property] "" The value of an XMP metadata property.
XmpStream "" The hex-encoded content of the XMP metadata stream.

Example: pdfedit.InputFile = "input.pdf"; pdfedit.Open(); string description = pdfedit.GetDocumentProperty("Xmp[dc:description]"); string metadataXml = pdfedit.GetDocumentProperty("Xmp"); // Use language descriptors for multi-language properties string descriptionEs = pdfedit.GetDocumentProperty("Xmp[dc:description[es]]"); pdfedit.Close(); NOTE: Each document property is only populated once the document has been loaded, which is reported by the DocumentInfo event.

GetDocumentText Method (PDFEdit Component)

Returns the entire text content contained in the document.

Syntax

public string GetDocumentText();

Async Version
public async Task<string> GetDocumentText();
public async Task<string> GetDocumentText(CancellationToken cancellationToken);
Public Function GetDocumentText() As String

Async Version
Public Function GetDocumentText() As Task(Of String)
Public Function GetDocumentText(cancellationToken As CancellationToken) As Task(Of String)

Remarks

This method is used to obtain the whole body of text from the opened document.

GetPageProperty Method (PDFEdit Component)

Returns the value of a page property.

Syntax

public string GetPageProperty(int pageIndex, string pageProperty);

Async Version
public async Task<string> GetPageProperty(int pageIndex, string pageProperty);
public async Task<string> GetPageProperty(int pageIndex, string pageProperty, CancellationToken cancellationToken);
Public Function GetPageProperty(ByVal PageIndex As Integer, ByVal PageProperty As String) As String

Async Version
Public Function GetPageProperty(ByVal PageIndex As Integer, ByVal PageProperty As String) As Task(Of String)
Public Function GetPageProperty(ByVal PageIndex As Integer, ByVal PageProperty As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

This method is used to obtain general information about the pages of the document, such as their dimensions and content positioning details.

The PageIndex parameter specifies the page to read information about (with a valid range from 0 to PageCount - 1), and the PageProperty parameter specifies the page property to read. The latter can take one of the following values:

Page property Default value Description
CropLowerLeftX 0 The lower-left X coordinate of the page crop area in points.
CropLowerLeftY 0 The lower-left Y coordinate of the page crop area in points.
CropUpperRightX 0 The upper-right X coordinate of the page crop area in points.
CropUpperRightY 0 The upper-right Y coordinate of the page crop area in points.
Height 0 The height of the page in points. Both integer and decimal values are supported.
MediaLowerLeftX 0 The lower-left X coordinate of the page media area in points.
MediaLowerLeftY 0 The lower-left Y coordinate of the page media area in points.
MediaUpperRightX 0 The upper-right X coordinate of the page media area in points.
MediaUpperRightY 0 The upper-right Y coordinate of the page media area in points.
Rotation 0 The rotation angle of the page in degrees. Possible values: 0, 90, 180, 270.
Width 0 The width of the page in points. Both integer and decimal values are supported.

Example: int pageCount = 0; component.OnDocumentInfo += (s, e) => { pageCount = e.PageCount; }; component.InputFile = "input.pdf"; component.Open(); for (int i = 0; i < pageCount; i++) component.GetPageProperty(i, "Height"); component.Close(); The page properties can be used to adjust the position of the signature widget based on the page dimensions. For example: int x = int.Parse(pdfsign.GetPageProperty(0, "Width")) - 100; int y = int.Parse(pdfsign.GetPageProperty(0, "Height")) - 100; pdfsign.SetWidgetProperty("OffsetX", x.ToString()); pdfsign.SetWidgetProperty("OffsetY", y.ToString()); NOTE: Each page property is only populated once the document has been loaded, which is reported by the DocumentInfo event.

NOTE: If the document is not already opened, this method will open it, perform the operation, then close it.

GetPageText Method (PDFEdit Component)

Returns the text content residing on a specific page.

Syntax

public string GetPageText(int pageIndex);

Async Version
public async Task<string> GetPageText(int pageIndex);
public async Task<string> GetPageText(int pageIndex, CancellationToken cancellationToken);
Public Function GetPageText(ByVal PageIndex As Integer) As String

Async Version
Public Function GetPageText(ByVal PageIndex As Integer) As Task(Of String)
Public Function GetPageText(ByVal PageIndex As Integer, cancellationToken As CancellationToken) As Task(Of String)

Remarks

This method is used to obtain a part of the document text residing on the page specified by the PageIndex parameter (zero-based).

InsertPage Method (PDFEdit Component)

Inserts a page into the document.

Syntax

public void InsertPage(int pageIndex);

Async Version
public async Task InsertPage(int pageIndex);
public async Task InsertPage(int pageIndex, CancellationToken cancellationToken);
Public Sub InsertPage(ByVal PageIndex As Integer)

Async Version
Public Sub InsertPage(ByVal PageIndex As Integer) As Task
Public Sub InsertPage(ByVal PageIndex As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method is used to insert the page specified in the NewPage property into the opened document at the position specified by the PageIndex parameter (zero-based). If NewPage is not set, the component will insert a new blank page.

Note that when this method returns, the Position will not be automatically moved to the newly inserted page.

Open Method (PDFEdit Component)

Opens the document for processing.

Syntax

public void Open();

Async Version
public async Task Open();
public async Task Open(CancellationToken cancellationToken);
Public Sub Open()

Async Version
Public Sub Open() As Task
Public Sub Open(cancellationToken As CancellationToken) As Task

Remarks

This method is used to open the document specified in InputFile, InputData, or SetInputStream before performing some operation on it, such as extracting, editing, or replacing text. When finished, call Close to complete or discard the operation.

It is recommended to use this method (alongside Close) when performing multiple operations on the document at once.

RemoveAttachment Method (PDFEdit Component)

Removes an attachment from the document.

Syntax

public void RemoveAttachment(int index);

Async Version
public async Task RemoveAttachment(int index);
public async Task RemoveAttachment(int index, CancellationToken cancellationToken);
Public Sub RemoveAttachment(ByVal Index As Integer)

Async Version
Public Sub RemoveAttachment(ByVal Index As Integer) As Task
Public Sub RemoveAttachment(ByVal Index As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method is used to remove an attachment from the document and from the Attachments collection.

The Index parameter is the index of the attachment in the Attachments collection to be removed.

Example: pdfsign.InputFile = "input_with_attachment.pdf"; pdfsign.OutputFile = "attachment_removed.pdf"; pdfsign.Open(); pdfsign.RemoveAttachment(0); // Alternatively, remove an attachment from Attachments manually: PDFAttachment attachment = pdfsign.Attachments[0]; pdfsign.Attachments.Remove(attachment); pdfsign.Close(); NOTE: If the document is not already opened, this method will open it, perform the operation, then close it.

RemovePage Method (PDFEdit Component)

Removes a page from the document.

Syntax

public void RemovePage(int pageIndex);

Async Version
public async Task RemovePage(int pageIndex);
public async Task RemovePage(int pageIndex, CancellationToken cancellationToken);
Public Sub RemovePage(ByVal PageIndex As Integer)

Async Version
Public Sub RemovePage(ByVal PageIndex As Integer) As Task
Public Sub RemovePage(ByVal PageIndex As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method is used to remove the page specified by the PageIndex parameter (zero-based) from the opened document.

RemovePages Method (PDFEdit Component)

Removes a subset of pages from the document.

Syntax

public void RemovePages(int pageIndex, int count);

Async Version
public async Task RemovePages(int pageIndex, int count);
public async Task RemovePages(int pageIndex, int count, CancellationToken cancellationToken);
Public Sub RemovePages(ByVal PageIndex As Integer, ByVal Count As Integer)

Async Version
Public Sub RemovePages(ByVal PageIndex As Integer, ByVal Count As Integer) As Task
Public Sub RemovePages(ByVal PageIndex As Integer, ByVal Count As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method is used to remove a sequence of Count pages from the opened document starting at the position specified by the PageIndex parameter (zero-based).

ReplaceDocumentText Method (PDFEdit Component)

Replaces text in the document.

Syntax

public int ReplaceDocumentText(string pattern, string value);

Async Version
public async Task<int> ReplaceDocumentText(string pattern, string value);
public async Task<int> ReplaceDocumentText(string pattern, string value, CancellationToken cancellationToken);
Public Function ReplaceDocumentText(ByVal Pattern As String, ByVal Value As String) As Integer

Async Version
Public Function ReplaceDocumentText(ByVal Pattern As String, ByVal Value As String) As Task(Of Integer)
Public Function ReplaceDocumentText(ByVal Pattern As String, ByVal Value As String, cancellationToken As CancellationToken) As Task(Of Integer)

Remarks

This method is used to replace all entries of Pattern with Value in the whole document.

The ReplaceText event will fire repeatedly during its work to report every new search entry identified in the document. Subscribe to that event to adjust the substitute on the fly.

This method returns the number of occurrences found and replaced.

ReplacePageText Method (PDFEdit Component)

Replaces text on a page.

Syntax

public int ReplacePageText(int pageIndex, string pattern, string value);

Async Version
public async Task<int> ReplacePageText(int pageIndex, string pattern, string value);
public async Task<int> ReplacePageText(int pageIndex, string pattern, string value, CancellationToken cancellationToken);
Public Function ReplacePageText(ByVal PageIndex As Integer, ByVal Pattern As String, ByVal Value As String) As Integer

Async Version
Public Function ReplacePageText(ByVal PageIndex As Integer, ByVal Pattern As String, ByVal Value As String) As Task(Of Integer)
Public Function ReplacePageText(ByVal PageIndex As Integer, ByVal Pattern As String, ByVal Value As String, cancellationToken As CancellationToken) As Task(Of Integer)

Remarks

This method is used to replace all entries of Pattern with Value on the page specified by the PageIndex parameter (zero-based).

The ReplaceText event will fire repeatedly during its work to report every new search entry identified on the page. Subscribe to that event to adjust the substitute on the fly.

This method returns the number of occurrences found and replaced.

Reset Method (PDFEdit Component)

Resets the component.

Syntax

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);
Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

This method is used to reset the component's properties and configuration settings to their default values.

SaveAttachment Method (PDFEdit Component)

Saves a PDF attachment to a file.

Syntax

public void SaveAttachment(int index, string fileName);

Async Version
public async Task SaveAttachment(int index, string fileName);
public async Task SaveAttachment(int index, string fileName, CancellationToken cancellationToken);
Public Sub SaveAttachment(ByVal Index As Integer, ByVal FileName As String)

Async Version
Public Sub SaveAttachment(ByVal Index As Integer, ByVal FileName As String) As Task
Public Sub SaveAttachment(ByVal Index As Integer, ByVal FileName As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to retrieve the contents of an attachment from the document and save it to a file. It does not modify the Attachments collection's contents.

The Index parameter is the index of the attachment in the Attachments collection to be saved.

The FileName parameter specifies the filename that the attachment will be saved to.

Example: component.InputFile = "input_with_attachment.pdf"; component.Open(); component.SaveAttachment(0, "a.dat"); component.Close(); Example (saving to a stream): component.InputFile = "input_with_attachment.pdf"; component.Attachments[0].OutputStream = myStream; component.SaveAttachment(0, null); // null means use the OutputStream field if it's set NOTE: If the document is not already opened, this method will open it, perform the operation, then close it.

SaveMedia Method (PDFEdit Component)

Saves a media object to a file.

Syntax

public void SaveMedia(int index, string fileName);

Async Version
public async Task SaveMedia(int index, string fileName);
public async Task SaveMedia(int index, string fileName, CancellationToken cancellationToken);
Public Sub SaveMedia(ByVal Index As Integer, ByVal FileName As String)

Async Version
Public Sub SaveMedia(ByVal Index As Integer, ByVal FileName As String) As Task
Public Sub SaveMedia(ByVal Index As Integer, ByVal FileName As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to retrieve the contents of a media object from the document and save it to a file. It does not modify the Media collection's contents.

The Index parameter is the index of the media object in the Media collection to be saved.

The FileName parameter specifies the filename that the media object will be saved to.

Example: pdfedit.InputFile = "input_with_pictures.pdf"; pdfedit.Open(); pdfedit.SaveMedia(0, "picture.jpg"); pdfedit.Close(); Example (saving to a stream): pdfedit.InputFile = "input_with_pictures.pdf"; pdfedit.Open(); pdfedit.Media[0].OutputStream = myStream; pdfedit.SaveMedia(0, null); // null means use the OutputStream field if it's set pdfedit.Close();

SelectPage Method (PDFEdit Component)

Selects a page.

Syntax

public void SelectPage(int pageIndex);

Async Version
public async Task SelectPage(int pageIndex);
public async Task SelectPage(int pageIndex, CancellationToken cancellationToken);
Public Sub SelectPage(ByVal PageIndex As Integer)

Async Version
Public Sub SelectPage(ByVal PageIndex As Integer) As Task
Public Sub SelectPage(ByVal PageIndex As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method is used to select the page specified by the PageIndex parameter (zero-based) and populate its details in the SelectedPage property. Use page selection to access a page's properties or copy it to another document.

SetAlignment Method (PDFEdit Component)

Sets the object alignment for subsequent insertion operations.

Syntax

public void SetAlignment(int horizontalAlignment, int verticalAlignment);

Async Version
public async Task SetAlignment(int horizontalAlignment, int verticalAlignment);
public async Task SetAlignment(int horizontalAlignment, int verticalAlignment, CancellationToken cancellationToken);
Public Sub SetAlignment(ByVal HorizontalAlignment As Integer, ByVal VerticalAlignment As Integer)

Async Version
Public Sub SetAlignment(ByVal HorizontalAlignment As Integer, ByVal VerticalAlignment As Integer) As Task
Public Sub SetAlignment(ByVal HorizontalAlignment As Integer, ByVal VerticalAlignment As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method is used to set the horizontal and vertical alignment parameters to apply when AddTextBlock or AddBitmap is called. Alignment specifies the position of the newly added text block or image relative to the current Position on the page.

The HorizontalAlignment parameter specifies the horizontal alignment and can be one of the following values:

0 (haLeft - default)
1 (haCenter)
2 (haRight)

The VerticalAlignment parameter specifies the vertical alignment and can be one of the following values:

0 (vaTop - default)
1 (vaCenter)
2 (vaBottom)

SetDocumentProperty Method (PDFEdit Component)

Sets the value of a document property.

Syntax

public void SetDocumentProperty(string documentProperty, string value);

Async Version
public async Task SetDocumentProperty(string documentProperty, string value);
public async Task SetDocumentProperty(string documentProperty, string value, CancellationToken cancellationToken);
Public Sub SetDocumentProperty(ByVal DocumentProperty As String, ByVal Value As String)

Async Version
Public Sub SetDocumentProperty(ByVal DocumentProperty As String, ByVal Value As String) As Task
Public Sub SetDocumentProperty(ByVal DocumentProperty As String, ByVal Value As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to adjust properties of the opened document. Together with GetDocumentProperty, this method provides an extensible way of managing the document settings that are not available through other means. The list of settings below may be extended in the future.

The DocumentProperty and Value parameters specify the document property and value to set respectively. The former can take one of the following values:

Document property Default value Description
Xmp "" The XML body of the XMP metadata embedded in the document.
Xmp[property] "" The value of an XMP metadata property.
XmpStream "" The hex-encoded content of the XMP metadata stream.

Example: pdfedit.InputFile = "input.pdf"; pdfedit.Open(); pdfedit.SetDocumentProperty("Xmp[dc:description]", "My first book draft"); pdfedit.SetDocumentProperty("Xmp", "...xml data here..."); // Use language descriptors for multi-language properties pdfedit.SetDocumentProperty("Xmp[dc:description[es]]", "El primer borrador de mi libro"); pdfedit.Close();

SetFont Method (PDFEdit Component)

Sets the font properties to be applied to text.

Syntax

public void SetFont(string name, string size, string style, string color);

Async Version
public async Task SetFont(string name, string size, string style, string color);
public async Task SetFont(string name, string size, string style, string color, CancellationToken cancellationToken);
Public Sub SetFont(ByVal Name As String, ByVal Size As String, ByVal Style As String, ByVal Color As String)

Async Version
Public Sub SetFont(ByVal Name As String, ByVal Size As String, ByVal Style As String, ByVal Color As String) As Task
Public Sub SetFont(ByVal Name As String, ByVal Size As String, ByVal Style As String, ByVal Color As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to define the font attributes for text.

The Name parameter specifies the font name.

The Size parameter specifies the font size, either as an absolute value (e.g., 12) or relative adjustment (e.g., +2).

The Style parameter specifies the font style. The following syntax is supported:

[B][I][U][bold][italic][underline][##%][##%,##%][0.###][0.###]

For example:

  • bold
  • bold 50%
  • bold italic 50%
  • BI 50% 42%
  • B 50% italic 0.42
If only one transparency figure is provided, it applies to both pen and brush.

The Color parameter specifies the font color in hash-prefixed hexadecimal format (such as #FF0000 for red). The following HTML color aliases are also supported:

aliceblue antiquewhite aqua aquamarine
azure beige bisque black
blanchedalmond blue blueviolet brown
burlywood cadetblue chartreuse chocolate
coral cornflowerblue cornsilk crimson
cyan darkblue darkcyan darkgoldenrod
darkgray darkgrey darkgreen darkkhaki
darkmagenta darkolivegreen darkorange darkorchid
darkred darksalmon darkseagreen darkslateblue
darkslategray darkslategrey darkturquoise darkviolet
deeppink deepskyblue dimgray dimgrey
dodgerblue firebrick floralwhite forestgreen
fuchsia gainsboro ghostwhite gold
goldenrod gray grey green
greenyellow honeydew hotpink indianred
indigo ivory khaki lavender
lavenderblush lawngreen lemonchiffon lightblue
lightcoral lightcyan lightgoldenrodyellow lightgray
lightgrey lightgreen lightpink lightsalmon
lightseagreen lightskyblue lightslategray lightslategrey
lightsteelblue lightyellow lime limegreen
linen magenta maroon mediumaquamarine
mediumblue mediumorchid mediumpurple mediumseagreen
mediumslateblue mediumspringgreen mediumturquoise mediumvioletred
midnightblue mintcream mistyrose moccasin
navajowhite navy oldlace olive
olivedrab orange orangered orchid
palegoldenrod palegreen paleturquoise palevioletred
papayawhip peachpuff peru pink
plum powderblue purple rebeccapurple
red rosybrown royalblue saddlebrown
salmon sandybrown seagreen seashell
sienna silver skyblue slateblue
slategray slategrey snow springgreen
steelblue tan teal thistle
tomato turquoise violet wheat
white whitesmoke yellow yellowgreen

SetInputStream Method (PDFEdit Component)

Sets the stream containing the PDF document to process.

Syntax

public void SetInputStream(System.IO.Stream inputStream);

Async Version
public async Task SetInputStream(System.IO.Stream inputStream);
public async Task SetInputStream(System.IO.Stream inputStream, CancellationToken cancellationToken);
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream)

Async Version
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream) As Task
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

This method is used to set the stream from which the component will read the PDF document to be processed. If an input stream is set before the component attempts to perform operations on the document, the component will read the data from the input stream instead of from the InputFile or InputData properties.

NOTE: It may be useful to additionally set the CloseInputStreamAfterProcessing configuration setting to true when using input streams.

SetOutputStream Method (PDFEdit Component)

Sets the stream to write the processed document to.

Syntax

public void SetOutputStream(System.IO.Stream outputStream);

Async Version
public async Task SetOutputStream(System.IO.Stream outputStream);
public async Task SetOutputStream(System.IO.Stream outputStream, CancellationToken cancellationToken);
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream)

Async Version
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream) As Task
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

This method is used to set the stream to which the component will write the resulting PDF document. If an output stream is set before the component attempts to perform operations on the document, the component will write the data to the output stream instead of writing to OutputFile or populating OutputData.

NOTE: It may be useful to additionally set the CloseOutputStreamAfterProcessing configuration setting to true when using output streams.

SetPosition Method (PDFEdit Component)

Sets the page and position for new text blocks or images.

Syntax

public void SetPosition(int pageIndex, string X, string Y);

Async Version
public async Task SetPosition(int pageIndex, string X, string Y);
public async Task SetPosition(int pageIndex, string X, string Y, CancellationToken cancellationToken);
Public Sub SetPosition(ByVal PageIndex As Integer, ByVal X As String, ByVal Y As String)

Async Version
Public Sub SetPosition(ByVal PageIndex As Integer, ByVal X As String, ByVal Y As String) As Task
Public Sub SetPosition(ByVal PageIndex As Integer, ByVal X As String, ByVal Y As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to define the Position where new text blocks or images will be added. The page is identified by the PageIndex parameter (zero-based), the X parameter specifies the horizontal position, and the Y parameter specifies the vertical position.

X and Y values that are absolute, relative to the current position, and relative to the page dimensions are all supported.

Example: // Sets to exact coordinates. pdfedit.SetPosition(0, "100", "20"); // Moves 20 points to the right and 20 points down from the current position. pdfedit.SetPosition(0, "{x}+20", "{y}-20"); // Moves 20 points from the right edge and 120 points from the top edge of the page. pdfedit.SetPosition(0, "{width}-20", "{height}-120"); NOTE: PageIndex set to -1 specifies the last page of the document.

SetTransform Method (PDFEdit Component)

Sets the object transformation parameters for subsequent insertion operations.

Syntax

public void SetTransform(string translationX, string translationY, string scaleX, string scaleY, string rotation, string skewA, string skewB);

Async Version
public async Task SetTransform(string translationX, string translationY, string scaleX, string scaleY, string rotation, string skewA, string skewB);
public async Task SetTransform(string translationX, string translationY, string scaleX, string scaleY, string rotation, string skewA, string skewB, CancellationToken cancellationToken);
Public Sub SetTransform(ByVal TranslationX As String, ByVal TranslationY As String, ByVal ScaleX As String, ByVal ScaleY As String, ByVal Rotation As String, ByVal SkewA As String, ByVal SkewB As String)

Async Version
Public Sub SetTransform(ByVal TranslationX As String, ByVal TranslationY As String, ByVal ScaleX As String, ByVal ScaleY As String, ByVal Rotation As String, ByVal SkewA As String, ByVal SkewB As String) As Task
Public Sub SetTransform(ByVal TranslationX As String, ByVal TranslationY As String, ByVal ScaleX As String, ByVal ScaleY As String, ByVal Rotation As String, ByVal SkewA As String, ByVal SkewB As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to specify the transformation matrix to apply when AddTextBlock or AddBitmap is called. The transformation matrix defines how the coordinates and content of the newly added text block or image are mapped onto the page.

The TranslationX and TranslationY parameters specify the horizontal and vertical translation of the object in points.

The ScaleX and ScaleY parameters specify the horizontal and vertical scaling of the object (e.g., use 0.5 to scale an image to half its original size).

The Rotation parameter specifies the rotation angle of the object in degrees.

The SkewA and SkewB parameters specify the horizontal and vertical skew angles of the object in degrees (e.g., use 30 and 20 respectively to slant the object by 30 degrees horizontally and 20 degrees vertically).

DocumentInfo Event (PDFEdit Component)

Fired when the document has been loaded into memory.

Syntax

public event OnDocumentInfoHandler OnDocumentInfo;

public delegate void OnDocumentInfoHandler(object sender, PDFEditDocumentInfoEventArgs e);

public class PDFEditDocumentInfoEventArgs : EventArgs {
  public int PageCount { get; }
}
Public Event OnDocumentInfo As OnDocumentInfoHandler

Public Delegate Sub OnDocumentInfoHandler(sender As Object, e As PDFEditDocumentInfoEventArgs)

Public Class PDFEditDocumentInfoEventArgs Inherits EventArgs
  Public ReadOnly Property PageCount As Integer
End Class

Remarks

This event is fired once per document processing routine to report that the document has been processed and loaded into memory.

The handler for this event is a good place to check the document structure and access document-related information such as page number and document file details.

The PageCount parameter reports the number of pages in the document.

This event is fired when the Open method is called, but only after Password or RecipientInfo is fired (if applicable) and the document has been decrypted.

Error Event (PDFEdit Component)

Fired when information is available about errors during data delivery.

Syntax

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, PDFEditErrorEventArgs e);

public class PDFEditErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}
Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As PDFEditErrorEventArgs)

Public Class PDFEditErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Log Event (PDFEdit Component)

Fired once for each log message.

Syntax

public event OnLogHandler OnLog;

public delegate void OnLogHandler(object sender, PDFEditLogEventArgs e);

public class PDFEditLogEventArgs : EventArgs {
  public int LogLevel { get; }
  public string Message { get; }
  public string LogType { get; }
}
Public Event OnLog As OnLogHandler

Public Delegate Sub OnLogHandler(sender As Object, e As PDFEditLogEventArgs)

Public Class PDFEditLogEventArgs Inherits EventArgs
  Public ReadOnly Property LogLevel As Integer
  Public ReadOnly Property Message As String
  Public ReadOnly Property LogType As String
End Class

Remarks

This event is fired once for each log message generated by the component. The verbosity is controlled by the LogLevel configuration setting.

The LogLevel parameter indicates the detail level of the message. Possible values are:

0 (None) No messages are logged.
1 (Info - default) Informational events such as the basics of the chain validation procedure are logged.
2 (Verbose) Detailed data such as HTTP requests are logged.
3 (Debug) Debug data including the full chain validation procedure are logged.

The Message parameter is the log message.

The LogType parameter identifies the type of log entry. Possible values are:

  • CertValidator
  • Font
  • HTTP
  • PDFInvalidSignature
  • PDFRevocationInfo
  • Timestamp
  • TSL

Password Event (PDFEdit Component)

Fired when the component detects that the document is encrypted with a password.

Syntax

public event OnPasswordHandler OnPassword;

public delegate void OnPasswordHandler(object sender, PDFEditPasswordEventArgs e);

public class PDFEditPasswordEventArgs : EventArgs {
  public bool Available { get; }
  public bool Cancel { get; set; }
}
Public Event OnPassword As OnPasswordHandler

Public Delegate Sub OnPasswordHandler(sender As Object, e As PDFEditPasswordEventArgs)

Public Class PDFEditPasswordEventArgs Inherits EventArgs
  Public ReadOnly Property Available As Boolean
  Public Property Cancel As Boolean
End Class

Remarks

This event is fired during document processing to report that the document is encrypted with a password. It may be used to supply the correct decryption password to the Password property.

The Available parameter indicates whether the decryption password is already available to the component or still needs to be set. If this parameter is set to false, the correct password must be provided for the decryption attempt to succeed.

The Cancel parameter determines whether the component will stop firing this event to request a password.

RecipientInfo Event (PDFEdit Component)

Fired for each recipient certificate of the encrypted document.

Syntax

public event OnRecipientInfoHandler OnRecipientInfo;

public delegate void OnRecipientInfoHandler(object sender, PDFEditRecipientInfoEventArgs e);

public class PDFEditRecipientInfoEventArgs : EventArgs {
  public string Issuer { get; }
  public string SerialNumber { get; }
  public string SubjectKeyIdentifier { get; }
  public bool Available { get; }
  public bool Cancel { get; set; }
}
Public Event OnRecipientInfo As OnRecipientInfoHandler

Public Delegate Sub OnRecipientInfoHandler(sender As Object, e As PDFEditRecipientInfoEventArgs)

Public Class PDFEditRecipientInfoEventArgs Inherits EventArgs
  Public ReadOnly Property Issuer As String
  Public ReadOnly Property SerialNumber As String
  Public ReadOnly Property SubjectKeyIdentifier As String
  Public ReadOnly Property Available As Boolean
  Public Property Cancel As Boolean
End Class

Remarks

This event is fired during document processing for each recipient certificate that the document has been encrypted for (if applicable). It may be used to identify the certificate(s) to load and supply to the DecryptionCert property.

The Issuer parameter specifies the subject of the issuer certificate.

The SerialNumber parameter specifies the serial number of the encryption certificate.

The SubjectKeyIdentifier parameter specifies the X.509 subjectKeyIdentifier extension value of the encryption certificate, encoded as a hex string.

The Available parameter indicates whether the decryption certificate is already available to the component or still needs to be set. If this parameter is set to false, the correct certificate must be provided for the decryption attempt to succeed.

The Cancel parameter determines whether the component will stop firing this event to request a certificate.

NOTE: The document may be encrypted with more than one certificate (or have "more than one recipient"), in which case each certificate will cause its own invocation of this event.

ReplaceText Event (PDFEdit Component)

Fired when a substring in the document is due to be replaced.

Syntax

public event OnReplaceTextHandler OnReplaceText;

public delegate void OnReplaceTextHandler(object sender, PDFEditReplaceTextEventArgs e);

public class PDFEditReplaceTextEventArgs : EventArgs {
  public int PageIndex { get; }
  public int EntryIndex { get; }
  public int Offset { get; }
  public string Pattern { get; }
  public string Substitute { get; set; }
  public bool Skip { get; set; }
}
Public Event OnReplaceText As OnReplaceTextHandler

Public Delegate Sub OnReplaceTextHandler(sender As Object, e As PDFEditReplaceTextEventArgs)

Public Class PDFEditReplaceTextEventArgs Inherits EventArgs
  Public ReadOnly Property PageIndex As Integer
  Public ReadOnly Property EntryIndex As Integer
  Public ReadOnly Property Offset As Integer
  Public ReadOnly Property Pattern As String
  Public Property Substitute As String
  Public Property Skip As Boolean
End Class

Remarks

This event is fired from within the ReplaceDocumentText and ReplacePageText methods, repeatedly, for each located Pattern string. It may be used to track and, if required, alter individual text substitutions.

The PageIndex parameter contains the page number where the entry is located.

The EntryIndex parameter contains the index number of the entry related to the other entries.

The Offset parameter specifies the offset of the substring from the beginning of the page or document.

The Substitute parameter contains the value that Pattern is going to be replaced with. This value matches the Value parameter passed to the respective ReplaceDocumentText or ReplacePageText call. Adjust it from the event handler if required.

The Skip parameter determines whether the component will skip substituting this entry and proceed to the next one.

Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

The following fields are available:

Fields

EffectiveDate
string (read-only)

Default: ""

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

ExpirationDate
string (read-only)

Default: ""

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

ExtendedKeyUsage
string (read-only)

Default: ""

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

Fingerprint
string (read-only)

Default: ""

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

FingerprintSHA1
string (read-only)

Default: ""

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

FingerprintSHA256
string (read-only)

Default: ""

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

Issuer
string (read-only)

Default: ""

The issuer of the certificate. This field contains a string representation of the name of the issuing authority for the certificate.

PrivateKey
string (read-only)

Default: ""

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The PrivateKey may be available but not exportable. In this case, PrivateKey returns an empty string.

PrivateKeyAvailable
bool (read-only)

Default: False

Whether a PrivateKey is available for the selected certificate. If PrivateKeyAvailable is True, the certificate may be used for authentication purposes (e.g., server authentication).

PrivateKeyContainer
string (read-only)

Default: ""

The name of the PrivateKey container for the certificate (if available). This functionality is available only on Windows platforms.

PublicKey
string (read-only)

Default: ""

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

PublicKeyAlgorithm
string (read-only)

Default: ""

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

PublicKeyLength
int (read-only)

Default: 0

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

SerialNumber
string (read-only)

Default: ""

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

SignatureAlgorithm
string (read-only)

Default: ""

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

Store
string

Default: "MY"

The name of the certificate store for the client certificate.

The StoreType field denotes the type of the certificate store specified by Store. If the store is password-protected, specify the password in StorePassword.

Store is used in conjunction with the Subject field to specify client certificates. If Store has a value, and Subject or Encoded is set, a search for a certificate is initiated. Please see the Subject field for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

MYA certificate store holding personal certificates with their associated private keys.
CACertifying authority certificates.
ROOTRoot certificates.

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

StoreB
byte []

Default: "MY"

The name of the certificate store for the client certificate.

The StoreType field denotes the type of the certificate store specified by Store. If the store is password-protected, specify the password in StorePassword.

Store is used in conjunction with the Subject field to specify client certificates. If Store has a value, and Subject or Encoded is set, a search for a certificate is initiated. Please see the Subject field for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

MYA certificate store holding personal certificates with their associated private keys.
CACertifying authority certificates.
ROOTRoot certificates.

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

StorePassword
string

Default: ""

If the type of certificate store requires a password, this field is used to specify the password needed to open the certificate store.

StoreType
CertStoreTypes

Default: 0

The type of certificate store for this certificate.

The component supports both public and private keys in a variety of formats. When the cstAuto value is used, the component will automatically determine the type. This field can take one of the following values:

0 (cstUser - default)For Windows, this specifies that the certificate store is a certificate store owned by the current user.

NOTE: This store type is not available in Java.

1 (cstMachine)For Windows, this specifies that the certificate store is a machine store.

NOTE: This store type is not available in Java.

2 (cstPFXFile)The certificate store is the name of a PFX (PKCS#12) file containing certificates.
3 (cstPFXBlob)The certificate store is a string (binary or Base64-encoded) representing a certificate store in PFX (PKCS#12) format.
4 (cstJKSFile)The certificate store is the name of a Java Key Store (JKS) file containing certificates.

NOTE: This store type is only available in Java.

5 (cstJKSBlob)The certificate store is a string (binary or Base64-encoded) representing a certificate store in Java Key Store (JKS) format.

NOTE: This store type is only available in Java.

6 (cstPEMKeyFile)The certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate.
7 (cstPEMKeyBlob)The certificate store is a string (binary or Base64-encoded) that contains a private key and an optional certificate.
8 (cstPublicKeyFile)The certificate store is the name of a file that contains a PEM- or DER-encoded public key certificate.
9 (cstPublicKeyBlob)The certificate store is a string (binary or Base64-encoded) that contains a PEM- or DER-encoded public key certificate.
10 (cstSSHPublicKeyBlob)The certificate store is a string (binary or Base64-encoded) that contains an SSH-style public key.
11 (cstP7BFile)The certificate store is the name of a PKCS#7 file containing certificates.
12 (cstP7BBlob)The certificate store is a string (binary) representing a certificate store in PKCS#7 format.
13 (cstSSHPublicKeyFile)The certificate store is the name of a file that contains an SSH-style public key.
14 (cstPPKFile)The certificate store is the name of a file that contains a PPK (PuTTY Private Key).
15 (cstPPKBlob)The certificate store is a string (binary) that contains a PPK (PuTTY Private Key).
16 (cstXMLFile)The certificate store is the name of a file that contains a certificate in XML format.
17 (cstXMLBlob)The certificate store is a string that contains a certificate in XML format.
18 (cstJWKFile)The certificate store is the name of a file that contains a JWK (JSON Web Key).
19 (cstJWKBlob)The certificate store is a string that contains a JWK (JSON Web Key).
21 (cstBCFKSFile)The certificate store is the name of a file that contains a BCFKS (Bouncy Castle FIPS Key Store).

NOTE: This store type is only available in Java and .NET.

22 (cstBCFKSBlob)The certificate store is a string (binary or Base64-encoded) representing a certificate store in BCFKS (Bouncy Castle FIPS Key Store) format.

NOTE: This store type is only available in Java and .NET.

23 (cstPKCS11)The certificate is present on a physical security key accessible via a PKCS#11 interface.

To use a security key, the necessary data must first be collected using the CertMgr component. The ListStoreCertificates method may be called after setting CertStoreType to cstPKCS11, CertStorePassword to the PIN, and CertStore to the full path of the PKCS#11 DLL. The certificate information returned in the CertList event's CertEncoded parameter may be saved for later use.

When using a certificate, pass the previously saved security key information as the Store and set StorePassword to the PIN.

Code Example. SSH Authentication with Security Key: certmgr.CertStoreType = CertStoreTypes.cstPKCS11; certmgr.OnCertList += (s, e) => { secKeyBlob = e.CertEncoded; }; certmgr.CertStore = @"C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll"; certmgr.CertStorePassword = "123456"; //PIN certmgr.ListStoreCertificates(); sftp.SSHCert = new Certificate(CertStoreTypes.cstPKCS11, secKeyBlob, "123456", "*"); sftp.SSHUser = "test"; sftp.SSHLogon("myhost", 22);

99 (cstAuto)The store type is automatically detected from the input data. This setting may be used with both public and private keys and can detect any of the supported formats automatically.

SubjectAltNames
string (read-only)

Default: ""

Comma-separated lists of alternative subject names for the certificate.

ThumbprintMD5
string (read-only)

Default: ""

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

ThumbprintSHA1
string (read-only)

Default: ""

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

ThumbprintSHA256
string (read-only)

Default: ""

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

Usage
string (read-only)

Default: ""

The text description of UsageFlags.

This value will be one or more of the following strings and will be separated by commas:

  • Digital Signature
  • Non-Repudiation
  • Key Encipherment
  • Data Encipherment
  • Key Agreement
  • Certificate Signing
  • CRL Signing
  • Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

UsageFlags
int (read-only)

Default: 0

The flags that show intended use for the certificate. The value of UsageFlags is a combination of the following flags:

0x80Digital Signature
0x40Non-Repudiation
0x20Key Encipherment
0x10Data Encipherment
0x08Key Agreement
0x04Certificate Signing
0x02CRL Signing
0x01Encipher Only

Please see the Usage field for a text representation of UsageFlags.

This functionality currently is not available when the provider is OpenSSL.

Version
string (read-only)

Default: ""

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

Subject
string

Default: ""

The subject of the certificate used for client authentication.

This field will be populated with the full subject of the loaded certificate. When loading a certificate, the subject is used to locate the certificate in the store.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

FieldMeaning
CNCommon Name. This is commonly a hostname like www.server.com.
OOrganization
OUOrganizational Unit
LLocality
SState
CCountry
EEmail Address

If a field value contains a comma, it must be quoted.

Encoded
string

Default: ""

The certificate (PEM/Base64 encoded). This field is used to assign a specific certificate. The Store and Subject fields also may be used to specify a certificate.

When Encoded is set, a search is initiated in the current Store for the private key of the certificate. If the key is found, Subject is updated to reflect the full subject of the selected certificate; otherwise, Subject is set to an empty string.

EncodedB
byte []

Default: ""

The certificate (PEM/Base64 encoded). This field is used to assign a specific certificate. The Store and Subject fields also may be used to specify a certificate.

When Encoded is set, a search is initiated in the current Store for the private key of the certificate. If the key is found, Subject is updated to reflect the full subject of the selected certificate; otherwise, Subject is set to an empty string.

Constructors

public Certificate();
Public Certificate()

Creates a instance whose properties can be set.

public Certificate(string certificateFile);
Public Certificate(ByVal CertificateFile As String)

Opens CertificateFile and reads out the contents as an X.509 public key.

public Certificate(byte[] encoded);
Public Certificate(ByVal Encoded As Byte())

Parses Encoded as an X.509 public key.

public Certificate(CertStoreTypes storeType, string store, string storePassword, string subject);
Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String)

StoreType identifies the type of certificate store to use. See for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store.

After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN). The Subject parameter can also take an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load in a "Thumbprint=value" format.

public Certificate(CertStoreTypes storeType, string store, string storePassword, string subject, string configurationString);
Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

StoreType identifies the type of certificate store to use. See for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store.

ConfigurationString is a newline-separated list of name-value pairs that may be used to modify the default behavior. Possible values include "PersistPFXKey", which shows whether or not the PFX key is persisted after performing operations with the private key. This correlates to the PKCS12_NO_PERSIST_KEY CryptoAPI option. The default value is True (the key is persisted). "Thumbprint" - an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load. When specified, this value is used to select the certificate in the store. This is applicable to the cstUser , cstMachine , cstPublicKeyFile , and cstPFXFile store types. "UseInternalSecurityAPI" shows whether the platform (default) or the internal security API is used when performing certificate-related operations.

After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN). The Subject parameter can also take an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load in a "Thumbprint=value" format.

public Certificate(CertStoreTypes storeType, string store, string storePassword, byte[] encoded);
Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Encoded As Byte())

StoreType identifies the type of certificate store to use. See for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store.

After the store has been successfully opened, the component will load Encoded as an X.509 certificate and search the opened store for a corresponding private key.

public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, string subject);
Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As Byte(), ByVal StorePassword As String, ByVal Subject As String)

StoreType identifies the type of certificate store to use. See for descriptions of the different certificate stores. Store is a byte array containing the certificate data. StorePassword is the password used to protect the store.

After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN). The Subject parameter can also take an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load in a "Thumbprint=value" format.

public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, string subject, string configurationString);
Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As Byte(), ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

StoreType identifies the type of certificate store to use. See for descriptions of the different certificate stores. Store is a byte array containing the certificate data. StorePassword is the password used to protect the store.

After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN). The Subject parameter can also take an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load in a "Thumbprint=value" format.

public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, byte[] encoded);
Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As Byte(), ByVal StorePassword As String, ByVal Encoded As Byte())

StoreType identifies the type of certificate store to use. See for descriptions of the different certificate stores. Store is a byte array containing the certificate data. StorePassword is the password used to protect the store.

After the store has been successfully opened, the component will load Encoded as an X.509 certificate and search the opened store for a corresponding private key.

PDFAttachment Type

The file being attached to the PDF document.

Remarks

This type contains information about the file that is being attached to the document.

The following fields are available:

Fields

ContentType
string

Default: ""

The content type of the attachment.

CreationDate
string

Default: ""

The creation date of the attachment.

Data
string

Default: ""

The raw data of the attachment.

If OutputStream is not set to a valid stream, the component will write to this field when an empty string is passed to the SaveAttachment method.

DataB
byte []

Default: ""

The raw data of the attachment.

If OutputStream is not set to a valid stream, the component will write to this field when an empty string is passed to the SaveAttachment method.

Description
string

Default: ""

A textual description of the attachment.

FileName
string

Default: ""

The path and filename of the attachment.

InputStream
System.IO.Stream

Default: ""

A stream containing the attachment.

If this field is set to a valid stream, the component will attach the data from the stream as the current attachment.

ModificationDate
string

Default: ""

The date and time of the file's last modification.

Name
string

Default: ""

The name of the attachment.

OutputStream
System.IO.Stream

Default: ""

The stream to write the attachment to.

If this field is set to a valid stream, the component will write to this field when an empty string is passed to the SaveAttachment method.

Size
long (read-only)

Default: 0

The attachment's size in bytes.

Constructors

public PDFAttachment();
Public PDFAttachment()
public PDFAttachment(string fileName);
Public PDFAttachment(ByVal FileName As String)
public PDFAttachment(string fileName, string description);
Public PDFAttachment(ByVal FileName As String, ByVal Description As String)
public PDFAttachment(byte[] data, string name, string description);
Public PDFAttachment(ByVal Data As Byte(), ByVal Name As String, ByVal Description As String)
public PDFAttachment(System.IO.Stream inputStream, string name, string description);
Public PDFAttachment(ByVal InputStream As System.IO.Stream, ByVal Name As String, ByVal Description As String)

PDFFont Type

The font used in the PDF document.

Remarks

This type contains details about the font being applied to text.

The following fields are available:

Fields

Color
string (read-only)

Default: "#000000"

The color of the current font in hexadecimal format.

Name
string (read-only)

Default: "Arial"

The name of the current font.

Size
string (read-only)

Default: "12"

The size of the current font in points.

Style
string (read-only)

Default: ""

The style of the current font.

Constructors

public PDFFont();
Public PDFFont()

PDFMedia Type

The media object that is included as part of the PDF document.

Remarks

This type contains information about the media object (such as an image) that is included in the document.

The following fields are available:

Fields

ContentType
string (read-only)

Default: ""

The content type of the media object.

Data
string

Default: ""

The raw data of the media object.

If OutputStream is not set to a valid stream, the component will write to this field when an empty string is passed to the SaveMedia method.

DataB
byte []

Default: ""

The raw data of the media object.

If OutputStream is not set to a valid stream, the component will write to this field when an empty string is passed to the SaveMedia method.

Height
int (read-only)

Default: 0

The height of the media object in pixels (i.e., its vertical resolution).

InputStream
System.IO.Stream

Default: ""

A stream containing the media object.

If this field is set to a valid stream, the component will attach the data from the stream as the current image.

OutputStream
System.IO.Stream

Default: ""

The stream to write the image data to.

If this field is set to a valid stream, the component will write to this field when an empty string is passed to the SaveMedia method.

Size
long (read-only)

Default: 0

The size of the media in bytes.

Width
int (read-only)

Default: 0

The width of the media object in pixels (i.e., its horizontal resolution).

Constructors

public PDFMedia();
Public PDFMedia()
public PDFMedia(byte[] data);
Public PDFMedia(ByVal Data As Byte())
public PDFMedia(System.IO.Stream inputStream);
Public PDFMedia(ByVal InputStream As System.IO.Stream)

PDFPage Type

A container for PDF page details.

Remarks

This type contains general information about a document page, such as its dimensions and rotation.

The following fields are available:

Fields

Height
string (read-only)

Default: "0"

The height of the page in points. Both integer and decimal values are supported.

Rotate
int (read-only)

Default: 0

The rotation angle of the page in degrees.

Width
string (read-only)

Default: "0"

The width of the page in points. Both integer and decimal values are supported.

Constructors

public PDFPage();
Public PDFPage()

PDFPagePosition Type

The position within a PDF document.

Remarks

This type contains information about the current position on a page.

The following fields are available:

Fields

PageIndex
int (read-only)

Default: 0

The index of the current page in the PDF document.

X
string (read-only)

Default: "0"

The X coordinate of the current position on the page.

Y
string (read-only)

Default: "0"

The Y coordinate of the current position on the page.

Constructors

public PDFPagePosition();
Public PDFPagePosition()

Config Settings (PDFEdit Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

PDFEdit Config Settings

AFRelationship[Key]:   The value of the AFRelationship key for the attachment.

This setting specifies the value of the AFRelationship key for the attachment. This key in the file specification dictionary expresses the relationship between the attachment and the document, and it must be set for each attachment added to PDF/A-3 documents. Key is either the index of the attachment in the Attachments collection or the Name of the attachment.

AutoTurnPages:   Whether to change the page automatically upon exceeding the upper or lower page boundary.

This setting specifies whether the component will turn the page automatically. If set to true, the component will automatically progress to the next or previous page upon reaching a page boundary while adding new elements or changing the page position. If set to false, any new elements will be added to the current page, even if they are outside of the visible page region. The default value is true.

CloseInputStreamAfterProcessing:   Whether to close the input stream after processing.

This setting determines whether the input stream specified in SetInputStream will be closed after processing is complete. The default value is true.

CloseOutputStreamAfterProcessing:   Whether to close the output stream after processing.

This setting determines whether the output stream specified in SetOutputStream will be closed after processing is complete. The default value is true.

CompressStreams:   Whether to compress stream objects.

This setting specifies whether the bytes in the document's stream objects will be compressed when the document is saved. The default value is true.

DefaultPageHeight:   The default height for newly added pages.

This setting specifies the default height, in points, of pages added using the CreateNew or AddNewPage methods. The default value is 0, meaning the component will reuse the height of the previous page when adding a new page. If the new page will be the first in the document, the height will default to the standard 792.

DefaultPageWidth:   The default width for newly added pages.

This setting specifies the default width, in points, of pages added using the CreateNew or AddNewPage methods. The default value is 0, meaning the component will reuse the width of the previous page when adding a new page. If the new page will be the first in the document, the width will default to the standard 612.

EnforcePDFA:   Whether to enforce PDF/A compliance.

This setting specifies whether the component will enforce PDF/A compliance when operating on the document. If set to true, PDFALevel and PDFAPolicy will be used to establish the level of PDF/A compliance to apply. The default value is true.

FallbackFont:   The fallback font.

This setting specifies the font that the component will use if it cannot find the intended font on the local system. In PDF/A, fonts must be embedded into the document, so this setting can be useful when text must be added but no font is available. The default value is Arial.

FontPaths:   The font search paths.

This setting specifies a CRLF-separated list of paths where the component will search for additional TrueType font files. The default value is the system font search paths.

KeepPositionOnInsert:   Whether to keep the current position after inserting an element.

This setting specifies whether the component will keep the current position at the set value after inserting an element. In the default configuration, insertion of a new element, such as a text block, moves the page position marker to the right of the newly inserted element. If set to true, the component will keep the position marker at its original location after adding the element. The default value is false.

LoadMedia:   Whether to load images from the document.

This setting specifies whether the component will load images from the document. If media does not need to be accessed, it can be set to false to speed up document processing. The default value is true.

LogLevel:   The level of detail that is logged.

This setting controls the level of detail that is logged through the Log event. Possible values are:

0 (None) No messages are logged.
1 (Info - default) Informational events such as the basics of the chain validation procedure are logged.
2 (Verbose) Detailed data such as HTTP requests are logged.
3 (Debug) Debug data including the full chain validation procedure are logged.
OwnerPassword:   The owner password to decrypt the document with.

This setting is used to provide the document owner password for decryption. Though it may be different from Password, most implementations use the same value for both.

PageCopyByRefElements:   The names of page elements to be copied by reference.

This setting specifies a semicolon-separated list of names of page elements that will be copied by reference (shallow copy) instead of by value when AppendPage or InsertPage is called. If set to an empty string, the component will copy all page elements by value, which may lead to inefficient duplication of inherently shared objects such as fonts or bitmaps. The default value is Resources.

PDFALevel:   The PDF/A conformance level to enforce.

This setting specifies the desired PDF/A conformance level that the component will attempt to enforce when EnforcePDFA is set to true. Possible values are:

1 PDF/A-1.
2 PDF/A-2.
3 (default) PDF/A-3.
PDFAPolicy:   The PDF/A policy to follow.

This setting specifies the PDF/A policy the component will follow when EnforcePDFA is set to true. Possible values are:

Default Maps to Preserve.
Preserve Keep existing document features and only write PDF/A-compliant pieces. If the component needs to write a non-compliant piece, it will throw an exception.
Enforce Preserve PDF/A-compliant pieces and attempt to fix violations in the original document.
RightPadding:   The width of the whitespace gap to the right of newly added elements.

This setting specifies the width, in points, of the empty space that is allowed to the right of newly added elements. Using a non-zero value for this setting allows multiple text blocks and other elements to be placed next to each other without sticking them together. This setting is ignored if KeepPositionOnInsert is set to true. The default value is 5.

SaveChanges:   Whether to save changes made to the document.

This setting specifies whether and how changes made to the PDF document will be saved when the Close method is called. Possible values are:

0 Discard all changes.
1 Save the document to OutputFile, OutputData, or the stream set in SetOutputStream, even if it has not been modified.
2 (default) Save the document to OutputFile, OutputData, or the stream set in SetOutputStream, but only if it has been modified.
SystemFontNames:   The system font names.

This setting returns a CRLF-separated list of system TrueType font names that are supported by the component. This setting is read-only.

TempPath:   The location where temporary files are stored.

This setting specifies an absolute path to the location on disk where temporary files are stored. It can be useful to reduce memory usage.

Base Config Settings

BuildInfo:   Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

GUIAvailable:   Whether or not a message loop is available for processing events.

In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The component will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation.

In some non-GUI applications, an invalid message loop may be discovered that will result in errant behavior. In these cases, setting GUIAvailable to false will ensure that the component does not attempt to process external events.

LicenseInfo:   Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a component is using. It will return the following information:

  • Product: The product the license is for.
  • Product Key: The key the license was generated from.
  • License Source: Where the license was found (e.g., RuntimeLicense, License File).
  • License Type: The type of license installed (e.g., Royalty Free, Single Server).
  • Last Valid Build: The last valid build number for which the license will work.
MaskSensitiveData:   Whether sensitive data is masked in log messages.

In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to true to mask sensitive data. The default is true.

UseInternalSecurityAPI:   Whether or not to use the system security libraries or an internal implementation.

When set to false, the component will use the system security libraries by default to perform cryptographic functions where applicable. In this case, calls to unmanaged code will be made. In certain environments, this is not desirable. To use a completely managed security implementation, set this setting to true.

Setting this configuration setting to true tells the component to use the internal implementation instead of using the system security libraries.

On Windows, this setting is set to false by default. On Linux/macOS, this setting is set to true by default.

NOTE: This setting is static. The value set is applicable to all components used in the application.

When this value is set, the product's system dynamic link library (DLL) is no longer required as a reference, as all unmanaged code is stored in that file.

Trappable Errors (PDFEdit Component)

PDFEdit Errors

1203   Page index is out of bounds.
1209   Invalid PDF structure.
1210   Cannot remove last page.

PDF Errors

804   PDF decompression failed.
805   Cannot add entry to cross-reference table.
806   Unsupported field size.
807   Unsupported Encoding filter.
808   Unsupported predictor algorithm.
809   Unsupported document version.
812   Cannot read PDF file stream.
813   Cannot write to PDF file stream.
814   OutputFile already exists and Overwrite is false.
815   Invalid parameter.
817   Bad cross-reference entry.
818   Invalid object or generation number.
819   Invalid object stream.
820   Invalid stream dictionary.
821   Invalid AcroForm entry.
822   Invalid Root entry.
823   Invalid annotation.
824   The input document is empty.
826   OpenType font error. The error description contains the detailed message.
828   Invalid CMS data. The error description contains the detailed message.
835   Cannot change decryption mode for opened document.
836   Unsupported Date string.
838   Cryptographic error. The error description contains the detailed message.
840   DecryptionCert error. The error description contains the detailed message.
841   Encryption failed. The error description contains the detailed message.
842   No proper certificate for encryption found.
846   Unsupported revision.
847   Unsupported security handler SubFilter.
848   Failed to verify permissions.
849   Invalid password.
850   Invalid password information.
852   Unsupported encryption algorithm.
859   Cannot encrypt encrypted document.
864   Cannot modify document after signature update.
868   Cannot encrypt or decrypt object.
869   Invalid security handler information.
870   Invalid encrypted data.
871   Invalid block cipher padding.
872   Failed to reload signature.
873   Object is not encrypted.
874   Unexpected cipher information.
877   Invalid document. Bad document catalog.
878   Invalid document Id.
880   Invalid document. Invalid requirements dictionary.
881   Invalid linearization dictionary.
882   Invalid signature information.
883   Unsupported document format.
890   Unsupported feature.
891   Internal error. The error description contains the detailed message.
892   Unsupported color.
893   This operation is not supported for this PDF/A level.
894   Interactive features (Action) are not supported by PDF/A. Set EnforcePDFA to false or clear the Action property of the field.
895   Font file not found.

Parsing Errors

1001   Bad object.
1002   Bad document trailer.
1003   Illegal stream dictionary.
1004   Illegal string.
1005   Indirect object expected.
1007   Invalid reference.
1008   Invalid reference table.
1009   Invalid stream data.
1010   Unexpected character.
1011   Unexpected EOF.
1012   Unexpected indirect object in cross-reference table.
1013   RDF object not found.
1014   Invalid RDF object.
1015   Cannot create element with unknown prefix.
1021   Invalid type in Root object list.