Description

Static method.

Converts and combines the list of files using the requested conversion settings.The files are combined in the order in which they are given.

The conversion settings passed in  determine how the files are combined. For instance, passing conversion settings to create a multipaged PDF file will combine all input files into a single, multipage PDF file, while passing in the conversion settings to create serialized TIFF images will result in a serialized sequence of TIFF images, one for each page of each file.

Syntax

PNConverter.CombineFiles(FileList, OutputFolder, OutputName,

                         OverwriteExisting, CreateResultsLogFiles,

                         SettingsProfile, ExtensionsProfile, MIMEProfile, UserSettings,

                         RemoteComputerName, ConversionWorkingFolder,

                         ConvertFileProcessLoggingPath)

 

PNConverter.CombineFiles(FileList, OutputFolder, OutputName,

                         OverwriteExisting, CreateResultsLogFiles,

                         SettingsList, ExtensionsProfile, MIMEProfile, UserSettings,

                         RemoteComputerName, ConversionWorkingFolder,

                         ConvertFileProcessLoggingPath)

 

PNConverter.CombineFiles(FileInfoList, OutputFolder, OutputName,

                         OverwriteExisting, CreateResultsLogFiles,

                         SettingsProfile, ExtensionsProfile, MIMEProfile, UserSettings,

                         RemoteComputerName, ConversionWorkingFolder,

                         ConvertFileProcessLoggingPath)

 

PNConverter.CombineFiles(FileInfoList, OutputFolder, OutputName,

                         OverwriteExisting, CreateResultsLogFiles,

                         SettingsList, ExtensionsProfile, MIMEProfile, UserSettings,

                         RemoteComputerName, ConversionWorkingFolder,

                         ConvertFileProcessLoggingPath)

 

Returns a PNCombineItem object which contains a collection of PNConversionResult objects, one for each file in the supplied list of files added to the combined file. The PNCombineItem object contains a list of files used in the combine process, and a list of the resulting combined files as well as other information about the original combine request. Each inner PNConversionResult object contains information about the conversion results for a file in the combine set passed.

Parameters

IList<PNConvertFileInfo> FileInfoList

A list of PNConvertFileInfo objects, in the desired order, to convert and add to the output file. Each PNConvertFileInfo object describes a single input file to be converted and an optional collection of converter settings to use when converting the file. The PNConvertFileInfo OutputPath property is ignored, and the OutputFolder argument used instead.

Only the following converter settings are valid when combining files:

•General Converter Options

•Endorsement Options

•Word Converter Options

•Excel Converter Options

•PowerPoint Converter Options

•Adobe Reader Options

•Internet Explorer Options

•Ghostscript Converter Options

•Image Converter Options

•OutsideIn AX Options

 

 

IList<String> FileList

A list of strings, in the desired order, representing the full paths of each file to convert and add to the output file. The files can be on the local computer, on a shared location using a mapped drive letter or by passing a UNC formatted file path.

String OutputFolder

Full path to the save file location. This folder must be specified and it must be created before the call to CombineFiles is made. If the path doesn't exist or a file of the same name already exists in the output folder location, the conversion will fail. Pass True for OverwriteExisting to allow file overwriting.

String OutputName

The name to use for the output file, without extension. The default file extension for the type of multipaged file being created will always be added to the name provided here. This argument must be provided.

String OverwriteExisting

Set to True to overwrite existing files, or False to fail conversion when a file of the same name already exists in the save location.

String CreateResultsLogFile

Pass True to create a results log file containing a complete snapshot of the conversion information for each file. This file is saved with each output file. The name of the results log file is based on the name of the original file and also indicates the conversion status for that file. For example, when converting Sample.doc, a successful conversion will create Sample.doc.succeeded.dcsresults and if the conversion did not succeed, the file would be named Sample.doc.failed.dcsresults.

These log files can later be read from disk using the DeserializeFromXML method of the PNConversionItem class.

String SettingsProfile

The name of the profile to use, with or without the XML extension. Settings in the profile that do not apply to the type of output being created are ignored. Document Conversion Service includes several sample profiles for common types of output files for your use, or you can create your own and pass in a full path to your custom profile. See Creating and Customizing Profiles for a list of included profiles and how to create your own.

IDictionary<String, String> SettingsList

A dictionary of name\value pairs of settings that describes the conversion options. Used instead of SettingsProfile above. The name\value pairs that make up this dictionary are the same settings that are used to create the XML-formatted profiles included with Document Conversion Service. See Conversion Settings for a list of all of the settings that are available.

String ExtensionsProfile

