DWmail Client Software Development Kit

Transcription

1 SDK DOMINION WEB DESIGN DWmail Client Software Development Kit 0

2 D W M A I L C L I E N T SOFTWARE DEVELOPMENT KIT 2008 Dominion Web Design

3 Table of Contents Introduction... 1 What is the DWmail Plugin Client... 1 What is the Software Development Kit (SDK)... 1 How to get the SDK... 1 Requirements for the SDK... 1 Using the SDK... 2 Opening the SDK... 2 Customising the Client Name... 2 Editing the Setup Project Name... 3 Registry... 4 Editing the URL to your DWmail installation... 4 Setting DWmail Client to the default mailto: protocol... 5 Setting DWmail Client to the default Mail handler on the Start Menu... 5 Registered Applications... 6 Start Menu... 7 Start Menu Shortcuts... 7 Building the Setup Files... 9 Changing the MSI file name... 9 Prerequisites Building the setup files... 10

4 Chapter 1 Introduction What is the DWmail Plugin Client DWmail Plugin Client is a small Windows application that allows you to set your DWmail webmail to be your default Windows client. The Plugin Client to be run from link on Start Menu link from Internet Explorer mailto: hyperlinks in web pages What is the Software Development Kit (SDK) This SDK is available for registered clients of DWmail who wish to customise the default settings and rebundle the DWmail Client for their own DWmail installation. How to get the SDK Only existing license holders of DWmail can download and use the SDK. This is available for download from the Dominion Web Client Download area at Requirements for the SDK The DWmail Plugin Client SDK has the following requirements: Microsoft Visual Studio 2008 (The SDK may work with 2005 but has not been tested with this version).net Framework 2.0 1

5 Chapter 2 Using the SDK Opening the SDK Once you have download the SDK from the Dominion Web download area, double click on the executable SDK.exe file. This is a self extracting ZIP file. It is recommended you select your Visual Studio Projects folder as the path to unzip the SDK to. Once you have unzipped the SDK navigate to your Visual Studio Projects Folder. This is you usually in your Documents folder under Visual Studio 2008\Projects. A folder called SDK will have been created containing the DWmail Client SDK project solution. Navigate to the SDK folder and double click on the DWmail Client SDK.sln solution file. This will open Visual Studio 2008 with the SDK loaded. The Solution Explorer will show two open setup projects called DWmail Client for Windows Vista and DWmail Client for Windows XP. The only key difference between the two is the extended registry settings needed for the Client to become the default client under Windows Vista. Any changes you make to the Windows Vista project will need to be repeated in the Windows XP client but there will be fewer changes that need to be made. For the duration of this documentation we will refer to the changes needed for the Vista client to customise to your DWmail installation Customising the Client Name When the Client preferences are loaded through the Start Menu, the application name can be changed using the SDK by editing the file WebmailClient.exe.config. Right click on this file and select Open in the Solution Explorer 2

6 Find the section entitled: <applicationsettings> <DWmailClient.Properties.Settings> <setting name="appname" serializeas="string"> <value>dwmail Client</value> </setting> </DWmailClient.Properties.Settings> </applicationsettings> Edit the text within the <value> and </value> tags to reflect the name you wish to use for the Client. Note this will not change the application name under Help -> About dialog. Editing the Setup Project Name The setup project name is the name used for the installation directory, the name in the installer and the name in the Add/Remove Programs section of the Windows Control Panel. Single click on the Setup Project root called DWmail Client for Windows Vista in the Solution Explorer. The Properties section will now give you the options you can change. You may wish to change the following Properties Author Description Manufacturer (changing this property will require you to change part of the path to the application in the registry settings later) ManufacturerUrl to your own website ProductName (changing this property will require you to change part of the path to the application in the registry settings later) SupportPhone to your telephone number if you offer telephone support to your customers SupportUrl to the URL of your support area if you offer such a tool to your customers Title Version (the Setup Process will automatically upgrade and remove older versions but if this version number is the same as one already installed then the setup process will require the end user to manually remove via the control panel first. This can be run side by side with the Client available from Dominion Web however) 3

7 Chapter 3 Registry Editing the URL to your DWmail installation The registry settings are the key to the DWmail Client becoming the default client for Windows and hooking into the mailto: URL protocol in your web browser. To access the registry settings, right click on DWmail Client for Windows Vista in the Solution Explorer and select View -> Registry The main workspace will change to the registry layout for the Client. These are registry settings used by the Client to allow it to hook into the default mailto: protocols and the default client from the Start Menu. 4

