Catalyst Internet Mail Control 4.0
Frequently Asked Questions
This document will provide answers to those questions most frequently asked by developers who are using the Catalyst Internet Mail ActiveX control. For specific information about control properties and events, please refer to the documentation and help files included with the product.
| 1. | What is the Catalyst Internet Mail control? The Catalyst Internet Mail control is an ActiveX control which provides comprehensive e-mail functionality to your applications. The Internet Mail control is a single component which implements the standard protocols for composing, sending and retrieving e-mail messages. The Internet Mail control is a single component which makes development and deployment significantly simpler, not a repackaged collection of controls. The control was built on the foundation of the SocketTools core libraries, offering the same stability and features using a new, streamlined interface. |
| 2. | What are the minimum system requirements? The Catalyst Internet Mail control is a 32-bit ActiveX component which requires Windows 98 or later versions of the Windows platform. Windows NT 4.0 requires that Service Pack 6 (SP6) be installed on the system for both developers and end-users. The minimum memory and disk space requirements for end-users are the same as for the base operating system. The following table lists the minimum operating system releases that are supported:
Although not required, it is recommended that the Windows 98 SE update be installed for Windows 98. For Windows 2000, it is recommended that at least Service Pack 2 (SP2) be installed. Note that while the Windows 95 platform is no longer officially supported, the control will work provided that the OSR2 and TCP/IP stack updates have been installed. Operating system updates can be downloaded from the Microsoft website or ordered from Microsoft on CD-ROM. Developers can use the control in any language which fully supports the ActiveX control specification and/or COM objects. Visual Basic 5.0, Visual FoxPro 5.0 and Visual C++ 6.0 are the minimum versions of the Microsoft Visual Studio languages which are supported. |
| 3. | Are there multiple components in this product? No, the Catalyst Internet Mail product consists of a single ActiveX control and includes everything that is needed to compose, send and retrieve e-mail messages. This is not a collection of repackaged SocketTools controls but rather a completely new component designed to make it even easier to incorporate e-mail functionality in your applications. Although based on the core networking and message handling libraries in SocketTools 4.0, the Internet Mail control is a different product line and sold separately from SocketTools. |
| 4. | What is the difference between this product and SocketTools? SocketTools is an extensive collection of ActiveX controls and libraries which implement a variety of Internet protocols. Designed as a general purpose Internet development toolkit, each component is designed to provide support for an individual protocol or standard. If the design of an application calls for using multiple protocols, the developer is responsible for creating the code that connects the different controls together in the application. For example, to create a full-featured e-mail application, the developer would need to use four components: the POP3 control to retrieve messages, the SMTP control to send messages, the DNS control to perform mail exchange (MX) record queries and the MIME control to compose and parse messages. On the other hand, the Internet Mail control incorporates support for all of these protocols and standards in a single component using a single interface, which significantly reduces the complexity of the application. In turn, this reduces the amount of time being spent incorporating and testing the application's e-mail related features, allowing the developer to focus on the core application code. SocketTools is an excellent product for those developers who need a powerful, comprehensive toolkit with low-level support for a wide variety of Internet protocols. However, those developers who just want to add e-mail functionality to their applications without writing a lot of code or redistributing multiple components will prefer the Catalyst Internet Mail control. Those developers who are currently using SocketTools can also use the Internet Mail control in conjunction with other components and/or libraries in SocketTools. |
| 5. | Can the control be used with Visual Studio 6? Yes, the ActiveX control can be used with Visual Studio development tools such as Visual Basic, Visual FoxPro and Visual C++. The product includes example programs and the documentation includes additional reference material specifically for Visual C++ programmers who wish to use the control in their projects. Scripting languages such as Visual Basic Script are also supported, and the control can be used as an object in server-side scripting environments such as ASP. |
| 6. | Can the control be used with .NET development tools? Yes. The .NET development platform supports the use of ActiveX controls and the product includes documentation and Visual Basic.NET example programs. |
| 7. | What standard protocols are implemented by the control? The control implements the Post Office Protocol (RFC 1939) to retrieve messages from a mail server. The Simple Mail Transfer Protocol (RFC 821) and SMTP Service Extensions (RFC 1869) are used to deliver messages. The Multipurpose Internet Mail Extensions (RFCs 2045, 2046, 2047) define the structure of an e-mail message and are used when composing new messages or processing existing messages. |
| 8. | Does the control support secure connections? Yes, the control implements three standard security protocols: Secure Sockets Layer (SSL) versions 2.0 and 3.0, Private Communication Technology (PCT) version 1.0 and Transport Layer Security (TLS) version 1.0. The Secure property determines if a secure connection is established and there are a number of related properties which return details about the certificate and encryption used. Refer to the technical reference documentation for more information. |
| 9. | Does the control require any third-party libraries? No, the control is completely self-contained with no dependencies on third-party libraries or Microsoft support libraries. The only thing that needs to be redistributed with your application is the control OCX itself. Note that to establish secure connections under Windows 98, some Microsoft system libraries may need to be updated. |
| 10. | Does the control use the Microsoft WinInet library? No, the control does not use Microsoft's proprietary WinInet library to establish secure connections. It is not required that you redistribute this library with your software unless you make use of it elsewhere in your application. The control uses the standard Windows Security Support Provider Interface (SSPI), which is modeled after the Generic Security Service (GSS-API) interface outlined in RFC 2078. |
| 11. | Are there any royalties or runtime licensing fees? No, there are no runtime licensing fees and there are no restrictions on the number of products that you can create using the Catalyst Internet Mail control. Applications created using the control may be redistributed to any number of end-users. |
| 12. | Is there an evaluation copy of the product available? Yes. If you choose to install the product without a serial number then it will be installed with an evaluation license that is valid for a period of thirty (30) days. The software is fully functional during the evaluation period, however you will be unable to create redistributable applications using the control. In other words, you will be able to create and test applications on the system on which the evaluation license was created, but you will not be able to run those programs on any other system until you purchase the product. |
| 1. | How do I obtain the current version of the product? The current version of the product can be downloaded from the Catalyst Development website at http://www.catalyst.com/download/products.html. |
| 2. | What happens if an error occurs during installation? If an error occurs during installation, there are several steps that you can take to attempt to correct the problem and restart the installation:
If you continue to have problems with the installation, please complete our Technical Support Request Form describing the problem and your system configuration (including operating system version, memory and available diskspace). |
| 3. | What system updates must be installed for Windows 98? To use the security features of the control under Windows 98, there are some additional system updates that may need to be installed. There is no need to apply these updates to the system if secure (SSL) connections are not going to be used. The control uses the Security Support Provider Interface (SSPI) and requires that the current versions of various shared system libraries be installed. The requirements listed below are for a newly installed system without any additional software. If the listed software has already been installed, it will not be necessary to reinstall it. Please note that the following requirements apply only to Windows 98. Later versions of Windows already have the prerequisite system libraries installed.
For convenience, we have copies of the required software also available for download from our FTP server at ftp://ftp.catalyst.com/pub/cstools/support/. |
| 4. | What is the difference between component and license registration? ActiveX controls must be registered on any system that uses them, which means that specific entries are created in the registry database which provides information to the COM subsystem about the control. The control is typically registered by the installation program which installs it along with the application, however it can also be registered manually using the RegSvr32.exe utility from the command line. License registration is the process of registering the control with Catalyst after the product has been installed. This enables the control to be redistributed to other systems and should only be performed on the development system. If the developer chooses, license registration can also send product information back to Catalyst. This ensures that the developer can obtain technical support and is notified of updates. |
| 5. | Can I update an evaluation version of this product? Yes, as long as there is time remaining in the 30-day evaluation period, updated versions of the product can be installed on the development system. However, this will not extend the evaluation period and once the evaluation period has expired, entering a valid serial number is required to install the product. The amount of time remaining in the current evaluation period is displayed during the installation of the product. |
| 1. | What are the general terms of the license agreement? The complete license agreement for the product can be found in the online help. In general terms, it permits you to install a single copy of the product on your computer system, use the product to build application software and redistribute that software to your end-users. There are no runtime licensing fees, and there are no restrictions on the number of products which may be developed using the control. There are two primary restrictions, the first being that the product is only licensed for a single developer. The second restriction is that you may not use the control to create a software development product which is then used and/or resold by your customers. In other words, you may use the control to build application software, but you are not permitted to create software development components or libraries which are then used by your customers to create software which, in turn, they distribute to end-users. If you have any questions regarding the licensing agreement, please send an e-mail message to info@catalyst.com. |
| 2. | What are the limitations of an evaluation license? The control is fully functional during the evaluation period and the same code that you develop during the evaluation period can be compiled and used once you have purchased the product. However, there are two limitations to consider when developing software using an evaluation license. First, the control will cease to function after the evaluation period has expired. This means that you will not be able to load it into your development environment, and any application that uses the control will no longer function. Second, you cannot redistribute any application created using the control with an evaluation license. An application that is created using an evaluation license will only function on the development system where the license is installed. Once you have purchased a license, you only need to recompile your application with your new, registered license. |
| 3. | Is a license required for each developer using the control? Yes, a license is required for each developer who is using the control. It is a violation of the terms of the license agreement for more than one developer to use the same copy of the product. However, the same developer may install the control on more than one system as long as there is no chance that it will be used by another developer. For information about purchasing additional licenses, please send an e-mail message to sales@catalyst.com. |
| 4. | Does this product require activation or online registration? No, this product does not require electronic activation or registration. We feel that this is too restrictive for developers who frequently must develop and test applications on multiple platforms. Although registration is not required, it is recommended because this entitles the developer to technical support and free service pack updates to the product. |
| 5. | What is the runtime license key? When the product is installed with a serial number, a runtime license key will be created which is used by the control to validate that a licensed copy of the product has been purchased. For languages like Visual Basic, the license key is managed internally and doesn't require any additional coding by the developer. However, some languages don't directly support the use of runtime license keys so the control must be initialized with the license key by calling the Initialize method. The key itself is stored in the \Include folder where the product was installed. For more information, refer to the online help for the Initialize method. |
| 6. | Can the control be used with Active Server Pages? Yes, the control can be used in Active Service Pages by using the function CreateObject to create an instance of the object. The class name for the object is SocketTools.InternetMail. Note that the use of CreateObject requires that the control be initialized with a runtime license key by calling the Initialize method after the control has been created. |
| 7. | Why do I get a licensing error when redistributing my application? There are two common reasons that a licensing error may occur when attempting to execute an application on another system. If the control was installed with an evaluation license, then the control can only be used on the development system during the evaluation period. Attempting to use an evaluation copy of the product will generate an error if the application is installed on another system. If a development license has been purchased and registered on the development system, then it may be that the language does not support the appropriate interface to automatically manage the runtime license key. For example, using the CreateObject function to create an instance of the control will cause a licensing error when the application is redistributed to another system. The control's Initialize method must be called immediately after the control has been created, specifying the runtime license key as one of the arguments. |
| 1. | Can the control be used to create HTML e-mail messages? Yes, the ComposeMessage method can be used to easily create HTML formatted e-mail messages, along with an alternate plain text version of the message for those mail clients which cannot display HTML. For example, the following code in Visual Basic could be used to create an HTML message: nError = InternetMail1.ComposeMessage(strFrom, strTo, strCc, strBcc,
editSubject.Text, _
strMessageText, _
strMessageHTML)
The strMessageText argument would contain the plain text version of the message body, while the strMessageHTML argument would contain the HTML version. Refer to the online technical reference documentation for more information. |
2. |
Can the control be used to attach files to messages? Yes, the AttachFile method can be used to attach any type of file to an e-mail message. Attachments to both standard plain text messages as well as to HMTL messages is supported. For example, the following Visual Basic code would attach a file that was entered into an edit control: If Len(editFileName.Text) > 0 Then
nError = InternetMail1.AttachFile(editFileName.Text)
If nError Then
MsgBox "Unable to attach file " & editFileName.Text & _
vbCrLf & InternetMail1.LastErrorString, vbExclamation
Exit Sub
End If
Binary files are automatically encoded using the standard base64 algorithm, while text files may be included inline or explicitly encoded. Refer to the online technical reference documentation for more information. |
| 3. | Can the control be configured to use relay mail servers? Yes, two properties named RelayServer and RelayPort can be specified so that the control sends all messages through the relay server rather than delivering the message directly to the recipient. |
| 4. | How do you send messages to multiple recipients? There are three properties which determine the recipients for an e-mail message. The To property specifies the primary recipient of the message, while the Cc property specifies those recipients who should receive a copy of the message. Multiple addresses may be assigned to each property by separating each address with a comma. The Bcc property specifies recipients who should receive a "blind" copy of the message; in other words, the message is sent to the specified recipient, but the address is not included in the message header so that the other recipients are unaware to whom it was sent. The Recipients property and Recipient property array can be used to enumerate the recipient addresses that have been specified for the current message. |
| 5. | How do you check if a message contains file attachments? The Attachment property returns the name of an attached file in the current message part. If there is no attachment, then the property returns an empty string. The following example, in Visual Basic, demonstrates how a program could check the current message to determine if it contains any file attachments: bHasAttachments = False
For nPart = 0 To InternetMail1.MessageParts - 1
InternetMail1.MessagePart = nPart
If Len(InternetMail1.Attachment) > 0 Then
bHasAttachments = True
Exit For
End If
Next
The MessageParts property returns the current number of parts in a multipart message. The For..Next loop iterates through each message part, checking the value of the Attachment property, and if it returns something other than an empty string then the message contains an attachment and the loop is exited. |
| 6. | How do you check if a user's mailbox has new messages? To check a user's mailbox for new messages, the application must establish a network connection with the mail server using the Connect method and then check the MessageCount property which will return the number of messages in the mailbox. The following Visual Basic code demonstrates this: Dim nError As Long
nError = InternetMail1.Connect(editServerName.Text, , _
editUserName.Text, _
editPassword.Text)
If nError Then
MsgBox "Unable to connect to " & editServerName.Text & vbCrLf & _
InternetMail1.LastErrorString, vbExclamation
Exit Sub
End If
If InternetMail1.MessageCount > 0 Then
MsgBox "This mailbox has " & InternetMail1.MessageCount & _
" new messages available", vbInformation
End If
InternetMail1.Disconnect
Note that this example presumes that new messages are eventually downloaded by the client and deleted from the server. For more information about retrieving e-mail messages, refer to the online technical reference. |
| 7. | Does the control support APOP authentication? Yes. Set the Options property to the constant value mailOptionAPOP or specify that option to the Connect method. This causes the control to use APOP authentication instead of the standard username and password authentication which is used by default. Refer to the Options property in the online technical reference for more information. |
| 8. | Does the control support secure (SSL) connections? Yes. Set the Secure property to a value of True and secure connections will be established with the mail server. Note that this requires that the server support the standard SSL/TLS extensions. Secure connections using the SMTP protocol are only established if a relay server has been specified; otherwise a non-secure connection will be used to deliver messages regardless of the value of the Secure property. |
| 9. | Can the control be used in Visual Basic without a form? Yes, there are two ways that the control can be used without a form in Visual Basic. One is to create a reference to the control by selecting Project | References from the menu, then clicking on the Browse button and selecting the control's file name. Then, in the program, an instance of the control can be created using the Dim statement as follows: Dim objInternetMail As New InternetMailCtl.InternetMail The other approach is to use the CreateObject method: Dim objInternetMail As Object
Dim strLicenseKey As String
Set objInternetMail = CreateObject("SocketTools.InternetMail")
objInternetMail.Initialize "", strLicenseKey
Note that the strLicenseKey value must be obtained from the csimxkey.bas module that was created in the \Include folder where the product was installed. The Initialize method must be called explicitly when using the CreateObject function; otherwise a licensing error will occur when redistributing the application. |
| 10. | Can the control be used with Visual C++? Yes, the control can be used in Visual C++ using one of several methods. The simplest is to include the control in the project and place it on a dialog, which is similar to using the control with a Visual Basic form. Other methods include using a CWnd derived class and creating an instance of the control dynamically or using the #import directive to import the the control into the project. The control can also be used as a COM object and created using the lower level COM API. Refer to the online technical reference which contains detailed information about using the control with Visual C++. |