Name of the file mapping profile XML file, with or without the XML extension. Providing this parameter is optional and an internal default mapping is provided. You would only need to provide this file if you wanted to override the default file extension to converter mappings provided.

String MimeProfile

Reserved for future use - pass String.Empty.

IDictionary<String, String> UserSettings

Optional. Pass a dictionary of additional conversion settings. These settings will override any matching settings passed in for SettingsProfile or SettingsList. Pass null if not using.

String RemoteComputerName

Optional. Pass String.Empty if you are converting locally or the name of the remote computer where Document Conversion Service is running. When converting remotely, a ConversionWorkingFolder must also be provided.

String ConversionWorkingFolder

Used to provide a shared path to be used when doing remote conversion or an alternate temporary working instead of our default of the Windows TEMP folder.

This setting is required when RemoteComputerName is provided for remote conversion (DCOM) as both the local and the remote computer need access to a shared path in which to do the conversion. Pass String.Empty if you are not using this setting.

When not doing remote conversion, this setting is not required in most cases but can be useful when dealing with folder and file names longer than 255 characters. When converting a file, the conversion tool copies the file and performs the conversion in temporary staging and working folders created on demand in the default Windows temp folder. These folders need to be less than 255 characters as required by the underlying programs used by Document Conversion Service to perform conversions. When dealing with these long path and file names the default folders created can occasionally cause path names that are too long for Document Conversion Service to process. When this happens this switch can be used to set the temporary folder to a shorter path to allow processing. Again, pass String.Empty if you are not using this setting.

String ConvertFileProcessLoggingPath

Optional. Specify a path to a folder in which to store the SmartInspect logs files of any failed conversions. These files are stored in the temp folder by default and can be viewed using the SmartInspect Redistributable Console. These log files are a tracing of the entire conversion process and are not the same as the conversion results log files created when a conversion fails. See Controlling the SmartInspect Logging Files to change where these files are stored, how they are named, or to disable creation of these files.

Remarks

In the case of a failed combine, the combine results log file is always created. When the combine does not succeed, a .failed folder is created in the save folder location specified by OutputFolder argument and the results log files are stored there.

The name of the results log when the combine does not succeed will be similar to the following:

PNCombineFiles_2013_05_31_2_50_05_PM_3.failed.dcsresults

The bold text in the name will change for each file and is based on the date and time of the run and an internal counter. See Controlling the Failed Results File Location to store these files in a different location, disable the use of the date and time in the name, or to disable the creation of these file.

Exceptions

Exception

Condition

ArgumentException

An empty, or badly formatted profile was passed for SettingsProfile.

An empty list was passed for SettingsList.

An empty, or badly formatted profile was passed for ExtensionsProfile.

An empty list was passed for FileList.

An empty name was passed for OutputName.

A name for RemoteComputerName was passed but no corresponding ConversionWorkingFolder specified.

FileNotFoundException

One of the input files in the FileList does not exist or cannot be accessed.

DirectoryNotFoundException

The output path for OutputFolder is specified but the path does not exist or is invalid.

When ConversionWorkingFolder is specified but does not exist or is invalid.

See Also:

ConvertFile ConvertFileList ConvertFolder CombineFolder IsConversionServiceRunning

 

Code Sample - C# - Combine both files into a multipage TIFF image

PNCombineItem resultItem = null;

IList<String> filesToTIFF = new List<String>();
 
filesToTIFF.Add(@"C:\Test\File1.pdf");
filesToTIFF.Add(@"C:\Test\File2.pdf");

 
resultItem = PNConverter.CombineFiles(filesToTIFF,
                                      @"C:\Test\Output\",
                                      @"CombinedPDF",
                                     true, // overwrite existing
                                     false, // do not create log
                                     "TIFF 200dpi OptimizedColor",
                                     String.Empty,
                                     String.Empty,
                                     null,         // no custom user settings
                                     String.Empty, // not using DCOM
                                     String.Empty, // use default working folder
                                     String.Empty); // do not use custom log folder

 

Code Sample - VB.NET - Combine both files into a multipage TIFF image

Dim resultItem As PNCombineItem
Dim filesToTIFF As IList(Of String)
 
resultItem = Nothing
 
filesToTIFF.Add("C:\Test\File1.pdf")
filesToTIFF.Add("C:\Test\File2.pdf")
 
resultItem = PNConverter.CombineFiles(filesToTIFF, _
                                     "C:\Test\Output\", _
                                     "CombinedPDF", _
                                     True, _
                                     False, _
                                     "TIFF 200dpi OptimizedColor", _
                                     String.Empty, _
                                     String.Empty, _
                                     Nothing, _
                                     String.Empty, _
                                     String.Empty, _
                                     String.Empty)