Redistribution to Clients

From PDF XChange PDF SDK
Jump to: navigation, search
Line 6: Line 6:
 
{{ToReview}}
 
{{ToReview}}
  
There is simple way to install required SDK on the end-user system and are several ways to get it work there.
+
Redistributing and installing the required components onto a target users system is a relatively straight forward process and we provide several ways to do so - dependent on the functionality that has been used within your application, below you will find detailed instructions on doing so - please do not simply redistribute our 'developers SDK' in its entirety - this will simply clutter your users system, bloat your own installer and most likely confuse your clients as to what applications are available for their use.
  
 +
Option 1.
  
First of all, when your installer installing the '''PDF-XChange Editor SDK''' - it should copy to client's machine the two files (both into one folder):
+
If you have used the UI based functionality contained in the '''PDF-XChange Editor SDK''' - your installer must include the following two files (note the 32/64 bit dependency of specific DLL's and locate both into one common folder on the users system.
 
:<tt>PDFXEditCore.x86.dll</tt>
 
:<tt>PDFXEditCore.x86.dll</tt>
:(for 32-bit application)
+
:(for 32-bit applications)
 
'''or'''
 
'''or'''
 
:<tt>PDFXEditCore.x64.dll</tt>
 
:<tt>PDFXEditCore.x64.dll</tt>
:(for 64-bit application)
+
:(for 64-bit applications)
 
'''and'''
 
'''and'''
:<tt>Resources.dat</tt>
+
:<tt>Resources.dat</tt> - this file is not 32/64 bit dependent and always the same.
  
NOTE: if you need to use in runtime the different localizations for Editor's UI - please also take the whole '''Languages''' folder within all containing files from location, that is created by our official SDK-installer, and place it into the same directory that already contains other files of our SDK.
+
NOTE: If wish to include different localizations for the Editor's UI - please also include the entire '''Languages''' folder we provide and relevant language files as installed by your initial SDK development system installed from us. These files should be located in the same directory as the files detailed above.
  
 +
Do you have any improvements to our Localization files or perhaps a new one you would like us to include - if so we would be pleased to add them to our official releases in coming updates, see [http://www.tracker-software.com/editor_lang here] for more info.
 +
 +
 +
Option 2.
 +
 +
If your application makes use only of 'non UI' based functionality as available in the '''PDF-XChange Core API SDK''' you need copy only a single file to your clients target system - again please note the specific version will be 32/64 bit dependent ...
  
Otherwise, when your installer installing the '''PDF-XChange Core API SDK''' - it should copy to client's machine the one file:
 
 
:<tt>PDFXCoreAPI.x86.dll</tt>
 
:<tt>PDFXCoreAPI.x86.dll</tt>
:(for 32-bit application)
+
:(for 32-bit applications)
 
'''or'''
 
'''or'''
 
:<tt>PDFXCoreAPI.x64.dll</tt>
 
:<tt>PDFXCoreAPI.x64.dll</tt>
:(for 64-bit application)
+
:(for 64-bit applications)
  
  
Next, the installer should prepare the SDK for using it programmatically. There are several methods:
+
Your installer must then prepare your clients system for use of the installed components, the installer should prepare the SDK for use - there are several methods of doing so and you should choose that which is most appropriate for your needs and clients most likely circumstances ;
  
 
== COM-Server Method. ==
 
== COM-Server Method. ==
COM-server should be registered on the destination system. To do that, run the following command:
+
COM-server to be registered on the target system. To do so, run the following command:
 
:<tt>regsvr32 <SDKLibName>.x86.DLL</tt>  
 
:<tt>regsvr32 <SDKLibName>.x86.DLL</tt>  
 
:(for 32-bit apps)
 
:(for 32-bit apps)
Line 38: Line 44:
 
:<tt>regsvr32 <SDKLibName>.x64.DLL</tt>
 
:<tt>regsvr32 <SDKLibName>.x64.DLL</tt>
 
:(for 64-bit apps)
 
:(for 64-bit apps)
The installer should execute this command. Additional command line option <tt>/S</tt> can be passed to <tt>regsvr32</tt> to remove the message box reporting the result of registration.
+
 
With this method it does not matter where COM-server files are located relative to the files of your application, as the COM-server are registered globally in the system (using registry) and it become available for all applications in the system. This can cause a potential problem. The following sample shows that problem. Let we have the system where an application called '''AppA''' and that uses the SDK version '''5.5.313'''. During the installation of this app, the SDK was globally registered as a COM-server. Than another application '''AppB''', that also uses the SDK is installing on the system, but the installer of this app contains older build of the SDK. When this installer will register SDK’s COM-server, it will '''override''' existing COM-server registration and now '''all''' applications will use the last installed SDK. If '''AppA''' requires newer SDK, it may cause serious issues when it will try to use older version of the SDK.  
+
Additional command line options <tt>/S</tt> can be passed to <tt>regsvr32</tt> to remove the message box reporting the result of registration.
 +
 
 +
Using this method ensures that irrespective of the COM server files location relative to your application files the SDK functionality will work correctly, as the COM-server are registered globally within the target system as relationships are managed by the system registry.  
 +
 
 +
One potential problem this can cause however is where a user has multiple applications using our Editor SDK functionality (perhaps from you or multiple 3rd party developers) but each relies on differing releases of our SDK (for example one developer used Version 5.5.313 when creating his application - but you have used a subsequent release) an issue may arise should each developer's installer use the COM global registration method. Whichever installer ran last will be the COM server available to all applications. Should new functionality be available in a later release and one applications is dependent on this functionality - but subsequently another installer is used to install an older version - the new functionality is no longer available and one application or more will cease to function correctly ...
 +
 
 +
Good installation management will therefore be essential and you may prefer to resist using the global registration method on users system for this reason.
 +
 
  
 
== Registration-Free(Click-Once) Method. ==
 
== Registration-Free(Click-Once) Method. ==
Application’s installer should save executable file of the application and SDK’s files in the same folder, and additional two XML files with special names should be placed in that folder:
+
Your application installer should locate all application executable files and the require '''PDF-XChange Editor SDK''' files in a single common folder along with 2 additional XML files with prescribed file names as follows:
 
:<tt><YourProgramName>.exe.manifest</tt>
 
:<tt><YourProgramName>.exe.manifest</tt>
 
:<tt><SDKLibName>.x86.X.manifest (or <SDKLibName>.x64.X.manifest)</tt>
 
:<tt><SDKLibName>.x86.X.manifest (or <SDKLibName>.x64.X.manifest)</tt>
 
Where,
 
Where,
<tt><YourProgramName></tt> - name of the application’s executable file without extension.  
+
<tt><YourProgramName></tt> - is the name of the application’s executable file without a file extension.  
  
 
Sample XML files for Click-Once can be found there: <link>
 
Sample XML files for Click-Once can be found there: <link>
  
That method allows avoiding sharing SDK’s DLLs with other applications and conflicts with different versions. Each application that use this method will use own independent version of the SDK.
+
That method ensures that sharing our SDK’s DLLs with other applications is avoided as are version conflicts described previously. Each application uses its own unique version of our SDK DLL's etc.
  
The more information about Click-Once technology can be found [https://msdn.microsoft.com/en-us/library/142dbbz4%28v=vs.90%29.aspx there].
+
More detailed information regarding Click-Once technology can be found [https://msdn.microsoft.com/en-us/library/142dbbz4%28v=vs.90%29.aspx here].
  
'''NOTE:''' In your development environment you have to change settings of your project to use external manifest files instead of built-in.
+
'''IMPORTANT:''' In your development environment you will also need to change the settings of your project to use external manifest files as opposed to those built-in by default.
  
 
== Using the C-export Method. ==
 
== Using the C-export Method. ==
This method differs in that it does not require any global registration of COM-server and no additional manifest files. However, this method requires to manually loading SDK’s DLL using Windows API function '''LoadLibrary'''. Than a special function should be retrieved and called from this DLL to create and receive a pointer to the main SDK’s object that will provide an access to the entire SDK functionality.
+
This method differs in that it does not require any global COM-server registration or additional manifest files. Instead, this method requires manually loading the SDK’s DLL by use of the Windows API function '''LoadLibrary'''. Then a special function should be retrieved and called from this DLL to create and receive a pointer to the main SDK’s object that will provide access to the entire SDK functionality.
For more information, please refer to sections '''How to Instantiate''' in the [[PXV:PXV_Inst|PXV_Inst]] and [[PXV:PXС_Inst|PXС_Inst]] ActiveX-objects’ descriptions.
+
For more information, please refer to the topics; '''How to Instantiate''' [[PXV:PXV_Inst|PXV_Inst]] and [[PXV:PXС_Inst|PXС_Inst]] ActiveX-objects’ description.
 
 

Revision as of 14:37, 8 June 2015


Redistributing and installing the required components onto a target users system is a relatively straight forward process and we provide several ways to do so - dependent on the functionality that has been used within your application, below you will find detailed instructions on doing so - please do not simply redistribute our 'developers SDK' in its entirety - this will simply clutter your users system, bloat your own installer and most likely confuse your clients as to what applications are available for their use.

Option 1.

If you have used the UI based functionality contained in the PDF-XChange Editor SDK - your installer must include the following two files (note the 32/64 bit dependency of specific DLL's and locate both into one common folder on the users system.

PDFXEditCore.x86.dll
(for 32-bit applications)

or

PDFXEditCore.x64.dll
(for 64-bit applications)

and

Resources.dat - this file is not 32/64 bit dependent and always the same.

NOTE: If wish to include different localizations for the Editor's UI - please also include the entire Languages folder we provide and relevant language files as installed by your initial SDK development system installed from us. These files should be located in the same directory as the files detailed above.

Do you have any improvements to our Localization files or perhaps a new one you would like us to include - if so we would be pleased to add them to our official releases in coming updates, see here for more info.


Option 2.

If your application makes use only of 'non UI' based functionality as available in the PDF-XChange Core API SDK you need copy only a single file to your clients target system - again please note the specific version will be 32/64 bit dependent ...

PDFXCoreAPI.x86.dll
(for 32-bit applications)

or

PDFXCoreAPI.x64.dll
(for 64-bit applications)


Your installer must then prepare your clients system for use of the installed components, the installer should prepare the SDK for use - there are several methods of doing so and you should choose that which is most appropriate for your needs and clients most likely circumstances ;

COM-Server Method.

COM-server to be registered on the target system. To do so, run the following command:

regsvr32 <SDKLibName>.x86.DLL
(for 32-bit apps)

or

regsvr32 <SDKLibName>.x64.DLL
(for 64-bit apps)

Additional command line options /S can be passed to regsvr32 to remove the message box reporting the result of registration.

Using this method ensures that irrespective of the COM server files location relative to your application files the SDK functionality will work correctly, as the COM-server are registered globally within the target system as relationships are managed by the system registry.

One potential problem this can cause however is where a user has multiple applications using our Editor SDK functionality (perhaps from you or multiple 3rd party developers) but each relies on differing releases of our SDK (for example one developer used Version 5.5.313 when creating his application - but you have used a subsequent release) an issue may arise should each developer's installer use the COM global registration method. Whichever installer ran last will be the COM server available to all applications. Should new functionality be available in a later release and one applications is dependent on this functionality - but subsequently another installer is used to install an older version - the new functionality is no longer available and one application or more will cease to function correctly ...

Good installation management will therefore be essential and you may prefer to resist using the global registration method on users system for this reason.


Registration-Free(Click-Once) Method.

Your application installer should locate all application executable files and the require PDF-XChange Editor SDK files in a single common folder along with 2 additional XML files with prescribed file names as follows:

<YourProgramName>.exe.manifest
<SDKLibName>.x86.X.manifest (or <SDKLibName>.x64.X.manifest)

Where, <YourProgramName> - is the name of the application’s executable file without a file extension.

Sample XML files for Click-Once can be found there: <link>

That method ensures that sharing our SDK’s DLLs with other applications is avoided as are version conflicts described previously. Each application uses its own unique version of our SDK DLL's etc.

More detailed information regarding Click-Once technology can be found here.

IMPORTANT: In your development environment you will also need to change the settings of your project to use external manifest files as opposed to those built-in by default.

Using the C-export Method.

This method differs in that it does not require any global COM-server registration or additional manifest files. Instead, this method requires manually loading the SDK’s DLL by use of the Windows API function LoadLibrary. Then a special function should be retrieved and called from this DLL to create and receive a pointer to the main SDK’s object that will provide access to the entire SDK functionality. For more information, please refer to the topics; How to Instantiate PXV_Inst and PXС_Inst ActiveX-objects’ description.