8 Firstly we need to change HKEY_CURRENT_USER (HKCU). Click on the + icon to expand and navigate to HKCU\Software\DWmailClient The only registry setting that should need changing is the uri key. This is the URL to your DWmail webmail installation. By default this is set to Single click on the uri entry and the Properties dialog will allow you to edit it. Edit the Value field to reflect the URL to your DWmail installation. Do not include a trailing forward slash to this entry. The other setting here is composepath. Unless you have renamed compose.php then there should be no need to change this entry. Setting DWmail Client to the default mailto: protocol Navigate to HKEY_LOCAL_MACHINE (HKLM) and then to HKLM\Classes\DWmailClient.Url.mailto The only entry needed to be customised here is FriendlyTypeName. This is set to DWmail Client mailto protocol by default, simply edit this to reflect your application name. HKLM\Classes\DWmailClient.Url.mailto\DefaultIcon (Default) Path to the default icon for the DWmail Client. By default this is "[ProgramFilesFolder]Dominion Web\DWmail Client\dwmailclient.ico". Please note that this is enclosed in double quotation marks. If you changed Manufacturer and ProductName in the Setup Project settings you will need to edit this path. HKLM\Classes\DWmailClient.Url.mailto\shell\open\command (Default) Path to the DWmail Client executable. By default this is "[ProgramFilesFolder]Dominion Web\DWmail Client\WebmailClient.exe" %1. Please note the double quotation marks around the executable path. If you changed Manufacturer and ProductName in the Setup Project settings you will need to edit this path. Setting DWmail Client to the default Mail handler on the Start Menu Navigate to HKEY_LOCAL_MACHINE (HKLM) and then to HKLM\Clients\Mail\DWmail Client 5

9 Rename the main key to your application name Rename the (Default) key to match the name you just used HKLM\Clients\Mail\DWmail Client\Capabilities ApplicationDescription the description of the DWmail client displayed under Start -> Default Programs -> Set your default programs ApplicationName the name of your application, should match the main key name you changed above. HKLM\Clients\Mail\DWmail Client\Capabilities\Startmenu Mail the name of the application, should match the main key name you changed earlier. HKLM\Clients\Mail\DWmail Client\Capabilities\UrlAssociations mailto this is a referencing path to the HKLM\Classes setting and should not need to be changed HKLM\Clients\Mail\DWmail Client\DefaultIcon (Default) Path to the default icon for the DWmail Client. By default this is "[ProgramFilesFolder]Dominion Web\DWmail Client\dwmailclient.ico". Please note that this is enclosed in double quotation marks. If you changed Manufacturer and ProductName in the Setup Project settings you will need to edit this path. HKLM\Clients\Mail\DWmail Client\Protocols\mailto\DefaultIcon (Default) Path to the default icon for the DWmail Client. By default this is "[ProgramFilesFolder]Dominion Web\DWmail Client\dwmailclient.ico". Please note that this is enclosed in double quotation marks. If you changed Manufacturer and ProductName in the Setup Project settings you will need to edit this path. HKLM\Clients\Mail\DWmail Client\Protocols\mailto\shell\open\command (Default) Path to the DWmail Client executable. By default this is "[ProgramFilesFolder]Dominion Web\DWmail Client\WebmailClient.exe" %1. Please note the double quotation marks around the executable path. If you changed Manufacturer and ProductName in the Setup Project settings you will need to edit this path. HKLM\Clients\Mail\DWmail Client\Protocols\shell\open\command (Default) Path to the DWmail Client executable. By default this is "[ProgramFilesFolder]Dominion Web\DWmail Client\WebmailClient.exe" %1. Please note the double quotation marks around the executable path. If you changed Manufacturer and ProductName in the Setup Project settings you will need to edit this path. Registered Applications Under Windows Vista this registry key is required for DWmail Client to appear in the Default Programs list. Navigate to HKLM\RegisteredApplications\ DWmail Client The key name must match the name of the name of the Application you changed earlier. The value, default Software\Clients\Mail\DWmail Client\Capabilities must match the registry path to the Capabilities setting you edited earlier. 6

10 Chapter 4 Start Menu Start Menu Shortcuts To access the Start Menu Shortcuts, right click on DWmail Client for Windows Vista in the Solution Explorer and select View -> File System The Workspace will now change to show the installation file system. Navigate to User s Programs Menu Click on DWmail Client and the Properties dialog will change. To edit the name of the folder you can edit the (Name) field. 7

11 Navigate to User s Programs Menu\DWmail Client and click on the file DWmail Client. This is the icon on the start menu to load the Client s settings dialog. The Properties dialog will change and you can edit the following fields: (Name) The name of your application in the shortcut Description A description tooltip that appears when you hover over the shortcut The other dialog options should not need to be edited. Do not change the Arguments option. 8

12 Chapter 5 Building the Setup Files Changing the MSI file name To access the Build Options, right click on DWmail Client for Windows Vista in the Solution Explorer and select Properties Make sure the current Configuration is set correctly by clicking on Configuration Manager and making sure both projects are set to Release Change the Output file name: to the directory and name of the MSI file you wish to create when the project is built. 9

13 Prerequisites Prerequisites are packages required before DWmail Client can be installed and run. You can access these by clicking on the Prerequisites button. By default.net Framework 2.0 and Windows Installer 3.1 are selected as they are required by DWmail Client. Prerequisites will automatically download at the same time as installation from Microsoft s website if they are not already installed. Building the setup files To access built the setup files, right click on DWmail Client for Windows Vista in the Solution Explorer and select Build. The Output dialog will show you the build process and assuming no mistakes have been made when editing the SDK files, the process will complete. The setup files will be located in your documents folder in the subfolder Visual Studio 2008\Projects\SDK\ DWmail Client Setup Vista\Release\ There are two files, setup.exe and (if the output name was not changed above) client.msi. client.msi is the only file required for the setup, however setup.exe is a bootstrap wrapper that includes the detection of the prerequisites such as.net 2.0 Framework. 10