%%ItemTitle%%

PowerTCP Mail for ActiveX
PowerTCP Mail for ActiveX

Welcome!

Welcome and thank you for choosing PowerTCP Mail for ActiveX. You have selected what we feel is the most sophisticated and complete ActiveX Email package available on the market. We know you have a choice in software vendors and we will do our best to exceed your expectations.

Overview

PowerTCP Mail for ActiveX provides file transferring capabilities, and has been designed for Email novices and experts alike, providing powerful but easy-to-use components and classes that can be plugged into any COM application. Some of this extended functionality includes:
  • Secure Smtp, Pop and Imap support
  • SSL 2.0, SSL 3.0, PCT, TLS 1.0, TLS 1.1, TLS 1.2 support
  • Create HTML messages from HTML source with a single method call
  • Rich X509 certificate management objects included
  • Multi-national character sets fully supported
  • Base64, Quoted Printable, UUEncode and Y-encoding supported
  • On-the-fly encoding and decoding with the Message object
  • Email address verification

About Us

Quality!

Dart Communications, located in upstate New York, has been designing and developing Internet communication components since 1994. More than a decade later, PowerTCP, PowerSNMP, and PowerWEB for ASP.NET are International bestsellers to small businesses, consultants, and Fortune 500 companies.

Each targeted protocol is extensively researched by Dart and each product is tested and supported by consistent processes and customer feedback. Developers using our products can focus on creating the unique features they require rather than wasting weeks on research and unnecessary code writing.

Added Value

Dart Communications is committed to creating products that are of high quality, flexible, and easily implemented into a project. This process means maintaining meticulous documentation and a readily available support staff. In addition, Dart consistently processes feedback and requests, using this information for new product and feature development.

Dart's development team is also available for custom development projects relating to their product line. A customer may lack the time or background to complete a particular project as needed. Dart's team will draw on their protocol knowledge and experience to supply a quality solution within the time frame required.

Expertise

Building components is about reliability. Developers need products that can stand up to use, that work as intended, and that go beyond original expectations. Our research tells us that users often change the scope of a project once it is underway. PowerTCP products are designed to scale to those increased expectations. To give you time to evaluate this claim prior to purchase, Dart supplies a fully functional trial for all of its products. See for yourself how a component can have both high-level functionality for quick and easy solutions, and also provide a low-level interface for customization.

In today's world, software developers are routinely asked to produce solutions using unfamiliar technologies, with little time allowed for research. When Internet Communications is part of your project, consider leveraging Dart's proven components to connect, encode, compress, encrypt and transfer data. Our goal is to help you build applications that work the first time, every time.

Documentation Version 2.13
© 2017 Dart Communications. All Rights Reserved.
Send comments on this topic


%%ItemTitle%%

PowerTCP Mail for ActiveX
PowerTCP Overview

Dart has transformed its world-class Internet Toolkit into a Component Object Model (COM) based set of ActiveX controls that are supported in more development environments than ever before. Our ActiveX (ATL) controls and sample applications plug into all popular development environments: Visual Studio, C++Builder, Delphi, PowerBuilder, Internet Information Server (ASP), JavaScript, FoxPro, and other VB script and VBA environments. New features include:

  • Multi-tier architecture that separates all processing into 3 layers. No competing product offers this level of flexibility and modularity:
  • Formatting tier converts bytes into objects
  • Upper-layer protocol tier (Telnet, FTP, SMTP, etc.) implements communication protocols
  • Winsock tier handles all communication tasks
  • Controls can be placed on forms OR dynamically instantiated, making this product perfect for both form-based environments like Visual Basic AND formless environments like ASP.
  • Blocking behavior is included, so you can write applications using blocking or non-blocking operation. Scripting languages such as VB and JavaScript are now fully supported.
  • 'Apartment Model Threading' provides multi-thread support for the most demanding applications.
  • Superior Object Model maximizes your effectiveness in your development environment collection properties provide superior list handling, formatting objects make it easier to manipulate complex structures (like MIME messages), and the use of enumerated types and objects makes your job as simple as it should be.

PowerTCP is a complete collection of Internet protocol controls and formatting objects. The controls provide concise programming models for the protocols and contain events to help monitor lengthy operations, and the formatting objects transform data between network bytes and COM objects with which your application can easily work.


%%ItemTitle%%

PowerTCP Mail for ActiveX
PowerTCP License Installation

Your PowerTCP License Agreement provides you with a single-seat development license and the right to distribute PowerTCP controls with NO ROYALTIES of any kind. Some PowerTCP objects are marked as licensed. This topic covers:

  • Trial Installation
  • Installing a Fully Licensed PowerTCP for ActiveX
  • Re-installing a PowerTCP for ActiveX Product
  • License Details
  • Special Notes on Tested Development Environments

Trial Installation

Installing PowerTCP for ActiveX as a fully functional trial involves running the setup program (available from www.dart.com) without completing the Registration process. The trial will operate for 30 days after installation. Proceed to step 2 of 'Installing a Fully Licensed PowerTCP for ActiveX Product' below when you are ready to license the product.

See Trial Operation for more information.

Installing a Fully Licensed PowerTCP for ActiveX Product

Once you have downloaded the latest version, complete the following steps to register PowerTCP for ActiveX:

  1. From the Start menu, point to Programs, point to PowerTCP, point to the PowerTCP for ActiveX product you downloaded, and then click Registration.
  2. In the PowerTCP Registration dialog box, click Register.
  3. Enter your Serial Number, First Name, Last Name, and Organization information.
  4. Click Next.
  5. Enter your Email Address, Purchased From, and Purchased Date information.
  6. Click Next.
  7. Verify that the information is correct, and then click Next.
  8. When the registration process is complete, click Exit. (Note Clicking Done at this step displays your currently registered PowerTCP Tools. Click Exit to end the complete the registration process and close the dialog box.)

If you do not have Internet Access on your development machine, please follow these instructions:

  1. From the Start menu, point to Programs, point to PowerTCP, point to the PowerTCP for ActiveX product you downloaded, and then click Registration.
  2. In the PowerTCP Registration dialog box, click Edit.
  3. In the Currently Registered Products area, write down the number in the Key field (the fields appears dimmed).
  4. On a machine that has Internet access, log on to the Dart registration page (http://www.dart.com/register/).
  5. Enter all required information. Required information is bolded. Key is the number you wrote down in Step 3 above.
  6. Click Submit. A seven-digit registration code appears.
  7. On your machine (the machine on which you completed Steps 1-3), if necessary, access the PowerTCP Registration dialog box to display the Currently Registered Products area containing the Key number.
  8. Enter your serial number and the seven-digit registration number you obtained in Step 6.
  9. Click Update.
  10. Click Exit.

After either of the two registration procedures are complete, your PowerTCP for ActiveX product appears in the Registered Tools field of the registration form. Make sure you recompile your application after you register PowerTCP for ActiveX. For distribution instructions specific to your development environment, please view the Readme file. The Readme file is located in the Samples directory; for example, to locate the Readme file for Winsock for ActiveX in VB6, use the following path: Start>Programs>PowerTCP>WinsockTool>VB Samples>VB6>Readme.

If you do not register PowerTCP for ActiveX at this point, it will operate as a trial. Remember to distribute with your applications any necessary PowerTCP files and any dependent files. Dependent files are listed in the Introduction topic for each PowerTCP Control, and must be installed on each target system. See Distribution for more information on system requirements.

Re-installing a PowerTCP for ActiveX Product

The Key provided by the Registration Program is derived from a system number that is changed when the C: drive is reformatted. If you reformat your hard disk, and need to re-install PowerTCP for ActiveX, follow the steps in 'Installing a Fully Licensed PowerTCP for ActiveX Product' above. You will be prompted to complete a License Transfer form, and a new Registration Number will be generated.

If you need to re-install more than once, you will be prompted to complete a License Transfer form that will be sent to your sales representative for approval. Within two working days Dart will reset your Serial Number and notify you when you can re-register your product. The product will operate as a trial for up to 30 days.

License Details

When you insert a PowerTCP control into a project, most development environments verify that the control is licensed for development. The control will work if you correctly entered the PowerTCP Serial Number. See Installing a 'Fully Licensed PowerTCP for ActiveX Product' above for more information. When you compile your application, the development environment requests this Serial Number and embeds it in the application. When users run your application, the application submits this Serial Number to the control and the Serial Number is checked for validity. If the Serial Number is correct, then the application runs. This verification process occurs automatically.

Special Notes on Tested Development Environments

  • Visual Basic checks for a Serial Number when a PowerTCP control is first inserted on a form or first shown on a form. When a PowerTCP control is loaded as a reference and is dynamically instantiated (for example, Dim Tcp as New Tcp), the Serial Number is similarly checked.
  • Visual C++ obtains the Serial Number when you first insert a PowerTCP control on a form, and caches that number as a dialog resource. For this reason, Dart ships Visual C++ samples without inserted controls. You will need to insert them before you compile any of the samples. See the readme.txt file for more information. Information on dynamically creating objects using ClassFactory2 is included. License caching is MFC only; for our new C++ classes, you must specify the License as a parameter in the Create method.
  • Active Server Page deployment requires a Serial Number for each server because the environment checks for a development license each time a licensed control is used. If you deploy PowerTCP Tools for operation under IIS, install your development license into the registry as it appears on your development platform (check registry location HKEY_LOCAL_MACHINE / SOFTWARE / Dart / PowerTCP / License to see what should be installed). PowerTCP is royalty-free, including under IIS.
  • PowerBuilder also caches licensing information. See the readme.txt file for instructions on how to compile the sample applications.
  • Excel will cache licensing information when the control is originally inserted, so your spreadsheet will carry this information forward to any deployment platforms. You must use the control as a reference.
  • Delphi has special requirements. Before you can use the sample applications you MUST add the PowerTCP Tools that are in the sample to the Component Library. Refer to the readme.txt file for specific instructions.
  • C++ Builder is similar to Delphi. See the readme.txt file for specific instructions.


%%ItemTitle%%

PowerTCP Mail for ActiveX
PowerTCP Trial Operation

If you install a PowerTCP product without registering a Serial Number, it operates as a fully functional trial for up to 30 days. If you need more time to evaluate the product, reinstall it; the trial period will start over.

Trial Notification in Development Mode

When you insert a PowerTCP control on your form or dynamically create one, the control checks for a Serial Number. When it does not find one, a dialog box appears identifying the product as a trial. This dialog box does not appear if you are running under IIS; this allows the product to work within the ASP environment as a trial. After the trial period expires, you cannot insert the control without first reinstalling it.

Trial Notification during Compile

PowerTCP controls request a Serial Number when you compile your application. A dialog box appears warning you that the component is not licensed for deployment. Do not distribute your application using a trial productthe component will not work after the trial period! However, you may test your application during your trial period. To continue testing after the trial period, reinstall the product and recompile your application.

See License Installation for more information on product registration.


%%ItemTitle%%

PowerTCP Mail for ActiveX
PowerTCP Distribution

System File Updates

Windows 95

DCOM95 version 1.3 must be installed before installing PowerTCP DLLs. You can redistribute DCOM95 with your product so your users can install it. Obtain DCOM95 from www.microsoft.com/com/dcom/dcom95/download.asp.

Windows 98

DCOM98 version 1.3 must be installed before installing PowerTCP DLLs. Microsoft does not allow redistribution of DCOM98, so your users will need to obtain it from www.microsoft.com/com/dcom/dcom98/download.asp.

Windows NT4

Your system must be updated to a level of at least Service Pack 3 (the Secure DLL requires SP4) before installing PowerTCP DLLs. You must update the following OLE system files to the following levels:

DLL | Version
OLEAUT32.DLL | 2.40.4275 (or higher)
STDOLE2.TLB | 2.40.4275 (or higher)
ASYCFILT.DLL | 2.40.4275 (or higher)
OLEPRO32.DLL | 2.40.4275 (or higher)
COMCAT.DLL | 4.71 (or higher)

System updates are performed using the 4275-Ole.exe file, which is located in the Bin directory in your PowerTCP for ActiveX install root directory. You can redistribute this file to your users. Note This system update file will not run under Win95/98 (see Windows 95 and Windows 98 above for Win95/98 requirements).

Windows ME

Windows ME requires no system file updates.

Windows 2000

Windows 2000 requires no system file updates.

Windows XP

Windows XP requires no system file updates.

Winsock version 2 System Support

Windows 95 ships with Winsock version 1; all other operating systems (Win98/2000/NT/XP/Vista/Windows 7) ship with version 2. Version 2 is only required by applications that use raw datagrams and multicast features. Dart's Ping Control and UDP Control (multicast feature) are the only products that require version 2. This update was last available at www.microsoft.com/windows95/downloads/contents/wuadmintools/s_wunetworkingtools/w95sockets2/.

PowerTCP links to Winsock version 1, but the operating system redirects these calls to version 2 (if installed). Therefore, performance is optimal (no performance degradation occurs due to linking to Winsock version 1), while still allowing PowerTCP to be installed on Windows 95 systems that have not been updated to version 2.

If you use raw or multicast datagrams, make sure Winsock version 2 is available on your deployment platforms.

Dependencies and Distribution

PowerTCP DLLs must be registered. Most installation utilities will do this automatically; however, you can also use Regsvr32.exe. See 'System File Updates' above for more information on system file support before registering PowerTCP Tools.

DartMail.dll is dependent upon:

  • DartCertificate.dll
  • DartSecure2.dll
  • DartSock.dll
  • DartUtil.dll

Distribution in Scripted Environments (such as IIS)

If you are using PowerTCP in scripted environments (such as IIS or Excel) and you have not installed a Serial Number, the product will work for 30 days as a Trial, but will then cease operation. Scripted environment deployment requires a Serial Number for each server because the environment checks for a development license each time a licensed control is used. If you deploy PowerTCP Tools for operation in scripting environments, install your development license into the registry as it appears on your development platform (check registry location "HKEY_LOCAL_MACHINE / SOFTWARE / Dart / PowerTCP / License" or "HKEY_LOCAL_MACHINE / SOFTWARE / Wow6432Node / Dart / PowerTCP / License" on 64 bit systems to see what should be installed).

For most compiled applications, your PowerTCP Serial Number is automatically included when you compile, so no special license considerations are necessary. The only exception is Dart's C++ wrapper, in which the Create method takes your development license as a parameter.

Troubleshooting

If you receive "not licensed for distribution" messages, try removing the control from your project and then re-inserting it. If a trial was already installed and used to build a project, some development environments cache the licensing information even after registering the control. Refer to environment-specific readme.txt files for more information.


%%ItemTitle%%

PowerTCP Mail for ActiveX
PowerTCP Visual C++ Notes

Each development environment has it's own unique way of supporting ActiveX controls. Visual Basic, for example, offers superb support for using controls both on forms (by adding it to the component bar and dragging it onto a form) and off forms (by instantiating them at run-time using "Dim" and "Set" constructs). In Visual C++ it is a little harder, and there are different techniques possible using MFC and "straight" WIN32.

MFC Support for ActiveX

MFC provides direct support for placing a control on a form. Using the ClassWizard, you then reference the control ID, add a variable, and then add event handles for each event. This mechanism works well with Dart PowerTCP controls, but has the following shortcomings that require a workaround:

  1. When you insert a control, the resource file caches license information. When you use the control as a trial and subsequently purchases a license, you must manually remove the control and then read it so that the license information is properly included and passes the license check at run time.
  2. When Dart ships the sample as part of PowerTCP for ActiveX, it must be shipped with the control missing, so the application does not compile as shipped (the control must be added first, even to operate as a trial).
  3. You cannot use this technique for non-MFC or formless applications, such as console applications, service applications, ATL controls, "straight" WIN32 applications, and other C++ environments (such as Borland C++ and C++ Builder).

To work around these limitations, many Dart controls have already been upgraded to provide the following benefit.

Class Support for ActiveX

Dart has provided a "wrapper" class for many controls (and objects) that uses licensing, such that:

  1. Developers may not be familiar with using using the C function to create a licensed control (CoComCreateInstanceLic). Dart has provided a Create() method to handle the instantiation of a licensed control.
  2. Developers may also be unfamiliar with manually adding event support. Dart has provided code to create this connection within the class.
  3. You can uses these classes in any C++ environment, simplifying the use of our product in these environments.
  4. Samples will compile right out of the box.


%%ItemTitle%%

PowerTCP Mail for ActiveX
Message Encoding

When composing or reading Internet email, there are two types of encoding to be aware of:

  1. File encoding
  2. Character encoding

This topic attempts to explain why these encoding types are needed when sending/receiving Internet email, and how to properly handle sending/receiving email that contains 8-bit data and international characters.

File Encoding

File encoding is needed when sending/receiving email for the following reason: Many email messages contain 8-bit data. However, the SMTP protocol may limit data transmission to 7-bit data only. As a result, any message containing 8-bit data must be file encoded to make it compatible with SMTP servers using a 7-bit encoding algorithm. Generally, this encoding is done using one of two algorithms:

  • Quoted-Printable Encoding
  • Base64 Encoding

Quoted-Printable encoding works like the following: An 8-bit character has 256 possible values. Of these, the low 128 are 7-bit ASCII values and not a problem for transfer through an SMTP server. The high 128 characters require 8-bits of storage and need to be encoded to be able to be transferred. Each 8-bit character is converted to its hexadecimal value and quoted, so decimal 200 becomes the ASCII string value =C8. Since this encoding scheme leaves ASCII characters intact, it is very efficient for encoding data that contains a large amount of ASCII text.

Base64 Encoding scheme works in this way. Groups of 24-bits are broken off. In the data's native form this would represent 3, 8-bit segments. For SMTP transmission, this data is encoded as 4, 6-bit segments.

When a message or message part is encoded by an email client using one of these two encoding algorithms, a header (content-encoding) is added to the message or message part which indicates to the receiving mail client which algorithm to use to properly decode the data.

Once the message has been properly Base64 or Quoted-Printable decoded it is NOT yet properly interpreted. The message contents now have to be interpreted using a character set.

Character Encoding

Once a received email has been file decoded, it still may not be interpreted properly by the receiving mail client. The reason for this is the mail client always has to take into account the character set the email was composed in to properly interpret the strings contained within it. This process is known as character encoding/decoding.

When communicating with international mail clients, you should always be aware of character encoding issues. At the highest level, character encoding/decoding can be viewed as taking a visual string representation displayable in a UI, translating that visual string representation into a multibyte value for transmission between systems, then retranslating the numerical value back into the original string representation. At one time a simple procedure, now made much more complex by the advent of the Internet and international exchange of data.

In the early days of the SMTP protocol, the only string characters that English-speaking developers used were 7-bit ASCII values. For this reason, any time an email was received it was always safe to assume that it was comprised completely of ASCII values for decoding purposes and there was never any problems reading email.

Eventually, as demand required the use of more characters, the original 7-bit ASCII characters was extended into many 8-bit character sets, enabling developers to add an additional 128 characters to their character set definitions. For example, one of these was the Latin1 character set which extended the ASCII characters to include such values as the copyright symbol (©), the trademark symbol (™), and other useful symbols which was used by English speaking people. Now English speaking people could send email containing these non-ASCII symbols to other English speaking people and, both clients assuming that the Latin1 character set was being used, and all characters were interpreted and displayed properly. Meanwhile, in other areas of the world, the original 7-bit ASCII character set was being extended in ways useful for non-English speaking people. For example, the Russian alphabet was added on top of the original ASCII values to form the Cyrillic character set. Now a Russian speaking person could send email to another Russian speaking person using Russian characters and, both clients assuming that the Cyrillic character set was being used, all characters were interpreted and displayed correctly.

The problem became clear when international data transfer became more commonplace. An English speaking person may use a non-ASCII Latin1 character such as the cent symbol (¢). For data transmission, this character would be represented by the sending mail client as the 8-bit value 162 (as specified by the Latin1 character set). A Russian mail application, reading this message, would wrongly convert the 8-bit value 162 using the Cyrillic character set, resulting in the end user seeing the character Ў instead of ¢.

To enable the receiving mail client to properly interpret the characters, the charset parameter was added to the content-type mail header. The value of this parameter maps to a code page which the client can use to use the correct visual representation of a character for a given 8-bit value.

Special note about header encoding (or word encoding)

If a message header line contains 8-bit data it must use a special encoding syntax of the following format:

     =?[charset]?[encoding]?[header content]?=

The =? and ?= delimiters at the beginning and end of the header indicate that this header was encoded. The value of [charset] indicates the character set to use to correctly interpret this header. The value of [encoding] indicates the encoding type to use (B for Base64, Q for Quoted-Printable) to correctly decode this header. The value of [header content] contains the encoded content. An example of a Base64 encoded shift-jis header line is below.

     =?shift-jis?B?UmU6IA0KUmVsZWFzZSBkYXRlIHV0ayB2ZXIgMi4wID8=?=

Although the example above addresses most Internal email scenarios, it does not address all. Namely, some languages contain many more characters than can possibly be encoded using 8 bits, such as some Asian dialects. For dialects such as this, a multi-byte representation must be used.

Note about Unicode

As the above examples illustrate, using an 8-bit representation is limiting. If a dialect has greater.than 256 characters, there is no way to represent all possible characters. For that reason, the Unicode encoding, using a wide character representation (allowing up to 65,536 potential characters) provides a numerical value for all known characters.

The concept with Unicode is that any known character can always be represented by a multi-byte sequence of 1 or more bytes, and that representation can always be returned to the Unicode character.

When using PowerTCP

At what time do these encodings/decodings occur when using a PowerTCP product? As an example, take an email composed on a machine that uses Shift-JIS as the default character set, then Base64 encoded for SMTP transmission. When a PowerTCP product reads this data, it is parsed on-the-fly and Base64 decoded. After this process, you have an object representation of a message. As the parts of the message are accessed (for example, when reading Message.Text) the content of this message is correctly interpreted using the specified character set.


%%ItemTitle%%

PowerTCP Mail for ActiveX
Imap Security

Overview

The Imap control can be used to communicate securely with servers using SSL 2.0, SSL 3.0, TLS, or PCT by setting the Privacy property. Handle server certificate authentication (whether or not to accept the certificate the server sends) in the Authenticate event, or using the Security property in scripted environments with no events. Handle client certificate authentication (when the server requests the client authenticate itself using a certificate) in the Certificate event and using the Certificate property.

Using basic security with the Imap control

The simplest way the Imap control could be used to communicate securely is to set the Security property to secureIgnoreCertificate (which will cause the control to automatically accept any certificate the server sends) and connect to a secure server. This technique, while simple, has obvious security holes that are addressed in the remainder of this topic. Incidentally, for environments that lack events such as ASP, the Security property should always be used to dictate how the control should handle the server's certificate.

Example
Copy Code
Private Sub SecurityTest1()
    ' Accept any certificate the server sends, valid or invalid.
    Imap1.Security = secureIgnoreCertificate

    ' Set the SSL privacy to use - privacyImplicitAuto works in most cases
    Imap1.Privacy = privacyImplicitAuto

    ' Connect and login to a secure Imap server on the standard secure Imap port 993.
    Imap1.Login "myImapServer", "myAccount", "myPassword", 993
End Sub

Customizing certificate handling with the Imap control

As stated above, disabling security checks is the easiest way to use connect to a secure server but has massive security drawbacks. To remedy this, set the Security property back to secureNormal to perform all certificate checks within the Authenticate event.

Example
Copy Code
Private Sub SecurityTest2()
    ' Perform all checks in the Authenticate event
    Imap1.Security = secureNormal

    ' Set the SSL privacy to use - privacyImplicitAuto works in most cases
    Imap1.Privacy = privacyImplicitAuto

    ' Connect and login to a secure Imap server on the standard secure Imap port 993.
    Imap1.Login "myImapServer", "myAccount", "myPassword", 993
End Sub

Private Sub Imap1_Authenticate(ByVal RemoteCertificate As DartMailCtl.ICertificate, ByVal TrustedRoot As Boolean, ByVal ValidDate As Boolean, ByVal ValidSignature As Boolean, Valid As Boolean)
    ' The server's certificate has been received.
    Dim Msg As String

    ' Check to see if it passed all the checks.
    If Not Valid Then
        ' It didn't, so check everything and give the user the option to accept/reject.
        If Not ValidDate Then Msg = Msg + "- Certificate date is invalid" + vbCrLf
        If Not TrustedRoot Then Msg = Msg + "- Certificate Authority is not trusted" + vbCrLf
        If Not ValidSignature Then Msg = Msg + "- Certificate does not contain a valid signature" + vbCrLf

        Msg = "The following conditions are true:" + vbCrLf + vbCrLf + Msg + vbCrLf + vbCrLf
        Msg = Msg + "Do you still wish to authenticate?"
        If MsgBox(Msg, vbYesNo + vbExclamation, "Security Alert") = vbYes Then
            ' User still wants to accept so accept it (by setting Valid to true)
            Valid = True
        End If
    End If
End Sub

Using client authentication with the Imap control

Occasionally, a server may require a client authenticate itself to the server by sending a certificate. If this happens, the Certificate event will fire and the Certificate property must be set to a valid Certificate object. In environments that do not support events, the property can be set before logging in.

The following code demonstrates using a CertificateStore object to select a certificate, although the CertificateList control is useful for this purpose as well (and is demonstrated in most of the installed sample applications).

Note, in order for a client to authenticate themselves, the local machine must have an installed certificate. See the Certificate Manager topic for information on obtaining a certificate.

Example
Copy Code
Private Sub Imap1_Certificate()
    ' The server has requested a certificate from the client.
    Dim Store As New CertificateStore

    'Get the certificates in "MY" certificate store located in the
    'current user registry key.
    Store.Name = "MY"
    Store.Location = locationCurrentUser
    Store.Refresh

    ' Check to see if any certificates were found in this store.
    If Store.Certificates.Count > 0 Then
        ' Yep. Just use the first one.
        SecureTcp1.Certificate = Store.Certificates.Item(1)
    Else
        ' Uh oh. No client certificate. Authentication will fail.
    End If
End Sub

Using Explicit Security (STARTTLS)

In addition to establishing implicitly secure connections to servers on port 993 as demonstrated in the examples above, the control can make explicitly secure connections, if the server supports the STARTTLS command. With explicit security, the control first connects non-securely, then switches to a secure connection. This can be accomplished by setting the Privacy property to privacyExplicitTLS.

Example
Copy Code
Private Sub ExplicitLogin()
    ' Accept any certificate the server sends, valid or invalid.
    Imap1.Security = secureIgnoreCertificate

    ' Connect non-securely, then switch to TLS
    Imap1.Privacy = privacyExplicitTLS

    ' Connect and login to an Imap server on the standard port.
    Imap1.Login "myImapServer", "myAccount", "myPassword", 143
End Sub


%%Phrase%%

Dart Smtp, Pop, Imap Controls
Project Overview
Description
Dart Smtp, Pop, Imap Controls
Classes
Class Module | Description
DartStrings | Collection of strings. The DartStrings Object is used as a supporting formatting object for several PowerTCP objects and controls.
HeaderFields

Use the HeaderFields Object to manage message header fields. This collection is similar to the DartStrings collection, with additional methods for processing header fields.

Header fields may be added individually, or as a block to be automatically unwrapped and parsed through the Add method. This collection also provides an Item method to support access by position, symbolic field name, or matching string.

The Message object implements the To, Cc, and Bcc properties with the DartStrings object. Use those properties for recipient storage instead of the HeaderFields Object.

Imap

Use the IMAP Control to retrieve mail from or store mail to any IMAP server. Mailboxes on the server are exposed as a collection of Mailbox Objects. Each Mailbox Object contains messages that can be retrieved and stored in its Messages property.

Powerful default operations are provided, including iteration through a message set to populate the Messages property.

Mailbox | The Mailbox Object transforms an IMAP mailbox on a server into a local object that you can easily manipulate. Most properties manipulate the object model and the mailbox on the server.
Mailboxes | The Mailboxes Object represents a collection of Mailbox Objects returned from an IMAP server.
Message

The Message Object transforms any Internet mail message into an object that you can easily manipulate within your program. Alternatively, any message that you build or modify can be quickly encoded and sent.

Most of the properties manipulate the object model, with the exception of Content, which when set, dynamically creates a new object. When read, Content encodes the object model and returns it as a String or Byte array.

The Message Object provides complete support for MIME structures. High level methods (AddAttachment, Reply, Forward, AddMessage, AddText, and AddDigest) streamline the composition of sophisticated messages.

Additional features include persistence to disk in two formats: transport ready (encoded) message format and a quick loading (decoded) object format.

Messages | Collection of Message Objects.
Part | Use the Part Object to perform complex manipulation of message parts.
PartList | Collection of all Part Objects in the message. Parts are ordered numerically by the Part.Index property.
Parts | Parts Class
Pop

Use the POP Control to retrieve mail from any POP3 server. Retrieve and store sets of messages in the Messages property.

Powerful default operations are provided, including iteration through a message set to populate the Messages property.

Smtp | Use the SMTP Control to send mail to any SMTP server. This control supports popular protocol extensions (ESMTP), provides both Blocking and high performance event-based non-blocking operation, and can be statically placed on a form or dynamically created in virtually any development environment.
Public Enumerations
Enumeration | Description
AttributeConstants | Enumerates the values of the Index parameter of the Attribute property.
CodingConstants | Enumerates encoding/decoding algorithms.
DsnConstants | Enumerates values of the Notify parameter of the DSN method.
FormatConstants | Enumerates the values of the Format parameter of the Store method.
GetConstants | Enumerates values of the Part parameter of the Get method.
ImapMethodConstants | Enumerates values of the Method parameter of the Progress event.
ImapStatusConstants | Enumerates values of the Status parameter of the Progress Event.
LabelConstants | Some HeaderFields Object methods use a symbolic name for the Label parameter. The following labels are specified as the Common Internet Message Headers (these headers are explained in RFC 2076):
MailErrorConstants | Enumerates Mail-Specific Errors
MailPrivacyConstants | Enumerates values of the Privacy property.
PartConstants | Enumerates the values of the Part parameter of the Get method.
PopMethodConstants | Enumerates the values of the Method parameter of the Progress event.
PopStatusConstants | Enumerates the values of the Status parameter of the Progress event.
PutConstants | Enumerates values of the Part parameter of Put method.
ReturnTypeConstants | Enumerates the type of buffer to be returned from a property that returns either a String and Byte array.
SecurityConstants | Security Constants
SegmentConstants | Enumerates the message segments.
SmtpMethodConstants | Enumerates values of the Method parameter of the Progress event. Indicates the method that initiated the event.
SmtpStatusConstants | Enumerates values of the Status parameter of the Progress event. Provides success / failure / progress information.
StateConstants | Enumerates values of the State property.
VerifyMethodConstants | Enumerates the return value of the Verify method.


%%PageItemTitle%%

DartStrings Collection
Members
Description
Collection of strings. The DartStrings Object is used as a supporting formatting object for several PowerTCP objects and controls.
See Also

DartStrings Members


%%PageItemTitle%% $$Members$$

DartStrings Collection Members
Overview
Public Methods
Public Method Add | Add a string to the collection
Public Method Clear | Removes all strings in the collection
Public Method Find | Return a string from the collection where the beginning substring matches the specified string. The string comparison is case-insensitive, starting with the leftmost character.
Public Method Remove | Remove and return a String from the collection
Public Properties
Public Property All | Concatenates and returns all the strings in the collection. Delimiter is inserted between each string in the collection.
Public Property Count | The number of Strings in the collection
Public Property Delimiter | Separates a string into substrings when adding a string to the collection with the Add method. Also used as a separator when reading the All property. Defaults to NULL.
Public Property Item | Returns or sets a string in the collection.
See Also

DartStrings Collection


%%PageItemTitle%%

Add Method
DartStrings Collection : Add Method
What is added to the collection.
Optional. Defaults to the end of the collection. Specifies where in the collection the string should be inserted. If multiple substrings are added, then they will start at this index. Should be at least 1 and no greater than 1 more than the Count property.
Description
Add a string to the collection
Syntax
Visual Basic
Public Sub Add( _
   ByVal Item As String, _
   Optional ByVal Index As Long = 0 _
)
Parameters
Item
What is added to the collection.
Index
Optional. Defaults to the end of the collection. Specifies where in the collection the string should be inserted. If multiple substrings are added, then they will start at this index. Should be at least 1 and no greater than 1 more than the Count property.
Remarks

Item is parsed for the Delimiter, and is segmented into substrings if found. All substrings are added as individual strings to the collection.

For example, if the Delimiter is ":" and Item is "ab:cd:ef", then "ab", "cd", and "ef" are added.

The Add method takes linear (O(n)) time, where n is the number of delimited strings being added.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • mailInvalidParam2 (Index is greater than Count + 1.) Note: Index of 0 will add to the end of the collection, as if no Index was specified.
See Also

DartStrings Collection | DartStrings Members


%%PageItemTitle%%

Clear Method
DartStrings Collection : Clear Method
Description
Removes all strings in the collection
Syntax
Visual Basic
Public Sub Clear()
Remarks
The Add method takes linear (O(n)) time, where n is the number of delimited strings being added.
See Also

DartStrings Collection | DartStrings Members


%%PageItemTitle%%

Find Method
DartStrings Collection : Find Method
The substring to match. Matching starts with the first character.
Optional. Defaults to 0. On input, it contains the index in the collection after which to start the search. On return, it is updated to the index of the string returned by Find. If no string is found, StartAfter is set to 0.
Description
Return a string from the collection where the beginning substring matches the specified string. The string comparison is case-insensitive, starting with the leftmost character.
Syntax
Visual Basic
Public Function Find( _
   ByVal SubString As String, _
   Optional ByRef StartAfter As Variant _
) As String
Parameters
SubString
The substring to match. Matching starts with the first character.
StartAfter
Optional. Defaults to 0. On input, it contains the index in the collection after which to start the search. On return, it is updated to the index of the string returned by Find. If no string is found, StartAfter is set to 0.
Remarks

When specifying StartAfter, use an index between 0 and one less than the collection's Count property. Specifying a value of 0 (the default) starts with the first string in the collection.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • mailInvalidParam2 (StartAfter is not between 0 and Count - 1)
See Also

DartStrings Collection | DartStrings Members


%%PageItemTitle%%

Remove Method
DartStrings Collection : Remove Method
String or Long. Specifies a substring to search for or an index into the collection.
Description
Remove and return a String from the collection
Syntax
Visual Basic
Public Function Remove( _
   ByRef Index As Variant _
) As String
Parameters
Index
String or Long. Specifies a substring to search for or an index into the collection.
Return Value
Returns a copy of the string removed.
Remarks

When Index is a Long, it must be between one and Count. When Index is a string, the first string in the collection matching all the characters of the specified substring is returned (both strings are compared starting with the left-most character and is case insensitive).

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • mailInvalidParam1 (Index is not a Long or String)
See Also

DartStrings Collection | DartStrings Members


%%PageItemTitle%%

All Property
DartStrings Collection : All Property
Description
Concatenates and returns all the strings in the collection. Delimiter is inserted between each string in the collection.
Property type
Read-only property
Syntax
Visual Basic
Public Property All As String
Remarks

Read-only. For example, if the Delimiter is ":" and the strings in the collection are "ab", "cd", and "ef", then this property returns "ab:cd:ef".

The All property takes linear (O(n)) time for strings of less than 50kB, and O(n*size/50kB) for longer strings, where n is the number of independent strings and size is the size of the resultant string in kB.

See Also

DartStrings Collection | DartStrings Members


%%PageItemTitle%%

Count Property
DartStrings Collection : Count Property
Description
The number of Strings in the collection
Property type
Read-only property
Syntax
Visual Basic
Public Property Count As Long
See Also

DartStrings Collection | DartStrings Members


%%PageItemTitle%%

Delimiter Property
DartStrings Collection : Delimiter Property
Description
Separates a string into substrings when adding a string to the collection with the Add method. Also used as a separator when reading the All property. Defaults to NULL.
Property type
Read-write property
Syntax
Visual Basic
Public Property Delimiter As String
Remarks

This property takes constant time to get or set.

See Also

DartStrings Collection | DartStrings Members


%%PageItemTitle%%

Item Property
DartStrings Collection : Item Property
String or Long. Specifies a substring to search for or an index into the collection.
Description
Returns or sets a string in the collection.
Property type
Read-write property
Syntax
Visual Basic
Public Property Item( _
   ByRef Index As Variant _
) As String
Parameters
Index
String or Long. Specifies a substring to search for or an index into the collection.
Return Value
The string found in the collection or an empty string if none is found.
Remarks

When Index is a Long, its value must be between one and the collection's Count property. When specifying Index as a String, the first string in the collection matching all the characters of the substring is returned (strings are compared starting with the leftmost character, and are case-insensitive).

This is a parameterized property instead of a (read-only) method so that it can be used to set a value.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • mailInvalidParam1 (When reading the property, Index is not a Long or String. When setting the property, Index is not a Long between 1 and Count or the sub-string is not found.)
See Also

DartStrings Collection | DartStrings Members


%%PageItemTitle%%

HeaderFields Collection
Members
Description

Use the HeaderFields Object to manage message header fields. This collection is similar to the DartStrings collection, with additional methods for processing header fields.

Header fields may be added individually, or as a block to be automatically unwrapped and parsed through the Add method. This collection also provides an Item method to support access by position, symbolic field name, or matching string.

The Message object implements the To, Cc, and Bcc properties with the DartStrings object. Use those properties for recipient storage instead of the HeaderFields Object.

Example
This example displays all the "Received" headers from a message, then the Subject.
  • Example (VB6)
Private Sub Command1_Click()
    Dim Hdr As New HeaderFields, Begin As Long
    Hdr.Add msgFrom, "developer@dart.com"
    Hdr.Add msgReceived, "from x@y by a@b with z id abc"
    Hdr.Add msgReceived, "from xx@dart.com by a22 with grasp id 33a1"
    Hdr.Add msgReceived, "from frd@dart.com by kahuna with z id k32"
    Hdr.Add msgFrom, "sales@dart.com"
    Hdr.Add msgSubject, "time marches on"
    Begin = 0 ' start search at beginning
    While Hdr.Find(msgReceived, , Begin) <> "" ' find index of next "Received"
        MsgBox "Found: " & Hdr(Begin) ' use positional lookup
    Wend
    MsgBox (Hdr.Find(msgSubject)) ' show the message Subject line
End Sub
See Also

HeaderFields Members


%%PageItemTitle%% $$Members$$

HeaderFields Collection Members
Overview
Public Methods
Public Method Add | Add one or more header fields to the collection. If multiple header fields are provided they must be separated by CR/LF pairs.
Public Method Clear | Remove all header fields from the collection.
Public Method Find | Find a header field in the collection.
Public Method Item | Access to the collection by index.
Public Method Remove | Remove a header field from the collection.
Public Properties
Public Property All | The concatenation of all strings in the collection separted by a CR/LF pair.
Public Property Charset | Gets and sets the preferred character set label that is used to for converting non-ASCII characters contained in header field strings to/from a byte encoded representation.
Public Property Count | Number of objects in the collection.
See Also

HeaderFields Collection


%%PageItemTitle%%

Add Method
HeaderFields Collection : Add Method
Specifies the symbolic name for the header label being added. Use msgNull if Value includes the label.
Value to add to the collection.
Optional. Specifies whether the header field should replace any existing header fields with the same label. Defaults to False.
Description
Add one or more header fields to the collection. If multiple header fields are provided they must be separated by CR/LF pairs.
Syntax
Visual Basic
Public Function Add( _
   ByVal Label As LabelConstants, _
   ByVal Value As String, _
   Optional ByVal Unique As Boolean = False _
) As Long
Parameters
Label
Value | Description
msgAlsoControl | "Also-Control:"
msgAlternateRecipient | "Alternate-Recipient:"
msgApparentlyTo | "Apparently-To:"
msgApproved | "Approved:"
msgArticleNames | "Article-Names:"
msgArticleUpdates | "Article-Updates:"
msgAutoForwarded | "Auto-Forwarded:"
msgComments | "Comments:"
msgContentBase | "Content-Base:"
msgContentConversion | "Content-Conversion:"
msgContentDescription | "Content-Description:"
msgContentDisposition | "Content-Disposition:"
msgContentID | "Content-ID:"
msgContentIdentifier | "Content-Identifier:"
msgContentLanguage | "Content-Language:"
msgContentLength | "Content-Length:"
msgContentLocation | "Content-Location:"
msgContentMD5 | "Content-MD5:"
msgContentReturn | "Content-Return:"
msgContentSGMLEntity | "Content-SGML-Entity:"
msgContentTransferEncoding | "Content-Transfer-Encoding:"
msgContentType | "Content-Type:"
msgControl | "Control:"
msgConversion | "Conversion:"
msgConversionWithLoss | "Conversion-With-Loss:"
msgDate | "Date:"
msgDeliveryDate | "Delivery-Date:"
msgDeliveryReport | "Delivery-Report:"
msgDiscardedX400IPMSExtensions | "Discarded-X400-IPMS-Extensions:"
msgDiscardedX400MTSExtensions | "Discarded-X400-MTS-Extensions:"
msgDiscloseRecipients | "Disclose-Recipients:"
msgDistribution | "Distribution:"
msgDLExpansionHistoryIndication | "DL-Expansion-History-Indication:"
msgEncoding | "Encoding:"
msgErrorsTo | "Errors-To:"
msgExpires | "Expires:"
msgFax | "Fax:"
msgFcc | "Fcc:"
msgFollowupTo | "Followup-To:"
msgForComment | "For-Comment:"
msgForHandling | "For-Handling:"
msgFrom | "From:"
msgGenerateDeliveryReport | "Generate-Delivery-Report:"
msgImportance | "Importance:"
msgIncompleteCopy | "In-Reply-To:"
msgInReplyTo | "Incomplete-Copy:"
msgKeywords | "Keywords:"
msgLanguage | "Language:"
msgLines | "Lines:"
msgMailer | "Mailer:"
msgMailSystemVersion | "Mail-System-Version:"
msgMessageID | "Message-ID"
msgMessageType | "Message-Type:"
msgMIMEVersion | "MIME-Version:"
msgNewsgroups | "Newsgroups:"
msgNull | N/A
msgObsoletes | "Obsoletes:"
msgOrganisation | "Organisation:"
msgOrganization | "Organization:"
msgOriginalEncodedInformationTypes | "Original-Encoded-Information-Types:"
msgOriginatingClient | "Originating-Client:"
msgPath | "Path:"
msgPhone | "Phone:"
msgPrecedence | "Precedence:"
msgPreventNonDeliveryReport | "Prevent-NonDelivery-Report:"
msgPriority | "Priority:"
msgReceived | "Received:"
msgReferences | "References:"
msgReplyBy | "Reply-By:"
msgReplyTo | "Reply-To:"
msgReturnPath | "Return-Path:"
msgReturnReceiptTo | "Return-Receipt-To:"
msgSeeAlso | "See-Also:"
msgSender | "Sender:"
msgSensitivity | "Sensitivity:"
msgStatus | "Status:"
msgSubject | "Subject:"
msgSummary | "Summary:"
msgSupersedes | "Supersedes:"
msgTelefax | "Telefax:"
msgX400ContentReturn | "X400-Content-Return:"
msgXMailer | "X-Mailer:"
msgXNewsreader | "X-Newsreader:"
msgXref | "Xref:"
Specifies the symbolic name for the header label being added. Use msgNull if Value includes the label.
Value
Value to add to the collection.
Unique
Optional. Specifies whether the header field should replace any existing header fields with the same label. Defaults to False.
Return Value
Number of strings added to the collection.
Remarks

A header field is a label, followed by a colon, followed by a space, followed by one or more values separated by semicolons.

This method allows you to add header fields in the following two ways:

  • If Label is not msgNull, then Value will be prepended with the string representation of the specified Label and a space before adding it to the collection.
  • If Label is msgNull, then Value must contain a complete header field, including the label.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • mailInvalidParam1
  • mailNoMemory
See Also

HeaderFields Collection | HeaderFields Members


%%PageItemTitle%%

Clear Method
HeaderFields Collection : Clear Method
Description
Remove all header fields from the collection.
Syntax
Visual Basic
Public Sub Clear()
Remarks
This method takes linear (O(n)) time, where n is the number of items stored.
See Also

HeaderFields Collection | HeaderFields Members


%%PageItemTitle%%

Find Method
HeaderFields Collection : Find Method
Specifies the symbolic name for the label to find. If msgNull, the LabelString parameter will be used as the search string.
Optional. Specifies the label to find. Use this parameter to find a non-standard label (not available in LabelConstants). When using this parameter, Label should be msgNull.
Optional. Indicates the index to start the search after. StartAfter is updated to reflect the index of the header field found.
Description
Find a header field in the collection.
Syntax
Visual Basic
Public Function Find( _
   ByVal Label As LabelConstants, _
   Optional ByVal LabelString As String, _
   Optional ByRef StartAfter As Long = 0 _
) As String
Parameters
Label
Value | Description
msgAlsoControl | "Also-Control:"
msgAlternateRecipient | "Alternate-Recipient:"
msgApparentlyTo | "Apparently-To:"
msgApproved | "Approved:"
msgArticleNames | "Article-Names:"
msgArticleUpdates | "Article-Updates:"
msgAutoForwarded | "Auto-Forwarded:"
msgComments | "Comments:"
msgContentBase | "Content-Base:"
msgContentConversion | "Content-Conversion:"
msgContentDescription | "Content-Description:"
msgContentDisposition | "Content-Disposition:"
msgContentID | "Content-ID:"
msgContentIdentifier | "Content-Identifier:"
msgContentLanguage | "Content-Language:"
msgContentLength | "Content-Length:"
msgContentLocation | "Content-Location:"
msgContentMD5 | "Content-MD5:"
msgContentReturn | "Content-Return:"
msgContentSGMLEntity | "Content-SGML-Entity:"
msgContentTransferEncoding | "Content-Transfer-Encoding:"
msgContentType | "Content-Type:"
msgControl | "Control:"
msgConversion | "Conversion:"
msgConversionWithLoss | "Conversion-With-Loss:"
msgDate | "Date:"
msgDeliveryDate | "Delivery-Date:"
msgDeliveryReport | "Delivery-Report:"
msgDiscardedX400IPMSExtensions | "Discarded-X400-IPMS-Extensions:"
msgDiscardedX400MTSExtensions | "Discarded-X400-MTS-Extensions:"
msgDiscloseRecipients | "Disclose-Recipients:"
msgDistribution | "Distribution:"
msgDLExpansionHistoryIndication | "DL-Expansion-History-Indication:"
msgEncoding | "Encoding:"
msgErrorsTo | "Errors-To:"
msgExpires | "Expires:"
msgFax | "Fax:"
msgFcc | "Fcc:"
msgFollowupTo | "Followup-To:"
msgForComment | "For-Comment:"
msgForHandling | "For-Handling:"
msgFrom | "From:"
msgGenerateDeliveryReport | "Generate-Delivery-Report:"
msgImportance | "Importance:"
msgIncompleteCopy | "In-Reply-To:"
msgInReplyTo | "Incomplete-Copy:"
msgKeywords | "Keywords:"
msgLanguage | "Language:"
msgLines | "Lines:"
msgMailer | "Mailer:"
msgMailSystemVersion | "Mail-System-Version:"
msgMessageID | "Message-ID"
msgMessageType | "Message-Type:"
msgMIMEVersion | "MIME-Version:"
msgNewsgroups | "Newsgroups:"
msgNull | N/A
msgObsoletes | "Obsoletes:"
msgOrganisation | "Organisation:"
msgOrganization | "Organization:"
msgOriginalEncodedInformationTypes | "Original-Encoded-Information-Types:"
msgOriginatingClient | "Originating-Client:"
msgPath | "Path:"
msgPhone | "Phone:"
msgPrecedence | "Precedence:"
msgPreventNonDeliveryReport | "Prevent-NonDelivery-Report:"
msgPriority | "Priority:"
msgReceived | "Received:"
msgReferences | "References:"
msgReplyBy | "Reply-By:"
msgReplyTo | "Reply-To:"
msgReturnPath | "Return-Path:"
msgReturnReceiptTo | "Return-Receipt-To:"
msgSeeAlso | "See-Also:"
msgSender | "Sender:"
msgSensitivity | "Sensitivity:"
msgStatus | "Status:"
msgSubject | "Subject:"
msgSummary | "Summary:"
msgSupersedes | "Supersedes:"
msgTelefax | "Telefax:"
msgX400ContentReturn | "X400-Content-Return:"
msgXMailer | "X-Mailer:"
msgXNewsreader | "X-Newsreader:"
msgXref | "Xref:"
Specifies the symbolic name for the label to find. If msgNull, the LabelString parameter will be used as the search string.
LabelString
Optional. Specifies the label to find. Use this parameter to find a non-standard label (not available in LabelConstants). When using this parameter, Label should be msgNull.
StartAfter
Optional. Indicates the index to start the search after. StartAfter is updated to reflect the index of the header field found.
Return Value
The requested header field.
Remarks

This method searches the collection for a label. On return, StartAfter is updated to reflect the index of the label found; this allows you to find multiple header fields that have the same label.

StartAfter cannot be a constant because the method updates its value. Providing a constant value for StartAfter generates a run-time error. Specifying StartAfter with a value of zero starts the search at the head of the collection. StartAfter is set to 0 and "" is returned if the item is not found.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptInvalidParam1
  • ptInvalidParam3
  • ptNoBufferSpace
Example

HeaderFields Collection

See Also

HeaderFields Collection | HeaderFields Members


%%PageItemTitle%%

Item Method
HeaderFields Collection : Item Method
Specifies a header field by position in the collection.
Description
Access to the collection by index.
Syntax
Visual Basic
Public Function Item( _
   ByVal Index As Long _
) As String
Parameters
Index
Specifies a header field by position in the collection.
Return Value
The requested header field.
Remarks

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptInvalidParam1
  • ptNoBufferSpace
Example
  • Example (VB6)
Private Sub Command1_Click()
    Dim Msg As New Message, S As String
    Msg.Load "C:\NewTest.msg"
    S = Msg.Header.Item(1) ' explicit use of Item method
    S = Msg.Header(1) ' implicit use of Item method
    Text1.Text = S
End Sub
See Also

HeaderFields Collection | HeaderFields Members


%%PageItemTitle%%

Remove Method
HeaderFields Collection : Remove Method
LabelConstants specifies the symbolic name for the header field to be removed. If msgNull, the Index parameter will be used to specify the header field to be removed.
Optional. Identifies a header field by position in the collection. When using this parameter Label must be set to msgNull.
Description
Remove a header field from the collection.
Syntax
Visual Basic
Public Function Remove( _
   ByVal Label As LabelConstants, _
   Optional ByVal Index As Long = 0 _
) As String
Parameters
Label
Value | Description
msgAlsoControl | "Also-Control:"
msgAlternateRecipient | "Alternate-Recipient:"
msgApparentlyTo | "Apparently-To:"
msgApproved | "Approved:"
msgArticleNames | "Article-Names:"
msgArticleUpdates | "Article-Updates:"
msgAutoForwarded | "Auto-Forwarded:"
msgComments | "Comments:"
msgContentBase | "Content-Base:"
msgContentConversion | "Content-Conversion:"
msgContentDescription | "Content-Description:"
msgContentDisposition | "Content-Disposition:"
msgContentID | "Content-ID:"
msgContentIdentifier | "Content-Identifier:"
msgContentLanguage | "Content-Language:"
msgContentLength | "Content-Length:"
msgContentLocation | "Content-Location:"
msgContentMD5 | "Content-MD5:"
msgContentReturn | "Content-Return:"
msgContentSGMLEntity | "Content-SGML-Entity:"
msgContentTransferEncoding | "Content-Transfer-Encoding:"
msgContentType | "Content-Type:"
msgControl | "Control:"
msgConversion | "Conversion:"
msgConversionWithLoss | "Conversion-With-Loss:"
msgDate | "Date:"
msgDeliveryDate | "Delivery-Date:"
msgDeliveryReport | "Delivery-Report:"
msgDiscardedX400IPMSExtensions | "Discarded-X400-IPMS-Extensions:"
msgDiscardedX400MTSExtensions | "Discarded-X400-MTS-Extensions:"
msgDiscloseRecipients | "Disclose-Recipients:"
msgDistribution | "Distribution:"
msgDLExpansionHistoryIndication | "DL-Expansion-History-Indication:"
msgEncoding | "Encoding:"
msgErrorsTo | "Errors-To:"
msgExpires | "Expires:"
msgFax | "Fax:"
msgFcc | "Fcc:"
msgFollowupTo | "Followup-To:"
msgForComment | "For-Comment:"
msgForHandling | "For-Handling:"
msgFrom | "From:"
msgGenerateDeliveryReport | "Generate-Delivery-Report:"
msgImportance | "Importance:"
msgIncompleteCopy | "In-Reply-To:"
msgInReplyTo | "Incomplete-Copy:"
msgKeywords | "Keywords:"
msgLanguage | "Language:"
msgLines | "Lines:"
msgMailer | "Mailer:"
msgMailSystemVersion | "Mail-System-Version:"
msgMessageID | "Message-ID"
msgMessageType | "Message-Type:"
msgMIMEVersion | "MIME-Version:"
msgNewsgroups | "Newsgroups:"
msgNull | N/A
msgObsoletes | "Obsoletes:"
msgOrganisation | "Organisation:"
msgOrganization | "Organization:"
msgOriginalEncodedInformationTypes | "Original-Encoded-Information-Types:"
msgOriginatingClient | "Originating-Client:"
msgPath | "Path:"
msgPhone | "Phone:"
msgPrecedence | "Precedence:"
msgPreventNonDeliveryReport | "Prevent-NonDelivery-Report:"
msgPriority | "Priority:"
msgReceived | "Received:"
msgReferences | "References:"
msgReplyBy | "Reply-By:"
msgReplyTo | "Reply-To:"
msgReturnPath | "Return-Path:"
msgReturnReceiptTo | "Return-Receipt-To:"
msgSeeAlso | "See-Also:"
msgSender | "Sender:"
msgSensitivity | "Sensitivity:"
msgStatus | "Status:"
msgSubject | "Subject:"
msgSummary | "Summary:"
msgSupersedes | "Supersedes:"
msgTelefax | "Telefax:"
msgX400ContentReturn | "X400-Content-Return:"
msgXMailer | "X-Mailer:"
msgXNewsreader | "X-Newsreader:"
msgXref | "Xref:"
LabelConstants specifies the symbolic name for the header field to be removed. If msgNull, the Index parameter will be used to specify the header field to be removed.
Index
Optional. Identifies a header field by position in the collection. When using this parameter Label must be set to msgNull.
Return Value
The removed header field.
Remarks
This method removes the first header field matching Label or the header field at Index in the collection.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptInvalidParam1
  • ptInvalidParam2
  • ptNoBufferSpace
Example
  • Example (VB6)
Private Sub Command1_Click()
    Dim Msg As New Message
    Msg.Load "C:\Temp\Test.msg"
    ' view the headers
    Text1.Text = Msg.Header.All
    ' remove the Content-Type header field
    ' and then view the headers less the Content-Type header
    Msg.Header.Remove msgContentType
    Text2.Text = Msg.Header.All
    ' remove the first header field in the collection
    ' and then view the headers less the Content-Type and first header
    Msg.Header.Remove msgNull, 1
    Text3.Text = Msg.Header.All
End Sub
See Also

HeaderFields Collection | HeaderFields Members


%%PageItemTitle%%

All Property
HeaderFields Collection : All Property
Description
The concatenation of all strings in the collection separted by a CR/LF pair.
Property type
Read-only property
Syntax
Visual Basic
Public Property All As String
Remarks
Use this property to return the header fields as a single string. This property does not return a string that is "transport-ready." The Content property of a Message Object returns an encoded header that can be safely sent.
See Also

HeaderFields Collection | HeaderFields Members


%%PageItemTitle%%

Charset Property
HeaderFields Collection : Charset Property
Description
Gets and sets the preferred character set label that is used to for converting non-ASCII characters contained in header field strings to/from a byte encoded representation.
Property type
Read-write property
Syntax
Visual Basic
Public Property Charset As String
Remarks

When communicating with international mail clients, you may need to be aware of Unicode character encoding/decoding issues. At the highest level, character encoding/decoding can be viewed as taking a visual string representation displayable in a UI, translating that visual string representation into a multi-byte values for transmission between systems, then retranslating the multi-byte values back into the original visual string (Unicode) representation. For this operation to occur successfully, the correct preferred character set must be specified so that the correct codepage is used.

Header fields, by RFC specification, are required to use the ASCII character set. Such an approach creates a challenge when working with multi-national character sets which require going beyond the 0-127 character limit. To accommodate these non-ASCII requirements, a system of encoding and decoding that converts non-ASCII characters into a string of ASCII characters was created. This technique uses a character set designation that maps to a codepage. A codepage is a mapping between a Unicode character and a multi-byte sequence. This mapping is unique for different codepages.

When creating a message (encoding), this property will default to the current system codepage and its preferred character set label. Set this property to override this behavior and specify a different preferred character set. For example, if your operating system is using CodePage 1252, which is Western European (ISO) and the preferred character set defaults to "iso-8859-1", but you wish to use the Japanese preferred character set of iso-2022-jp that maps to CodePage 932, you would set this property to "iso-2022-jp".

When reading a message (decoding), if the header contains non-ASCII data, but is properly encoded into an ASCII representation using the RFC 2047 specification of charset/encoding/content then the preferred character set is read from the header data. If the header erroneously contains non-encoded non-ASCII characters, a conversion from multi-byte to Unicode strings must still be made so the Message object will first look to see if the Charset property has been set. If no character set information is found, then the Content-Type header is checked for a character set label. If a character set label is not found, the message will be scanned for other encoded words (words that follow the encoding rule specified below) that contain character set information. If character set information is still not found, the system default value will be used. Please note that raw non-ASCII data in a header field is not allowed by RFC standards, and this is only done to add compatibility to non-compliant mail clients.

In order to properly decode the encoded data back to its original form, you must know the character set that was used to encode the data. If a header field has been encoded, the content of the header will use a special syntax which looks like the following:

     =?[charset]?[encoding]?[header content]?=

The =? and ?= delimiters at the beginning and end of the header indicate that this header was encoded. The value of [charset] indicates the preferred character set (which maps to an ANSI code page, defining the multi-byte representation for a given character) to use to correctly interpret this header (an example preferred character set for Japanese CodePage 932 is: "iso-2022-jp"). The value of [encoding] indicates the encoding type to use ("B" for Base64, "Q" for Quoted-Printable) which performs 7-bit encoding on data that could be 8-bit. The value of [header content] contains the encoded content. An example of a Base64 encoded iso-2022-jp header line is below.

     Subject: =?iso-2022-jp?B?UmU6IA0KUmVsZWFzZSBkYXRlIHV0ayB2ZXIgMi4wID8=?=

When reading messages this property will contain the character set string used to encode the headers (if one was used).

This property applies to header fields only. To get/set the character set used to encode message body or body parts, see Message.Charset or Part.Charset. For more information on message encoding see Message Encoding.

See Also

HeaderFields Collection | HeaderFields Members


%%PageItemTitle%%

Count Property
HeaderFields Collection : Count Property
Description
Number of objects in the collection.
Property type
Read-only property
Syntax
Visual Basic
Public Property Count As Long
See Also

HeaderFields Collection | HeaderFields Members


%%PageItemTitle%%

Imap Object
Members
Description

Use the IMAP Control to retrieve mail from or store mail to any IMAP server. Mailboxes on the server are exposed as a collection of Mailbox Objects. Each Mailbox Object contains messages that can be retrieved and stored in its Messages property.

Powerful default operations are provided, including iteration through a message set to populate the Messages property.

Object Model
Imap ObjectDartStrings CollectionICertificate ObjectMailboxes Collection
Remarks

The IMAP Control can:

  • Operate transparently in the background while the user of your application is doing other tasks.
  • Function interactively with the user.

Simple methods are provided to perform the following tasks:

  • Authentication. Login method connects to a server and authenticates in one easy step.
  • Mailbox creation, deletion, and enumeration are accomplished with the Add, Remove, and Refresh methods.
  • Get Mail. Get method retrieves all or part of a message set.
  • Delete Mail. Delete and Purge methods delete messages from mailboxes.
  • Session termination. Logout method gracefully terminates a session.
  • Other Functions. Supports all the functionality of RFC 2060 while maximizing ease-of-use and flexibility.

Example
  • Example (VB6)
Private Sub Command1_Click()
    On Error GoTo OnError ' use intrinsic error handling
    ' default timeout implies blocking operation
    Imap1.Login "imap.server.com", "user", "pass"
    ' Get all mailboxes
    Imap1.Refresh
    ' Imap1.Mailboxes("INBOX").Count now contains the number of messages in the INBOX
    ' Get messages and put them into the Imap1.Mailboxes("INBOX").Messages
    ' collection
    Imap1.Mailboxes("INBOX").Get
    Imap1.Mailboxes("INBOX").Refresh
    Text1.Text = Imap1.Mailboxes("INBOX").Count
    Exit Sub
OnError: ' Any error jumps here
    Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub
You want your mail transfer to operate in the background with minimal system impact. We recommend you program the mail transfer using non-blocking operation, so the user interface is not affected in any way. The following VB example shows how to retrieve a message when the user clicks a button:
  • Transparent Use (VB6)
Private Sub Command1_Click()
    ' use non-blocking operation
    Imap1.Timeout = 0
    ' login to our server
    Imap1.Login "imap.test.com", "user", "pass"
    ' pick this operation up in the Progress event
End Sub

Private Sub Imap1_Progress(ByVal Method As DartMailCtl.ImapMethodConstants, ByVal Status As DartMailCtl.ImapStatusConstants, ByVal Reply As String, ByVal MessageNumber As Long, ByVal Count As Long, ByVal Size As Long)
    If Status = imapOk Then
        Select Case Method
        Case imapLogin
            ' logged in, get mailboxes
            Imap1.Refresh
        Case imapMailboxesRefresh
            ' mailbox listing complete, get INBOX messages
            Imap1.Mailboxes("INBOX").Get
        Case imapGet
            ' mail retrieve is complete for INBOX, log out
            Imap1.Logout
        Case imapLogout
            ' operation complete
        End Select
    End If
End Sub
For interactive applications, transparency is not as important and blocking operation may be acceptable as shown in the following VB example:
  • Interactive Use (VB6)
Private Sub Command1_Click()
    On Error Goto OnError ' use intrinsic error handling
    ' Use the Timeout property to establish blocking operation
    Imap1.Timeout = 1000
    ' Specify the address of the server to connect to
    Imap1.Login "imap.test.com", "user", "pass"
    'Get Mailbox listing
    Imap1.Refresh
    ' get all the messages from INBOX and put them in the messages property
    Imap1.Mailboxes("INBOX").Get
    ' all done, close connection!!
    Imap1.Logout
    Exit Sub
OnError: ' Any error jumps here
    Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub
See Also

Imap Members


%%PageItemTitle%% $$Members$$

Imap Object Members
Overview
Public Methods
Public Method Abort | Release all buffers, close the connection, and abort any blocking method.
Public Method About | Displays control information in a dialog box.
Public Method ClearCertificate | Clears the Certificate Property
Public Method Command | Send any command string.
Public Method Login | Connect to a server and authenticate in one step.
Public Method Logout | Gracefully end a session.
Public Method Refresh | Get a listing of mailboxes.
Public Method Trace

Start or stop the accumulation of trace or debug data. Once started, this method accumulates data until it is turned off.

This method provides a convenient mechanism for viewing all data being sent and received over the connection and can be used to troubleshoot host interoperability issues and expose protocol communications.

Public Properties
Public Property AttachmentDirectory | Decoded message attachments are created in this directory.
Public Property AttachmentOverwrite | Specifies whether decoded message attachments are overwritten if the filename is the same.
Public Property AutoClose | Specifies whether to close a Mailbox when done with it.
Public Property Blocked | A True value indicates the control is currently executing a blocking method (Timeout is greater than 0), which has neither completed nor timed out with a ptTimeout error.
Public Property Capabilities | Collection of strings that contains the protocol extensions advertised as supported by the server. Values are initialized during login.
Public Property Certificate | Certificate Object to use when authenticating to the remote host.
Public Property EnableNonAscii | Enables the usage of Non-ASCII characters in the Username
Public Property Idle | Controls whether the Imap control is in IDLE mode.
Public Property IpV6 | Specifies whether hostname addresses should be favorably resolved to IPv6.
Public Property Mailboxes | Collection of Mailbox obejcts.
Public Property Privacy | Specifies the security protocol (PCT, SSL2, SSL3, TLS, none) and type (Implicit, Explicit) used.
Public Property Security | Sets the security level during communication.
Public Property State | Provides status information. The State event fires to signal that this property has changed.
Public Property Timeout | Controls the blocking behavior of methods that can be used in blocking and non-blocking ways.
Events
Public Event Alert | Fires when the server sends an alert message.
Public Event Authenticate | Fires when the remote host has sent a certificate to be authenticated.
Public Event Certificate | Fires when the remote host is requesting a certificate and the Certificate property is not set to a valid Certificate Object.
Public Event Error | Fires when an error occurs.
Public Event Progress | Fires when a method has completed, the server has sent a reply, or progress information is available.
Public Event State | Fires when the State property changes.
See Also

Imap Object


%%PageItemTitle%%

Abort Method
Imap Object : Abort Method
Description
Release all buffers, close the connection, and abort any blocking method.
Syntax
Visual Basic
Public Sub Abort()
Remarks

Use this method at any time to abruptly release all resources. The State property is tcpClosed when this method returns.

Destruction of the control automatically uses this method to release all resources.

When a blocking call is in progress (like Get), and Abort is called with an immediate call to a second Get (or other method), the first Get method does not return until the subsequent Get method(s) complete. It will return a mailAbort error.

Calling Abort will raise a mailAbort Error event.

Note For TCP-based controls, the Abort method performs a "hard close", with a socket LINGER option time of 0. To prevent the socket from entering a WAIT_STATE, and to immediately release it for reuse, use Abort instead of Close.

CAUTION Use the Logout method in most cases, as buffers are cleared and communications terminate gracefully. Use the Abort method only when the application in abruptly terminated while a blocking method is executing or under any other unusual circumstances.

See Also

Imap Object | Imap Members


%%PageItemTitle%%

About Method
Imap Object : About Method
Description
Displays control information in a dialog box.
Syntax
Visual Basic
Public Sub About()
See Also

Imap Object | Imap Members


%%PageItemTitle%%

ClearCertificate Method
Imap Object : ClearCertificate Method
Description
Clears the Certificate Property
Syntax
Visual Basic
Public Sub ClearCertificate()
Remarks
Use this to clear the currently set certificate and set it to nothing. This method is only necessary on some environments, otherwise the Certificate property may be used.
See Also

Imap Object | Imap Members


%%PageItemTitle%%

Command Method
Imap Object : Command Method
Specifies the command to send.
Undimensioned String or Byte Array. Where the reply from the server will be put. Any contents will be replaced. A message would not be returned for this parameter when the Progress event fires, as that information would be available elsewhere.
Description
Send any command string.
Syntax
Visual Basic
Public Sub Command( _
   ByVal Command As String, _
   ByRef Reply As Variant _
)
Parameters
Command
Specifies the command to send.
Reply
Undimensioned String or Byte Array. Where the reply from the server will be put. Any contents will be replaced. A message would not be returned for this parameter when the Progress event fires, as that information would be available elsewhere.
Remarks

This method allows standard and non-standard commands to be sent. The reply from the server is copied to Reply; you determine success or failure. Reply must not go out of scope while the command completes (it must have file or global scope)

The control appends a CR/LF pair to the end of all commands so you should not send commands with a trailing CR/LF.

All commands must begin with a unique command identifier. The control generates and adds this to the beginning of a command you should not send commands with preceding command identifiers.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol
  • ptTimeout
Example
  • Example (VB6)
Private Sub Command1_Click()
    On Error GoTo OnError ' use intrinsic error handling
    Dim Reply As String
    ' Timeout 30 seconds
    Imap1.Timeout = 30000
    ' login to the server
    Imap1.Login "imap.test.com", "MyUsername", "MyPassword"
    ' send a standard NOOP command to the server
    Imap1.Command "NOOP", Reply
    MsgBox "Server Reply: " & Reply
    Exit Sub
OnError: ' Any error jumps here
    Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub
See Also

Imap Object | Imap Members


%%PageItemTitle%%

Login Method
Imap Object : Login Method
A hostname or IP address.
Optional. Specifies the server account.
Optional. Specifies the password for the server account.
Optional. Specifies the desired port number. Defaults to the well-known port 143 (or 993 for implicitly secure connections).
Description
Connect to a server and authenticate in one step.
Syntax
Visual Basic
Public Sub Login( _
   ByVal Server As String, _
   Optional ByVal Username As String, _
   Optional ByVal Password As String, _
   Optional ByVal RemotePort As Long = 0 _
)
Parameters
Server
A hostname or IP address.
Username
Optional. Specifies the server account.
Password
Optional. Specifies the password for the server account.
RemotePort
Optional. Specifies the desired port number. Defaults to the well-known port 143 (or 993 for implicitly secure connections).
Remarks
Most IMAP servers require a Username and a Password.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptAbort
  • ptAddressInUse
  • ptAddressNotAvailable
  • ptAuthentication (An Invalid Username or Password was specified)
  • ptBlocked
  • ptConnected
  • ptConnectionAborted
  • ptConnectionRefused
  • ptConnectionReset
  • ptHostNotFound
  • ptNetworkDown
  • ptNetworkReset
  • ptNetworkUnreachable
  • ptNotInitialized
  • ptNoBufferSpace
  • ptNoData
  • ptProtocol (A protocol error was encountered)
  • ptTimeout
  • ptTryAgain
Example
Most IMAP servers require a Username and Password, as shown in the following VB example.
  • Example (VB6)
Private Sub Command1_Click()
    On Error GoTo OnError ' use intrinsic error handling
    Imap1.Timeout = 30000
    Imap1.Login "imap.test.com", "user", "pass"
    If Imap1.State = tcpConnected Then MsgBox "Logged In!"
    Imap1.Logout ' end server session
    If Imap1.State = tcpClosed Then MsgBox "Session Completed"
    Exit Sub
OnError: ' Any error jumps here
    Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub
See Also

Imap Object | Imap Members


%%PageItemTitle%%

Logout Method
Imap Object : Logout Method
Description
Gracefully end a session.
Syntax
Visual Basic
Public Sub Logout()
Remarks
Unlike the POP Control, the IMAP Control does not delete all messages marked for deletion upon logout. The Purge method must be called to delete these messages.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol (A protocol error was encountered)
  • ptTimeout
Example

Login Method

See Also

Imap Object | Imap Members


%%PageItemTitle%%

Refresh Method
Imap Object : Refresh Method
Optional. Specifies the name of the mailbox; may include wildcards. Defaults to all mailboxes (*).
Optional. Specifies the reference point to start the listing. Defaults to the current path.
Description
Get a listing of mailboxes.
Syntax
Visual Basic
Public Sub Refresh( _
   Optional ByVal Name As String, _
   Optional ByVal Reference As String _
)
Parameters
Name
Optional. Specifies the name of the mailbox; may include wildcards. Defaults to all mailboxes (*).
Reference
Optional. Specifies the reference point to start the listing. Defaults to the current path.
Remarks
The Mailboxes property is emptied and repopulated each time this method is called. Each Mailbox Object and the messages they hold are destroyed unless stored to another object.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol
  • ptTimeout
Example
  • Example (VB6)
Private Sub Command1_Click()
    On Error GoTo OnError ' use intrinsic error handling
    Dim Mailbox As Mailbox
    Imap1.Login "imap.test.com", "user", "pass"
    ' Get new listing from the server. The collection will be
    ' cleared and repopulated.
    Imap1.Refresh
    ' Display all mailboxes returned in the listing
    For Each Mailbox In Imap1.Mailboxes
        List1.AddItem Mailbox.Name
    Next
    Exit Sub
OnError: ' Any error jumps here
    Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub
See Also

Imap Object | Imap Members


%%PageItemTitle%%

Trace Method
Imap Object : Trace Method
Optional. An undimensioned string dynamically expanded to contain trace data or a filename that is used to store all trace data. If not provided or a Null value, then trace data is no longer stored.
Optional. Defaults to False. A True value indicates that sent data should be traced.
Optional. Defaults to False. A True value indicates that received data should be traced.
Optional. Prompt to precede sent data.
Optional. Prompt to precede received data.
Description

Start or stop the accumulation of trace or debug data. Once started, this method accumulates data until it is turned off.

This method provides a convenient mechanism for viewing all data being sent and received over the connection and can be used to troubleshoot host interoperability issues and expose protocol communications.

Syntax
Visual Basic
Public Sub Trace( _
   Optional ByRef Result As Variant, _
   Optional ByVal Send As Boolean = False, _
   Optional ByVal Receive As Boolean = False, _
   Optional ByVal SendPrompt As String, _
   Optional ByVal ReceivePrompt As String _
)
Parameters
Result
Optional. An undimensioned string dynamically expanded to contain trace data or a filename that is used to store all trace data. If not provided or a Null value, then trace data is no longer stored.
Send
Optional. Defaults to False. A True value indicates that sent data should be traced.
Receive
Optional. Defaults to False. A True value indicates that received data should be traced.
SendPrompt
Optional. Prompt to precede sent data.
ReceivePrompt
Optional. Prompt to precede received data.
Remarks
ReceivePrompt and SendPrompt allow the application to specify what delimiters separate and label data being captured.
Example
  • Example (VB6)
Private Sub Command1_Click()
    On Error GoTo OnError ' use intrinsic error handling
    'Starts logging to Debug.txt
    Tcp1.Trace "Debug.txt", True, True, vbCrLf & "Sent: ", vbCrLf & "Recv: "
    Exit Sub
OnError: ' Any error jumps here
    Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub

Private Sub Command2_Click()
    On Error GoTo OnError ' use intrinsic error handling
    'Stops logging
    Tcp1.Trace
    Exit Sub
OnError: ' Any error jumps here
    Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub
See Also

Imap Object | Imap Members


%%PageItemTitle%%

AttachmentDirectory Property
Imap Object : AttachmentDirectory Property
Description
Decoded message attachments are created in this directory.
Property type
Read-write property
Syntax
Visual Basic
Public Property AttachmentDirectory As String
Remarks

The default value is ".\" (the default directory). This property can only be set at run time.

A message can include attached files. When these messages are decoded, the filename from the message is combined with this property to produce the file path used to recreate the attached file.

Due to an operating system limitation, this value cannot be longer than 256 characters.

Note This property may be set at anytime for subsequent decoding operations.

If set to "" (an empty string) or the 'Content-Type' header does not include a name for the file, then the file is not created, and the Data property contains the decoded file.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptFile
  • ptInvalidParam1
  • ptNoBufferSpace
See Also

Imap Object | Imap Members


%%PageItemTitle%%

AttachmentOverwrite Property
Imap Object : AttachmentOverwrite Property
Description
Specifies whether decoded message attachments are overwritten if the filename is the same.
Property type
Read-write property
Syntax
Visual Basic
Public Property AttachmentOverwrite As Boolean
Remarks

Defaults to False.

By default, attachments create a unique number to add to their filename if there is already an existing file with the same name. When this property is set to false, existing files are overwritten by attachments.

See Also

Imap Object | Imap Members


%%PageItemTitle%%

AutoClose Property
Imap Object : AutoClose Property
Description
Specifies whether to close a Mailbox when done with it.
Property type
Read-write property
Syntax
Visual Basic
Public Property AutoClose As Boolean
Remarks

Defaults to True.

By default, old mailboxes are closed when the active mailbox is changed. This can cause deleted messages to be purged. Set this parameter to false to make sure that deleted message will not be purged until Purge is called.

See Also

Imap Object | Imap Members


%%PageItemTitle%%

Blocked Property
Imap Object : Blocked Property
Description
A True value indicates the control is currently executing a blocking method (Timeout is greater than 0), which has neither completed nor timed out with a ptTimeout error.
Property type
Read-only property
Syntax
Visual Basic
Public Property Blocked As Boolean
Remarks

Read-only.

Check this property to prevent your application from prematurely exiting or destroying the control while it is blocking in a method.

Your application still processes normal Windows messages while blocked, and the user interface continues to function normally. Events still fire while blocked, so code placed in these events continues to execute.

Your application cannot execute another method (except the Abort method) while it is blocked; a ptBlocked error is generated. Use the Abort method to terminate a blocked method prematurely. Abort signals the blocked method to abort, and then returns. Shortly thereafter, the blocked method releases all system resources, calls the State event (with the object's State property set to ptClosed), and returns with the ptAbort error.

WARNING Terminating your application or destroying the TCP object while blocked in a method may cause a fatal application error. To prevent this, perform either of the following:

  • Only allow object destruction if the Blocked property returns False.
  • Never use a positive Timeout value.
See Also

Imap Object | Imap Members


%%PageItemTitle%%

Capabilities Property
Imap Object : Capabilities Property
Description
Collection of strings that contains the protocol extensions advertised as supported by the server. Values are initialized during login.
Property type
Read-only property
Syntax
Visual Basic
Public Property Capabilities As DartStrings
Remarks

Read-only (but you can remove Strings in the collection).

As part of the Login process, every IMAP server announces the capabilities of that server implementation. For example, the following strings may be added to the Imap.Capabilities string collection during login:

  • IMAP4
  • IMAP4REV1
  • NAMESPACE
  • IDLE
  • SCAN
  • SORT
  • MAILBOX-REFERRALS
  • LOGIN-REFERRALS
  • X-NOOP-DUPLICATE-SELECT
  • AUTH=LOGIN
  • THREAD=ORDEREDSUBJECT

Unlike the SMTP Control (which uses the Capabilities property to optimize the transmission of mail), the IMAP Control provides these values for informational purposes only.

See Also

Imap Object | Imap Members


%%PageItemTitle%%

Certificate Property
Imap Object : Certificate Property
Description
Certificate Object to use when authenticating to the remote host.
Property type
Read-write property
Syntax
Visual Basic
Public Property Certificate As ICertificate
Remarks
This property is typically unused. If the server wants the client to authenticate and this property has not been set, then the Certificate event fires to allow you to set a certificate on demand.
Example
  • Example (VB6)
Dim Store As New CertificateStore
Dim Certificate As Certificate
'Get the certificates in "MY" certificate store located in the
'Local Machine registry key.
Store.Name = "MY"
Store.Location = locationLocalMachine
'Must use Refresh to populate Store.Certificates
Store.Refresh
MsgBox "There are " & Store.Certificates.Count & " certificates."
'Set the certificate to the one for "DartServer"
For Each Certificate In Store.Certificates
    If Certificate.IssuedTo = "DartServer" Then
        SecureTcp1.Certificate = Certificate
        Exit For
    End If
Next
Alternatively, you can use the Find method to set the certificate:
  • Example (VB6)
Dim Store As New CertificateStore
'Get the desired certificate
SecureTcp1.Certificate = Store.Find("ROOT", locationLocalMachine, g_SavedIssuedBy, g_SavedSerialNumber)
See Also

Imap Object | Imap Members


%%PageItemTitle%%

EnableNonAscii Property
Imap Object : EnableNonAscii Property
Description
Enables the usage of Non-ASCII characters in the Username
Property type
Read-write property
Syntax
Visual Basic
Public Property EnableNonAscii As Boolean
Remarks
This mechanism works with Microsoft Exchange server, and it allows 8-bit characters to be sent to the server.
See Also

Imap Object | Imap Members


%%PageItemTitle%%

Idle Property
Imap Object : Idle Property
Description
Controls whether the Imap control is in IDLE mode.
Property type
Read-write property
Syntax
Visual Basic
Public Property Idle As Boolean
Remarks

Defaults to False.

When set to true, the Progress event will fire when unsolicited messages are received from the server.

See Also

Imap Object | Imap Members


%%PageItemTitle%%

IpV6 Property
Imap Object : IpV6 Property
Description
Specifies whether hostname addresses should be favorably resolved to IPv6.
Property type
Read-write property
Syntax
Visual Basic
Public Property IpV6 As Boolean
See Also

Imap Object | Imap Members


%%PageItemTitle%%

Mailboxes Property
Imap Object : Mailboxes Property
Description
Collection of Mailbox obejcts.
Property type
Read-only property
Syntax
Visual Basic
Public Property Mailboxes As Mailboxes
Remarks

The Refresh method populates this property.

Example
  • Example (VB6)
Private Sub Command1_Click()
    On Error GoTo OnError ' use intrinsic error handling
    Dim Mailbox As Mailbox
    'Set timeout to 30 seconds
    Imap1.Timeout = 30000
    Imap1.Login "imap.dart.com", "user", "pass"
    'Logged in, get mailbox listing
    Imap1.Refresh
    'Display mailboxes returned in listing
    For Each Mailbox In Imap1.Mailboxes
        List1.AddItem Mailbox.Name
    Next
    Exit Sub
OnError: ' Any error jumps here
    Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub
See Also

Imap Object | Imap Members


%%PageItemTitle%%

Privacy Property
Imap Object : Privacy Property
Description
Specifies the security protocol (PCT, SSL2, SSL3, TLS, none) and type (Implicit, Explicit) used.
Property type
Read-write property
Syntax
Visual Basic
Public Property Privacy As MailPrivacyConstants
Remarks

The default value is privacyNone.

If the server and the client specify secureAuto, then SSL3 is normally used. If one side uses secureAuto and the other side specifies a protocol, then the protocol specified is used. If the client and server specify protocols that are different, then the Error event will fire with Number=ptProtocol and the connection will be closed.

See Also

Imap Object | Imap Members


%%PageItemTitle%%

Security Property
Imap Object : Security Property
Description
Sets the security level during communication.
Property type
Read-write property
Syntax
Visual Basic
Public Property Security As SecurityConstants
Remarks
This property enables variable security settings, from absolute certificate confirmation to no security.
See Also

Imap Object | Imap Members


%%PageItemTitle%%

State Property
Imap Object : State Property
Description
Provides status information. The State event fires to signal that this property has changed.
Property type
Read-only property
Syntax
Visual Basic
Public Property State As StateConstants
Remarks
To protect you from programming errors, most methods return an error condition if your code attempts to send data when no TCP connection exists. By checking the value of this property, your application can determine the state of the connection.
See Also

Imap Object | Imap Members


%%PageItemTitle%%

Timeout Property
Imap Object : Timeout Property
Description
Controls the blocking behavior of methods that can be used in blocking and non-blocking ways.
Property type
Read-write property
Syntax
Visual Basic
Public Property Timeout As Long
Remarks

The default value is 30000 (30 seconds). This is a design-time property.

Most users will start using blocking operation. The developer's decision to use blocking (Timeout > 0) or non-blocking (Timeout = 0) operation is important; these controls were designed to consistently support both methods of operation.

When set to a positive number of milliseconds, methods block while waiting for the initial response from the method. For example, an FTP or HTTP Get() method on a file will block until response is received. The Blocked property indicates this state. For example, if the Login method is used with a Timeout of 30000, then the method only returns without error if the connection is established within 30 seconds. This is the easiest design to implement, but not the most robust. If the user attempts to initiate a different method while the Blocked property is True, an error is generated. Also, if the user attempts to close the application while the Blocked property is True, abnormal program termination may result.

When set to 0, no method blocks. It is up to the application to sense the success or failure of the operation by putting code in the related event. For example, if the Login method is used with a Timeout of 0, then the application can test for the value of the State property from within the State event. This is the most efficient technique, as no idle loops are used to capture the thread of execution waiting for an event to occur. This is also the safest way to use PowerTCP because non-blocking use allows PowerTCP to unload gracefully under any condition.

The novice will probably use blocking operation first because this is the easiest way to immediately use the product. With no explicit error handling enabled (for example, the VB OnError statement), methods return errors into the environment and program execution stops. Once you add error-handling code, most applications will work satisfactorily. While the thread is captured in the method, an idle loop processes Windows messages and few side effects will ever be noted. There are some limits, however, that you should be aware of:

  • The only way to abort a blocking method is to call the Abort method off a Timer or some user interface event.
  • With the exception of the Abort method, the developer can only be in one method at a time (this protects your program from reentrancy problems).
  • If the user closes the application while PowerTCP is blocking, the blocking method attempts to return when this is sensed, but a general protection fault may still be experienced (because the application is being terminated while PowerTCP is in an idle loop).

Non-blocking operations are more fault-tolerant. Set the Timeout property to 0 (at design time or at run time), initiate methods as desired, and insert most of your code in the appropriate event. This eliminates problems associated with reentrancy, users performing unanticipated actions in your application, and error recovery.

Note: Asynchronous operation is dependent upon an active MessageLoop. If an asynchronous operation is started, and subsequently a synchronous process (such as a lengthy database query) is started (immediately or off a timer), operation may be affected. In some development environments, the MessageLoop can be executed by calling DoEvents() repeatedly, but this design is not optimal. Preferred approaches include:

  • Operate the synchronous process on another worker thread
  • Operate the control itself on another thread or process
  • Split the synchronous process into smaller pieces that operate off a timer event
See Also

Imap Object | Imap Members


%%PageItemTitle%%

Alert Event
Imap Object : Alert Event
The human-readable alert message received from the server.
Description
Fires when the server sends an alert message.
Syntax
Visual Basic
Public Event Alert( _
   ByVal Message As String _
)
Parameters
Message
The human-readable alert message received from the server.
Remarks
The message may be immediately displayed to the user. If the control is being used in non-blocking mode, this event will be raised whenever an alert message is received from the server. If the control is being used in blocking mode, this event will ONLY be raised if the control is blocking for a response from the server.
Example
  • Example (VB6)
Private Sub Imap1_Alert(ByVal Message As String)
    On Error GoTo OnError ' use intrinsic error handling
    ' Display the message to the user.
    MsgBox Message
    Exit Sub
OnError: ' Any error jumps here
    Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub
See Also

Imap Object | Imap Members


%%PageItemTitle%%

Authenticate Event
Imap Object : Authenticate Event
Remote host's certificate.
Indicates if the certificate was from a Trusted Root Authority (CA).
Indicates if the current date-time is within the certificate's life span.
Indicates if the certificate has a valid signature.
Set this value to True to authenticate the remote certificate or set it to False to deny it.
Description
Fires when the remote host has sent a certificate to be authenticated.
Syntax
Visual Basic
Public Event Authenticate( _
   ByVal RemoteCertificate As ICertificate, _
   ByVal TrustedRoot As Boolean, _
   ByVal ValidDate As Boolean, _
   ByVal ValidSignature As Boolean, _
   ByRef Valid As Boolean _
)
Parameters
RemoteCertificate
Remote host's certificate.
TrustedRoot
Indicates if the certificate was from a Trusted Root Authority (CA).
ValidDate
Indicates if the current date-time is within the certificate's life span.
ValidSignature
Indicates if the certificate has a valid signature.
Valid
Set this value to True to authenticate the remote certificate or set it to False to deny it.
Remarks
Typically, the remote certificate is rejected if TrustedRoot, ValidDate, or ValidSignature is False. This event allows you to ease or strengthen the restrictions on the remote host's certificate. To authenticate a certificate if one or all of the parameters are False, set Valid to True. You can also deny a certificate if the hostname is not the same as the IssuedTo property of the Certificate.
Example
This example demonstrates denying a certificate.
  • Example (VB6)
Private Sub SecureTcp1_Authenticate(RemoteCertificate As Certificate, TrustedRoot As Boolean, ValidDate As Boolean, ValidSignature As Boolean, ByRef Valid As Boolean)
    On Error GoTo OnError ' use intrinsic error handling
    If RemoteCertificate.IssuedTo <> gRemoteHostName Then Valid = False
    Exit Sub
OnError: ' Any error jumps here
    Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub
See Also

Imap Object | Imap Members


%%PageItemTitle%%

Certificate Event
Imap Object : Certificate Event
Description
Fires when the remote host is requesting a certificate and the Certificate property is not set to a valid Certificate Object.
Syntax
Visual Basic
Public Event Certificate()
Remarks
This event is used to set a certificate on demand. In some cases a server will request that the client authenticate, and it may not be desirable to set the Certificate property unless necessary.
Example
  • Example (VB6)
Private Sub SecureTcp1_Certificate ( )
    Dim Store As New CertificateStore
    'Get the desired certificate
    SecureTcp1.Certificate = Store.Find("ROOT", locationLocalMachine, g_SavedIssuedBy, g_SavedSerialNumber)
    'Or you could pop up a list box so the user could select a certificate
End Sub
See Also

Imap Object | Imap Members


%%PageItemTitle%%

Error Event
Imap Object : Error Event
Human-readable description of the error.
Description
Fires when an error occurs.
Syntax
Visual Basic
Public Event Error( _
   ByVal Number As MailErrorConstants, _
   ByVal Description As String _
)
Parameters
Number
Value | Description
mailAbort | The Abort method was called. FATAL.
mailAddressInUse | Address already in use. Only one usage of each socket address (protocol/IP address/port) is normally permitted. This error occurs if an application attempts to bind() a socket to an IP address/port that has already been used for an existing socket, or a socket that wasn't closed properly, or one that is still in the process of closing. For server applications that need to bind() multiple sockets to the same port number, the ReuseAddress property can be used. FATAL.
mailAddressNotAvailable | Cannot assign requested address. The requested address is not valid in its context. Normally results from an attempt to bind() to an address that is not valid for the local machine. This may also result from connect(), sendto(), WSAConnect(), WSAJoinLeaf(), or WSASendTo() when the remote address or port is not valid for a remote machine (for example, address or port 0). FATAL.
mailAttachUuencode | Only (uuencoded) files may be attached to this non-MIME message. Consider using MIME or putting all text in the Message.Data property area.
mailAuthentication | Authentication with the server failed. FATAL.
mailBadConfigItem | Invalid Configuration Item
mailBadDataType | Cannot create the requested data type or format.
mailBadRecipient | Mail Recipient Not Accepted.
mailBadSender | Sender address not accepted.
mailBlocked | User thread is blocking in another method. INFO.
mailCompile | An error occurred while compiling
mailConnected | A connection already exists
mailConnectionAborted | Software caused connection abort. An established connection was aborted by the software in your host machine, possibly due to a data transmission timeout or protocol error. FATAL.
mailConnectionRefused | Connection refused. No connection could be made because the target machine actively refused it. This usually results from trying to connect to a service that is inactive on the foreign host (for example,. one with no server application running). May also be generated by a Daemon that refuses a connection because its resources have been exhausted. FATAL.
mailConnectionReset | Connection reset by peer. An existing connection was forcibly closed by the remote host. This normally results if the peer application on the remote host is suddenly stopped, the host is rebooted, or the remote host used a "hard close" (see Abort method) on the remote socket. This error may also result if a connection was broken due to keep-alive activity detecting a failure while one or more operations are in progress. Operations that were in progress fail with ptNetworkReset. Subsequent operations fail with ptConnectionReset. FATAL.
mailDuplicateMessage | Message object already exists in collection.
mailError | Unexpected general error. FATAL.
mailFile | Error accessing local file storage. FATAL.
mailFileOpen | Unable to open file.
mailFileOperation | A file operation (such as size) had failed.
mailFileRead | A file read error has caused the operation to fail.
mailFileWrite | A file write error has occurred. Check disk free space.
mailFormatError | The server was unable to interpret the query.
mailHeader | Occurs when a proper termination (usually a CRLFCRLF) is not found in the header.
mailHostNotFound | Host not found. No such host is known. The name is not an official hostname or alias, or it cannot be found in the database(s) being queried. This error may also be returned for protocol and service queries, and means the specified name could not be found in the relevant database. FATAL.
mailHostUnreachable | Remote host does not exist
mailHttpInvalidUrl | The Url is unspecified or invalid.
mailInvalidMailAddress | The Email address specified was not valid.
mailInvalidMessageHeader | A recipient, from, and subject are needed for a valid message header.
mailInvalidParam1 | Parameter #1 is invalid. INFO.
mailInvalidParam2 | Parameter #2 is invalid. INFO.
mailInvalidParam3 | Parameter #3 is invalid. INFO.
mailInvalidParam4 | Parameter #4 is invalid. INFO.
mailInvalidProperty | Invalid property assignment. INFO.
mailInvDecodeType | An invalid or unsupported Decode Type was specified.
mailMsgObjRead | An error has occurred while reading data from the Message object. Verify the Message object contents.
mailNetworkDown | Network is down. A socket operation encountered a dead network. This could indicate a serious failure of the network system (for example,. the protocol stack that the Winsock DLL runs over), the network interface, or the local network itself. FATAL.
mailNetworkReset | Network dropped connection on reset. The connection has been broken due to keep-alive activity detecting a failure while the operation was in progress. FATAL.
mailNetworkUnreachable | Network is unreachable. A socket operation was attempted to an unreachable network. This usually means the local software knows no route to reach the remote host. FATAL.
mailNoAccess | The user does not have the proper permissions
mailNoAuthMech | No authentication mechanism was found in the server's advertised capabilities, a secure connection may be required.
mailNoBufferSpace | No buffer space available. An operation on a socket could not be performed because the system lacked sufficient buffer space or because a queue was full. FATAL.
mailNoCertificate | There was an error in creating credentials.
mailNoData | Valid name, no data record of requested type. The requested name is valid and was found in the database, but it does not have the correct associated data being resolved for. The usual example for this is a hostname -> address translation attempt which uses the DNS, and an MX record is returned but no A record - indicating the host itself exists but is not directly reachable. FATAL.
mailNoHeader | The message is invalid because the header was not found.
mailNoMemory | There was not enough memory available to complete the operation.
mailNoMessageHeader | The message does not contain a valid header.
mailNoRecipientsFound | The message header does not contain any (valid) recipients (To).
mailNoRecovery | This is a non-recoverable error. This indicates some sort of non-recoverable error occurred during a database lookup. This may be because the database files (for example, BSD-compatible HOSTS, SERVICES or PROTOCOLS files) could not be found, or a DNS (Domain Name Server) request was returned by the server with a severe error. FATAL.
mailNoSecurity | Secure communications is not available on this machine.
mailNotConnected | Socket is not connected. A request to send or receive data was disallowed because the socket is not connected or allocated. Any other type of operation might also return this error. FATAL.
mailNotFound | The name referred to in the query does not exist.
mailNotImplemented | The server does not support the request type of query.
mailNotInitialized | Network interface could not be initialized. FATAL.Host not found. No such host is known. The name is not an official hostname or alias, or it cannot be found in the database(s) being queried. This error may also be returned for protocol and service queries, and means the specified name could not be found in the relevant database. FATAL.
mailNotInSpoolMode | Method not allowed when spool mail mode is active.
mailNotMessageObject | The passed object is not a Message object.
mailNotPartObject | The operation requested requires an object of type Part.
mailOk | Ok
mailOnlyInSpoolMode | The DeSpool Method is only available when mail spooling is enabled.
mailOperationRefused | The server refused to perform the specified operation.
mailOptionNotSupported | The specified socket option is not supported by the system. INFO.
mailPartInStructure | The Part to Add already exists in this structure.
mailProtocol | Unexpected protocol error. FATAL.
mailServerError | There was a failure on the server.
mailSocks4DifferentUserID | The SOCKS4 server rejected the connection because the client program and identd report different user-ids
mailSocks4NoAcceptableMethods | The SOCKS5 server will not accept any of the requested methods
mailSocks4NoIdentd | The SOCKS4 server rejected the connection because it was unable to connect to identd on the client
mailSocks4RequestRejected | The SOCKS4 server rejected the connection (No reason given)
mailSocks5AddressTypeNotSupported | The SOCKS5 server reported that the address type is not supported
mailSocks5AuthFailed | The SOCKS5 server rejected the connection because authorization failed
mailSocks5CommandNotSupported | The SOCKS5 server reported that the command is not supported
mailSocks5ConnectionRefused | The SOCKS5 server reported that the host connection was refused
mailSocks5HostUnreachable | The SOCKS5 server reported that the host was unreachable
mailSocks5NetworkUnreachable | The SOCKS5 server reported that the network was unreachable
mailSocks5NoRuleSet | The SOCKS5 server reported that the connection was not allowed by the ruleset
mailSocks5ServerFailure | The SOCKS5 server reported a general failure
mailSocks5TTLExpired | The SOCKS5 server reported that the TTL has expired
mailTimeout | Timed out. A connection attempt failed because the connected party did not properly respond after a period of time, or an established connection failed because connected host has failed to respond. Alternatively, a blocked method failed to return within the period specified by the Timeout property. FATAL.
mailTryAgain | Non-authoritative host not found. This is usually a temporary error during hostname resolution and means that the local server did not receive a response from an authoritative server. A retry at some time later may be successful. FATAL.
mailUseMimeEncode | mailUseMimeEncoding must be Always, Never, or Smallest
Description
Human-readable description of the error.
Remarks

Some environments, such as IIS Active Server Pages, do not support event handling. In this case the application must rely on blocking and the Error object that is returned to the container when an error condition occurs.

Note See the appropriate method and property description for a list of errors that may be generated.

See Also

Imap Object | Imap Members


%%PageItemTitle%%

Progress Event
Imap Object : Progress Event
Indicates the method that the event pertains to.
Indicates the status of the method.
Specifies the server reply related to the status.
Specifies the server-side message the event pertains to. This value corresponds to the message's Attribute(msgNumber) property.
Specifies the number of bytes that have been received (so far) for the transfer that is currently in progress. The value normally falls between 0 and Size. Only valid when Status is imapContent, and is 0 at other times.
Specifies the total number of bytes in the message transfer currently in progress. This value is constant during any single transfer. Only valid when Status is imapContent, and is 0 at other times.
Description
Fires when a method has completed, the server has sent a reply, or progress information is available.
Syntax
Visual Basic
Public Event Progress( _
   ByVal Method As ImapMethodConstants, _
   ByVal Status As ImapStatusConstants, _
   ByVal Reply As String, _
   ByVal MessageNumber As Long, _
   ByVal Count As Long, _
   ByVal Size As Long _
)
Parameters
Method
Value | Description
imapCommand | Command method.
imapCopy | Copy method.
imapDelete | Delete method.
imapGet | Get method.
imapIdle | Idle.
imapLogin | Login method.
imapLogout | Logout method.
imapMailboxAdd | Mailbox Add method.
imapMailboxesAdd | Mailboxes Add method.
imapMailboxesRefresh | Refresh method.
imapMailboxRefresh | Mailbox Refresh method.
imapPurge | Purge method.
imapPut | Put method.
imapRemove | Remove method.
imapRename | Rename.
imapSearch | Search method.
imapSubscribe | Subscribe method.
imapUndelete | Undelete method.
imapUnknown | Unknown command.
imapUnsubscribe | Unsubscribe method.
Indicates the method that the event pertains to.
Status
Value | Description
imapBad | Server has responded with a status indicating bad syntax.
imapBye | Server has indicated that it is about to close the connection.
imapContent | Indicates intermediate events during the receipt of a mail message. Useful for percentage indication on a status display.
imapInfo | Server has supplied information.
imapNo | Server has responded with a negative status.
imapOk | Method has completed with a positive status.
Indicates the status of the method.
Reply
Specifies the server reply related to the status.
MessageNumber
Specifies the server-side message the event pertains to. This value corresponds to the message's Attribute(msgNumber) property.
Count
Specifies the number of bytes that have been received (so far) for the transfer that is currently in progress. The value normally falls between 0 and Size. Only valid when Status is imapContent, and is 0 at other times.
Size
Specifies the total number of bytes in the message transfer currently in progress. This value is constant during any single transfer. Only valid when Status is imapContent, and is 0 at other times.
Remarks
Use the Trace method to gather protocol-level data if Reply is inadequate.
Example

Imap Object

See Also

Imap Object | Imap Members


%%PageItemTitle%%

State Event
Imap Object : State Event
Description
Fires when the State property changes.
Syntax
Visual Basic
Public Event State()
Remarks
WARNING Timeout must be 0 when calling methods from within an event. Failure to observe this rule may cause reentrancy problems and unpredictable results.
Example
  • Example (VB6)
Private Sub Telnet1_State()
    On Error GoTo OnError ' use intrinsic error handling
    ' State of the Telnet1 connection has changed...put up user feedback
    Select Case Telnet1.State
    Case tcpConnecting
        Label1.Caption = "Client Connecting..."
    Case tcpConnected
        Label2.Caption = "Client Connected to " & Tcp1.RemoteAddress
    Case tcpClosing
        Label3.Caption = "Client Closing..."
    Case tcpClosed
        Label4.Caption = "Client Closed"
    End Select
Exit Sub
OnError: ' Any error jumps here
    Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub
See Also

Imap Object | Imap Members


%%PageItemTitle%%

Mailbox Object
Members
Description
The Mailbox Object transforms an IMAP mailbox on a server into a local object that you can easily manipulate. Most properties manipulate the object model and the mailbox on the server.
Object Model
Mailbox ObjectDartStrings CollectionMessages Collection
Example
This example demonstrates how access a Mailboxes Object to rename a Mailbox Object.
  • Example (VB6)
Private Sub Command1_Click()
    On Error GoTo OnError ' use intrinsic error handling
    ' Rename the "Misc" mailbox to "Test"
    Imap1.Mailboxes.Item("Misc").Name = "Test"
    Exit Sub
OnError: ' Any error jumps here
    Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub
See Also

Mailbox Members


%%PageItemTitle%% $$Members$$

Mailbox Object Members
Overview
Public Methods
Public Method Add | Add a message to the mailbox.
Public Method Append | Append a message to a mailbox.
Public Method Copy | Copy one or more messages to another mailbox.
Public Method Delete | Mark one or more messages for deletion.
Public Method Get | Get one or more messages or message parts.
Public Method Purge | Permanently deletes all messages previously marked for deletion.
Public Method Put | Set message attributes.
Public Method Refresh | Update the mailbox Count, Recent, and Uid properties.
Public Method Search | Search for a specific message or set of messages.
Public Method Undelete | Unmark one or more messages previously marked for deletion.
Public Properties
Public Property Count | Number of messages in the server mailbox. The Refresh method is used to initialize the value of this property.
Public Property Delimiter | Used to parse Name into a hierarchy.
Public Property Flags | Collection of flags set for the mailbox.
Public Property Messages | Collection of Message Objects that is the default destination for downloaded messages when using Get.
Public Property Name | Mailbox name.
Public Property ReadOnly | Mailbox is read-only or read-write.
Public Property Recent | Number of messages in the mailbox with a "Recent" flag.
Public Property Uid | Unique identifier of the mailbox. The Refresh method is used to initialize the value of this property.
Public Property Unseen | Number of messages marked "Unseen" in the server mailbox. The Refresh method is used to initialize the value of this property.
See Also

Mailbox Object


%%PageItemTitle%%

Add Method
Mailbox Object : Add Method
Description
Add a message to the mailbox.
Syntax
Visual Basic
Public Sub Add( _
   ByVal Message As String _
)
Parameters
Message
Remarks

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol
  • ptTimeout
Example
  • Example (VB6)
Dim Message As Message
    Private Sub Command1_Click()
    On Error GoTo OnError ' use intrinsic error handling
    ' Add a Message to the INBOX.
    Imap1.Mailboxes("INBOX").Add Message.Content
    Exit Sub
OnError: ' Any error jumps here
    Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Append Method
Mailbox Object : Append Method
The encoded message, or the file path of a file containing the message.
Specifies the flags to set in the resulting message.
Description
Append a message to a mailbox.
Syntax
Visual Basic
Public Sub Append( _
   ByVal Message As String, _
   Optional ByVal bFlags As String _
)
Parameters
Message
The encoded message, or the file path of a file containing the message.
bFlags
Specifies the flags to set in the resulting message.
Remarks

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol
  • ptTimeout
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Copy Method
Mailbox Object : Copy Method
Specifies the name of the destination mailbox.
Optional. Specifies the message numbers to copy. The default is all messages.
Description
Copy one or more messages to another mailbox.
Syntax
Visual Basic
Public Sub Copy( _
   ByVal Destination As String, _
   Optional ByVal MsgSet As String _
)
Parameters
Destination
Specifies the name of the destination mailbox.
MsgSet
Optional. Specifies the message numbers to copy. The default is all messages.
Remarks
If provided, MsgSet specifies one or more message numbers in the range from 1 to Count. Each number should be separated with a comma. A range of numbers may be indicated with a lower and upper number separated with a colon. For example, a message set of "1, 5:7, 12" will retrieve 5 messages: 1, 5, 6, 7, and 12.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol
  • ptTimeout
Example
  • Example (VB6)
Private Sub Command1_Click()
    On Error GoTo OnError ' use intrinsic error handling
    Dim MsgSet As String
    ' Copy All Messages from INBOX to the OldMail mailbox
    Imap1.Mailboxes("INBOX").Copy "OldMail"
    ' Copy just the first and last message from INBOX to TestMbx
    MsgSet = "1," & Imap1.Mailboxes("INBOX").Count()
    Imap1.Mailboxes("INBOX").Copy "TestMbx", MsgSet
    Exit Sub
OnError: ' Any error jumps here
    Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Delete Method
Mailbox Object : Delete Method
Specifies the message numbers to mark for deletion. The default is all messages.
Description
Mark one or more messages for deletion.
Syntax
Visual Basic
Public Sub Delete( _
   Optional ByVal MsgSet As String _
)
Parameters
MsgSet
Specifies the message numbers to mark for deletion. The default is all messages.
Remarks

This method only marks a message for deletion. The message is not permanently removed until the Purge method is used.

If provided, MsgSet specifies one or more message numbers in the range from 1 to Count. Each number should be separated with a comma. A range of numbers may be indicated with a lower and upper number separated with a colon. For example, a message set of "1, 5:7, 12" retrieves the following five messages: 1, 5, 6, 7, and 12.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol
  • ptTimeout
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Get Method
Mailbox Object : Get Method
Specifies the message part to be retrieved. The default value is imapContent.
Specifies the message numbers to get. The default is all messages.
Optional String that specifies an undimensioned String or Byte array that will be dynamically expanded and filled with a single message. If not specified or NULL, the Messages property is used as the destination.
Description
Get one or more messages or message parts.
Syntax
Visual Basic
Public Sub Get( _
   Optional ByVal Part As GetConstants = imapGetContent, _
   Optional ByVal MsgSet As String, _
   Optional ByRef Msg As Variant _
)
Parameters
Part
Value | Description
imapGetContent | Requests retrieval of the complete message for each message in MsgSet.
imapGetFlags | Requests the flags for each message specified in MsgSet.
imapGetHeaders | Requests the retrieval of the header fields for each message in the MsgSet.
imapGetPreview | Requests the retrieval of the header fields plus parts information for each message in the MsgSet.
imapGetSize | Requests the size for each message specified in MsgSet.
imapGetUid | Requests the message UID label for each message in MsgSet.
Specifies the message part to be retrieved. The default value is imapContent.
MsgSet
Specifies the message numbers to get. The default is all messages.
Msg
Optional String that specifies an undimensioned String or Byte array that will be dynamically expanded and filled with a single message. If not specified or NULL, the Messages property is used as the destination.
Remarks

This method makes it easy to download any or all parts of a set of messages. The default destination for messages is the Messages property.

If provided, MsgSet specifies one or more message numbers in the range from 1 to Count. Each number should be separated with a comma. A range of numbers may be indicated with a lower and upper number separated with a colon. For example, a message set of "1, 5:7, 12" will retrieve 5 messages: 1, 5, 6, 7, and 12.

If the destination is the Messages Collection, this method creates all required Message Objects. If a Message Object exists with the same Attribute property, it is reused. Therefore, you can first get the Size of messages causing creation of a Message Object for each message. Getting the imapGetContent will reuse the Message Objects previously created.

If Msg is specified, MsgSet must reference a single message. If Msg is a buffer and Timeout is 0 (non-blocking), Msg must not go out of scope while the operation completes (the Msg String or Byte array must be global in scope).

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol
  • ptTimeout
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Purge Method
Mailbox Object : Purge Method
Description
Permanently deletes all messages previously marked for deletion.
Syntax
Visual Basic
Public Sub Purge()
Remarks

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol
  • ptTimeout
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Put Method
Mailbox Object : Put Method
Specifies the value to set for the Part.
Specifies the message part to be set. The default value is imapPutFlagsAdd.
Specifies the message numbers to set. The default is all messages.
Description
Set message attributes.
Syntax
Visual Basic
Public Sub Put( _
   ByVal Value As String, _
   Optional ByVal Part As PutConstants = imapPutFlagsAdd, _
   Optional ByVal MsgSet As String _
)
Parameters
Value
Specifies the value to set for the Part.
Part
Value | Description
imapPutFlags | Replaces the flags for each message in the MsgSet.
imapPutFlagsAdd | Adds flags for each message in the MsgSet.
imapPutFlagsRemove | Removes flags for each message in the MsgSet.
Specifies the message part to be set. The default value is imapPutFlagsAdd.
MsgSet
Specifies the message numbers to set. The default is all messages.
Remarks

This method makes it easy to alter parts of a message or messages on the server. According to RFC 2060, you can only set the flags message part.

If provided, MsgSet specifies one or more message numbers in the range from 1 to Count. Each number should be separated with a comma. A range of numbers may be indicated with a lower and upper number separated with a colon. For example, a message set of "1, 5:7, 12" will retrieve 5 messages: 1, 5, 6, 7, and 12.

See RFC 2060 for a list of predefined flags that can be set for a message. Other server implementations may have additional flags that can be set.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol
  • ptTimeout
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Refresh Method
Mailbox Object : Refresh Method
Description
Update the mailbox Count, Recent, and Uid properties.
Syntax
Visual Basic
Public Sub Refresh()
Remarks
Use this method to get information about a mailbox without performing any operations on it. Normally the Count, Recent, and Uid properties are updated after an operation is performed on the mailbox.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol
  • ptTimeout
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Search Method
Mailbox Object : Search Method
Specifies the criteria used for searching. This string must be in the format specified by RFC 2060 Section 6.4.4.
Undimensioned string. Where the reply from the search will be put. Any contents will be replaced.
Specifies the character set used for the search.
Description
Search for a specific message or set of messages.
Syntax
Visual Basic
Public Sub Search( _
   ByVal Criteria As String, _
   ByRef MsgSet As Variant, _
   Optional ByVal CharacterSet As String _
)
Parameters
Criteria
Specifies the criteria used for searching. This string must be in the format specified by RFC 2060 Section 6.4.4.
MsgSet
Undimensioned string. Where the reply from the search will be put. Any contents will be replaced.
CharacterSet
Specifies the character set used for the search.
Remarks
MsgSet will be empty or will contain numbers separated by a space. These numbers specify the message numbers on the server that meet the search criteria. MsgSet must not go out of scope while the command completes (it must have file or global scope).

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol
  • ptTimeout
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Undelete Method
Mailbox Object : Undelete Method
Specifies the message numbers to unmark for deletion. The default is all messages.
Description
Unmark one or more messages previously marked for deletion.
Syntax
Visual Basic
Public Sub Undelete( _
   Optional ByVal MsgSet As String _
)
Parameters
MsgSet
Specifies the message numbers to unmark for deletion. The default is all messages.
Remarks

An unmarked message is not deleted when the Purge method is called.

If provided, MsgSet specifies one or more message numbers in the range from 1 to Count. Each number should be separated with a comma. A range of numbers may be indicated with a lower and upper number separated with a colon. For example, a message set of "1, 5:7, 12" will retrieve 5 messages: 1, 5, 6, 7, and 12.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol
  • ptTimeout
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Count Property
Mailbox Object : Count Property
Description
Number of messages in the server mailbox. The Refresh method is used to initialize the value of this property.
Property type
Read-only property
Syntax
Visual Basic
Public Property Count As Long
Remarks
This property is updated whenever an action is performed on the mailbox. Use the Refresh method to update this property without performing an action on the mailbox.
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Delimiter Property
Mailbox Object : Delimiter Property
Description
Used to parse Name into a hierarchy.
Property type
Read-only property
Syntax
Visual Basic
Public Property Delimiter As String
Remarks

The Name property may contain a name that is to be parsed into a hierarchy. Use this property as a separator for parsing. For example the name /home/testuser/mailbox1 may be the value for the name. The name should be parsed using the "/" delimiter into a hierarchy.

See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Flags Property
Mailbox Object : Flags Property
Description
Collection of flags set for the mailbox.
Property type
Read-only property
Syntax
Visual Basic
Public Property Flags As DartStrings
Remarks

The following are examples and definitions of flags that the server may set for the mailbox:

  • \Marked Mailbox has been marked "interesting" by the server; commonly means the mailbox contains new messages.
  • \Unmarked Mailbox does not contain any additional messages since the last time it was accessed.
  • \Noinferiors Mailbox cannot contain any sub-mailboxes.
  • \Noselect Mailbox may not contain messages. Typically used for storing sub-mailboxes.
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Messages Property
Mailbox Object : Messages Property
Description
Collection of Message Objects that is the default destination for downloaded messages when using Get.
Property type
Read-write property
Syntax
Visual Basic
Public Property Messages As Messages
Remarks

This property provides the default destination for Get operations. Initially, this collection is empty. If Get is then used to request header information for messages 1, 3, and 5, three Message Objects are created and added to this collection to hold the data provided by the server.

The index for the message reflects the position in the collection, not the message number on the server. The message's Attribute property can be used to correlate downloaded messages with messages on the server.

See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Name Property
Mailbox Object : Name Property
Description
Mailbox name.
Property type
Read-write property
Syntax
Visual Basic
Public Property Name As String
Remarks

The Refresh method is used to initialize the value of this property. Change this property to rename the mailbox on the server. If the new value is the same as the current value or the Mailbox Object is not part of a Mailboxes collection, then no operation is performed.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol
  • ptTimeout
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

ReadOnly Property
Mailbox Object : ReadOnly Property
Description
Mailbox is read-only or read-write.
Property type
Read-write property
Syntax
Visual Basic
Public Property ReadOnly As Boolean
Remarks

Set to False to attempt to reopen the mailbox as read-write during the next operation on the mailbox. Set to True to attempt to reopen the mailbox as read-only during the next operation on the mailbox.

If the mailbox cannot be reopened to its new state then the property is set to its original value. Setting this property to the current value has no effect.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol
  • ptTimeout
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Recent Property
Mailbox Object : Recent Property
Description
Number of messages in the mailbox with a "Recent" flag.
Property type
Read-only property
Syntax
Visual Basic
Public Property Recent As Long
Remarks
This property is updated whenever an action is performed on the mailbox. Use the Refresh method to update this property without performing an action on the mailbox.
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Uid Property
Mailbox Object : Uid Property
Description
Unique identifier of the mailbox. The Refresh method is used to initialize the value of this property.
Property type
Read-only property
Syntax
Visual Basic
Public Property Uid As String
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Unseen Property
Mailbox Object : Unseen Property
Description
Number of messages marked "Unseen" in the server mailbox. The Refresh method is used to initialize the value of this property.
Property type
Read-only property
Syntax
Visual Basic
Public Property Unseen As Long
Remarks
This property is updated whenever an action is performed on the mailbox. Use the Refresh method to update this property without performing an action on the mailbox.
See Also

Mailbox Object | Mailbox Members


%%PageItemTitle%%

Mailboxes Collection
Members
Description
The Mailboxes Object represents a collection of Mailbox Objects returned from an IMAP server.
See Also

Mailboxes Members


%%PageItemTitle%% $$Members$$

Mailboxes Collection Members
Overview
Public Methods
Public Method Add | Create a mailbox.
Public Method Item | Provides array access to the collection.
Public Method Remove | Remove a mailbox.
Public Method Subscribe | Subscribe to a public mailbox.
Public Method Unsubscribe | Unsubscribe from a public mailbox.
Public Properties
Public Property Count Number of mailboxes in the collection.
See Also

Mailboxes Collection


%%PageItemTitle%%

Add Method
Mailboxes Collection : Add Method
Mailbox Object to add to the collection and create on the server. The mailbox Name property is used when creating on the server.
Description
Create a mailbox.
Syntax
Visual Basic
Public Sub Add( _
   ByVal Mailbox As Mailbox _
)
Parameters
Mailbox
Mailbox Object to add to the collection and create on the server. The mailbox Name property is used when creating on the server.
Remarks
This method adds a Mailbox object to the local collection and creates the mailbox on the server. If the mailbox already exists, a runtime error is generated. The mailbox is added to the local collection if the command succeeds; otherwise, the mailbox is not added.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol (if mailbox already exists)
  • ptTimeout
See Also

Mailboxes Collection | Mailboxes Members


%%PageItemTitle%%

Item Method
Mailboxes Collection : Item Method
Long index or String. Contains the mailbox name to return.
Description
Provides array access to the collection.
Syntax
Visual Basic
Public Function Item( _
   ByVal Index As Variant _
) As Mailbox
Parameters
Index
Long index or String. Contains the mailbox name to return.
Remarks
The Item method may be used to access a mailbox by index in the collection or by the name of the mailbox.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptInvalidParam1
See Also

Mailboxes Collection | Mailboxes Members


%%PageItemTitle%%

Remove Method
Mailboxes Collection : Remove Method
Long index or String. Specifies the mailbox name to remove.
Description
Remove a mailbox.
Syntax
Visual Basic
Public Sub Remove( _
   ByVal Index As Variant _
)
Parameters
Index
Long index or String. Specifies the mailbox name to remove.
Remarks
This method removes the corresponding Mailbox Object from the collection and deletes the mailbox from the server. The mailbox is removed from the local collection if the command succeeds; otherwise, it is not removed from the collection.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptInvalidParam1 (if mailbox does not exist in collection)
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol (A protocol error was encountered)
  • ptTimeout
See Also

Mailboxes Collection | Mailboxes Members


%%PageItemTitle%%

Subscribe Method
Mailboxes Collection : Subscribe Method
Specifies the name of the public mailbox to subscribe to.
Description
Subscribe to a public mailbox.
Syntax
Visual Basic
Public Sub Subscribe( _
   ByVal Name As String _
)
Parameters
Name
Specifies the name of the public mailbox to subscribe to.
Remarks
A public mailbox is a mailbox that anyone can access. Messages usually cannot be deleted from public mailboxes unless special privileges are given.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol (Mailbox does not exist)
  • ptTimeout
See Also

Mailboxes Collection | Mailboxes Members


%%PageItemTitle%%

Unsubscribe Method
Mailboxes Collection : Unsubscribe Method
Specifies the name of the public mailbox to unsubscribe from.
Description
Unsubscribe from a public mailbox.
Syntax
Visual Basic
Public Sub Unsubscribe( _
   ByVal Name As String _
)
Parameters
Name
Specifies the name of the public mailbox to unsubscribe from.
Remarks
A public mailbox is a mailbox that everyone can access. Messages usually cannot be deleted from public mailboxes unless special privileges are given.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol (Not subscribed to mailbox)
  • ptTimeout
See Also

Mailboxes Collection | Mailboxes Members


%%PageItemTitle%%

Count Property
Mailboxes Collection : Count Property
Description
Number of mailboxes in the collection.
Property type
Read-only property
Syntax
Visual Basic
Public Property Count As Long
See Also

Mailboxes Collection | Mailboxes Members


%%PageItemTitle%%

Message Object
Members
Description

The Message Object transforms any Internet mail message into an object that you can easily manipulate within your program. Alternatively, any message that you build or modify can be quickly encoded and sent.

Most of the properties manipulate the object model, with the exception of Content, which when set, dynamically creates a new object. When read, Content encodes the object model and returns it as a String or Byte array.

The Message Object provides complete support for MIME structures. High level methods (AddAttachment, Reply, Forward, AddMessage, AddText, and AddDigest) streamline the composition of sophisticated messages.

Additional features include persistence to disk in two formats: transport ready (encoded) message format and a quick loading (decoded) object format.

Object Model
Message ObjectPart ObjectHeaderFields CollectionParts CollectionPart ObjectHeaderFields CollectionParts CollectionPart ObjectHeaderFields CollectionParts CollectionPart ObjectHeaderFields CollectionParts CollectionDartStrings CollectionDartStrings CollectionDartStrings CollectionMessage ObjectPart ObjectPart ObjectPart ObjectPart ObjectDartStrings CollectionDartStrings CollectionDartStrings CollectionMessage ObjectHeaderFields CollectionPartList CollectionParts CollectionMessage ObjectDartStrings CollectionHeaderFields CollectionPartList CollectionParts CollectionMessage ObjectPart ObjectPart ObjectPart ObjectPart ObjectDartStrings CollectionDartStrings CollectionDartStrings CollectionMessage ObjectHeaderFields CollectionPartList CollectionParts CollectionMessage ObjectDartStrings CollectionDartStrings Collection
See Also

Message Members


%%PageItemTitle%% $$Members$$

Message Object Members
Overview
Public Methods
Public Method AddAttachment | Attach a file to the message.
Public Method AddDigest | Create a digest message such as that used to archive newsgroup or mailing list correspondence.
Public Method AddHtml | Create a ready-to-send HTML email message.
Public Method AddMessage | Attach an existing message to the message.
Public Method AddText | Add a text body part, optionally specifying a character set.
Public Method Browse | Activate the edit window. This is a debugging feature that supports run-time access for message browsing and editing.
Public Method Decode | Decode a message from consecutive buffers of encoded data.
Public Method DecodeBuf | Decode a single buffer.
Public Method Encode | Generate consecutive segments of the encoded message stream.
Public Method EncodeBuf | Encode a buffer.
Public Method Forward | Create a "forwarded" message to the specified recipient.
Public Method Load | Load a message from disk.
Public Method Reply | Create a "reply" message to sender or all recipients.
Public Method Store | Store a message in a file.
Public Properties
Public Property AttachmentDefaults | When an attachment is added to a message, header fields are included that describe the attachment. This property provides default header fields for common attachment file types. These strings may be modified or more added so subsequent calls to the AddAttachment method use the header fields you provide.
Public Property AttachmentDirectory | Directory for decoded mail attachments.
Public Property AttachmentOverwrite | Specifies whether decoded message attachments are overwritten if the filename is the same.
Public Property Attribute | Server-related attributes of the message.
Public Property Bcc | Collection of recipient address strings that are not disclosed to other recipients (Blind Carbon Copy).
Public Property Cc | Collection of address strings for the secondary recipients (Carbon Copy).
Public Property Charset | Gets and sets the preferred character set label that is used to for converting non-ASCII Unicode characters contained in the message body or message part to/from a byte encoded representation.
Public Property Content | Read from this property to encode the message or write to this property to initialize the object.
Public Property From | Specifies the author of the message.
Public Property Header | Collection of header fields contained in a Message Object or a Part Object.
Public Property PartList | Collection of all Part Objects in a multipart message.
Public Property Parts | Collection of "sibling" Part Objects existing at a single level in the message.
Public Property QuotedPrintable | When set to True, Quoted-Printable encoding is applied to textual parts of the message when it is encoded. When set to False, textual parts of the message are sent "as-is".
Public Property Size | Returns the size of the encoded message.
Public Property Subject | Subject of the message.
Public Property Text | Message text for non-multipart messages.
Public Property To | Collection of recipient address strings.
See Also

Message Object


%%PageItemTitle%%

AddAttachment Method
Message Object : AddAttachment Method
Fully qualified path of the file to attach.
Description
Attach a file to the message.
Syntax
Visual Basic
Public Function AddAttachment( _
   ByVal FileName As String _
) As Part
Parameters
FileName
Fully qualified path of the file to attach.
Return Value
The Part Object created and added to the message's Parts property.
Remarks

This method provides a simple way to attach a file to a message. The attributes of the file are determined by the file extension and AttachmentDefaults, which are used to correctly label and encode the file. Any number of attachments may be added.

The file does not have to exist yet, because the file is not read until encoding is performed. An error is generated if the file cannot be accessed.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptFile
  • ptNoBufferSpace
See Also

Message Object | Message Members


%%PageItemTitle%%

AddDigest Method
Message Object : AddDigest Method
String or Byte array providing the encoded message to be added to the digest, or a String containing the name of a file containing the message.
String or Byte Array. If provided on the first call, this parameter specifies introductory text for the digest.
Description
Create a digest message such as that used to archive newsgroup or mailing list correspondence.
Syntax
Visual Basic
Public Function AddDigest( _
   ByVal Message As Variant, _
   Optional ByVal Intro As Variant _
) As Part
Parameters
Message
String or Byte array providing the encoded message to be added to the digest, or a String containing the name of a file containing the message.
Intro
String or Byte Array. If provided on the first call, this parameter specifies introductory text for the digest.
Return Value
The Part Object object created and added to the message's Parts property.
Remarks
A mail digest is a collection of complete mail messages including the To/From/Subject/Date and message body, for a series of related messages. The messages may be related to a topic, or related by a period of time (for example, the month of January). The digest generally includes introductory text explaining the relationship of the messages that follow (for example, "Wall-Paper Appreciation Mailing list Archive for January, 1999").

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptFile
  • ptNoBufferSpace
See Also

Message Object | Message Members


%%PageItemTitle%%

AddHtml Method
Message Object : AddHtml Method
Fully qualified path of the HTML file to create the message from.
Description
Create a ready-to-send HTML email message.
Syntax
Visual Basic
Public Sub AddHtml( _
   ByVal FileName As String _
)
Parameters
FileName
Fully qualified path of the HTML file to create the message from.
Remarks

This method provides an easy way to create a ready-to-send HTML email message. When the method is called, the HTML file specified by FileName is grabbed and added as a part. The text from this file is also added as a part for any mail reader that cannot read HTML. All images referenced by the HTML text (using "img" tags) are added as parts to the message.

It is not advised to alter the Message object once it has been created using the AddHtml method.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptFile
  • ptNoBufferSpace
See Also

Message Object | Message Members


%%PageItemTitle%%

AddMessage Method
Message Object : AddMessage Method
String or Byte array providing the encoded message to be added to the new message part, or a String containing the name of the file containing the encoded message.
Description
Attach an existing message to the message.
Syntax
Visual Basic
Public Function AddMessage( _
   ByVal Message As Variant _
) As Part
Parameters
Message
String or Byte array providing the encoded message to be added to the new message part, or a String containing the name of the file containing the encoded message.
Return Value
The Part Object object created and added to the message's Parts property.
Remarks
This method provides a simple way to attach an existing message. Any number of existing messages can be added to a Message object. Although this method may be used to "Forward" a message, the Forward method is even easier to use.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptFile
  • ptNoBufferSpace
See Also

Message Object | Message Members


%%PageItemTitle%%

AddText Method
Message Object : AddText Method
String or Byte array with text to use for the part, or a String containing the name of the file containing the text to use for the part.
Specifies the character set. Any registered character set may be specified. Default is "us-ascii".
Description
Add a text body part, optionally specifying a character set.
Syntax
Visual Basic
Public Function AddText( _
   ByVal Text As Variant, _
   Optional ByVal Charset As String _
) As Part
Parameters
Text
String or Byte array with text to use for the part, or a String containing the name of the file containing the text to use for the part.
Charset
Specifies the character set. Any registered character set may be specified. Default is "us-ascii".
Return Value
The Part Object created and added to the message's Parts property.
Remarks

This method allows text parts to be added to multipart messages. Together with the AddAttachment, AddMessage, and AddDigest methods, many common message formats may be created.

This method is used to add text if the message is multipart (Message.Parts.Count > 0). If a non-multipart message is being composed, the Text property can be used instead.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptFile
  • ptNoBufferSpace
See Also

Message Object | Message Members


%%PageItemTitle%%

Browse Method
Message Object : Browse Method
Description
Activate the edit window. This is a debugging feature that supports run-time access for message browsing and editing.
Syntax
Visual Basic
Public Sub Browse()
Remarks

This method creates a modal edit dialog window allowing browsing and modification of the Message Object. You may load/save messages, as well as browse and edit the message structure and contents.

This method can be invoked from the Visual Basic Immediate window at any breakpoint to support your development.

See Also

Message Object | Message Members


%%PageItemTitle%%

Decode Method
Message Object : Decode Method
String or Byte array. Provides the encoded message stream.
Description
Decode a message from consecutive buffers of encoded data.
Syntax
Visual Basic
Public Sub Decode( _
   ByVal Segment As Variant _
)
Parameters
Segment
String or Byte array. Provides the encoded message stream.
Remarks

This method decodes a data stream of consecutive buffer segments. It is useful for decoding very large messages, where a large buffer assignment to the Content property would negatively impact the operating system or user interface.

The AttachmentDirectory property indicates if and where attachments will be stored.

The Content property can be set to an empty String to clear the contents of the Message Object between messages.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptFile
  • ptInvalidParam1
  • ptNoBufferSpace
See Also

Message Object | Message Members


%%PageItemTitle%%

DecodeBuf Method
Message Object : DecodeBuf Method
String or Byte array. String to be decoded.
String or Byte array. Buffer to receive the decoded result.
The type of decoding to apply.
Description
Decode a single buffer.
Syntax
Visual Basic
Public Sub DecodeBuf( _
   ByVal SourceBuf As Variant, _
   ByRef DestBuf As Variant, _
   ByVal CodingType As CodingConstants _
)
Parameters
SourceBuf
String or Byte array. String to be decoded.
DestBuf
String or Byte array. Buffer to receive the decoded result.
CodingType
Value | Description
msgBase64 | Base 64
msgBinHex40 | BinHex 4.0
msgEucJp | EucJp
msgIso2022Jp | Iso-2022Jp
msgQuotedPrintable | Quoted Printable
msgShiftJis | ShiftJis
msgUTF7 | UTF 7
msgUTF8 | UTF 8
msgUUEncode | UUENCODE
The type of decoding to apply.
Remarks

This function supports isolated decoding requirements such as header field interpretation. DecodeBuf does not affect the Message.

If DestBuf specifies a dimensioned Byte array or a non-empty String, it is redimensioned and filled with decoded data that may contain embedded nulls. If DestBuf specifies an undimensioned Byte array or empty String, it is dynamically expanded and filled. DestBuf must not be a fixed length String (String*100 will not work).

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptInvalidArg1
  • ptInvalidArg2
  • ptInvalidArg3
  • ptNoBufferSpace
See Also

Message Object | Message Members


%%PageItemTitle%%

Encode Method
Message Object : Encode Method
Byte Array. Provides the buffer to receive the next encoded message segment. A buffer length of 0 will reset encoding to the start of the message.
Description
Generate consecutive segments of the encoded message stream.
Syntax
Visual Basic
Public Function Encode( _
   ByVal Segment As Variant _
) As Long
Parameters
Segment
Byte Array. Provides the buffer to receive the next encoded message segment. A buffer length of 0 will reset encoding to the start of the message.
Return Value
Returns the number of bytes stored in Segment.
Remarks

Each use of this method generates another consecutive segment of the encoded message stream. Each segment can then be streamed by the SMTP Control (for example) for transmission.

Segment may be arbitrarily redimensioned as necessary. The value returned is the only indicator of the number of bytes encoded.

When the entire message is encoded, Segment returns a length of 0 indicating the end. The cycle of segments may be reset at any time by setting Segment to length 0; the next call to the Encode method returns the first segment.

The SMTP Control uses this method to encode and send all messages from its Message property.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptFile
  • ptInvalidParam1
  • ptNoBufferSpace
See Also

Message Object | Message Members


%%PageItemTitle%%

EncodeBuf Method
Message Object : EncodeBuf Method
String or Byte array. Data to be encoded.
String or Byte array. Buffer to receive the encoded result.
Type of encoding to apply.
Description
Encode a buffer.
Syntax
Visual Basic
Public Sub EncodeBuf( _
   ByVal SourceBuf As Variant, _
   ByRef DestBuf As Variant, _
   ByVal CodingType As CodingConstants _
)
Parameters
SourceBuf
String or Byte array. Data to be encoded.
DestBuf
String or Byte array. Buffer to receive the encoded result.
CodingType
Value | Description
msgBase64 | Base 64
msgBinHex40 | BinHex 4.0
msgEucJp | EucJp
msgIso2022Jp | Iso-2022Jp
msgQuotedPrintable | Quoted Printable
msgShiftJis | ShiftJis
msgUTF7 | UTF 7
msgUTF8 | UTF 8
msgUUEncode | UUENCODE
Type of encoding to apply.
Remarks

This function is provided to support isolated encoding requirements such as header label generation. This method does not affect the Message Object.

If DestBuf specifies a dimensioned Byte array or a non-empty String, it is redimensioned and filled with encoded data that may contain embedded nulls. If DestBuf specifies an undimensioned Byte array or empty String, it is dynamically expanded and filled. DestBuf must not be a fixed length String (String*100 will not work).

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptNoBufferSpace
  • ptInvalidArg1
  • ptInvalidArg2
  • ptInvalidArg3
See Also

Message Object | Message Members


%%PageItemTitle%%

Forward Method
Message Object : Forward Method
String containing addresses that the message is to be forwarded to.
Optional String or Byte array with introductory text for the forwarded message.
Description
Create a "forwarded" message to the specified recipient.
Syntax
Visual Basic
Public Function Forward( _
   ByVal To As String, _
   Optional ByVal Text As Variant _
) As Message
Parameters
To
String containing addresses that the message is to be forwarded to.
Text
Optional String or Byte array with introductory text for the forwarded message.
Return Value
New "forwarded" Message.
Remarks

This method returns a new message that contains the specified text and the original message. The new message contains the original message including attachments.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptNoBufferSpace
  • ptFile
See Also

Message Object | Message Members


%%PageItemTitle%%

Load Method
Message Object : Load Method
Contains the fully qualified filename to be loaded.
Determines how much of the message is to be read from the file. Defaults to msgMessage.
Description
Load a message from disk.
Syntax
Visual Basic
Public Sub Load( _
   ByVal File As String, _
   Optional ByVal Segment As SegmentConstants = msgMessage _
)
Parameters
File
Contains the fully qualified filename to be loaded.
Segment
Value | Description
msgHeader | Perform the operation on the header of the message.
msgMessage | Perform the operation on the complete message.
Determines how much of the message is to be read from the file. Defaults to msgMessage.
Remarks

This method senses the format of the file (encoded message or object) and initializes the Message Object as the file contents are read. See the Store method.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptNoBufferSpace
  • ptFile
See Also

Message Object | Message Members


%%PageItemTitle%%

Reply Method
Message Object : Reply Method
String or Byte array. Provides the new text for the reply message.
Provides the indent character string for the old message text. The default is ">".
Defaults to False. False addresses the reply to the sender of the original message; True addresses the reply to all recipients listed in the original message (To and Cc).
Description
Create a "reply" message to sender or all recipients.
Syntax
Visual Basic
Public Function Reply( _
   ByVal Text As Variant, _
   Optional ByVal Leader As String, _
   Optional ByVal All As Boolean = False _
) As Message
Parameters
Text
String or Byte array. Provides the new text for the reply message.
Leader
Provides the indent character string for the old message text. The default is ">".
All
Defaults to False. False addresses the reply to the sender of the original message; True addresses the reply to all recipients listed in the original message (To and Cc).
Return Value
The created Message.
Remarks

When responding to one or all recipients of a mail message, this method can be used to create the new message. The Content of the Reply will be the first text/plain MIME part.

The original text is indented with the specified Leader and prepended with Text. Any attachments are removed from the Reply.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptNoBufferSpace
  • ptInvalidParam1
See Also

Message Object | Message Members


%%PageItemTitle%%

Store Method
Message Object : Store Method
Contains the fully qualified filename to be created.
Specifies the format of the saved message. Defaults to msgEncoded.
Description
Store a message in a file.
Syntax
Visual Basic
Public Sub Store( _
   ByVal File As String, _
   Optional ByVal Format As FormatConstants = msgEncoded _
)
Parameters
File
Contains the fully qualified filename to be created.
Format
Value | Description
msgDecoded | Store the decoded object model version of the message.
msgEncoded | Store the encoded "transport-ready" version of the message.
Specifies the format of the saved message. Defaults to msgEncoded.
Remarks

If the Format parameter is msgEncoded or unspecified, the message will be stored as a transport ready file containing the encoded message.

If the Format parameter is msgDecoded the message will be stored in an object format. These files are smaller and quicker to read and write then an encoded file. Decoded files store attached files externally. In addition, data is stored as 8-bit data instead of the 7-bit data used in msgEncoded format. This results in smaller files and there is no decoding required when the file is loaded (see the Load method).

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptFile
  • ptInvalidParam2
  • ptNoBufferSpace
See Also

Message Object | Message Members


%%PageItemTitle%%

AttachmentDefaults Property
Message Object : AttachmentDefaults Property
Description
When an attachment is added to a message, header fields are included that describe the attachment. This property provides default header fields for common attachment file types. These strings may be modified or more added so subsequent calls to the AddAttachment method use the header fields you provide.
Property type
Read-write property
Syntax
Visual Basic
Public Property AttachmentDefaults As DartStrings
Remarks

Each string contains a single header field for an attachment type. Defaults are supplied by the control. Multiple strings may apply to the same file type. Typical strings may be:

  • "TXT:Content-Type: text/plain;charset=us-ascii"
  • "TXT:Content-dispositon: inline"

The text preceding the first colon always indicates the suffix of the file type to which the header field pertains.

See Also

Message Object | Message Members


%%PageItemTitle%%

AttachmentDirectory Property
Message Object : AttachmentDirectory Property
Description
Directory for decoded mail attachments.
Property type
Read-write property
Syntax
Visual Basic
Public Property AttachmentDirectory As String
Remarks

The default value is ".\" (the default directory). This property can only be set at run time.

A message can include attached files. When these messages are decoded, the filename from the message is combined with this property to produce the file path used to recreate the attached file.

Due to an operating system limitation, this value cannot be longer than 256 characters.

Note This property may be set at anytime for subsequent decoding operations.

If set to "" (an empty string) or the 'Content-Type' header does not include a name for the file, then the file is not created, and the Data property contains the decoded file.

See Also

Message Object | Message Members


%%PageItemTitle%%

AttachmentOverwrite Property
Message Object : AttachmentOverwrite Property
Description
Specifies whether decoded message attachments are overwritten if the filename is the same.
Property type
Read-write property
Syntax
Visual Basic
Public Property AttachmentOverwrite As Boolean
Remarks

Defaults to False.

By default, attachments create a unique number to add to their filename if there is already an existing file with the same name. When this property is set to false, existing files are overwritten by attachments.

See Also

Message Object | Message Members


%%PageItemTitle%%

Attribute Property
Message Object : Attribute Property
Description
Server-related attributes of the message.
Property type
Read-only property
Syntax
Visual Basic
Public Property Attribute( _
   ByVal Attribute As AttributeConstants _
) As Variant
Parameters
Attribute
Value | Description
msgAnswered | Message has been answered (IMAP only).
msgDeleted | Message is marked for removal (POP3 and IMAP).
msgDraft | Composition of message not complete (IMAP only).
msgFlagged | Message is marked for urgent attention (IMAP only).
msgNumber | Message number assigned by a POP3 or IMAP server.
msgRecent | Message is new this session (IMAP only).
msgSeen | Message has been read (IMAP only).
msgUid | Message unique id assigned by a POP3 or IMAP server.
Remarks
This value sets and returns the server-related attributes of a message.
See Also

Message Object | Message Members


%%PageItemTitle%%

Bcc Property
Message Object : Bcc Property
Description
Collection of recipient address strings that are not disclosed to other recipients (Blind Carbon Copy).
Property type
Read-write property
Syntax
Visual Basic
Public Property Bcc As DartStrings
Remarks
The message is sent to these recipients, but the Bcc header field is removed from the message before it is sent.
See Also

Message Object | Message Members


%%PageItemTitle%%

Cc Property
Message Object : Cc Property
Description
Collection of address strings for the secondary recipients (Carbon Copy).
Property type
Read-write property
Syntax
Visual Basic
Public Property Cc As DartStrings
See Also

Message Object | Message Members


%%PageItemTitle%%

Charset Property
Message Object : Charset Property
Description
Gets and sets the preferred character set label that is used to for converting non-ASCII Unicode characters contained in the message body or message part to/from a byte encoded representation.
Property type
Read-write property
Syntax
Visual Basic
Public Property Charset As String
Remarks

When communicating with international mail clients, you may need to be aware of Unicode character encoding/decoding issues. At the highest level, character encoding/decoding can be viewed as taking a visual string representation displayable in a UI, translating that visual string representation into a multi-byte values for transmission between systems, then retranslating the multi-byte values back into the original visual string (Unicode) representation. For this operation to occur successfully, the correct preferred character set must be specified so that the correct codepage is used. A codepage is a mapping between a Unicode visual character and a multi-byte sequence. This mapping is unique for different codepages.

When Message.Charset is specified, the value only affects text that is added by using Message.Text. This will no impact any of the parts. To specify the character set on a part, Part.Charset must be set.

In order to properly decode the encoded data back to its original form, you must know the character set that was used to encode the data. When dealing with message data or message part data, this information can be found in the "charset" label of the "content-type" header like so:

Content-Type: text/plain; charset="big5"

The label above signifies that the data in this part was encoded using Chinese Big5 Unicode character set. Character sets map to an ANSI CodePage, in this case CodePage 950 for the big5 preferred character set, which define the multi-byte representation for a given Unicode character in the character set.

When creating a message, this property will default to the current system preferred character set. Set this property to override this behavior and specify a different character set. For example, if your operating system character set is "iso-8859-1" and you wish to use a Japanese character set, you would set this property to "iso-2022-jp".

When reading messages this property will contain the character set string used to encode the message or message part (if one was used).

This property applies to message/message parts only. To get/set the character set used to encode header fields, see HeaderFields.Charset.

See Also

Message Object | Message Members


%%PageItemTitle%%

Content Property
Message Object : Content Property
Specifies either the header or the complete message.
Specifies the return value is a String or a Byte array.
Description
Read from this property to encode the message or write to this property to initialize the object.
Property type
Read-write property
Syntax
Visual Basic
Public Property Content( _
   Optional ByVal Segment As SegmentConstants = msgMessage, _
   Optional ByVal ReturnType As ReturnTypeConstants = msgString _
) As Variant
Parameters
Segment
Value | Description
msgHeader | Perform the operation on the header of the message.
msgMessage | Perform the operation on the complete message.
Specifies either the header or the complete message.
ReturnType
Value | Description
msgByteArray | Return the value as a Byte array.
msgString | Return the value as a String.
Specifies the return value is a String or a Byte array.
Return Value
String or Byte array.
Remarks

The Message Object represents a message as properties and collections of properties. The header is comprised of the To, Cc, Bcc, and Header properties. These elements are formatted to produce the encoded header. The message text and attachments are stored in Part Objects and are managed by the PartList Object and Parts Collection.

When setting this property, the Segment and ReturnType parameters are ignored if provided. Setting this property causes a re-initialization of the object. By setting this property to "" (an empty string), the object is cleared of all content.

When reading this property, Segment defaults to msgMessage and ReturnType defaults to msgString. Alternative parameters can be used to return only the encoded header and/or a Byte array. The message is dynamically encoded when this property is read. When Segment is msgHeader, the returned value includes a trailing CRLFCRLF sequence so that a message body can be easily appended.

This property is commonly used to populate a Message Object or to get an encoded message that may be saved or sent to a mail server.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptFile
  • ptInvalidParam1
  • ptInvalidParam2
  • ptNoBufferSpace
See Also

Message Object | Message Members


%%PageItemTitle%%

From Property
Message Object : From Property
Description
Specifies the author of the message.
Property type
Read-write property
Syntax
Visual Basic
Public Property From As String
Remarks
Sets and returns the From header value in the Header property.
See Also

Message Object | Message Members


%%PageItemTitle%%

Header Property
Message Object : Header Property
Description
Collection of header fields contained in a Message Object or a Part Object.
Property type
Read-write property
Syntax
Visual Basic
Public Property Header As HeaderFields
Remarks

The difference between the Header property associated with the Message Object and Part Object is the treatment of the To, Cc, and Bcc labels. The Message Object has separate properties for these labels, and therefore excludes these labels from the Header property. Part Objects include these labels within this property.

Refer to the HeaderFields Object for more information.

See Also

Message Object | Message Members


%%PageItemTitle%%

PartList Property
Message Object : PartList Property
Description
Collection of all Part Objects in a multipart message.
Property type
Read-only property
Syntax
Visual Basic
Public Property PartList As PartList
Remarks
The Message Object provides two means of accessing body parts in a multipart message. The Parts Object contains "sibling" Part Objects at a single level in the message and the PartList Object includes all (possibly nested) parts in the message.
See Also

Message Object | Message Members


%%PageItemTitle%%

Parts Property
Message Object : Parts Property
Description
Collection of "sibling" Part Objects existing at a single level in the message.
Property type
Read-write property
Syntax
Visual Basic
Public Property Parts As Parts
Remarks
Messages may include body parts that contain body parts that contain body parts, etc. This property contains only the "sibling" parts that exist at the level of the referenced Message Object or Part Object.
See Also

Message Object | Message Members


%%PageItemTitle%%

QuotedPrintable Property
Message Object : QuotedPrintable Property
Description
When set to True, Quoted-Printable encoding is applied to textual parts of the message when it is encoded. When set to False, textual parts of the message are sent "as-is".
Property type
Read-write property
Syntax
Visual Basic
Public Property QuotedPrintable As Boolean
Remarks

The default value is False. You can set this property at design time.

Quoted-Printable encoding ensures the correct transmission of primarily textual information, while making is possible for the recipient to understand the message by inspection if it cannot be decoded. When set to False and the textual information being sent includes special characters (such as an "end of message" sequence), it is possible for your user to include text that cannot be sent.

See Also

Message Object | Message Members


%%PageItemTitle%%

Size Property
Message Object : Size Property
Description
Returns the size of the encoded message.
Property type
Read-only property
Syntax
Visual Basic
Public Property Size As Long
Remarks
When large messages are sent it is sometimes desirable to display a progress indication. This property provides an estimate of the size of the encoded message. When the POP Control Get method is used to get the size of a message, this property is initialized to the value provided by the server.
See Also

Message Object | Message Members


%%PageItemTitle%%

Subject Property
Message Object : Subject Property
Description
Subject of the message.
Property type
Read-write property
Syntax
Visual Basic
Public Property Subject As String
Remarks
This value sets and returns the Subject header value in the Header property.
See Also

Message Object | Message Members


%%PageItemTitle%%

Text Property
Message Object : Text Property
Description
Message text for non-multipart messages.
Property type
Read-write property
Syntax
Visual Basic
Public Property Text As String
Remarks
This property contains message text associated with a non-multipart message (Message.Parts.Count = 0). If the message is a multipart message (Message.Parts.Count > 0), then this property can be used to add a preface, which will be displayed by older email clients that do not support MIME.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptFile
  • ptNoBufferSpace
See Also

Message Object | Message Members


%%PageItemTitle%%

To Property
Message Object : To Property
Description
Collection of recipient address strings.
Property type
Read-write property
Syntax
Visual Basic
Public Property To As DartStrings
See Also

Message Object | Message Members


%%PageItemTitle%%

Messages Collection
Members
Description
Collection of Message Objects.
See Also

Messages Members


%%PageItemTitle%% $$Members$$

Messages Collection Members
Overview
Public Methods
Public Method Add | Add a message to the collection.
Public Method Clear | Remove all messages from the collection.
Public Method Item | Provides array access to the collection.
Public Method Remove | Remove a message the collection.
Public Properties
Public Property Count Number of Messages in the collection.
See Also

Messages Collection


%%PageItemTitle%%

Add Method
Messages Collection : Add Method
Message Object to add to the collection.
Defaults to the end of the collection. Specifies where in the collection the Message should be inserted.
Description
Add a message to the collection.
Syntax
Visual Basic
Public Sub Add( _
   ByVal Message As Message, _
   Optional ByVal Index As Long = 0 _
)
Parameters
Message
Message Object to add to the collection.
Index
Defaults to the end of the collection. Specifies where in the collection the Message should be inserted.
Remarks
An object may be explicitly inserted at any point in the collection through use of the Index parameter. If the Index parameter is not specified, then Message will be added to the end of the collection.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptNoBufferSpace
  • ptFile
  • ptInvalidParam1
  • ptInvalidParam2
See Also

Messages Collection | Messages Members


%%PageItemTitle%%

Clear Method
Messages Collection : Clear Method
Description
Remove all messages from the collection.
Syntax
Visual Basic
Public Sub Clear()
Remarks
Use of this method results in an empty collection (the Count property returns zero).
See Also

Messages Collection | Messages Members


%%PageItemTitle%%

Item Method
Messages Collection : Item Method
Index of the Message to return.
Description
Provides array access to the collection.
Syntax
Visual Basic
Public Function Item( _
   ByVal Index As Long _
) As Message
Parameters
Index
Index of the Message to return.
Return Value
Message found at Index position in the collection.
Remarks

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptInvalidParam1
See Also

Messages Collection | Messages Members


%%PageItemTitle%%

Remove Method
Messages Collection : Remove Method
Index of the Message to remove.
Description
Remove a message the collection.
Syntax
Visual Basic
Public Sub Remove( _
   ByVal Index As Long _
)
Parameters
Index
Index of the Message to remove.
Remarks
Index is a ones-based numeric value indicating the position of the object in the collection.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptInvalidParam1
See Also

Messages Collection | Messages Members


%%PageItemTitle%%

Count Property
Messages Collection : Count Property
Description
Number of Messages in the collection.
Property type
Read-only property
Syntax
Visual Basic
Public Property Count As Long
See Also

Messages Collection | Messages Members


%%PageItemTitle%%

Part Object
Members
Description
Use the Part Object to perform complex manipulation of message parts.
Object Model
Part ObjectHeaderFields CollectionParts Collection
See Also

Part Members


%%PageItemTitle%% $$Members$$

Part Object Members
Overview
Public Properties
Public Property Charset | Gets and sets the preferred character set label that is used to for converting non-ASCII Unicode characters contained in the message body or message part to/from a byte encoded representation.
Public Property Data | Message data contained in the Part Object.
Public Property Error | Indicates that an MD5 digest string was included and the digest has been checked and found invalid. This suggests that the received message part does not match the authored message part.
Public Property File | The attached (decoded) file for this Part.
Public Property Header | A collection of header fields for this part.
Public Property Index | Identifier for a body part. This value is recalculated whenever changes to the message structure occur.
Public Property Name | Name of attachment or inline part.
Public Property Parts | Collection of "sibling" Part Objects existing at a single level in the message.
See Also

Part Object


%%PageItemTitle%%

Charset Property
Part Object : Charset Property
Description
Gets and sets the preferred character set label that is used to for converting non-ASCII Unicode characters contained in the message body or message part to/from a byte encoded representation.
Property type
Read-write property
Syntax
Visual Basic
Public Property Charset As String
Remarks

When communicating with international mail clients, you may need to be aware of Unicode character encoding/decoding issues. At the highest level, character encoding/decoding can be viewed as taking a visual string representation displayable in a UI, translating that visual string representation into a multi-byte values for transmission between systems, then retranslating the multi-byte values back into the original visual string (Unicode) representation. For this operation to occur successfully, the correct preferred character set must be specified so that the correct codepage is used. A codepage is a mapping between a Unicode visual character and a multi-byte sequence. This mapping is unique for different codepages.

When Message.Charset is specified, the value only affects text that is added by using Message.Text. This will no impact any of the parts. To specify the character set on a part, Part.Charset must be set.

In order to properly decode the encoded data back to its original form, you must know the character set that was used to encode the data. When dealing with message data or message part data, this information can be found in the "charset" label of the "content-type" header like so:

Content-Type: text/plain; charset="big5"

The label above signifies that the data in this part was encoded using Chinese Big5 Unicode character set. Character sets map to an ANSI CodePage, in this case CodePage 950 for the big5 preferred character set, which define the multi-byte representation for a given Unicode character in the character set.

When creating a message, this property will default to the current system preferred character set. Set this property to override this behavior and specify a different character set. For example, if your operating system character set is "iso-8859-1" and you wish to use a Japanese character set, you would set this property to "iso-2022-jp".

When reading messages this property will contain the character set string used to encode the message or message part (if one was used).

This property applies to message/message parts only. To get/set the character set used to encode header fields, see HeaderFields.Charset.

See Also

Part Object | Part Members


%%PageItemTitle%%

Data Property
Part Object : Data Property
Specifies the return value as a String or a Byte array. Defaults to msgString.
Description
Message data contained in the Part Object.
Property type
Read-write property
Syntax
Visual Basic
Public Property Data( _
   Optional ByVal ReturnType As ReturnTypeConstants = msgString _
) As Variant
Parameters
ReturnType
Value | Description
msgByteArray | Return the value as a Byte array.
msgString | Return the value as a String.
Specifies the return value as a String or a Byte array. Defaults to msgString.
Return Value
String or Byte array.
Remarks

This property contains data associated with the part.

If the part references an attached file, and the AttachmentDirectory property is "" (empty string), this property contains the file contents when the message is decoded. Otherwise, the property is empty.

If the part contains text, this property is used to set or read the text. When this property is set, ReturnType is ignored. The Data and File properties are mutually exclusive.

If the inline part is a file, the file data is available in either this property or the File property. The filename is available in the Name property.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptFile
  • ptInvalidParam1
  • ptNoBufferSpace
See Also

Part Object | Part Members


%%PageItemTitle%%

Error Property
Part Object : Error Property
Description
Indicates that an MD5 digest string was included and the digest has been checked and found invalid. This suggests that the received message part does not match the authored message part.
Property type
Read-only property
Syntax
Visual Basic
Public Property Error As Boolean
Remarks

The integrity of individual body parts is reflected in this property. MD5 digest checking is always performed when a Content-MD5 label is detected. You can test for the existence of the MD5 label using the following code:

If Msg.Parts(1).Header( msgContentMD5 ) <> "" then label exists.
See Also

Part Object | Part Members


%%PageItemTitle%%

File Property
Part Object : File Property
Description
The attached (decoded) file for this Part.
Property type
Read-write property
Syntax
Visual Basic
Public Property File As String
Remarks

When a message containing an attachment is received, the filename is stripped of path information and the AttachmentDirectory property is prepended to the received name to produce this property. When composing, you may set the File property to the fully qualified name of the file to be attached.

File data is also available as a decoded string or encoded byte array in the Data property.

If the Part uses JIS encoding, and the system is Japanese, then the file is saved using Shift-JIS encoding.

See Also

Part Object | Part Members


%%PageItemTitle%%

Header Property
Part Object : Header Property
Description
A collection of header fields for this part.
Property type
Read-write property
Syntax
Visual Basic
Public Property Header As HeaderFields
See Also

Part Object | Part Members


%%PageItemTitle%%

Index Property
Part Object : Index Property
Description
Identifier for a body part. This value is recalculated whenever changes to the message structure occur.
Property type
Read-only property
Syntax
Visual Basic
Public Property Index As String
Remarks

This property is defined by the relative position of the Part Object within the structure of a message. If the structure of the message is altered, then this property changes.

This property is returned in the form Level1.Level2&ldots;Levelx. For example, "2.3.1" identifies this part as Message.Parts(2).Parts(3).Parts(1).

See Also

Part Object | Part Members


%%PageItemTitle%%

Name Property
Part Object : Name Property
Description
Name of attachment or inline part.
Property type
Read-only property
Syntax
Visual Basic
Public Property Name As String
See Also

Part Object | Part Members


%%PageItemTitle%%

Parts Property
Part Object : Parts Property
Description
Collection of "sibling" Part Objects existing at a single level in the message.
Property type
Read-write property
Syntax
Visual Basic
Public Property Parts As Parts
Remarks
Messages may include body parts that contain body parts that contain body parts, etc. This property contains only the "sibling" parts that exist at the level of the referenced Message Object or Part Object.
See Also

Part Object | Part Members


%%PageItemTitle%%

PartList Collection
Members
Description
Collection of all Part Objects in the message. Parts are ordered numerically by the Part.Index property.
See Also

PartList Members


%%PageItemTitle%% $$Members$$

PartList Collection Members
Overview
Public Methods
Public Method Item Provides array access into the collection.
Public Properties
Public Property Count The number of Part objects in the collection.
See Also

PartList Collection


%%PageItemTitle%%

Item Method
PartList Collection : Item Method
Index of the Part to return.
Description
Provides array access into the collection.
Syntax
Visual Basic
Public Function Item( _
   ByVal Index As Long _
) As Part
Parameters
Index
Index of the Part to return.
Return Value
The Part Object located at Index in the collection.
Remarks

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptInvalidParam1
See Also

PartList Collection | PartList Members


%%PageItemTitle%%

Count Property
PartList Collection : Count Property
Description
The number of Part objects in the collection.
Property type
Read-only property
Syntax
Visual Basic
Public Property Count As Long
See Also

PartList Collection | PartList Members


%%PageItemTitle%%

Parts Collection
Members
Description
Parts Class
See Also

Parts Members


%%PageItemTitle%% $$Members$$

Parts Collection Members
Overview
Public Methods
Public Method Add | Add a Part to the collection.
Public Method Clear | Removes all Part objects from the collection.
Public Method Item | Provides array access to the collection.
Public Method Remove | Remove a Part from the collection.
Public Properties
Public Property Count The number of Part objects in the collection.
See Also

Parts Collection


%%PageItemTitle%%

Add Method
Parts Collection : Add Method
Part Object to add to the collection.
Indicates the Part Object is to be added at this index value. Defaults to the end of the collection.
Description
Add a Part to the collection.
Syntax
Visual Basic
Public Sub Add( _
   ByVal Part As Part, _
   Optional ByVal Index As Long = 0 _
)
Parameters
Part
Part Object to add to the collection.
Index
Indicates the Part Object is to be added at this index value. Defaults to the end of the collection.
Remarks

The optional parameter Index indicates that Part is to be inserted at the specified index. This index is a ones based number up to the collection's Count property plus 1.

If Index is not specified, the Part object is added to the end of the collection.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptInvalidParam2
See Also

Parts Collection | Parts Members


%%PageItemTitle%%

Clear Method
Parts Collection : Clear Method
Description
Removes all Part objects from the collection.
Syntax
Visual Basic
Public Sub Clear()
Remarks
Use of this method results in an empty collection (the Count property returns zero).
See Also

Parts Collection | Parts Members


%%PageItemTitle%%

Item Method
Parts Collection : Item Method
Index of the Part to return.
Description
Provides array access to the collection.
Syntax
Visual Basic
Public Function Item( _
   ByVal Index As Long _
) As Part
Parameters
Index
Index of the Part to return.
Return Value
The Part at Index.
Remarks

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptInvalidParam1
See Also

Parts Collection | Parts Members


%%PageItemTitle%%

Remove Method
Parts Collection : Remove Method
Index of the Part to remove.
Description
Remove a Part from the collection.
Syntax
Visual Basic
Public Sub Remove( _
   ByVal Index As Long _
)
Parameters
Index
Index of the Part to remove.
Remarks

Index is a ones-based numeric value indicating the position of the object in the collection.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptInvalidParam1
See Also

Parts Collection | Parts Members


%%PageItemTitle%%

Count Property
Parts Collection : Count Property
Description
The number of Part objects in the collection.
Property type
Read-only property
Syntax
Visual Basic
Public Property Count As Long
See Also

Parts Collection | Parts Members


%%PageItemTitle%%

Pop Object
Members
Description

Use the POP Control to retrieve mail from any POP3 server. Retrieve and store sets of messages in the Messages property.

Powerful default operations are provided, including iteration through a message set to populate the Messages property.

Object Model
Pop ObjectICertificate ObjectMessages Collection
See Also

Pop Members


%%PageItemTitle%% $$Members$$

Pop Object Members
Overview
Public Methods
Public Method Abort | Abort any blocking method and release all system resources.
Public Method About | Display Control information in a dialog box.
Public Method ClearCertificate | Clears the Certificate object contained in the Cerificate property.
Public Method Command | Send any command to the server.
Public Method CommandEx | Send any command to the server.
Public Method Delete | Mark one or more messages for removal upon normal completion of the session.
Public Method Get | Get all or part of one or more messages.
Public Method Login | Connect to a POP3 server and authenticate in one easy step.
Public Method Logout | End a session.
Public Method Reset | Remove the "mark-for-delete" flag from all messages on the server.
Public Method Trace

Start or stop the accumulation of trace or debug data. Once started, this method accumulates data until it is turned off.

This method provides a convenient mechanism for viewing all data being sent and received over the connection and can be used to troubleshoot host interoperability issues and expose protocol communications.

Public Properties
Public Property AttachmentDirectory | Decoded message attachments are created in this directory.
Public Property AttachmentOverwrite | Specifies whether decoded message attachments are overwritten if the filename is the same.
Public Property Blocked | A True value indicates the control is currently executing a blocking method (Timeout is greater than 0), which has neither completed nor timed out with a ptTimeout error.
Public Property Certificate | Certificate Object to use when authenticating to the remote host.
Public Property Count | Returns the number of messages on the server.
Public Property IpV6 | Specifies whether hostname addresses should be favorably resolved to IPv6.
Public Property Messages | Collection of Message Objects that is the default destination for downloaded messages when using Get.
Public Property Preview | Number of lines of message body desired when using Get with msgPreview specified as a parameter.
Public Property Privacy | Specifies the security protocol (PCT, SSL2, SSL3, TLS, none) and type (Implicit, Explicit) used.
Public Property Security | Specifies criteria for accepting certificate credentials.
Public Property State | Provides status information to the user interface. The State event fires to signal that this property has changed.
Public Property Timeout | Controls the blocking behavior of methods that can be used in blocking and non-blocking ways.
Events
Public Event Authenticate | Fires when the remote host has sent a certificate to be authenticated.
Public Event Certificate | Fires when the remote host is requesting a certificate and the Certificate property is not set to a valid Certificate Object.
Public Event Error | Fires when an Error condition occurs.
Public Event Progress | Fires when a method has completed, the server has sent a reply, or progress information is available.
Public Event State | Fires when the State property changes.
See Also

Pop Object


%%PageItemTitle%%

Abort Method
Pop Object : Abort Method
Description
Abort any blocking method and release all system resources.
Syntax
Visual Basic
Public Sub Abort()
Remarks

Use this method at any time to abruptly release all resources. The State property is tcpClosed when this method returns.

Destruction of the control automatically uses this method to release all resources.

When a blocking call is in progress (like Get), and Abort is called with an immediate call to a second Get (or other method), the first Get method does not return until the subsequent Get method(s) complete. It will return a ptAbort error.

Calling Abort will raise a ptAbort Error event.

Note For TCP-based controls, the Abort method performs a "hard close", with a socket LINGER option time of 0. To prevent the socket from entering a WAIT_STATE, and to immediately release it for reuse, use Abort instead of Close.

CAUTION Use the Close method in most cases, as buffers are cleared and communications terminate gracefully. Use the Abort method only when the application in abruptly terminated while a blocking method is executing or under any other unusual circumstances.

See Also

Pop Object | Pop Members


%%PageItemTitle%%

About Method
Pop Object : About Method
Description
Display Control information in a dialog box.
Syntax
Visual Basic
Public Sub About()
See Also

Pop Object | Pop Members


%%PageItemTitle%%

ClearCertificate Method
Pop Object : ClearCertificate Method
Description
Clears the Certificate object contained in the Cerificate property.
Syntax
Visual Basic
Public Sub ClearCertificate()
Remarks
Use this to clear the currently set certificate and set it to nothing. This method is only necessary on some environments, otherwise the Certificate property will work.
See Also

Pop Object | Pop Members


%%PageItemTitle%%

Command Method
Pop Object : Command Method
The command to send.
Where the reply from the server will be stored. A message would not be returned for this parameter when the Progress event fires, as that information would be available elsewhere.
True if a multiline reply is expected, otherwise False.
Description
Send any command to the server.
Syntax
Visual Basic
Public Sub Command( _
   ByVal Command As String, _
   ByRef Reply As String, _
   ByVal Multiline As Boolean _
)
Parameters
Command
The command to send.
Reply
Where the reply from the server will be stored. A message would not be returned for this parameter when the Progress event fires, as that information would be available elsewhere.
Multiline
True if a multiline reply is expected, otherwise False.
Remarks

Allows execution of standard and non-standard extension. The response from the server is copied to the Reply parameter, and you determine success or failure of the command.

You must correctly set Multiline for the command being sent. If a multiline response is specified, but not returned from the server, this method times out looking for a response termination sequence. If a Multiline reply is received but not specified, only the first line of the response returns.

Command should not include a trailing CR/LF.

For scripting environments, use CommandEx.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol
  • ptTimeout
See Also

Pop Object | Pop Members


%%PageItemTitle%%

CommandEx Method
Pop Object : CommandEx Method
The command to send.
Where the reply from the server will be stored. A message would not be returned for this parameter when the Progress event fires, as that information would be available elsewhere.
True if a multiline reply is expected, otherwise False.
Description
Send any command to the server.
Syntax
Visual Basic
Public Sub CommandEx( _
   ByVal Command As String, _
   ByRef Reply As Variant, _
   ByVal Multiline As Boolean _
)
Parameters
Command
The command to send.
Reply
Where the reply from the server will be stored. A message would not be returned for this parameter when the Progress event fires, as that information would be available elsewhere.
Multiline
True if a multiline reply is expected, otherwise False.
Remarks

This method is functionally equivalent to Command, but CommandEx can be used in a scripting environment.

Allows execution of standard and non-standard extension. The response from the server is copied to the Reply parameter, and you determine success or failure of the command.

You must correctly set Multiline for the command being sent. If a multiline response is specified, but not returned from the server, this method times out looking for a response termination sequence. If a Multiline reply is received but not specified, only the first line of the response returns.

Command should not include a trailing CR/LF.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol
  • ptTimeout
See Also

Pop Object | Pop Members


%%PageItemTitle%%

Delete Method
Pop Object : Delete Method
Specifies the message numbers to remove. The default is all messages. If provided, this string must indicate one or more values in the range from 1 to Count (for example, "1:12, 15, 18").
Description
Mark one or more messages for removal upon normal completion of the session.
Syntax
Visual Basic
Public Sub Delete( _
   Optional ByVal MsgSet As String _
)
Parameters
MsgSet
Specifies the message numbers to remove. The default is all messages. If provided, this string must indicate one or more values in the range from 1 to Count (for example, "1:12, 15, 18").
Remarks

The messages specified by MsgSet are "marked-for-delete". Message removal occurs when the session is gracefully ended using Logout. If Logout is not used all messages marked for deletion are "unmarked".

Call the Reset method to unmark messages "marked-for-delete".

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptInvalidParam1
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotInitialized
  • ptNotConnected
  • ptProtocol (A protocol error was encountered)
  • ptTimeout
See Also

Pop Object | Pop Members


%%PageItemTitle%%

Get Method
Pop Object : Get Method
Specifies the message part or attribute to be retrieved. Defaults to msgContent.
Specifies the message numbers to get. The default is all messages.
Optional String specifying the (local) destination file name, or an undimensioned String or Byte array that will be dynamically expanded and filled with a single message. If not specified or NULL, the Messages property will be used as the destination. This parameter is ignored unless Part is msgContent and MsgSet designates a single message.
Description
Get all or part of one or more messages.
Syntax
Visual Basic
Public Sub Get( _
   Optional ByVal Part As PartConstants = msgContent, _
   Optional ByVal MsgSet As String, _
   Optional ByRef Msg As Variant _
)
Parameters
Part
Value | Description
msgContent | Requests the retrieval of the complete message for each message in MsgSet.
msgPreview | Requests the message header followed by 'n' lines, where 'n' is the value of the Preview property.
msgSize | Requests the size for each message specified in MsgSet.
msgUidl | Requests the message UID label for each message in MsgSet.
Specifies the message part or attribute to be retrieved. Defaults to msgContent.
MsgSet
Specifies the message numbers to get. The default is all messages.
Msg
Optional String specifying the (local) destination file name, or an undimensioned String or Byte array that will be dynamically expanded and filled with a single message. If not specified or NULL, the Messages property will be used as the destination. This parameter is ignored unless Part is msgContent and MsgSet designates a single message.
Remarks

This method makes it easy to download any or all parts of a set of messages. The default destination for messages is the Messages property.

If provided, MsgSet specifies one or more message numbers in the range from 1 to Count. Each number should be separated with a comma. A range of numbers may be indicated with a lower and upper number separated with a colon. For example, a message set of "1, 5:7, 12" will retrieve 5 messages: 1, 5, 6, 7, and 12. The POP protocol does support any other criteria for downloading messages.

If the destination is the Messages Collection, this method creates all required Message Objects. If a Message Object exists with the same Attribute(msgNumber) property, it is reused. Therefore, you can first get the Size of messages causing creation of a Message object for each message. Getting the msgContent reuses the Message Objects previously created.

To discover what messages have arrived since the last download, save the number of messages in the mailbox at the end of each session. When you return, the mailbox may have more messages that you can reference by number. Alternatively, use Part=msgUidl. This creates a collection of Message Objects with the Attribute(msgNumber) property initialized to the UID of each message. Then set MsgSet to all the message numbers with UIDs that you have not yet downloaded.

If Msg is specified, MsgSet must reference a single message. If Msg is a buffer and Timeout is 0 (non-blocking), Msg must not go out of scope while the operation completes (the Msg String or Byte array should be global in scope).

If you use the Delete method to mark a message for deletion, and you subsequently include this message in MsgSet, then the ptInvalidParam2 error is generated. If a message is "marked for delete", and MsgSet is not specified (all messages are to be retrieved), then messages "marked for delete" are skipped, protecting you from a server error.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptInvalidParam1
  • ptInvalidParam2
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptNotInitialized
  • ptProtocol (A protocol error was encountered)
  • ptTimeout
See Also

Pop Object | Pop Members


%%PageItemTitle%%

Login Method
Pop Object : Login Method
A hostname or IP address.
Specifies the server account to access.
Specifies the password for the server account.
Specifies the desired port number. Defaults to port 110 (or 995 for implicitly secure connections).
Description
Connect to a POP3 server and authenticate in one easy step.
Syntax
Visual Basic
Public Sub Login( _
   ByVal Server As String, _
   Optional ByVal Username As String, _
   Optional ByVal Password As String, _
   Optional ByVal RemotePort As Long = 0 _
)
Parameters
Server
A hostname or IP address.
Username
Specifies the server account to access.
Password
Specifies the password for the server account.
RemotePort
Specifies the desired port number. Defaults to port 110 (or 995 for implicitly secure connections).
Remarks

Most POP servers require a Username and Password; typically both should be specified. After a successful login the Count property is set to the number of messages on the server.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptAbort
  • ptAddressNotAvailable
  • ptAddressInUse
  • ptAuthentication (An Invalid Username or Password was specified)
  • ptBlocked
  • ptConnected
  • ptConnectionAborted
  • ptConnectionRefused
  • ptConnectionReset
  • ptHostNotFound
  • ptNetworkDown
  • ptNetworkReset
  • ptNetworkUnreachable
  • ptNoBufferSpace
  • ptNoData
  • ptNotInitialized
  • ptProtocol (A protocol error was encountered)
  • ptTimeout
  • ptTryAgain
See Also

Pop Object | Pop Members


%%PageItemTitle%%

Logout Method
Pop Object : Logout Method
Description
End a session.
Syntax
Visual Basic
Public Sub Logout()
Remarks

Call this method to end a session. Successful execution of this method permanently removes any "marked-for-delete" messages from the server, ends the session, and causes the server to terminate the connection. Failure to use this method causes the server to clear any pending "marked-for-delete" message flags.

The Message.Attribute(msgNumber) property of each message is set to 0.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptProtocol (A protocol error was encountered)
  • ptTimeout
See Also

Pop Object | Pop Members


%%PageItemTitle%%

Reset Method
Pop Object : Reset Method
Description
Remove the "mark-for-delete" flag from all messages on the server.
Syntax
Visual Basic
Public Sub Reset()
Remarks

After calling this method, unless messages are again "marked-for-delete" with Delete, no messages are deleted from the server when Logout is called.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptNotInitialized
  • ptProtocol (A protocol error was encountered)
  • ptTimeout
See Also

Pop Object | Pop Members


%%PageItemTitle%%

Trace Method
Pop Object : Trace Method
An undimensioned string dynamically expanded to contain trace data or a filename that is used to store all trace data. If not provided or a Null value, then trace data is no longer stored.
Defaults to False. A True value indicates that sent data should be traced.
Defaults to False. A True value indicates that received data should be traced.
Prompt to precede sent data.
Prompt to precede received data.
Description

Start or stop the accumulation of trace or debug data. Once started, this method accumulates data until it is turned off.

This method provides a convenient mechanism for viewing all data being sent and received over the connection and can be used to troubleshoot host interoperability issues and expose protocol communications.

Syntax
Visual Basic
Public Sub Trace( _
   Optional ByRef Result As Variant, _
   Optional ByVal Send As Boolean = False, _
   Optional ByVal Receive As Boolean = False, _
   Optional ByVal SendPrompt As String, _
   Optional ByVal ReceivePrompt As String _
)
Parameters
Result
An undimensioned string dynamically expanded to contain trace data or a filename that is used to store all trace data. If not provided or a Null value, then trace data is no longer stored.
Send
Defaults to False. A True value indicates that sent data should be traced.
Receive
Defaults to False. A True value indicates that received data should be traced.
SendPrompt
Prompt to precede sent data.
ReceivePrompt
Prompt to precede received data.
Remarks
ReceivePrompt and SendPrompt allow the application to specify what delimiters separate and label data being captured.
See Also

Pop Object | Pop Members


%%PageItemTitle%%

AttachmentDirectory Property
Pop Object : AttachmentDirectory Property
Description
Decoded message attachments are created in this directory.
Property type
Read-write property
Syntax
Visual Basic
Public Property AttachmentDirectory As String
Remarks

The default value is ".\" (the default directory). This property can only be set at run time.

A message can include attached files. When these messages are decoded, the filename from the message is combined with this property to produce the file path used to recreate the attached file.

Due to an operating system limitation, this value cannot be longer than 256 characters.

Note This property may be set at anytime for subsequent decoding operations.

If set to "" (an empty string) or the 'Content-Type' header does not include a name for the file, then the file is not created, and the Data property contains the decoded file.

See Also

Pop Object | Pop Members


%%PageItemTitle%%

AttachmentOverwrite Property
Pop Object : AttachmentOverwrite Property
Description
Specifies whether decoded message attachments are overwritten if the filename is the same.
Property type
Read-write property
Syntax
Visual Basic
Public Property AttachmentOverwrite As Boolean
Remarks

Defaults to False.

By default, attachments create a unique number to add to their filename if there is already an existing file with the same name. When this property is set to false, existing files are overwritten by attachments.

See Also

Pop Object | Pop Members


%%PageItemTitle%%

Blocked Property
Pop Object : Blocked Property
Description
A True value indicates the control is currently executing a blocking method (Timeout is greater than 0), which has neither completed nor timed out with a ptTimeout error.
Property type
Read-only property
Syntax
Visual Basic
Public Property Blocked As Boolean
Remarks

Check this property to prevent your application from prematurely exiting or destroying the control while it is blocking in a method.

Your application still processes normal Windows messages while blocked, and the user interface continues to function normally. Events still fire while blocked, so code placed in these events continues to execute.

Your application cannot execute another method (except the Abort method) while it is blocked; a ptBlocked error is generated. Use the Abort method to terminate a blocked method prematurely. Abort signals the blocked method to abort, and then returns. Shortly thereafter, the blocked method releases all system resources, calls the State event (with the object's State property set to ptClosed), and returns with the ptAbort error.

WARNING Terminating your application or destroying the TCP object while blocked in a method may cause a fatal application error. To prevent this, perform either of the following:

  • Only allow object destruction if the Blocked property returns False.
  • Never use a positive Timeout value.

See Also

Pop Object | Pop Members


%%PageItemTitle%%

Certificate Property
Pop Object : Certificate Property
Description
Certificate Object to use when authenticating to the remote host.
Property type
Read-write property
Syntax
Visual Basic
Public Property Certificate As ICertificate
Remarks
On the client side, this property is typically unused. If the server wants the client to authenticate and this property has not been set, then the Certificate event fires to allow you to set a certificate on demand.
See Also

Pop Object | Pop Members


%%PageItemTitle%%

Count Property
Pop Object : Count Property
Description
Returns the number of messages on the server.
Property type
Read-only property
Syntax
Visual Basic
Public Property Count As Long
Remarks

When Login is used to connect to a server and authenticate, this property is set to the number of messages in the user's mailbox. This property is valid during the session and returns 1 at other times.

Numbers between 1 and Count are used to reference messages on the server. Do not attempt to reference messages outside this range. The Count of messages remains constant for the session. Even when messages are "marked-for-delete" using the Delete method, Count does not change, because messages are not actually deleted until the session ends.

See Also

Pop Object | Pop Members


%%PageItemTitle%%

IpV6 Property
Pop Object : IpV6 Property
Description
Specifies whether hostname addresses should be favorably resolved to IPv6.
Property type
Read-write property
Syntax
Visual Basic
Public Property IpV6 As Boolean
See Also

Pop Object | Pop Members


%%PageItemTitle%%

Messages Property
Pop Object : Messages Property
Description
Collection of Message Objects that is the default destination for downloaded messages when using Get.
Property type
Read-write property
Syntax
Visual Basic
Public Property Messages As Messages
Remarks

This property provides the default destination for Get operations. Initially, this collection is empty. If Get is then used to request header information for messages 1, 3, and 5, three Message Objects are created and added to this collection to hold the data provided by the server.

The index for the message reflects the position in the collection, not the message number on the server. The message's Attribute property can be used to correlate downloaded messages with messages on the server.

See Also

Pop Object | Pop Members


%%PageItemTitle%%

Preview Property
Pop Object : Preview Property
Description
Number of lines of message body desired when using Get with msgPreview specified as a parameter.
Property type
Read-write property
Syntax
Visual Basic
Public Property Preview As Long
Remarks

The default value is 0.

When Get retrieves a preview of a message, the response includes the message header plus a number of lines from the beginning of the message body. The default value of 0 indicates that only the header is requested.

There is no guarantee that the preview lines returned are printable, or even intelligible. Commonly, however, they include some part of the text portion of the message.

See Also

Pop Object | Pop Members


%%PageItemTitle%%

Privacy Property
Pop Object : Privacy Property
Description
Specifies the security protocol (PCT, SSL2, SSL3, TLS, none) and type (Implicit, Explicit) used.
Property type
Read-write property
Syntax
Visual Basic
Public Property Privacy As MailPrivacyConstants
Remarks

The default value is privacyNone.

If the client and server specify protocols that are different, then the Error event will fire with Number=ptProtocol and the connection will be closed.

See Also

Pop Object | Pop Members


%%PageItemTitle%%

Security Property
Pop Object : Security Property
Description
Specifies criteria for accepting certificate credentials.
Property type
Read-write property
Syntax
Visual Basic
Public Property Security As SecurityConstants
Remarks
This property enables variable security settings, from absolute certificate confirmation to no security.
See Also

Pop Object | Pop Members


%%PageItemTitle%%

State Property
Pop Object : State Property
Description
Provides status information to the user interface. The State event fires to signal that this property has changed.
Property type
Read-only property
Syntax
Visual Basic
Public Property State As StateConstants
Remarks
To protect you from programming errors, most methods return an error condition if your code attempts to send data when no TCP connection exists. By checking the value of this property, your application can always determine the state of the connection.
See Also

Pop Object | Pop Members


%%PageItemTitle%%

Timeout Property
Pop Object : Timeout Property
Description
Controls the blocking behavior of methods that can be used in blocking and non-blocking ways.
Property type
Read-write property
Syntax
Visual Basic
Public Property Timeout As Long
Remarks

The default value is 30000 (30 seconds). This is a design-time property.

Most users will start using blocking operation. The developer's decision to use blocking (Timeout > 0) or non-blocking (Timeout = 0) operation is important; these controls were designed to consistently support both methods of operation.

When set to a positive number of milliseconds, methods block while waiting for the initial response from the method. For example, an FTP or HTTP Get() method on a file will block until response is received. The Blocked property indicates this state. For example, if the Connect method is used with a Timeout of 30000, then the method only returns without error if the connection is established within 30 seconds. This is the easiest design to implement, but not the most robust. If the user attempts to initiate a different method while the Blocked property is True, an error is generated. Also, if the user attempts to close the application while the Blocked property is True, abnormal program termination may result.

When set to 0, no method blocks. It is up to the application to sense the success or failure of the operation by putting code in the related event. For example, if the Connect method is used with a Timeout of 0, then the application can test for the value of the State property from within the State event. This is the most efficient technique, as no idle loops are used to capture the thread of execution waiting for an event to occur. This is also the safest way to use PowerTCP because non-blocking use allows PowerTCP to unload gracefully under any condition.

The novice will probably use blocking operation first because this is the easiest way to immediately use the product. With no explicit error handling enabled (for example, the VB OnError statement), methods return errors into the environment and program execution stops. Once you add error-handling code, most applications will work satisfactorily. While the thread is captured in the method, an idle loop processes Windows messages and few side effects will ever be noted. There are some limits, however, that you should be aware of:

  • The only way to abort a blocking method is to call the Abort method off a Timer or some user interface event.
  • With the exception of the Abort method, the developer can only be in one method at a time (this protects your program from reentrancy problems).
  • If the user closes the application while PowerTCP is blocking, the blocking method attempts to return when this is sensed, but a general protection fault may still be experienced (because the application is being terminated while PowerTCP is in an idle loop).

Non-blocking operations are more fault-tolerant. Set the Timeout property to 0 (at design time or at run time), initiate methods as desired, and insert most of your code in the appropriate event. This eliminates problems associated with reentrancy, users performing unanticipated actions in your application, and error recovery.

Note: Asynchronous operation is dependent upon an active MessageLoop. If an asynchronous operation is started, and subsequently a synchronous process (such as a lengthy database query) is started (immediately or off a timer), operation may be affected. In some development environments, the MessageLoop can be executed by calling DoEvents() repeatedly, but this design is not optimal. Preferred approaches include:

  • Operate the synchronous process on another worker thread
  • Operate the control itself on another thread or process
  • Split the synchronous process into smaller pieces that operate off a timer event
See Also

Pop Object | Pop Members


%%PageItemTitle%%

Authenticate Event
Pop Object : Authenticate Event
Remote host's certificate.
Indicates if the certificate was from a Trusted Root Authority (CA).
Indicates if the current date-time is within the certificate's life span.
Indicates if the certificate has a valid signature.
Set this value to True to authenticate the remote certificate or set it to False to deny it.
Description
Fires when the remote host has sent a certificate to be authenticated.
Syntax
Visual Basic
Public Event Authenticate( _
   ByVal RemoteCertificate As ICertificate, _
   ByVal TrustedRoot As Boolean, _
   ByVal ValidDate As Boolean, _
   ByVal ValidSignature As Boolean, _
   ByRef Valid As Boolean _
)
Parameters
RemoteCertificate
Remote host's certificate.
TrustedRoot
Indicates if the certificate was from a Trusted Root Authority (CA).
ValidDate
Indicates if the current date-time is within the certificate's life span.
ValidSignature
Indicates if the certificate has a valid signature.
Valid
Set this value to True to authenticate the remote certificate or set it to False to deny it.
Remarks
Typically, the remote certificate is rejected if TrustedRoot, ValidDate, or ValidSignature is False. This event allows you to ease or strengthen the restrictions on the remote host's certificate. To authenticate a certificate if one or all of the parameters are False, set Valid to True. You can also deny a certificate if the hostname is not the same as the IssuedTo property of the Certificate.
See Also

Pop Object | Pop Members


%%PageItemTitle%%

Certificate Event
Pop Object : Certificate Event
Description
Fires when the remote host is requesting a certificate and the Certificate property is not set to a valid Certificate Object.
Syntax
Visual Basic
Public Event Certificate()
Remarks
This event is used to set a certificate on demand. In some cases a server will request that the client authenticate, and it may not be desirable to set the Certificate property unless necessary.
See Also

Pop Object | Pop Members


%%PageItemTitle%%

Error Event
Pop Object : Error Event
ErrorConstants description.
Description
Fires when an Error condition occurs.
Syntax
Visual Basic
Public Event Error( _
   ByVal Error As MailErrorConstants, _
   ByVal Description As String _
)
Parameters
Error
Value | Description
mailAbort | The Abort method was called. FATAL.
mailAddressInUse | Address already in use. Only one usage of each socket address (protocol/IP address/port) is normally permitted. This error occurs if an application attempts to bind() a socket to an IP address/port that has already been used for an existing socket, or a socket that wasn't closed properly, or one that is still in the process of closing. For server applications that need to bind() multiple sockets to the same port number, the ReuseAddress property can be used. FATAL.
mailAddressNotAvailable | Cannot assign requested address. The requested address is not valid in its context. Normally results from an attempt to bind() to an address that is not valid for the local machine. This may also result from connect(), sendto(), WSAConnect(), WSAJoinLeaf(), or WSASendTo() when the remote address or port is not valid for a remote machine (for example, address or port 0). FATAL.
mailAttachUuencode | Only (uuencoded) files may be attached to this non-MIME message. Consider using MIME or putting all text in the Message.Data property area.
mailAuthentication | Authentication with the server failed. FATAL.
mailBadConfigItem | Invalid Configuration Item
mailBadDataType | Cannot create the requested data type or format.
mailBadRecipient | Mail Recipient Not Accepted.
mailBadSender | Sender address not accepted.
mailBlocked | User thread is blocking in another method. INFO.
mailCompile | An error occurred while compiling
mailConnected | A connection already exists
mailConnectionAborted | Software caused connection abort. An established connection was aborted by the software in your host machine, possibly due to a data transmission timeout or protocol error. FATAL.
mailConnectionRefused | Connection refused. No connection could be made because the target machine actively refused it. This usually results from trying to connect to a service that is inactive on the foreign host (for example,. one with no server application running). May also be generated by a Daemon that refuses a connection because its resources have been exhausted. FATAL.
mailConnectionReset | Connection reset by peer. An existing connection was forcibly closed by the remote host. This normally results if the peer application on the remote host is suddenly stopped, the host is rebooted, or the remote host used a "hard close" (see Abort method) on the remote socket. This error may also result if a connection was broken due to keep-alive activity detecting a failure while one or more operations are in progress. Operations that were in progress fail with ptNetworkReset. Subsequent operations fail with ptConnectionReset. FATAL.
mailDuplicateMessage | Message object already exists in collection.
mailError | Unexpected general error. FATAL.
mailFile | Error accessing local file storage. FATAL.
mailFileOpen | Unable to open file.
mailFileOperation | A file operation (such as size) had failed.
mailFileRead | A file read error has caused the operation to fail.
mailFileWrite | A file write error has occurred. Check disk free space.
mailFormatError | The server was unable to interpret the query.
mailHeader | Occurs when a proper termination (usually a CRLFCRLF) is not found in the header.
mailHostNotFound | Host not found. No such host is known. The name is not an official hostname or alias, or it cannot be found in the database(s) being queried. This error may also be returned for protocol and service queries, and means the specified name could not be found in the relevant database. FATAL.
mailHostUnreachable | Remote host does not exist
mailHttpInvalidUrl | The Url is unspecified or invalid.
mailInvalidMailAddress | The Email address specified was not valid.
mailInvalidMessageHeader | A recipient, from, and subject are needed for a valid message header.
mailInvalidParam1 | Parameter #1 is invalid. INFO.
mailInvalidParam2 | Parameter #2 is invalid. INFO.
mailInvalidParam3 | Parameter #3 is invalid. INFO.
mailInvalidParam4 | Parameter #4 is invalid. INFO.
mailInvalidProperty | Invalid property assignment. INFO.
mailInvDecodeType | An invalid or unsupported Decode Type was specified.
mailMsgObjRead | An error has occurred while reading data from the Message object. Verify the Message object contents.
mailNetworkDown | Network is down. A socket operation encountered a dead network. This could indicate a serious failure of the network system (for example,. the protocol stack that the Winsock DLL runs over), the network interface, or the local network itself. FATAL.
mailNetworkReset | Network dropped connection on reset. The connection has been broken due to keep-alive activity detecting a failure while the operation was in progress. FATAL.
mailNetworkUnreachable | Network is unreachable. A socket operation was attempted to an unreachable network. This usually means the local software knows no route to reach the remote host. FATAL.
mailNoAccess | The user does not have the proper permissions
mailNoAuthMech | No authentication mechanism was found in the server's advertised capabilities, a secure connection may be required.
mailNoBufferSpace | No buffer space available. An operation on a socket could not be performed because the system lacked sufficient buffer space or because a queue was full. FATAL.
mailNoCertificate | There was an error in creating credentials.
mailNoData | Valid name, no data record of requested type. The requested name is valid and was found in the database, but it does not have the correct associated data being resolved for. The usual example for this is a hostname -> address translation attempt which uses the DNS, and an MX record is returned but no A record - indicating the host itself exists but is not directly reachable. FATAL.
mailNoHeader | The message is invalid because the header was not found.
mailNoMemory | There was not enough memory available to complete the operation.
mailNoMessageHeader | The message does not contain a valid header.
mailNoRecipientsFound | The message header does not contain any (valid) recipients (To).
mailNoRecovery | This is a non-recoverable error. This indicates some sort of non-recoverable error occurred during a database lookup. This may be because the database files (for example, BSD-compatible HOSTS, SERVICES or PROTOCOLS files) could not be found, or a DNS (Domain Name Server) request was returned by the server with a severe error. FATAL.
mailNoSecurity | Secure communications is not available on this machine.
mailNotConnected | Socket is not connected. A request to send or receive data was disallowed because the socket is not connected or allocated. Any other type of operation might also return this error. FATAL.
mailNotFound | The name referred to in the query does not exist.
mailNotImplemented | The server does not support the request type of query.
mailNotInitialized | Network interface could not be initialized. FATAL.Host not found. No such host is known. The name is not an official hostname or alias, or it cannot be found in the database(s) being queried. This error may also be returned for protocol and service queries, and means the specified name could not be found in the relevant database. FATAL.
mailNotInSpoolMode | Method not allowed when spool mail mode is active.
mailNotMessageObject | The passed object is not a Message object.
mailNotPartObject | The operation requested requires an object of type Part.
mailOk | Ok
mailOnlyInSpoolMode | The DeSpool Method is only available when mail spooling is enabled.
mailOperationRefused | The server refused to perform the specified operation.
mailOptionNotSupported | The specified socket option is not supported by the system. INFO.
mailPartInStructure | The Part to Add already exists in this structure.
mailProtocol | Unexpected protocol error. FATAL.
mailServerError | There was a failure on the server.
mailSocks4DifferentUserID | The SOCKS4 server rejected the connection because the client program and identd report different user-ids
mailSocks4NoAcceptableMethods | The SOCKS5 server will not accept any of the requested methods
mailSocks4NoIdentd | The SOCKS4 server rejected the connection because it was unable to connect to identd on the client
mailSocks4RequestRejected | The SOCKS4 server rejected the connection (No reason given)
mailSocks5AddressTypeNotSupported | The SOCKS5 server reported that the address type is not supported
mailSocks5AuthFailed | The SOCKS5 server rejected the connection because authorization failed
mailSocks5CommandNotSupported | The SOCKS5 server reported that the command is not supported
mailSocks5ConnectionRefused | The SOCKS5 server reported that the host connection was refused
mailSocks5HostUnreachable | The SOCKS5 server reported that the host was unreachable
mailSocks5NetworkUnreachable | The SOCKS5 server reported that the network was unreachable
mailSocks5NoRuleSet | The SOCKS5 server reported that the connection was not allowed by the ruleset
mailSocks5ServerFailure | The SOCKS5 server reported a general failure
mailSocks5TTLExpired | The SOCKS5 server reported that the TTL has expired
mailTimeout | Timed out. A connection attempt failed because the connected party did not properly respond after a period of time, or an established connection failed because connected host has failed to respond. Alternatively, a blocked method failed to return within the period specified by the Timeout property. FATAL.
mailTryAgain | Non-authoritative host not found. This is usually a temporary error during hostname resolution and means that the local server did not receive a response from an authoritative server. A retry at some time later may be successful. FATAL.
mailUseMimeEncode | mailUseMimeEncoding must be Always, Never, or Smallest
Description
ErrorConstants description.
Remarks

Some environments, such as IIS Active Server Pages, do not support event handling. In this case the application must rely on blocking and the Error object that is returned to the container when an error condition occurs.

Note See the appropriate method and property description for a list of errors that may be generated.

See Also

Pop Object | Pop Members


%%PageItemTitle%%

Progress Event
Pop Object : Progress Event
Indicates the method that the event pertains to.
Indicates the Status of the method.
Contains the server reply related to the status.
Indicates the server-side message the event pertains to. Matches the message's Attribute(msgNumber) property.
Indicates the number of bytes that have transferred (so far) for the transfer that is currently in progress. The value normally falls between 0 and Size. Only valid when Status is popContent, and is 0 at other times.
Indicates the total number of bytes for the message transfer currently in progress. Value is constant during any single transfer. Only valid when Status is popContent, and is 0 at other times.
Description
Fires when a method has completed, the server has sent a reply, or progress information is available.
Syntax
Visual Basic
Public Event Progress( _
   ByVal Method As PopMethodConstants, _
   ByVal Status As PopStatusConstants, _
   ByVal Reply As String, _
   ByVal MessageNumber As Long, _
   ByVal Count As Long, _
   ByVal Size As Long _
)
Parameters
Method
Value | Description
popCommand | Command, CommandEx methods
popDelete | Delete method
popGet | Fetch method
popLogin | Login method
popLogout | Logout method
popReset | Reset method
popStls | StartTLS Command
Indicates the method that the event pertains to.
Status
Value | Description
popBad | The server has responded with a negative status.
popContent | Indicates intermediate events during the receipt of a mail message. Useful for percentage indication on a status display.
popCount | The Count property has been updated.
popDeleting | Indicates a message delete has been acknowledged.
popInfo | The server has supplied information.
popOk | The method has completed with a positive status.
popPreview | Retrieval of a complete message header plus preview lines.
popSize | The message Size property has been updated.
popUidl | Retrieval of a message UID label.
Indicates the Status of the method.
Reply
Contains the server reply related to the status.
MessageNumber
Indicates the server-side message the event pertains to. Matches the message's Attribute(msgNumber) property.
Count
Indicates the number of bytes that have transferred (so far) for the transfer that is currently in progress. The value normally falls between 0 and Size. Only valid when Status is popContent, and is 0 at other times.
Size
Indicates the total number of bytes for the message transfer currently in progress. Value is constant during any single transfer. Only valid when Status is popContent, and is 0 at other times.
Remarks
Use the Trace method to gather protocol-level data if the Reply parameter is inadequate.
See Also

Pop Object | Pop Members


%%PageItemTitle%%

State Event
Pop Object : State Event
Description
Fires when the State property changes.
Syntax
Visual Basic
Public Event State()
Remarks

WARNING Timeout must be 0 when calling methods from within an event. Failure to observe this rule may cause reentrancy problems and unpredictable results.

The Connect method (used to initiate an active connection) normally causes the State property to transition from tcpClosed to tcpConnecting (while resources are being allocated and the connection is being established) to tcpConnected, at which time communications activity can start.

The Close method normally causes the State property to transition from tcpConnected to tcpClosing (while resources are being de-allocated) to tcpClosed.

When the remote host closes the connection, there may still be data available in the stream. In this case, the State property is tcpClosing until all the data is received and the socket returns a 0 value, after which the State property changes to tcpClosed.

See Also

Pop Object | Pop Members


%%PageItemTitle%%

Smtp Object
Members
Description
Use the SMTP Control to send mail to any SMTP server. This control supports popular protocol extensions (ESMTP), provides both Blocking and high performance event-based non-blocking operation, and can be statically placed on a form or dynamically created in virtually any development environment.
Object Model
Smtp ObjectDartStrings CollectionICertificate ObjectMessage ObjectPart ObjectPart ObjectPart ObjectPart ObjectDartStrings CollectionDartStrings CollectionDartStrings CollectionMessage ObjectHeaderFields CollectionPartList CollectionParts CollectionMessage ObjectDartStrings CollectionDartStrings Collection
See Also

Smtp Members


%%PageItemTitle%% $$Members$$

Smtp Object Members
Overview
Public Methods
Public Method Abort | Abort any blocking method and release all system resources.
Public Method About | Display Control information in a dialog box.
Public Method ClearCertificate | Clears the Certificate object contained in the Cerificate property.
Public Method Command | Send any protocol command to the server.
Public Method CommandEx | Send any protocol command to the server.
Public Method DSN | Set parameters that define the type of Delivery Status Notification that will be requested for subsequent messages.
Public Method Login | Establish a session with a server.
Public Method Logout | End the session.
Public Method QuickSend | Build and send a message.
Public Method Reset | Recover from an error condition.
Public Method Send | Send message using the current session.
Public Method Trace

Start or stop the accumulation of trace or debug data. Once started, this method accumulates data until it is turned off.

This method provides a convenient mechanism for viewing all data being sent and received over the connection and can be used to troubleshoot host interoperability issues and expose protocol communications.

Public Method Verify | Validate an email address.
Public Properties
Public Property Blocked | A True value indicates the control is currently executing a blocking method (Timeout is greater than 0), which has neither completed nor timed out with a ptTimeout error.
Public Property Capabilities | Collection of strings that contains the protocol extensions supported by the server. Values are initialized during login.
Public Property Certificate | Certificate to use when authenticating to the remote host.
Public Property From | If provided, this return address is used for the SMTP envelope instead of the address found in the From header label of the message.
Public Property HelloName | A string value representing the hostname presented to the server during the greeting.
Public Property IpV6 | Specifies whether hostname addresses should be favorably resolved to IPv6.
Public Property Message | The message to be sent.
Public Property Privacy | Specifies the security protocol (PCT, SSL2, SSL3, TLS, none) and type (Implicit, Explicit) used.
Public Property Security | Sets the criteria for accepting certificates.
Public Property State | Provides status information to the user interface. The State event fires to signal that this property has changed.
Public Property Timeout | Controls the blocking behavior of methods that can be used in blocking and non-blocking ways.
Public Property To | If provided, these addresses will be used for the SMTP envelope instead of those found in the To, Cc, and Bcc header labels of the message.
Events
Public Event Authenticate | Fires when the remote host has sent a certificate to be authenticated.
Public Event Certificate | Fires when the remote host is requesting a certificate and the Certificate property is not set to a valid Certificate Object.
Public Event Error | Fires when an Error condition occurs.
Public Event Progress | Fires when a method has completed, the server has sent a reply, or progress information is available.
Public Event State | Fires when the State property changes.
See Also

Smtp Object


%%PageItemTitle%%

Abort Method
Smtp Object : Abort Method
Description
Abort any blocking method and release all system resources.
Syntax
Visual Basic
Public Sub Abort()
Remarks

Use this method at any time to abruptly release all resources. The State property is tcpClosed when this method returns.

Destruction of the control automatically uses this method to release all resources.

When a blocking call is in progress (like Get), and Abort is called with an immediate call to a second Get (or other method), the first Get method does not return until the subsequent Get method(s) complete. It will return a ptAbort error.

Calling Abort will raise a ptAbort Error event.

Note For TCP-based controls, the Abort method performs a "hard close", with a socket LINGER option time of 0. To prevent the socket from entering a WAIT_STATE, and to immediately release it for reuse, use Abort instead of Close.

CAUTION Use the Close method in most cases, as buffers are cleared and communications terminate gracefully. Use the Abort method only when the application in abruptly terminated while a blocking method is executing or under any other unusual circumstances.

See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

About Method
Smtp Object : About Method
Description
Display Control information in a dialog box.
Syntax
Visual Basic
Public Sub About()
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

ClearCertificate Method
Smtp Object : ClearCertificate Method
Description
Clears the Certificate object contained in the Cerificate property.
Syntax
Visual Basic
Public Sub ClearCertificate()
Remarks
Use this to clear the currently set certificate and set it to nothing. This method is only necessary on some environments, otherwise the Certificate property will work.
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Command Method
Smtp Object : Command Method
The command to send.
Where the reply from the server will be stored. A message would not be returned for this parameter when the Progress event fires, as that information would be available elsewhere.
Description
Send any protocol command to the server.
Syntax
Visual Basic
Public Sub Command( _
   ByVal Command As String, _
   ByRef Reply As String _
)
Parameters
Command
The command to send.
Reply
Where the reply from the server will be stored. A message would not be returned for this parameter when the Progress event fires, as that information would be available elsewhere.
Remarks

Allows execution of standard and non-standard extension. The response from the server is copied to the Reply parameter, and you determine success or failure of the command.

Command should not include a trailing CR/LF.

For scripting environments, use CommandEx.

See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

CommandEx Method
Smtp Object : CommandEx Method
The command to send.
Where the reply from the server will be stored. A message would not be returned for this parameter when the Progress event fires, as that information would be available elsewhere.
Description
Send any protocol command to the server.
Syntax
Visual Basic
Public Sub CommandEx( _
   ByVal Command As String, _
   ByRef Reply As Variant _
)
Parameters
Command
The command to send.
Reply
Where the reply from the server will be stored. A message would not be returned for this parameter when the Progress event fires, as that information would be available elsewhere.
Remarks

This method is functionally equivalent to Command, but CommandEx can be used in a scripting environment.

Allows execution of standard and non-standard extension. The response from the server is copied to the Reply parameter, and you determine success or failure of the command.

Command should not include a trailing CR/LF.

See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

DSN Method
Smtp Object : DSN Method
Defaults to msgHeader to return the header. If msgMessage, DSN will return the entire message.
Included in the return message header. The default is an empty string.
Description
Set parameters that define the type of Delivery Status Notification that will be requested for subsequent messages.
Syntax
Visual Basic
Public Sub DSN( _
   ByVal Notify As DsnConstants, _
   Optional ByVal Segment As SegmentConstants = msgHeader, _
   Optional ByVal EnvelopeId As String _
)
Parameters
Notify
Value | Description
dsnDefault | Directs the server to follow its default policy for DSN.
dsnDelay | Requests DSN for delayed delivery.
dsnFailure | Requests DSN for failure of delivery.
dsnFailureDelay | Requests DSN for failure or delay of delivery.
dsnNever | Directs the server not to send DSN under any circumstances.
dsnSuccess | Requests DSN for successful delivery.
dsnSuccessDelay | Requests DSN for success for delay of delivery.
dsnSuccessFailure | Requests DSN for success or Failure of delivery.
dsnSuccessFailureDelay | Requests DSN for success, failure, or delay of delivery.
Segment
Value | Description
msgHeader | Perform the operation on the header of the message.
msgMessage | Perform the operation on the complete message.
Defaults to msgHeader to return the header. If msgMessage, DSN will return the entire message.
EnvelopeId
Included in the return message header. The default is an empty string.
Remarks

If EnvelopeId is provided, the value will be included in any returned messages by the addition of a header to the notification message of the form:

Original-Envelope-ID: <EnvelopeId>

Reserved characters contained in the EnvelopeId string are encoded before transmittal.

Refer to RFC 1891 for additional information about return notifications.

The following example code requests DSN for message delivery success and failure, requests return of the message, and provides an identifying label to aid in processing the return receipt:

Smtp1.DSN dsnSuccessFailure, msgMessage, "bounce-2118"
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Login Method
Smtp Object : Login Method
A hostname or IP address.
Specifies the port number you wish to connect to. Defaults to the well-known port 25 (or 465 for implicitly secure connections).
Specifies the server account.
Specifies the Password.
Description
Establish a session with a server.
Syntax
Visual Basic
Public Sub Login( _
   ByVal Server As String, _
   Optional ByVal RemotePort As Long = 0, _
   Optional ByVal Username As String, _
   Optional ByVal Password As String _
)
Parameters
Server
A hostname or IP address.
RemotePort
Specifies the port number you wish to connect to. Defaults to the well-known port 25 (or 465 for implicitly secure connections).
Username
Specifies the server account.
Password
Specifies the Password.
Remarks

After a successful Login, the supported server extensions are listed in the Capabilities property and will be used when applicable. See the Capabilities property or the SMTP Protocol Overview section for more information regarding SMTP extensions.

See SMTP Control Event Sequencing for event information related to this method and SMTP Control Non-Blocking Sample for information on non-blocking operation.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptAbort
  • ptAddressInUse
  • ptAddressNotAvailable
  • ptAuthentication (An Invalid Username or Password was specified)
  • ptBlocked
  • ptConnected
  • ptConnectionAborted
  • ptConnectionReset
  • ptConnectionRefused
  • ptHostNotFound
  • ptNetworkDown
  • ptNetworkReset
  • ptNetworkUnreachable
  • ptNoBufferSpace
  • ptNoData
  • ptNotInitialized
  • ptProtocol (A protocol error was encountered)
  • ptTimeout
  • ptTryAgain
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Logout Method
Smtp Object : Logout Method
Description
End the session.
Syntax
Visual Basic
Public Sub Logout()
Remarks
This method gracefully ends a session. If you fail to log out, the server may cancel any incomplete mail activity, possibly causing a server fault.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNotConnected
  • ptNotInitialized
  • ptNoBufferSpace
  • ptProtocol (A protocol error was encountered)
  • ptTimeout
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

QuickSend Method
Smtp Object : QuickSend Method
Contains one or more recipient addresses separated by commas.
Contains the email address of the message originator.
Specifies the Subject of the message.
Contains the message text.
Contains one or more attachment file paths (separated by semicolons) to be sent with the message.
Specifies the name of the server to connect to.
Description
Build and send a message.
Syntax
Visual Basic
Public Sub QuickSend( _
   ByVal To As String, _
   ByVal From As String, _
   Optional ByVal Subject As String, _
   Optional ByVal Text As String, _
   Optional ByVal Attachments As String, _
   Optional ByVal Server As String _
)
Parameters
To
Contains one or more recipient addresses separated by commas.
From
Contains the email address of the message originator.
Subject
Specifies the Subject of the message.
Text
Contains the message text.
Attachments
Contains one or more attachment file paths (separated by semicolons) to be sent with the message.
Server
Specifies the name of the server to connect to.
Remarks

If Server is specified, login is attempted before the message is sent, and the session terminates after the message is sent. A ptConnected error is thrown if already logged in.

If Server is not specified, there must an active session and the session persists after the message is sent. This allows multiple messages to be sent without the overhead of logging in and out for each message. A ptNotConnected error is thrown if not already logged in.

This method allows you to send complex messages with just one line of code.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptAuthentication
  • ptBlocked
  • ptConnected
  • ptConnectionAborted
  • ptConnectionRefused
  • ptConnectionReset
  • ptFile
  • ptHostNotFound
  • ptInvalidParam1
  • ptInvalidParam2
  • ptNetworkDown
  • ptNetworkReset
  • ptNetworkUnreachable
  • ptNoBufferSpace
  • ptNoData
  • ptNotConnected
  • ptNotInitialized
  • ptProtocol
  • ptTimeout
  • ptTryAgain
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Reset Method
Smtp Object : Reset Method
Description
Recover from an error condition.
Syntax
Visual Basic
Public Sub Reset()
Remarks
This method recovers from an error that has left the server unsynchronized with the client.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNotConnected
  • ptNotInitialized
  • ptProtocol (A protocol error was encountered)
  • ptTimeout
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Send Method
Smtp Object : Send Method
String or Byte array containing an encoded message, or a String containing the filename of a file containing the message.
Description
Send message using the current session.
Syntax
Visual Basic
Public Sub Send( _
   Optional ByRef Msg As Variant _
)
Parameters
Msg
String or Byte array containing an encoded message, or a String containing the filename of a file containing the message.
Remarks

If the Msg parameter is not specified, the message contained in the Message property is sent.

The recipients of the message are determined by the To, Cc, and Bcc labels in the message header, unless overridden by the To property. Bcc header fields are removed from the message header before sending (Bcc fields are used for the message envelope only).

The sender of the message is determined by the From label in the message header, unless overridden by the From property.

Error Codes

This method may generate the following error code (refer to MailErrorConstants for a complete list of error codes):

  • ptBlocked
  • ptConnectionAborted
  • ptConnectionReset
  • ptInvalidParam1
  • ptFile
  • ptNetworkDown
  • ptNetworkReset
  • ptNoBufferSpace
  • ptNoRecipients (A recipient for the message could not be determined)
  • ptNotConnected
  • ptNotInitialized
  • ptProtocol (A protocol error was encountered)
  • ptTimeout
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Trace Method
Smtp Object : Trace Method
An undimensioned string dynamically expanded to contain trace data or a filename that is used to store all trace data. If not provided or a Null value, then trace data is no longer stored.
Defaults to False. A True value indicates that sent data should be traced.
Defaults to False. A True value indicates that received data should be traced.
Prompt to precede sent data.
Prompt to precede received data.
Description

Start or stop the accumulation of trace or debug data. Once started, this method accumulates data until it is turned off.

This method provides a convenient mechanism for viewing all data being sent and received over the connection and can be used to troubleshoot host interoperability issues and expose protocol communications.

Syntax
Visual Basic
Public Sub Trace( _
   Optional ByRef Result As Variant, _
   Optional ByVal Send As Boolean = False, _
   Optional ByVal Receive As Boolean = False, _
   Optional ByVal SendPrompt As String, _
   Optional ByVal ReceivePrompt As String _
)
Parameters
Result
An undimensioned string dynamically expanded to contain trace data or a filename that is used to store all trace data. If not provided or a Null value, then trace data is no longer stored.
Send
Defaults to False. A True value indicates that sent data should be traced.
Receive
Defaults to False. A True value indicates that received data should be traced.
SendPrompt
Prompt to precede sent data.
ReceivePrompt
Prompt to precede received data.
Remarks
ReceivePrompt and SendPrompt allow the application to specify what delimiters separate and label data being captured.
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Verify Method
Smtp Object : Verify Method
DartStrings collection that specifies a list of DNS servers used to locate the address of the mail server for Address.
The mail address to verify.
Description
Validate an email address.
Syntax
Visual Basic
Public Function Verify( _
   ByVal DnsServers As DartStrings, _
   ByVal Address As String _
) As VerifyMethodConstants
Parameters
DnsServers
DartStrings collection that specifies a list of DNS servers used to locate the address of the mail server for Address.
Address
The mail address to verify.
Remarks

This blocking method will verify if the domain of the specified address is valid, and that the user is a valid user within the domain.

The From address will be used as the MAIL FROM parameter when communicating with the SMTP server. If this property is not set, the control will use the address to be verified as the From address.

If the email address is badly formed, the specified domain does not exist, the mail server does not respond, or the user does not exist, a VerifyMethodConstant will be returned designating the nature of the problem. If the address is valid, the VerifyMethodConstant returned will be verifyValid.

If there is no response from the first DNS server in the DnsServers collection after three attempts, the next server will be tried. This will continue until the list of servers is exhausted. If a connection has already been established using the Login method, the Verify method will return with error ptConnect, as this method makes its own connection. Also, if the current thread is blocking, a ptBlocked error will result.

Please note that the performance of this capability is dependent upon the responsiveness of the DNS Servers used and security of the SMTP server. Some servers accept invalid mail and return later. This will cause an address to be falsely evaluated as good. In addition, failure may occur if your machine does not allow incoming traffic on port 113, which is used by mail servers to check port identity of the requesting machine.

See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Blocked Property
Smtp Object : Blocked Property
Description
A True value indicates the control is currently executing a blocking method (Timeout is greater than 0), which has neither completed nor timed out with a ptTimeout error.
Property type
Read-only property
Syntax
Visual Basic
Public Property Blocked As Boolean
Remarks

Check this property to prevent your application from prematurely exiting or destroying the control while it is blocking in a method.

Your application still processes normal Windows messages while blocked, and the user interface continues to function normally. Events still fire while blocked, so code placed in these events continues to execute.

Your application cannot execute another method (except the Abort method) while it is blocked; a ptBlocked error is generated. Use the Abort method to terminate a blocked method prematurely. Abort signals the blocked method to abort, and then returns. Shortly thereafter, the blocked method releases all system resources, calls the State event (with the object's State property set to ptClosed), and returns with the ptAbort error.

WARNING Terminating your application or destroying the TCP object while blocked in a method may cause a fatal application error. To prevent this, perform either of the following:

  • Only allow object destruction if the Blocked property returns False.
  • Never use a positive Timeout value.
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Capabilities Property
Smtp Object : Capabilities Property
Description
Collection of strings that contains the protocol extensions supported by the server. Values are initialized during login.
Property type
Read-only property
Syntax
Visual Basic
Public Property Capabilities As DartStrings
Remarks

Read-only (but you can remove Strings in the collection).

By default, capabilities supported by the server and the control are automatically used. Removing a capability from the collection disables use of the associated extension. Reactivate the use of the capability by restoring the capability to the collection or restarting the session. The following statement disables use of the "PIPELINING" extension:

Smtp1.Capabilities.Remove("PIPELINING") ' "PIPELINING" is disabled.

DSNTYPE, 8BITMIME, ENHSTATUSCODES, PIPELINING, and SIZE are automatically used if they are advertised by the server. See SMTP Protocol Overview for more information on these extensions.

See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Certificate Property
Smtp Object : Certificate Property
Description
Certificate to use when authenticating to the remote host.
Property type
Read-write property
Syntax
Visual Basic
Public Property Certificate As ICertificate
Remarks
On the client side, this property is typically unused. If the server wants the client to authenticate and this property has not been set, then the Certificate event fires to allow you to set a certificate on demand.
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

From Property
Smtp Object : From Property
Description
If provided, this return address is used for the SMTP envelope instead of the address found in the From header label of the message.
Property type
Read-write property
Syntax
Visual Basic
Public Property From As String
Remarks

An envelope identifying the sender and recipients is sent as part of the mail transfer. By default, the sender is extracted from the From header label of the message. This property overrides this default behavior.

Set this property as the MAIL FROM address when using the Verify method to validate email addresses.

See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

HelloName Property
Smtp Object : HelloName Property
Description
A string value representing the hostname presented to the server during the greeting.
Property type
Read-write property
Syntax
Visual Basic
Public Property HelloName As String
Remarks
The hello command (HELO) is sent when communication begins with the mail server. Typically the value presented after HELO is the domain.
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

IpV6 Property
Smtp Object : IpV6 Property
Description
Specifies whether hostname addresses should be favorably resolved to IPv6.
Property type
Read-write property
Syntax
Visual Basic
Public Property IpV6 As Boolean
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Message Property
Smtp Object : Message Property
Description
The message to be sent.
Property type
Read-write property
Syntax
Visual Basic
Public Property Message As Message
Remarks
The Send method normally encodes this message and sends it.
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Privacy Property
Smtp Object : Privacy Property
Description
Specifies the security protocol (PCT, SSL2, SSL3, TLS, none) and type (Implicit, Explicit) used.
Property type
Read-write property
Syntax
Visual Basic
Public Property Privacy As MailPrivacyConstants
Remarks

The default value is privacyNone.

If the server and the client specify secureAuto, then the highest shared protocol is normally used. If one side uses secureAuto and the other side specifies a protocol, then the protocol specified is used. If the client and server specify protocols that are different, then the Error event will fire with Number=ptProtocol and the connection will be closed.

See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Security Property
Smtp Object : Security Property
Description
Sets the criteria for accepting certificates.
Property type
Read-write property
Syntax
Visual Basic
Public Property Security As SecurityConstants
Remarks
This property enables variable security settings, from absolute certificate confirmation to no security.
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

State Property
Smtp Object : State Property
Description
Provides status information to the user interface. The State event fires to signal that this property has changed.
Property type
Read-only property
Syntax
Visual Basic
Public Property State As StateConstants
Remarks

To protect you from programming errors, most methods return an error condition if your code attempts to send data when no TCP connection exists. By checking the value of this property, your application can always determine the state of the connection.

This property is exposed by most TCP-based controls.

See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Timeout Property
Smtp Object : Timeout Property
Description
Controls the blocking behavior of methods that can be used in blocking and non-blocking ways.
Property type
Read-write property
Syntax
Visual Basic
Public Property Timeout As Long
Remarks

The default value is 30000 (30 seconds). This is a design-time property.

Most users will start using blocking operation. The developer's decision to use blocking (Timeout > 0) or non-blocking (Timeout = 0) operation is important; these controls were designed to consistently support both methods of operation.

When set to a positive number of milliseconds, methods block while waiting for the initial response from the method. For example, an FTP or HTTP Get() method on a file will block until response is received. The Blocked property indicates this state. For example, if the Connect method is used with a Timeout of 30000, then the method only returns without error if the connection is established within 30 seconds. This is the easiest design to implement, but not the most robust. If the user attempts to initiate a different method while the Blocked property is True, an error is generated. Also, if the user attempts to close the application while the Blocked property is True, abnormal program termination may result.

When set to 0, no method blocks. It is up to the application to sense the success or failure of the operation by putting code in the related event. For example, if the Connect method is used with a Timeout of 0, then the application can test for the value of the State property from within the State event. This is the most efficient technique, as no idle loops are used to capture the thread of execution waiting for an event to occur. This is also the safest way to use PowerTCP because non-blocking use allows PowerTCP to unload gracefully under any condition.

The novice will probably use blocking operation first because this is the easiest way to immediately use the product. With no explicit error handling enabled (for example, the VB OnError statement), methods return errors into the environment and program execution stops. Once you add error-handling code, most applications will work satisfactorily. While the thread is captured in the method, an idle loop processes Windows messages and few side effects will ever be noted. There are some limits, however, that you should be aware of:

  • The only way to abort a blocking method is to call the Abort method off a Timer or some user interface event.
  • With the exception of the Abort method, the developer can only be in one method at a time (this protects your program from reentrancy problems).
  • If the user closes the application while PowerTCP is blocking, the blocking method attempts to return when this is sensed, but a general protection fault may still be experienced (because the application is being terminated while PowerTCP is in an idle loop).

Non-blocking operations are more fault-tolerant. Set the Timeout property to 0 (at design time or at run time), initiate methods as desired, and insert most of your code in the appropriate event. This eliminates problems associated with reentrancy, users performing unanticipated actions in your application, and error recovery.

Note: Asynchronous operation is dependent upon an active MessageLoop. If an asynchronous operation is started, and subsequently a synchronous process (such as a lengthy database query) is started (immediately or off a timer), operation may be affected. In some development environments, the MessageLoop can be executed by calling DoEvents() repeatedly, but this design is not optimal. Preferred approaches include:

  • Operate the synchronous process on another worker thread
  • Operate the control itself on another thread or process
  • Split the synchronous process into smaller pieces that operate off a timer event

See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

To Property
Smtp Object : To Property
Description
If provided, these addresses will be used for the SMTP envelope instead of those found in the To, Cc, and Bcc header labels of the message.
Property type
Read-write property
Syntax
Visual Basic
Public Property To As DartStrings
Remarks
An envelope identifying the sender and recipients is sent as part of the mail transfer. By default, the recipients of the message are extracted from the message header labels To, Cc, and Bcc. This property will override this default behavior.
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Authenticate Event
Smtp Object : Authenticate Event
Remote host's certificate.
Indicates if the certificate was from a Trusted Root Authority (CA).
Indicates if the current date-time is within the certificate's life span.
Indicates if the certificate has a valid signature.
Set this value to True to authenticate the remote certificate or set it to False to deny it.
Description
Fires when the remote host has sent a certificate to be authenticated.
Syntax
Visual Basic
Public Event Authenticate( _
   ByVal RemoteCertificate As ICertificate, _
   ByVal TrustedRoot As Boolean, _
   ByVal ValidDate As Boolean, _
   ByVal ValidSignature As Boolean, _
   ByRef Valid As Boolean _
)
Parameters
RemoteCertificate
Remote host's certificate.
TrustedRoot
Indicates if the certificate was from a Trusted Root Authority (CA).
ValidDate
Indicates if the current date-time is within the certificate's life span.
ValidSignature
Indicates if the certificate has a valid signature.
Valid
Set this value to True to authenticate the remote certificate or set it to False to deny it.
Remarks
Typically, the remote certificate is rejected if TrustedRoot, ValidDate, or ValidSignature is False. This event allows you to ease or strengthen the restrictions on the remote host's certificate. To authenticate a certificate if one or all of the parameters are False, set Valid to True. You can also deny a certificate if the hostname is not the same as the IssuedTo property of the Certificate.
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Certificate Event
Smtp Object : Certificate Event
Description
Fires when the remote host is requesting a certificate and the Certificate property is not set to a valid Certificate Object.
Syntax
Visual Basic
Public Event Certificate()
Remarks
This event is used to set a certificate on demand. In some cases a server will request that the client authenticate, and it may not be desirable to set the Certificate property unless necessary.
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Error Event
Smtp Object : Error Event
ErrorConstants description.
Description
Fires when an Error condition occurs.
Syntax
Visual Basic
Public Event Error( _
   ByVal Number As MailErrorConstants, _
   ByVal Description As String _
)
Parameters
Number
Value | Description
mailAbort | The Abort method was called. FATAL.
mailAddressInUse | Address already in use. Only one usage of each socket address (protocol/IP address/port) is normally permitted. This error occurs if an application attempts to bind() a socket to an IP address/port that has already been used for an existing socket, or a socket that wasn't closed properly, or one that is still in the process of closing. For server applications that need to bind() multiple sockets to the same port number, the ReuseAddress property can be used. FATAL.
mailAddressNotAvailable | Cannot assign requested address. The requested address is not valid in its context. Normally results from an attempt to bind() to an address that is not valid for the local machine. This may also result from connect(), sendto(), WSAConnect(), WSAJoinLeaf(), or WSASendTo() when the remote address or port is not valid for a remote machine (for example, address or port 0). FATAL.
mailAttachUuencode | Only (uuencoded) files may be attached to this non-MIME message. Consider using MIME or putting all text in the Message.Data property area.
mailAuthentication | Authentication with the server failed. FATAL.
mailBadConfigItem | Invalid Configuration Item
mailBadDataType | Cannot create the requested data type or format.
mailBadRecipient | Mail Recipient Not Accepted.
mailBadSender | Sender address not accepted.
mailBlocked | User thread is blocking in another method. INFO.
mailCompile | An error occurred while compiling
mailConnected | A connection already exists
mailConnectionAborted | Software caused connection abort. An established connection was aborted by the software in your host machine, possibly due to a data transmission timeout or protocol error. FATAL.
mailConnectionRefused | Connection refused. No connection could be made because the target machine actively refused it. This usually results from trying to connect to a service that is inactive on the foreign host (for example,. one with no server application running). May also be generated by a Daemon that refuses a connection because its resources have been exhausted. FATAL.
mailConnectionReset | Connection reset by peer. An existing connection was forcibly closed by the remote host. This normally results if the peer application on the remote host is suddenly stopped, the host is rebooted, or the remote host used a "hard close" (see Abort method) on the remote socket. This error may also result if a connection was broken due to keep-alive activity detecting a failure while one or more operations are in progress. Operations that were in progress fail with ptNetworkReset. Subsequent operations fail with ptConnectionReset. FATAL.
mailDuplicateMessage | Message object already exists in collection.
mailError | Unexpected general error. FATAL.
mailFile | Error accessing local file storage. FATAL.
mailFileOpen | Unable to open file.
mailFileOperation | A file operation (such as size) had failed.
mailFileRead | A file read error has caused the operation to fail.
mailFileWrite | A file write error has occurred. Check disk free space.
mailFormatError | The server was unable to interpret the query.
mailHeader | Occurs when a proper termination (usually a CRLFCRLF) is not found in the header.
mailHostNotFound | Host not found. No such host is known. The name is not an official hostname or alias, or it cannot be found in the database(s) being queried. This error may also be returned for protocol and service queries, and means the specified name could not be found in the relevant database. FATAL.
mailHostUnreachable | Remote host does not exist
mailHttpInvalidUrl | The Url is unspecified or invalid.
mailInvalidMailAddress | The Email address specified was not valid.
mailInvalidMessageHeader | A recipient, from, and subject are needed for a valid message header.
mailInvalidParam1 | Parameter #1 is invalid. INFO.
mailInvalidParam2 | Parameter #2 is invalid. INFO.
mailInvalidParam3 | Parameter #3 is invalid. INFO.
mailInvalidParam4 | Parameter #4 is invalid. INFO.
mailInvalidProperty | Invalid property assignment. INFO.
mailInvDecodeType | An invalid or unsupported Decode Type was specified.
mailMsgObjRead | An error has occurred while reading data from the Message object. Verify the Message object contents.
mailNetworkDown | Network is down. A socket operation encountered a dead network. This could indicate a serious failure of the network system (for example,. the protocol stack that the Winsock DLL runs over), the network interface, or the local network itself. FATAL.
mailNetworkReset | Network dropped connection on reset. The connection has been broken due to keep-alive activity detecting a failure while the operation was in progress. FATAL.
mailNetworkUnreachable | Network is unreachable. A socket operation was attempted to an unreachable network. This usually means the local software knows no route to reach the remote host. FATAL.
mailNoAccess | The user does not have the proper permissions
mailNoAuthMech | No authentication mechanism was found in the server's advertised capabilities, a secure connection may be required.
mailNoBufferSpace | No buffer space available. An operation on a socket could not be performed because the system lacked sufficient buffer space or because a queue was full. FATAL.
mailNoCertificate | There was an error in creating credentials.
mailNoData | Valid name, no data record of requested type. The requested name is valid and was found in the database, but it does not have the correct associated data being resolved for. The usual example for this is a hostname -> address translation attempt which uses the DNS, and an MX record is returned but no A record - indicating the host itself exists but is not directly reachable. FATAL.
mailNoHeader | The message is invalid because the header was not found.
mailNoMemory | There was not enough memory available to complete the operation.
mailNoMessageHeader | The message does not contain a valid header.
mailNoRecipientsFound | The message header does not contain any (valid) recipients (To).
mailNoRecovery | This is a non-recoverable error. This indicates some sort of non-recoverable error occurred during a database lookup. This may be because the database files (for example, BSD-compatible HOSTS, SERVICES or PROTOCOLS files) could not be found, or a DNS (Domain Name Server) request was returned by the server with a severe error. FATAL.
mailNoSecurity | Secure communications is not available on this machine.
mailNotConnected | Socket is not connected. A request to send or receive data was disallowed because the socket is not connected or allocated. Any other type of operation might also return this error. FATAL.
mailNotFound | The name referred to in the query does not exist.
mailNotImplemented | The server does not support the request type of query.
mailNotInitialized | Network interface could not be initialized. FATAL.Host not found. No such host is known. The name is not an official hostname or alias, or it cannot be found in the database(s) being queried. This error may also be returned for protocol and service queries, and means the specified name could not be found in the relevant database. FATAL.
mailNotInSpoolMode | Method not allowed when spool mail mode is active.
mailNotMessageObject | The passed object is not a Message object.
mailNotPartObject | The operation requested requires an object of type Part.
mailOk | Ok
mailOnlyInSpoolMode | The DeSpool Method is only available when mail spooling is enabled.
mailOperationRefused | The server refused to perform the specified operation.
mailOptionNotSupported | The specified socket option is not supported by the system. INFO.
mailPartInStructure | The Part to Add already exists in this structure.
mailProtocol | Unexpected protocol error. FATAL.
mailServerError | There was a failure on the server.
mailSocks4DifferentUserID | The SOCKS4 server rejected the connection because the client program and identd report different user-ids
mailSocks4NoAcceptableMethods | The SOCKS5 server will not accept any of the requested methods
mailSocks4NoIdentd | The SOCKS4 server rejected the connection because it was unable to connect to identd on the client
mailSocks4RequestRejected | The SOCKS4 server rejected the connection (No reason given)
mailSocks5AddressTypeNotSupported | The SOCKS5 server reported that the address type is not supported
mailSocks5AuthFailed | The SOCKS5 server rejected the connection because authorization failed
mailSocks5CommandNotSupported | The SOCKS5 server reported that the command is not supported
mailSocks5ConnectionRefused | The SOCKS5 server reported that the host connection was refused
mailSocks5HostUnreachable | The SOCKS5 server reported that the host was unreachable
mailSocks5NetworkUnreachable | The SOCKS5 server reported that the network was unreachable
mailSocks5NoRuleSet | The SOCKS5 server reported that the connection was not allowed by the ruleset
mailSocks5ServerFailure | The SOCKS5 server reported a general failure
mailSocks5TTLExpired | The SOCKS5 server reported that the TTL has expired
mailTimeout | Timed out. A connection attempt failed because the connected party did not properly respond after a period of time, or an established connection failed because connected host has failed to respond. Alternatively, a blocked method failed to return within the period specified by the Timeout property. FATAL.
mailTryAgain | Non-authoritative host not found. This is usually a temporary error during hostname resolution and means that the local server did not receive a response from an authoritative server. A retry at some time later may be successful. FATAL.
mailUseMimeEncode | mailUseMimeEncoding must be Always, Never, or Smallest
Description
ErrorConstants description.
Remarks

Some environments, such as IIS Active Server Pages, do not support event handling. In this case the application must rely on blocking and the Error object that is returned to the container when an error condition occurs.

Note See the appropriate method and property description for a list of errors that may be generated.

See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

Progress Event
Smtp Object : Progress Event
Method that the event pertains to.
Status of the method.
Number of bytes of the message sent so far when Status is smtpSending. The value is between 0 and Size.
Size of the message when Status is smtpSending. This value is constant during a transfer.
Description
Fires when a method has completed, the server has sent a reply, or progress information is available.
Syntax
Visual Basic
Public Event Progress( _
   ByVal Method As SmtpMethodConstants, _
   ByVal Status As SmtpStatusConstants, _
   ByVal Reply As String, _
   ByVal Count As Long, _
   ByVal Size As Long _
)
Parameters
Method
Value | Description
smtpCommand | Command, CommandEx Methods
smtpLogin | Login method
smtpLogout | Logout method
smtpQuickSend | QuickSend method
smtpReset | Reset method
smtpSend | Send method
Method that the event pertains to.
Status
Value | Description
smtpBad | Server has responded with a negative status indicating an error condition.
smtpCapabilities | Capabilities is updated.
smtpFrom | Server has responded positive to "MAIL FROM:" during the execution of the Send or QuickSend method.
smtpOk | Method has completed with a positive status indicating successful operation.
smtpSending | Indicates progress during the transmission of a message. Useful for percentage indication on a status display.
smtpTo | Server has responded positive to "RCPT TO:" during the execution of the Send or QuickSend method.
Reply
Status of the method.
Count
Number of bytes of the message sent so far when Status is smtpSending. The value is between 0 and Size.
Size
Size of the message when Status is smtpSending. This value is constant during a transfer.
Remarks

When a method is called, it causes Progress to fire to indicate progress, status, or completion information, such that:

  • Method indicates the method used
  • Status provides success / failure information
  • Reply provides the server reply
  • Count and Size are used to update the progress of a Send or QuickSend operation when Status = smtpSending (at other times these parameters are 0).

Use the Trace method to gather protocol-level data if the Reply parameter is inadequate.

Reply normally begins with one of the following numbers:

Number | Meaning
211 | System status or help reply
214 | Help message (Information on how to use the receiver or the meaning of a particular non-standard command; this reply is useful only to the human user)
220 | <domain> Service ready
221 | <domain> Service closing transmission channel
250 | Requested mail action okay, completed
251 | User not local; will forward to <forward-path>
252 | Cannot VRFY user, but will accept message and attempt delivery
354 | Start mail input; end with <CRLF>.<CRLF>
421 | <domain> Service not available, closing transmission channel (This may be a reply to any command if the service knows it must shut down)
450 | Requested mail action not taken: mailbox unavailable (for example, mailbox busy)
451 | Requested action aborted: local error in processing
452 | Requested action not taken: insufficient system storage
500 | Syntax error, command unrecognized (This may include errors such as command line too long)
501 | Syntax error in parameters or arguments
502 | Command not implemented
503 | Bad sequence of commands
504 | Command parameter not implemented
550 | Requested action not taken: mailbox unavailable (for example, mailbox not found, no access, or command rejected for policy reasons)
551 | User not local; please try <forward-path>
552 | Requested mail action aborted: exceeded storage allocation
553 | Requested action not taken: mailbox name not allowed (for example, mailbox syntax incorrect)
554 | Transaction failed (Or, in the case of a connection-opening response, "No SMTP service here")
See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

State Event
Smtp Object : State Event
Description
Fires when the State property changes.
Syntax
Visual Basic
Public Event State()
Remarks

WARNING Timeout must be 0 when calling methods from within an event. Failure to observe this rule may cause reentrancy problems and unpredictable results.

The Connect method (used to initiate an active connection) normally causes the State property to transition from tcpClosed to tcpConnecting (while resources are being allocated and the connection is being established) to tcpConnected, at which time communications activity can start.

The Close method normally causes the State property to transition from tcpConnected to tcpClosing (while resources are being de-allocated) to tcpClosed.

When the remote host closes the connection, there may still be data available in the stream. In this case, the State property is tcpClosing until all the data is received and the socket returns a 0 value, after which the State property changes to tcpClosed.

See Also

Smtp Object | Smtp Members


%%PageItemTitle%%

AttributeConstants Enumeration
Description
Enumerates the values of the Index parameter of the Attribute property.
Members
Member | Value | Description
msgAnswered | 3 | Message has been answered (IMAP only).
msgDeleted | 5 | Message is marked for removal (POP3 and IMAP).
msgDraft | 6 | Composition of message not complete (IMAP only).
msgFlagged | 4 | Message is marked for urgent attention (IMAP only).
msgNumber | 0 | Message number assigned by a POP3 or IMAP server.
msgRecent | 7 | Message is new this session (IMAP only).
msgSeen | 2 | Message has been read (IMAP only).
msgUid | 1 | Message unique id assigned by a POP3 or IMAP server.


%%PageItemTitle%%

CodingConstants Enumeration
Description
Enumerates encoding/decoding algorithms.
Members
Member | Value | Description
msgBase64 | 0 | Base 64
msgBinHex40 | 8 | BinHex 4.0
msgEucJp | 7 | EucJp
msgIso2022Jp | 5 | Iso-2022Jp
msgQuotedPrintable | 1 | Quoted Printable
msgShiftJis | 6 | ShiftJis
msgUTF7 | 2 | UTF 7
msgUTF8 | 3 | UTF 8
msgUUEncode | 4 | UUENCODE


%%PageItemTitle%%

DsnConstants Enumeration
Description
Enumerates values of the Notify parameter of the DSN method.
Members
Member | Value | Description
dsnDefault | 1 | Directs the server to follow its default policy for DSN.
dsnDelay | 4 | Requests DSN for delayed delivery.
dsnFailure | 2 | Requests DSN for failure of delivery.
dsnFailureDelay | 5 | Requests DSN for failure or delay of delivery.
dsnNever | 0 | Directs the server not to send DSN under any circumstances.
dsnSuccess | 3 | Requests DSN for successful delivery.
dsnSuccessDelay | 6 | Requests DSN for success for delay of delivery.
dsnSuccessFailure | 7 | Requests DSN for success or Failure of delivery.
dsnSuccessFailureDelay | 8 | Requests DSN for success, failure, or delay of delivery.


%%PageItemTitle%%

FormatConstants Enumeration
Description
Enumerates the values of the Format parameter of the Store method.
Members
Member | Value | Description
msgDecoded | 1 | Store the decoded object model version of the message.
msgEncoded | 0 | Store the encoded "transport-ready" version of the message.


%%PageItemTitle%%

GetConstants Enumeration
Description
Enumerates values of the Part parameter of the Get method.
Members
Member | Value | Description
imapGetContent | 0 | Requests retrieval of the complete message for each message in MsgSet.
imapGetFlags | 3 | Requests the flags for each message specified in MsgSet.
imapGetHeaders | 4 | Requests the retrieval of the header fields for each message in the MsgSet.
imapGetPreview | 5 | Requests the retrieval of the header fields plus parts information for each message in the MsgSet.
imapGetSize | 1 | Requests the size for each message specified in MsgSet.
imapGetUid | 2 | Requests the message UID label for each message in MsgSet.


%%PageItemTitle%%

ImapMethodConstants Enumeration
Description
Enumerates values of the Method parameter of the Progress event.
Members
Member | Value | Description
imapCommand | 1 | Command method.
imapCopy | 10 | Copy method.
imapDelete | 11 | Delete method.
imapGet | 12 | Get method.
imapIdle | 19 | Idle.
imapLogin | 2 | Login method.
imapLogout | 3 | Logout method.
imapMailboxAdd | 9 | Mailbox Add method.
imapMailboxesAdd | 4 | Mailboxes Add method.
imapMailboxesRefresh | 6 | Refresh method.
imapMailboxRefresh | 17 | Mailbox Refresh method.
imapPurge | 13 | Purge method.
imapPut | 14 | Put method.
imapRemove | 5 | Remove method.
imapRename | 18 | Rename.
imapSearch | 15 | Search method.
imapSubscribe | 7 | Subscribe method.
imapUndelete | 16 | Undelete method.
imapUnknown | 0 | Unknown command.
imapUnsubscribe | 8 | Unsubscribe method.


%%PageItemTitle%%

ImapStatusConstants Enumeration
Description
Enumerates values of the Status parameter of the Progress Event.
Members
Member | Value | Description
imapBad | 1 | Server has responded with a status indicating bad syntax.
imapBye | 3 | Server has indicated that it is about to close the connection.
imapContent | 4 | Indicates intermediate events during the receipt of a mail message. Useful for percentage indication on a status display.
imapInfo | 5 | Server has supplied information.
imapNo | 2 | Server has responded with a negative status.
imapOk | 0 | Method has completed with a positive status.


%%PageItemTitle%%

LabelConstants Enumeration
Description
Some HeaderFields Object methods use a symbolic name for the Label parameter. The following labels are specified as the Common Internet Message Headers (these headers are explained in RFC 2076):
Members
Member | Value | Description
msgAlsoControl | 1 | "Also-Control:"
msgAlternateRecipient | 2 | "Alternate-Recipient:"
msgApparentlyTo | 3 | "Apparently-To:"
msgApproved | 4 | "Approved:"
msgArticleNames | 5 | "Article-Names:"
msgArticleUpdates | 6 | "Article-Updates:"
msgAutoForwarded | 7 | "Auto-Forwarded:"
msgComments | 8 | "Comments:"
msgContentBase | 9 | "Content-Base:"
msgContentConversion | 10 | "Content-Conversion:"
msgContentDescription | 11 | "Content-Description:"
msgContentDisposition | 12 | "Content-Disposition:"
msgContentID | 13 | "Content-ID:"
msgContentIdentifier | 14 | "Content-Identifier:"
msgContentLanguage | 15 | "Content-Language:"
msgContentLength | 16 | "Content-Length:"
msgContentLocation | 17 | "Content-Location:"
msgContentMD5 | 18 | "Content-MD5:"
msgContentReturn | 19 | "Content-Return:"
msgContentSGMLEntity | 20 | "Content-SGML-Entity:"
msgContentTransferEncoding | 21 | "Content-Transfer-Encoding:"
msgContentType | 22 | "Content-Type:"
msgControl | 23 | "Control:"
msgConversion | 24 | "Conversion:"
msgConversionWithLoss | 25 | "Conversion-With-Loss:"
msgDate | 26 | "Date:"
msgDeliveryDate | 27 | "Delivery-Date:"
msgDeliveryReport | 28 | "Delivery-Report:"
msgDiscardedX400IPMSExtensions | 29 | "Discarded-X400-IPMS-Extensions:"
msgDiscardedX400MTSExtensions | 30 | "Discarded-X400-MTS-Extensions:"
msgDiscloseRecipients | 31 | "Disclose-Recipients:"
msgDistribution | 32 | "Distribution:"
msgDLExpansionHistoryIndication | 33 | "DL-Expansion-History-Indication:"
msgEncoding | 34 | "Encoding:"
msgErrorsTo | 35 | "Errors-To:"
msgExpires | 36 | "Expires:"
msgFax | 37 | "Fax:"
msgFcc | 38 | "Fcc:"
msgFollowupTo | 39 | "Followup-To:"
msgForComment | 40 | "For-Comment:"
msgForHandling | 41 | "For-Handling:"
msgFrom | 42 | "From:"
msgGenerateDeliveryReport | 43 | "Generate-Delivery-Report:"
msgImportance | 44 | "Importance:"
msgIncompleteCopy | 47 | "In-Reply-To:"
msgInReplyTo | 46 | "Incomplete-Copy:"
msgKeywords | 48 | "Keywords:"
msgLanguage | 49 | "Language:"
msgLines | 50 | "Lines:"
msgMailer | 52 | "Mailer:"
msgMailSystemVersion | 51 | "Mail-System-Version:"
msgMessageID | 53 | "Message-ID"
msgMessageType | 54 | "Message-Type:"
msgMIMEVersion | 55 | "MIME-Version:"
msgNewsgroups | 56 | "Newsgroups:"
msgNull | 0 | N/A
msgObsoletes | 57 | "Obsoletes:"
msgOrganisation | 58 | "Organisation:"
msgOrganization | 59 | "Organization:"
msgOriginalEncodedInformationTypes | 60 | "Original-Encoded-Information-Types:"
msgOriginatingClient | 61 | "Originating-Client:"
msgPath | 62 | "Path:"
msgPhone | 63 | "Phone:"
msgPrecedence | 64 | "Precedence:"
msgPreventNonDeliveryReport | 65 | "Prevent-NonDelivery-Report:"
msgPriority | 66 | "Priority:"
msgReceived | 67 | "Received:"
msgReferences | 68 | "References:"
msgReplyBy | 69 | "Reply-By:"
msgReplyTo | 70 | "Reply-To:"
msgReturnPath | 72 | "Return-Path:"
msgReturnReceiptTo | 73 | "Return-Receipt-To:"
msgSeeAlso | 74 | "See-Also:"
msgSender | 75 | "Sender:"
msgSensitivity | 76 | "Sensitivity:"
msgStatus | 77 | "Status:"
msgSubject | 78 | "Subject:"
msgSummary | 79 | "Summary:"
msgSupersedes | 80 | "Supersedes:"
msgTelefax | 81 | "Telefax:"
msgX400ContentReturn | 82 | "X400-Content-Return:"
msgXMailer | 84 | "X-Mailer:"
msgXNewsreader | 85 | "X-Newsreader:"
msgXref | 86 | "Xref:"


%%PageItemTitle%%

MailErrorConstants Enumeration
Description
Enumerates Mail-Specific Errors
Members
Member | Value | Description
mailAbort | 11103 | The Abort method was called. FATAL.
mailAddressInUse | 10048 | Address already in use. Only one usage of each socket address (protocol/IP address/port) is normally permitted. This error occurs if an application attempts to bind() a socket to an IP address/port that has already been used for an existing socket, or a socket that wasn't closed properly, or one that is still in the process of closing. For server applications that need to bind() multiple sockets to the same port number, the ReuseAddress property can be used. FATAL.
mailAddressNotAvailable | 10049 | Cannot assign requested address. The requested address is not valid in its context. Normally results from an attempt to bind() to an address that is not valid for the local machine. This may also result from connect(), sendto(), WSAConnect(), WSAJoinLeaf(), or WSASendTo() when the remote address or port is not valid for a remote machine (for example, address or port 0). FATAL.
mailAttachUuencode | 15008 | Only (uuencoded) files may be attached to this non-MIME message. Consider using MIME or putting all text in the Message.Data property area.
mailAuthentication | 12012 | Authentication with the server failed. FATAL.
mailBadConfigItem | 15003 | Invalid Configuration Item
mailBadDataType | 15021 | Cannot create the requested data type or format.
mailBadRecipient | 15020 | Mail Recipient Not Accepted.
mailBadSender | 15019 | Sender address not accepted.
mailBlocked | 12011 | User thread is blocking in another method. INFO.
mailCompile | 12013 | An error occurred while compiling
mailConnected | 12014 | A connection already exists
mailConnectionAborted | 10053 | Software caused connection abort. An established connection was aborted by the software in your host machine, possibly due to a data transmission timeout or protocol error. FATAL.
mailConnectionRefused | 10061 | Connection refused. No connection could be made because the target machine actively refused it. This usually results from trying to connect to a service that is inactive on the foreign host (for example,. one with no server application running). May also be generated by a Daemon that refuses a connection because its resources have been exhausted. FATAL.
mailConnectionReset | 10054 | Connection reset by peer. An existing connection was forcibly closed by the remote host. This normally results if the peer application on the remote host is suddenly stopped, the host is rebooted, or the remote host used a "hard close" (see Abort method) on the remote socket. This error may also result if a connection was broken due to keep-alive activity detecting a failure while one or more operations are in progress. Operations that were in progress fail with ptNetworkReset. Subsequent operations fail with ptConnectionReset. FATAL.
mailDuplicateMessage | 15022 | Message object already exists in collection.
mailError | 11100 | Unexpected general error. FATAL.
mailFile | 11102 | Error accessing local file storage. FATAL.
mailFileOpen | 15000 | Unable to open file.
mailFileOperation | 15007 | A file operation (such as size) had failed.
mailFileRead | 15009 | A file read error has caused the operation to fail.
mailFileWrite | 15006 | A file write error has occurred. Check disk free space.
mailFormatError | 12015 | The server was unable to interpret the query.
mailHeader | 12101 | Occurs when a proper termination (usually a CRLFCRLF) is not found in the header.
mailHostNotFound | 11001 | Host not found. No such host is known. The name is not an official hostname or alias, or it cannot be found in the database(s) being queried. This error may also be returned for protocol and service queries, and means the specified name could not be found in the relevant database. FATAL.
mailHostUnreachable | 10065 | Remote host does not exist
mailHttpInvalidUrl | 12005 | The Url is unspecified or invalid.
mailInvalidMailAddress | 12021 | The Email address specified was not valid.
mailInvalidMessageHeader | 15005 | A recipient, from, and subject are needed for a valid message header.
mailInvalidParam1 | 12001 | Parameter #1 is invalid. INFO.
mailInvalidParam2 | 12002 | Parameter #2 is invalid. INFO.
mailInvalidParam3 | 12003 | Parameter #3 is invalid. INFO.
mailInvalidParam4 | 12004 | Parameter #4 is invalid. INFO.
mailInvalidProperty | 12009 | Invalid property assignment. INFO.
mailInvDecodeType | 15002 | An invalid or unsupported Decode Type was specified.
mailMsgObjRead | 15016 | An error has occurred while reading data from the Message object. Verify the Message object contents.
mailNetworkDown | 10050 | Network is down. A socket operation encountered a dead network. This could indicate a serious failure of the network system (for example,. the protocol stack that the Winsock DLL runs over), the network interface, or the local network itself. FATAL.
mailNetworkReset | 10052 | Network dropped connection on reset. The connection has been broken due to keep-alive activity detecting a failure while the operation was in progress. FATAL.
mailNetworkUnreachable | 10051 | Network is unreachable. A socket operation was attempted to an unreachable network. This usually means the local software knows no route to reach the remote host. FATAL.
mailNoAccess | 10013 | The user does not have the proper permissions
mailNoAuthMech | 15031 | No authentication mechanism was found in the server's advertised capabilities, a secure connection may be required.
mailNoBufferSpace | 10055 | No buffer space available. An operation on a socket could not be performed because the system lacked sufficient buffer space or because a queue was full. FATAL.
mailNoCertificate | 12020 | There was an error in creating credentials.
mailNoData | 11004 | Valid name, no data record of requested type. The requested name is valid and was found in the database, but it does not have the correct associated data being resolved for. The usual example for this is a hostname -> address translation attempt which uses the DNS, and an MX record is returned but no A record - indicating the host itself exists but is not directly reachable. FATAL.
mailNoHeader | 15015 | The message is invalid because the header was not found.
mailNoMemory | 15001 | There was not enough memory available to complete the operation.
mailNoMessageHeader | 15012 | The message does not contain a valid header.
mailNoRecipientsFound | 15013 | The message header does not contain any (valid) recipients (To).
mailNoRecovery | 11003 | This is a non-recoverable error. This indicates some sort of non-recoverable error occurred during a database lookup. This may be because the database files (for example, BSD-compatible HOSTS, SERVICES or PROTOCOLS files) could not be found, or a DNS (Domain Name Server) request was returned by the server with a severe error. FATAL.
mailNoSecurity | 12022 | Secure communications is not available on this machine.
mailNotConnected | 10057 | Socket is not connected. A request to send or receive data was disallowed because the socket is not connected or allocated. Any other type of operation might also return this error. FATAL.
mailNotFound | 12017 | The name referred to in the query does not exist.
mailNotImplemented | 12018 | The server does not support the request type of query.
mailNotInitialized | 10093 | Network interface could not be initialized. FATAL.Host not found. No such host is known. The name is not an official hostname or alias, or it cannot be found in the database(s) being queried. This error may also be returned for protocol and service queries, and means the specified name could not be found in the relevant database. FATAL.
mailNotInSpoolMode | 15017 | Method not allowed when spool mail mode is active.
mailNotMessageObject | 15014 | The passed object is not a Message object.
mailNotPartObject | 15011 | The operation requested requires an object of type Part.
mailOk | 0 | Ok
mailOnlyInSpoolMode | 15018 | The DeSpool Method is only available when mail spooling is enabled.
mailOperationRefused | 12019 | The server refused to perform the specified operation.
mailOptionNotSupported | 10042 | The specified socket option is not supported by the system. INFO.
mailPartInStructure | 15010 | The Part to Add already exists in this structure.
mailProtocol | 11101 | Unexpected protocol error. FATAL.
mailServerError | 12016 | There was a failure on the server.
mailSocks4DifferentUserID | 12093 | The SOCKS4 server rejected the connection because the client program and identd report different user-ids
mailSocks4NoAcceptableMethods | 12024 | The SOCKS5 server will not accept any of the requested methods
mailSocks4NoIdentd | 12092 | The SOCKS4 server rejected the connection because it was unable to connect to identd on the client
mailSocks4RequestRejected | 12091 | The SOCKS4 server rejected the connection (No reason given)
mailSocks5AddressTypeNotSupported | 12038 | The SOCKS5 server reported that the address type is not supported
mailSocks5AuthFailed | 12039 | The SOCKS5 server rejected the connection because authorization failed
mailSocks5CommandNotSupported | 12037 | The SOCKS5 server reported that the command is not supported
mailSocks5ConnectionRefused | 12035 | The SOCKS5 server reported that the host connection was refused
mailSocks5HostUnreachable | 12034 | The SOCKS5 server reported that the host was unreachable
mailSocks5NetworkUnreachable | 12033 | The SOCKS5 server reported that the network was unreachable
mailSocks5NoRuleSet | 12032 | The SOCKS5 server reported that the connection was not allowed by the ruleset
mailSocks5ServerFailure | 12031 | The SOCKS5 server reported a general failure
mailSocks5TTLExpired | 12036 | The SOCKS5 server reported that the TTL has expired
mailTimeout | 10060 | Timed out. A connection attempt failed because the connected party did not properly respond after a period of time, or an established connection failed because connected host has failed to respond. Alternatively, a blocked method failed to return within the period specified by the Timeout property. FATAL.
mailTryAgain | 11002 | Non-authoritative host not found. This is usually a temporary error during hostname resolution and means that the local server did not receive a response from an authoritative server. A retry at some time later may be successful. FATAL.
mailUseMimeEncode | 15004 | mailUseMimeEncoding must be Always, Never, or Smallest


%%PageItemTitle%%

MailPrivacyConstants Enumeration
Description
Enumerates values of the Privacy property.
Members
Member | Value | Description
privacyExplicitTLS | 6 | Use TLS 1.0, 1.1 or 1.2 as the explicit security protocol
privacyExplicitTLS1_1 | 8 | Use TLS 1.1 as the explicit security protocol
privacyExplicitTLS1_2 | 10 | Use TLS 1.2 as the explicit security protocol
privacyImplicitAuto | 0 | Automatically pick the implicit security protocol
privacyImplicitPCT | 3 | Use PCT 1.0 as the implicit security protocol
privacyImplicitSSL2 | 2 | Use SSL 2.0 as the implicit security protocol
privacyImplicitSSL3 | 1 | Use SSL 3.0 as the implicit security protocol
privacyImplicitTLS | 4 | Use TLS 1.0, 1.1 or 1.2 as the implicit security protocol
privacyImplicitTLS1_1 | 7 | Use TLS 1.1 as the implicit security protocol
privacyImplicitTLS1_2 | 9 | Use TLS 1.2 as the implicit security protocol
privacyNone | 5 | Operate connection in the clear


%%PageItemTitle%%

PartConstants Enumeration
Description
Enumerates the values of the Part parameter of the Get method.
Members
Member | Value | Description
msgContent | 0 | Requests the retrieval of the complete message for each message in MsgSet.
msgPreview | 3 | Requests the message header followed by 'n' lines, where 'n' is the value of the Preview property.
msgSize | 1 | Requests the size for each message specified in MsgSet.
msgUidl | 2 | Requests the message UID label for each message in MsgSet.


%%PageItemTitle%%

PopMethodConstants Enumeration
Description
Enumerates the values of the Method parameter of the Progress event.
Members
Member | Value | Description
popCommand | 5 | Command, CommandEx methods
popDelete | 2 | Delete method
popGet | 4 | Fetch method
popLogin | 0 | Login method
popLogout | 1 | Logout method
popReset | 3 | Reset method
popStls | 6 | StartTLS Command


%%PageItemTitle%%

PopStatusConstants Enumeration
Description
Enumerates the values of the Status parameter of the Progress event.
Members
Member | Value | Description
popBad | 1 | The server has responded with a negative status.
popContent | 5 | Indicates intermediate events during the receipt of a mail message. Useful for percentage indication on a status display.
popCount | 3 | The Count property has been updated.
popDeleting | 8 | Indicates a message delete has been acknowledged.
popInfo | 2 | The server has supplied information.
popOk | 0 | The method has completed with a positive status.
popPreview | 6 | Retrieval of a complete message header plus preview lines.
popSize | 4 | The message Size property has been updated.
popUidl | 7 | Retrieval of a message UID label.


%%PageItemTitle%%

PutConstants Enumeration
Description
Enumerates values of the Part parameter of Put method.
Members
Member | Value | Description
imapPutFlags | 0 | Replaces the flags for each message in the MsgSet.
imapPutFlagsAdd | 1 | Adds flags for each message in the MsgSet.
imapPutFlagsRemove | 2 | Removes flags for each message in the MsgSet.


%%PageItemTitle%%

ReturnTypeConstants Enumeration
Description
Enumerates the type of buffer to be returned from a property that returns either a String and Byte array.
Members
Member | Value | Description
msgByteArray | 1 | Return the value as a Byte array.
msgString | 0 | Return the value as a String.


%%PageItemTitle%%

SecurityConstants Enumeration
Description
Security Constants
Members
Member | Value | Description
secureIgnoreCertificate | 1 | Accept all certificates passed from the server
secureIgnoreDate | 2 | Accept otherwise valid certificate if date has expired
secureIgnoreSignature | 8 | Accept otherwise valid certificate if signature cannot be verified
secureIgnoreUntrustedRoot | 4 | Accept otherwise valid certificate if Certificate Authority Root is not known
secureNormal | 0 | Apply all server certificate security checks


%%PageItemTitle%%

SegmentConstants Enumeration
Description
Enumerates the message segments.
Members
Member | Value | Description
msgHeader | 0 | Perform the operation on the header of the message.
msgMessage | 1 | Perform the operation on the complete message.


%%PageItemTitle%%

SmtpMethodConstants Enumeration
Description
Enumerates values of the Method parameter of the Progress event. Indicates the method that initiated the event.
Members
Member | Value | Description
smtpCommand | 5 | Command, CommandEx Methods
smtpLogin | 0 | Login method
smtpLogout | 1 | Logout method
smtpQuickSend | 3 | QuickSend method
smtpReset | 4 | Reset method
smtpSend | 2 | Send method


%%PageItemTitle%%

SmtpStatusConstants Enumeration
Description
Enumerates values of the Status parameter of the Progress event. Provides success / failure / progress information.
Members
Member | Value | Description
smtpBad | 1 | Server has responded with a negative status indicating an error condition.
smtpCapabilities | 5 | Capabilities is updated.
smtpFrom | 2 | Server has responded positive to "MAIL FROM:" during the execution of the Send or QuickSend method.
smtpOk | 0 | Method has completed with a positive status indicating successful operation.
smtpSending | 4 | Indicates progress during the transmission of a message. Useful for percentage indication on a status display.
smtpTo | 3 | Server has responded positive to "RCPT TO:" during the execution of the Send or QuickSend method.


%%PageItemTitle%%

StateConstants Enumeration
Description
Enumerates values of the State property.
Members
Member | Value | Description
tcpClosed | 0 | The session is not connected and has no resources allocated to it.
tcpClosing | 3 | The session is transitioning gracefully from tcpConnected to tcpClosed.
tcpConnected | 2 | The session is active and can send/receive data.
tcpConnecting | 1 | The session is transitioning from tcpClosed to tcpConnected.


%%PageItemTitle%%

VerifyMethodConstants Enumeration
Description
Enumerates the return value of the Verify method.
Members
Member | Value | Description
verifyBadUser | 4 | The username of the Email address was not valid.
verifyConnectMailServer | 3 | A connection to the mail server specified in the Email address could not be made.
verifyDomain | 2 | The domain specified in the Email address was not valid.
verifyFormat | 1 | The format of the Email address was not valid.
verifyValid | 0 | No Error (default)


%%Phrase%%

Dart Tcp, Daemon, Udp Controls
Project Overview
Description
Dart Tcp, Daemon, Udp Controls
Classes
Class Module | Description
DartStream | Use the DartStream Object to manage a streamed buffer to/from memory or a file.
Public Enumerations
Enumeration | Description
ErrorConstants

Errors are reported to the application with the error object and by firing the Error event. ErrorConstants fall into two classes: design-time errors and run-time errors. The Error event always fires when any error occurs. When Timeout is 0, however, run-time errors are not thrown back to the container. This allows applications that use only non-blocking operation to localize all error handling in the Error event. To summarize:

Timeout is 0 (non-blocking). All errors are reported via the Error event. Only errors classified as design time errors are also reported back from methods using the error object.

Timeout is not 0 (blocking). All errors are reported via the Error event. All errors occurring within the scope of a method are reported back to the container using the error object.

Errors are marked as INFO or FATAL. An INFO error does not affect the State property. A FATAL error performs an Abort and releases all resources.

FileModeConstants | Enumerates values of the FileMode property.


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
DartStream Object
Members
Description
Use the DartStream Object to manage a streamed buffer to/from memory or a file.
See Also

DartStream Members


%%PageItemTitle%% $$Members$$

Dart Tcp, Daemon, Udp Controls
DartStream Object Members
Overview
Public Methods
Public Method Clear | Clear the stream.
Public Method Read | Read one or more bytes from the stream. Reading starts at the Position property. Set Position to change the position.
Public Method ReadBytes | Return data from the current position as a Byte Array. Reading starts at the Position property. Set Position to change the position.
Public Method ReadString | Return data from the current position as a String. Reading starts at the Position property. Set Position to change the position.
Public Method Write | Write one or more bytes to the stream. Writing starts at the Position property. Set Position to change the position.
Public Properties
Public Property DeleteOnDestroy | Specifies if the corresponding file should be deleted when the object is destroyed.
Public Property FileMode | How the file is to be created or opened.
Public Property FileName | Intended name of the file.
Public Property Position | Current byte position in the stream.
Public Property PositionHigh | Current byte position in the stream. Used only when the current position is greater than 2^31 (2147483648).
Public Property Ref | Stores a reference to another object, data type, or value.
Public Property Size | Size of the stream in bytes.
Public Property SizeHigh | Size of the stream in bytes. Used only when the size is 2^31 (2147483648).
Public Property UniqueName | Name of the file currently open.
See Also

DartStream Object


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
Clear Method
DartStream Object : Clear Method
Description
Clear the stream.
Syntax
Visual Basic
Public Sub Clear()
Remarks

WARNING USE WITH CAUTION!

This method sets Size and Position to 0. ALL DATA IS PERMANENTLY LOST!

Error Codes

This method may generate the following error code (refer to ErrorConstants for a complete list of error codes):

  • ptInvalidParam1
  • ptInvalidParam2
  • ptNoBufferSpace
See Also

DartStream Object | DartStream Members


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
Read Method
DartStream Object : Read Method
Read one or more bytes from the stream. Reading starts at the Position property. Set Position to change the position.
Specifies how much data to read.
Description
Read one or more bytes from the stream. Reading starts at the Position property. Set Position to change the position.
Syntax
Visual Basic
Public Function Read( _
   ByRef Buffer As Variant, _
   Optional ByVal Count As Long = 0 _
) As Long
Parameters
Buffer
Read one or more bytes from the stream. Reading starts at the Position property. Set Position to change the position.
Count
Specifies how much data to read.
Return Value
Indicates how much data was read.
Remarks

If the Buffer parameter is omitted, then this method attempts to read all the data from the current position to the end of the stream. The position is advanced Count bytes upon completion.

Error Codes

This method may generate the following error code (refer to ErrorConstants for a complete list of error codes):

  • ptInvalidParam1
  • ptInvalidParam2
  • ptNoBufferSpace
See Also

DartStream Object | DartStream Members


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
ReadBytes Method
DartStream Object : ReadBytes Method
Specifies how much data is to be read.
Description
Return data from the current position as a Byte Array. Reading starts at the Position property. Set Position to change the position.
Syntax
Visual Basic
Public Function ReadBytes( _
   Optional ByVal Count As Long = 0 _
) As Variant
Parameters
Count
Specifies how much data is to be read.
Return Value
Returned Byte Array. Indicates how much data was read.
Remarks

Some environments, such as JavaScript, do not support the passing of parameters by reference. Consequently, such methods as Receive cannot be used by passing in a String. You can use the DartStream Object to circumvent this limitation (see the ReadString method Remarks section for a Java sample).

Error Codes

This method may generate the following error code (refer to ErrorConstants for a complete list of error codes):

  • ptInvalidParam1
  • ptInvalidParam2
  • ptNoBufferSpace
See Also

DartStream Object | DartStream Members


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
ReadString Method
DartStream Object : ReadString Method
Specifies how much data is to be read.
Description
Return data from the current position as a String. Reading starts at the Position property. Set Position to change the position.
Syntax
Visual Basic
Public Function ReadString( _
   Optional ByVal Count As Long = 0 _
) As String
Parameters
Count
Specifies how much data is to be read.
Remarks

Some environments, such as JavaScript, do not support the passing of parameters by reference. Consequently, such methods as Receive cannot be used by passing in a String. You can use the DartStream Object to circumvent this limitation, as shown in the following Java sample:

<% @LANGUAGE="JScript"%>
<%
 var Tcp = Server.CreateObject("Dart.Tcp.1");
 Tcp.TimeOut = 30000;
 Tcp.Connect("www.microsoft.com", 80);
 Tcp.Send("GET / HTTP/1.0\r\n\r\n");
 var Stream = Server.CreateObject("Dart.DartStream");
 while(Tcp.State != 0)
 Tcp.Receive(Stream);
 Stream.Position = 0;
 Response.Write(Stream.ReadString());
%>

Error Codes

This method may generate the following error code (refer to ErrorConstants for a complete list of error codes):

  • ptInvalidParam1
  • ptInvalidParam2
  • ptNoBufferSpace
See Also

DartStream Object | DartStream Members


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
Write Method
DartStream Object : Write Method
Initialized String or Byte Array. Where data is being written from.
Specifies how much data is to be written.
Description
Write one or more bytes to the stream. Writing starts at the Position property. Set Position to change the position.
Syntax
Visual Basic
Public Function Write( _
   ByVal Buffer As Variant, _
   Optional ByVal Count As Long = 0 _
) As Long
Parameters
Buffer
Initialized String or Byte Array. Where data is being written from.
Count
Specifies how much data is to be written.
Return Value
Indicates how much data was written.
Remarks

If the Count parameter is omitted, then this method writes the entire contents of the Buffer parameter. After the data is written the Position is advanced Count bytes.

Error Codes

This method may generate the following error code (refer to ErrorConstants for a complete list of error codes):

  • ptInvalidParam1
  • ptInvalidParam2
  • ptNoBufferSpace
See Also

DartStream Object | DartStream Members


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
DeleteOnDestroy Property
DartStream Object : DeleteOnDestroy Property
Description
Specifies if the corresponding file should be deleted when the object is destroyed.
Property type
Read-write property
Syntax
Visual Basic
Public Property DeleteOnDestroy As Boolean
Remarks

WARNING USE WITH CAUTION!

When set to True and FileName specifies a file, the file is deleted when this object is destroyed.

See Also

DartStream Object | DartStream Members


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
FileMode Property
DartStream Object : FileMode Property
Description
How the file is to be created or opened.
Property type
Read-write property
Syntax
Visual Basic
Public Property FileMode As FileModeConstants
Remarks
Set this property prior to changing FileName to determine how the file is created.
See Also

DartStream Object | DartStream Members


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
FileName Property
DartStream Object : FileName Property
Description
Intended name of the file.
Property type
Read-write property
Syntax
Visual Basic
Public Property FileName As String
Remarks

When set to a file name, the file is opened. When set to an empty string, the file is closed.

When set to an empty string and then changed to a file name, a file is created or opened according to FileMode. If an existing file is opened, the value of the Size property determines how the file is treated:

  • If Size = 0 when the file is opened, it is assumed the file is being opened for reading, and Size is set to the size of the file.
  • If Size > 0 when the file is opened, it is assumed the file is being opened for writing, and the existing contents of the file are replaced.

When set to a file name and then changed to an empty string, all data in the file is buffered to memory and the file is closed.

When set to a file name and then changed to a different file name, the file is moved to the new location. If FileMode = createUnique, an existing file cannot be unintentionally overwritten.

You can delete a file only by setting this property to an existing file name, setting FileMode to createOpen or createExisting, setting DeleteOnDestroy to True, and allowing the DartStream Object to be destroyed.

See Also

DartStream Object | DartStream Members


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
Position Property
DartStream Object : Position Property
Description
Current byte position in the stream.
Property type
Read-write property
Syntax
Visual Basic
Public Property Position As Long
Remarks
The Read and Write methods use this starting position. This property can be set to any value between 0 and Size. Position is initialized to 0 when the buffer is empty.
See Also

DartStream Object | DartStream Members


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
PositionHigh Property
DartStream Object : PositionHigh Property
Description
Current byte position in the stream. Used only when the current position is greater than 2^31 (2147483648).
Property type
Read-write property
Syntax
Visual Basic
Public Property PositionHigh As Long
Remarks
Since the Position property is a Long, it is unable to be set to a value greater than 2^31. To set the position of a DartStream to a value greater than 2^31, first set this property to an integer value which will be multiplied by 2^31, then added to Position to determine the actual position.
See Also

DartStream Object | DartStream Members


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
Ref Property
DartStream Object : Ref Property
Description
Stores a reference to another object, data type, or value.
Property type
Read-write property
Syntax
Visual Basic
Public Property Ref As Variant
Remarks

This property is available only at run time.

Use this property to associate the control with any Variant. If the data type is String, Ref stores a copy of the string. If the data type is a Byte array, it stores a copy of the Byte array. If the data type is an object, it increases the reference count of the object.

When the DartStream is destroyed, and Ref holds an object reference, that object's reference count is decremented.

See Also

DartStream Object | DartStream Members


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
Size Property
DartStream Object : Size Property
Description
Size of the stream in bytes.
Property type
Read-only property
Syntax
Visual Basic
Public Property Size As Long
See Also

DartStream Object | DartStream Members


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
SizeHigh Property
DartStream Object : SizeHigh Property
Description
Size of the stream in bytes. Used only when the size is 2^31 (2147483648).
Property type
Read-only property
Syntax
Visual Basic
Public Property SizeHigh As Long
Remarks

This property is not an actual count of bytes, but a count of the number of times the size of the file has exceeded 2^31. For example, the first time a file is written to, this property will be 0. If the Size property exceeds 2^31, the Size property will go back to 0 and the SizeHigh property will be incremented to 1. If Size exceeds 2^31 again, it is again reset to 0 and SizeHigh is incremented to 2. So, to find the actual file size, use:

(SizeHigh * 2147483648) + Size

See Also

DartStream Object | DartStream Members


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
UniqueName Property
DartStream Object : UniqueName Property
Description
Name of the file currently open.
Property type
Read-only property
Syntax
Visual Basic
Public Property UniqueName As String
Remarks
This property is usually the same as FileName, but is different when FileMode property is createUnique and FileName already exists. In this case, a period and a number (starting at 1) is appended to FileName and saved as this property.
See Also

DartStream Object | DartStream Members


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
ErrorConstants Enumeration
Description

Errors are reported to the application with the error object and by firing the Error event. ErrorConstants fall into two classes: design-time errors and run-time errors. The Error event always fires when any error occurs. When Timeout is 0, however, run-time errors are not thrown back to the container. This allows applications that use only non-blocking operation to localize all error handling in the Error event. To summarize:

Timeout is 0 (non-blocking). All errors are reported via the Error event. Only errors classified as design time errors are also reported back from methods using the error object.

Timeout is not 0 (blocking). All errors are reported via the Error event. All errors occurring within the scope of a method are reported back to the container using the error object.

Errors are marked as INFO or FATAL. An INFO error does not affect the State property. A FATAL error performs an Abort and releases all resources.

Members
Member | Value | Description
ptAbort | 11103 | Blocking operation cancelled by user
ptAddressInUse | 10048 | Specified address in use (Connect method)
ptAddressNotAvailable | 10049 | The remote address is not a valid address
ptAuthentication | 12012 | An invalid UserName or Password was specified
ptBlocked | 12011 | User thread is blocking in another method
ptCompile | 12013 | An error occurred while compiling
ptConnected | 12014 | A connection already exists
ptConnectionAborted | 10053 | Connection was aborted due to timeout or other failure
ptConnectionRefused | 10061 | Connection forcefully refused
ptConnectionReset | 10054 | Connection was reset by the remote side executing a hard close
ptError | 11100 | Unexpected error
ptFile | 11102 | An error has occurred while performing a File I/O operation.
ptFormatError | 12015 | The server was unable to interpret the query
ptHeader | 12101 | The header is not properly terminated
ptHostNotFound | 11001 | Authoritative: Host name could not be resolved
ptHostUnreachable | 10065 | The host is not found
ptHttpInvalidUrl | 12005 | The Url is unspecified or invalid.
ptInvalidMailAddress | 12021 | The EMail address specified was not valid
ptInvalidParam1 | 12001 | Parameter #1 is invalid
ptInvalidParam2 | 12002 | Parameter #2 is invalid
ptInvalidParam3 | 12003 | Parameter #3 is invalid
ptInvalidParam4 | 12004 | Parameter #4 is invalid
ptInvalidProperty | 12009 | Invalid property assignment. You are attempting to use a property that is not available in this version of the control. Please contact support@dart.com for more information.
ptNetworkDown | 10050 | The network subsystem has failed
ptNetworkReset | 10052 | Connection has been broken due to keep-alive activity detecting a failure
ptNetworkUnreachable | 10051 | The network is unreachable
ptNoAccess | 10013 | The user does not have the proper permissions
ptNoBufferSpace | 10055 | No buffer space is available
ptNoCertificate | 12020 | There was an error in creating credentials
ptNoData | 11004 | Valid name, no data record of requested type
ptNoRecovery | 11003 | A non-recoverable error
ptNoSecurity | 12022 | Secure communications is not available on this machine
ptNotConnected | 10057 | Not connected
ptNotFound | 12017 | The name referred to in the query does not exist
ptNotImplemented | 12018 | The server does not support the request type of query
ptNotInitialized | 10093 | Network interface could not be initialized
ptOk | 0 | Ok
ptOperationRefused | 12019 | The server refused to perform the specified operation
ptOptionNotSupported | 10042 | Specified socket option not supported
ptProtocol | 11101 | An error has occurred in the the protocol
ptServerError | 12016 | There was a failure on the server
ptSocks4DifferentUserID | 12093 | The SOCKS4 server rejected the connection because the client program and identd report different user-ids
ptSocks4NoAcceptableMethods | 12024 | The SOCKS5 server will not accept any of the requested methods
ptSocks4NoIdentd | 12092 | The SOCKS4 server rejected the connection because it was unable to connect to identd on the client
ptSocks4RequestRejected | 12091 | The SOCKS4 server rejected the connection (No reason given)
ptSocks5AddressTypeNotSupported | 12038 | The SOCKS5 server reported that the address type is not supported
ptSocks5AuthFailed | 12039 | The SOCKS5 server rejected the connection because authorization failed
ptSocks5CommandNotSupported | 12037 | The SOCKS5 server reported that the command is not supported
ptSocks5ConnectionRefused | 12035 | The SOCKS5 server reported that the host connection was refused
ptSocks5HostUnreachable | 12034 | The SOCKS5 server reported that the host was unreachable
ptSocks5NetworkUnreachable | 12033 | The SOCKS5 server reported that the network was unreachable
ptSocks5NoRuleSet | 12032 | The SOCKS5 server reported that the connection was not allowed by the ruleset
ptSocks5ServerFailure | 12031 | The SOCKS5 server reported a general failure
ptSocks5TTLExpired | 12036 | The SOCKS5 server reported that the TTL has expired
ptTimeout | 10060 | Timeout occurred for requested operation
ptTryAgain | 11002 | Non-authoritiative: Host name could not be resolved
zipError | 14001 | An error occurred during a zip operation


%%PageItemTitle%%

Dart Tcp, Daemon, Udp Controls
FileModeConstants Enumeration
Description
Enumerates values of the FileMode property.
Members
Member | Value | Description
createAlways | 0 | If the file exists then replace the file, if it does not exist then create it.
createExisting | 1 | If the file exists then open it. If the file does not exist then throw an error.
createOpen | 3 | If the file exists then open the file, if it does not exist then create it.
createUnique | 2 | If the file exists then create a file with a unique name (a period and a number are appended to the filename). If it does not exist then create it.


%%Phrase%%

Dart CertificateList Control and Objects
Project Overview
Description
Dart CertificateList Control and Objects
Classes
Class Module | Description
Certificate | Use the Certificate Object to access information about a digital certificate.
CertificateList

Use this control to present the user with an interface to select certificates. The CertificateList Control is derived from a standard ListView window. By default it has this standard appearance:

  • Report view
  • Three column headers: Issued By, Issued To, and Key Size
  • Default certificate icon
Certificates | Collection of Certificate Objects.
CertificateStore | Use the CertificateStore Object to gain access to a store of certificates on the local system.
Public Enumerations
Enumeration | Description
AppearanceConstants | Enumerates the Appearance property.
BorderStyleConstants | Enumerates the BorderStyle property.
CertificateErrorConstants | Certificate Error Constants
KeyUsageConstants | Enumerates the Usage parameter of the KeyUsage property.
ProviderConstants | Enumerates the cryptographic providers allowed by Microsoft. The most commonly used provider for Microsoft certificates is the Microsoft Base Cryptographic Provider.
StoreLocationConstants | Enumerates the possible values of the Location property of the CertificateStore Object.


%%PageItemTitle%%

Dart CertificateList Control and Objects
Certificate Object
Members
Description
Use the Certificate Object to access information about a digital certificate.
See Also

Certificate Members


%%PageItemTitle%% $$Members$$

Dart CertificateList Control and Objects
Certificate Object Members
Overview
Public Properties
Public Property FriendlyName | Friendly name of the certificate.
Public Property Handle | Certificate handle.
Public Property IssuedBy | Name of the Certificate Authority that issued/signed the certificate.
Public Property IssuedTo | Certificate subject or owner.
Public Property KeyName | Name of the key container that contains the private key of the certificate.
Public Property KeySize | Size of the key measured in bits.
Public Property KeyUsage | Key usage attributes.
Public Property SerialNumber | Serial number of the certificate.
Public Property StoreLocation | The location of the certificate store that contains this certificate.
Public Property StoreName | The name of the certificate store that contains this certificate.
Public Property ValidFrom | Starting date and time (in Greenwich Mean Time) the certificate is valid.
Public Property ValidTo | Ending date and time (in Greenwich Mean Time) the certificate is valid.
Public Property Version | X.509 version of the certificate.
See Also

Certificate Object


%%PageItemTitle%%

Dart CertificateList Control and Objects
FriendlyName Property
Certificate Object : FriendlyName Property
Description
Friendly name of the certificate.
Property type
Read-only property
Syntax
Visual Basic
Public Property FriendlyName As String
See Also

Certificate Object | Certificate Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Handle Property
Certificate Object : Handle Property
Description
Certificate handle.
Property type
Read-write property
Syntax
Visual Basic
Public Property Handle As Long
Remarks
Use this handle in place of PCCERT_CONTEXT values in relevant Crypto API functions.
See Also

Certificate Object | Certificate Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
IssuedBy Property
Certificate Object : IssuedBy Property
Description
Name of the Certificate Authority that issued/signed the certificate.
Property type
Read-only property
Syntax
Visual Basic
Public Property IssuedBy As String
See Also

Certificate Object | Certificate Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
IssuedTo Property
Certificate Object : IssuedTo Property
Description
Certificate subject or owner.
Property type
Read-only property
Syntax
Visual Basic
Public Property IssuedTo As String
Remarks
When a certificate request is made, a "common name" is specified. The Certificate Authority usually uses this name for the subject name as defined by X.509, which corresponds to this property.
See Also

Certificate Object | Certificate Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
KeyName Property
Certificate Object : KeyName Property
Description
Name of the key container that contains the private key of the certificate.
Property type
Read-only property
Syntax
Visual Basic
Public Property KeyName As String
Remarks
The key name is also useful when deleting the key pair associated with a certificate. You cannot recover a key pair once it is destroyed. A new key pair needs to be generated and a new certificate needs to be issued. This is recommended for advanced users only. See the Microsoft Crypto API documentation for more information.
See Also

Certificate Object | Certificate Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
KeySize Property
Certificate Object : KeySize Property
Description
Size of the key measured in bits.
Property type
Read-only property
Syntax
Visual Basic
Public Property KeySize As Long
Remarks

This property indicates the strength of the keys used by the certifcate.

Key | Size | Strength
512 | bit | Weak
1024 | bit | Strong
2048 | bit | Stronger

Note To generate keys that are greater than 512 bits the "Microsoft Enhanced Cryptographic Provider v1.0" is needed.

See Also

Certificate Object | Certificate Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
KeyUsage Property
Certificate Object : KeyUsage Property
Description
Key usage attributes.
Property type
Read-only property
Syntax
Visual Basic
Public Property KeyUsage( _
   ByVal Usage As KeyUsageConstants _
) As Boolean
Parameters
Usage
Value | Description
usageAll | Used for the KeyUsageSelect property only, selects all Certificates in the Store.
usageCertSign | Certificate can be used for Certificate Signing.
usageClientAuthentication | Certificate can be used for Client Authentication.
usageCodeSigning | Certificate can be used for Code Signing.
usageCrlSign | Certificate can be used for Encipherment.
usageDataEncipherment | Certificate can be used for Data Encipherment.
usageDigitalSignature | Certificate can be used for Digital Signatures.
usageEmailProtection | Certificate can be used for Email Protection.
usageIPSecEndSystem | Certificate can be used for IPSec End System.
usageIPSecTunnel | Certificate can be used for IPSec Tunneling.
usageIPSecUser | Certificate can be used for IPSec Users.
usageKeyAgreement | Certificate can be used for Key Agreement.
usageKeyEncipherment | Certificate can be used for Key Encipherment.
usageNone | Certificate has no usage flag.
usageNonRepudiation | Certificate can be used prevent Repudiation.
usageOfflineCrlSign | Certificate can be used for CRL Signing.
usageServerAuthentication | Certificate can be used for Server Authentication.
usageTimeStampSigning | Certificate can be used for Time Stamp signing.
See Also

Certificate Object | Certificate Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
SerialNumber Property
Certificate Object : SerialNumber Property
Description
Serial number of the certificate.
Property type
Read-only property
Syntax
Visual Basic
Public Property SerialNumber As String
Remarks
In combination with IssuedBy, this property can be used to uniquely identify a certificate.
See Also

Certificate Object | Certificate Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
StoreLocation Property
Certificate Object : StoreLocation Property
Description
The location of the certificate store that contains this certificate.
Property type
Read-only property
Syntax
Visual Basic
Public Property StoreLocation As StoreLocationConstants
See Also

Certificate Object | Certificate Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
StoreName Property
Certificate Object : StoreName Property
Description
The name of the certificate store that contains this certificate.
Property type
Read-only property
Syntax
Visual Basic
Public Property StoreName As String
See Also

Certificate Object | Certificate Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
ValidFrom Property
Certificate Object : ValidFrom Property
Description
Starting date and time (in Greenwich Mean Time) the certificate is valid.
Property type
Read-only property
Syntax
Visual Basic
Public Property ValidFrom As Date
See Also

Certificate Object | Certificate Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
ValidTo Property
Certificate Object : ValidTo Property
Description
Ending date and time (in Greenwich Mean Time) the certificate is valid.
Property type
Read-only property
Syntax
Visual Basic
Public Property ValidTo As Date
See Also

Certificate Object | Certificate Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Version Property
Certificate Object : Version Property
Description
X.509 version of the certificate.
Property type
Read-only property
Syntax
Visual Basic
Public Property Version As Long
See Also

Certificate Object | Certificate Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
CertificateList Object
Members
Description

Use this control to present the user with an interface to select certificates. The CertificateList Control is derived from a standard ListView window. By default it has this standard appearance:

  • Report view
  • Three column headers: Issued By, Issued To, and Key Size
  • Default certificate icon
Object Model
CertificateList ObjectCertificates Collection
See Also

CertificateList Members


%%PageItemTitle%% $$Members$$

Dart CertificateList Control and Objects
CertificateList Object Members
Overview
Public Methods
Public Method Find | Searches the specified certificate store for the specified Certificate and returns the result.
Public Method Load | Loads the certificates in a certificate file into the Certificate List.
Public Method Refresh | Populates the Certificates property with the certificates in the store.
Public Properties
Public Property Appearance | Returns or sets the appearance (flat or 3-D) of the control.
Public Property BackColor | Returns or sets the background color of the control.
Public Property BorderStyle | Returns or sets the border style of the control.
Public Property Certificates | Collection of Certificate Objects in the store.
Public Property Enabled | Returns or sets a value that determines whether the control can respond to user-generated events.
Public Property Font | Returns or sets the font used in the display of the control.
Public Property ForeColor | Returns or sets the foreground color used for text.
Public Property GridLines | Returns or sets a value the determines if the CertificateList Control displays gridlines in Report View. The default is False (no gridlines).
Public Property HideColumnHeaders | Returns or sets whether ColumnHeader objects in the CertificateList Control are hidden in Report view.
Public Property HotTracking | Returns a value that determines whether mouse-sensitive highlighting is enabled.
Public Property hWnd | Returns the handle to the window of the CertificateList Control.
Public Property KeyUsageSelect | Filters out all certificates that do not have the specified KeyUsage attribute.
Public Property SelectedIndex | Index of the selected certificate.
Public Property StoreLocation | Location of the certificate store.
Public Property StoreName | Name of the certificate store.
Events
Public Event Click | Fires when the user clicks the left mouse button on the CertificateList Control.
Public Event DblClick | Fires when the user double clicks the left mouse button on the control.
Public Event KeyDown | Fires when the user presses a key while the control has focus.
Public Event RightClick | Fires when the user clicks the right mouse button on the control.
See Also

CertificateList Object


%%PageItemTitle%%

Dart CertificateList Control and Objects
Find Method
CertificateList Object : Find Method
Name of the certificate store.
Registry location of the certificate store.
Name of the Certificate Authority that issued/signed the certificate. Matches the IssuedBy property of the returned certificate.
Serial number of the certificate. Matches the SerialNumber property of the returned certificate.
Returned Certificate.
Description
Searches the specified certificate store for the specified Certificate and returns the result.
Syntax
Visual Basic
Public Sub Find( _
   ByVal Name As String, _
   ByVal Location As StoreLocationConstants, _
   ByVal IssuedBy As String, _
   ByVal SerialNumber As String, _
   ByVal Value As Certificate _
)
Parameters
Name
Name of the certificate store.
Location
Value | Description
locationCurrentUser | Store is located in the HKEY_CURRENT_USER registry key.
locationLocalMachine | Store is located in the HKEY_LOCAL_MACHINE registry key.
locationRemote | Used by a Certificate that is not part of a store.
Registry location of the certificate store.
IssuedBy
Name of the Certificate Authority that issued/signed the certificate. Matches the IssuedBy property of the returned certificate.
SerialNumber
Serial number of the certificate. Matches the SerialNumber property of the returned certificate.
Value
Returned Certificate.
Remarks

This method is used to do a quick lookup of the specified certificate.

Error Codes

This method may generate the following error code (refer to CertificateErrorConstants for a complete list of error codes):

  • ptNoCertificate (no matching certificate found)
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Load Method
CertificateList Object : Load Method
Filename of the Certificate to load.
Certificate password.
Description
Loads the certificates in a certificate file into the Certificate List.
Syntax
Visual Basic
Public Sub Load( _
   ByVal CertFileName As String, _
   Optional ByVal Password As String _
)
Parameters
CertFileName
Filename of the Certificate to load.
Password
Certificate password.
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Refresh Method
CertificateList Object : Refresh Method
Description
Populates the Certificates property with the certificates in the store.
Syntax
Visual Basic
Public Sub Refresh()
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Appearance Property
CertificateList Object : Appearance Property
Description
Returns or sets the appearance (flat or 3-D) of the control.
Property type
Read-write property
Syntax
Visual Basic
Public Property Appearance As AppearanceConstants
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
BackColor Property
CertificateList Object : BackColor Property
Description
Returns or sets the background color of the control.
Property type
Read-write property
Syntax
Visual Basic
Public Property BackColor As ULong
Remarks

Long value or constant that specifies an RGB color.

The default value is the system color for window background.

Reference the standard Windows controls documentation for information on color usage.

See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
BorderStyle Property
CertificateList Object : BorderStyle Property
Description
Returns or sets the border style of the control.
Property type
Read-write property
Syntax
Visual Basic
Public Property BorderStyle As BorderStyleConstants
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Certificates Property
CertificateList Object : Certificates Property
Description
Collection of Certificate Objects in the store.
Property type
Read-only property
Syntax
Visual Basic
Public Property Certificates As Certificates
Remarks
The Refresh method must be called to populate this collection.
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Enabled Property
CertificateList Object : Enabled Property
Description
Returns or sets a value that determines whether the control can respond to user-generated events.
Property type
Read-write property
Syntax
Visual Basic
Public Property Enabled As Boolean
Remarks

The default value is True (respond to events).

When set to True, the CertificateList Control can respond to events. When set to False, the CertificateList Control cannot respond to events.

See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Font Property
CertificateList Object : Font Property
Description
Returns or sets the font used in the display of the control.
Property type
Read-write property
Syntax
Visual Basic
Public Property Font As Font
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
ForeColor Property
CertificateList Object : ForeColor Property
Description
Returns or sets the foreground color used for text.
Property type
Read-write property
Syntax
Visual Basic
Public Property ForeColor As ULong
Remarks
Reference the standard Windows controls documentation for information on color usage.
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
GridLines Property
CertificateList Object : GridLines Property
Description
Returns or sets a value the determines if the CertificateList Control displays gridlines in Report View. The default is False (no gridlines).
Property type
Read-write property
Syntax
Visual Basic
Public Property GridLines As Boolean
Remarks
When set to True, the CertificateList Control displays gridlines. When set to False, the CertificateList Control does not display gridlines.
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
HideColumnHeaders Property
CertificateList Object : HideColumnHeaders Property
Description
Returns or sets whether ColumnHeader objects in the CertificateList Control are hidden in Report view.
Property type
Read-write property
Syntax
Visual Basic
Public Property HideColumnHeaders As Boolean
Remarks

The default is False (column headers visible).

When set to True, the CertificateList Control column headers are not visible. When set to False, the CertificateList Control column headers are visible.

See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
HotTracking Property
CertificateList Object : HotTracking Property
Description
Returns a value that determines whether mouse-sensitive highlighting is enabled.
Property type
Read-write property
Syntax
Visual Basic
Public Property HotTracking As Boolean
Remarks

The default is False (mouse-sensitive highlighting disabled).

When set to True, hot tracking is enabled and the header is highlighted when the user positions the mouse over the header. When set to False, the headers are not highlighted.

See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
hWnd Property
CertificateList Object : hWnd Property
Description
Returns the handle to the window of the CertificateList Control.
Property type
Read-only property
Syntax
Visual Basic
Public Property hWnd As Integer
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
KeyUsageSelect Property
CertificateList Object : KeyUsageSelect Property
Description
Filters out all certificates that do not have the specified KeyUsage attribute.
Property type
Write-only property
Syntax
Visual Basic
Public Property KeyUsageSelect
Remarks

The default value is UsageAll.

When set to UsageAll, all certificates can be included in the Certificates property of the same object. When set to another value, the Certificates Object (collection) is filled with certificates that possess the specified KeyUsage value.

The Refresh method must be called after setting this property to refresh the Certificates Object.

See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
SelectedIndex Property
CertificateList Object : SelectedIndex Property
Description
Index of the selected certificate.
Property type
Read-write property
Syntax
Visual Basic
Public Property SelectedIndex As Long
Remarks
This property indicates the index into the Certificates property of the selected certificate when read. You can set this property to force a certificate to be selected by default. The property will return -1 if no certificate is selected.
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
StoreLocation Property
CertificateList Object : StoreLocation Property
Description
Location of the certificate store.
Property type
Read-write property
Syntax
Visual Basic
Public Property StoreLocation As StoreLocationConstants
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
StoreName Property
CertificateList Object : StoreName Property
Description
Name of the certificate store.
Property type
Read-write property
Syntax
Visual Basic
Public Property StoreName As String
Remarks

Some common names are:

Name | Description
"MY" | Personal certificates.
"CA" | Certifying authority certificates.
"ROOT" | Root certificates.
"SPC" | Software publisher certificates.
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Click Event
CertificateList Object : Click Event
Description
Fires when the user clicks the left mouse button on the CertificateList Control.
Syntax
Visual Basic
Public Event Click()
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
DblClick Event
CertificateList Object : DblClick Event
Description
Fires when the user double clicks the left mouse button on the control.
Syntax
Visual Basic
Public Event DblClick()
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
KeyDown Event
CertificateList Object : KeyDown Event
Virtual key code for the key pressed.
Corresponds to the state of the SHIFT, CTRL, and ALT keys when the event fires.
Description
Fires when the user presses a key while the control has focus.
Syntax
Visual Basic
Public Event KeyDown( _
   ByVal KeyCode As Integer, _
   ByVal Shift As Integer _
)
Parameters
KeyCode
Virtual key code for the key pressed.
Shift
Corresponds to the state of the SHIFT, CTRL, and ALT keys when the event fires.
Remarks

The Shift parameter is a bit field with the least-significant bits corresponding to the SHIFT key (bit 0), the CTRL key (bit 1), and the ALT key (bit 2). The number of bits that can be set depends on which keys are pressed.

One or more of the following values are added together to represent Shift combinations (for example, if both SHIFT and CTRL are pressed, Shift is 3):

Constant | Setting | Description
vbShiftMask | 1 | SHIFT key bit mask
vbCtrlMask | 2 | CTRL key bit mask
vbAltMask | 4 | ALT key bit mask
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
RightClick Event
CertificateList Object : RightClick Event
Description
Fires when the user clicks the right mouse button on the control.
Syntax
Visual Basic
Public Event RightClick()
See Also

CertificateList Object | CertificateList Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Certificates Collection
Members
Description
Collection of Certificate Objects.
See Also

Certificates Members


%%PageItemTitle%% $$Members$$

Dart CertificateList Control and Objects
Certificates Collection Members
Overview
Public Methods
Public Method Item Get a Certificate Object based on an index.
Public Properties
Public Property Count Number of Certificate Objects in the collection.
See Also

Certificates Collection


%%PageItemTitle%%

Dart CertificateList Control and Objects
Item Method
Certificates Collection : Item Method
Index of the desired Certificate Object.
Description
Get a Certificate Object based on an index.
Syntax
Visual Basic
Public Function Item( _
   ByVal Index As Long _
) As Certificate
Parameters
Index
Index of the desired Certificate Object.
Return Value
The Certificate Object at Index.
See Also

Certificates Collection | Certificates Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Count Property
Certificates Collection : Count Property
Description
Number of Certificate Objects in the collection.
Property type
Read-only property
Syntax
Visual Basic
Public Property Count As Long
See Also

Certificates Collection | Certificates Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
CertificateStore Object
Members
Description
Use the CertificateStore Object to gain access to a store of certificates on the local system.
Object Model
CertificateStore ObjectCertificates CollectionCertificate ObjectCertificate Object
See Also

CertificateStore Members


%%PageItemTitle%% $$Members$$

Dart CertificateList Control and Objects
CertificateStore Object Members
Overview
Public Methods
Public Method CreateCert | Creates a new certificate and places it into the Certificate Store.
Public Method DeleteCert | Removes the Certificate from the Certificate Store.
Public Method Find | Searches the specified certificate store for the specified Certificate and returns the result.
Public Method Load | Loads the certificates in a certificate file into the Certificate Store.
Public Method Refresh | Populates the Certificates property with the certificates in the store.
Public Properties
Public Property Certificates | Collection of Certificate Objects in the store.
Public Property KeyUsageSelect | Filters out all certificates that do not have the specified KeyUsage attribute.
Public Property Location | Location of the certificate store.
Public Property Name | Name of the certificate store.
See Also

CertificateStore Object


%%PageItemTitle%%

Dart CertificateList Control and Objects
CreateCert Method
CertificateStore Object : CreateCert Method
The official x509 Subject Name of the certificate to be created.
Specifies how the certificate is to be used. The values are additive.
The certifying Certificate Authority certificate for this certificate taken from the Certificate Store.
Default is 60. Specifies the number of months the certificate is to remain valid.
Default is False. Specifies the type of key type to use. When False, the key type is Exchange, for data transfer. If True, the key type will be a digital signature, for data authentication.
Default is providerBase. The cryptographic provider used with the certificate.
Description
Creates a new certificate and places it into the Certificate Store.
Syntax
Visual Basic
Public Function CreateCert( _
   ByVal Name As String, _
   ByVal Usage As KeyUsageConstants, _
   Optional ByVal CACertificate As Certificate, _
   Optional ByVal Lifetime As Long = 0, _
   Optional ByVal UseSignatureKey As Boolean = False, _
   Optional ByVal Provider As ProviderConstants = providerBase _
) As Certificate
Parameters
Name
The official x509 Subject Name of the certificate to be created.
Usage
Value | Description
usageAll | Used for the KeyUsageSelect property only, selects all Certificates in the Store.
usageCertSign | Certificate can be used for Certificate Signing.
usageClientAuthentication | Certificate can be used for Client Authentication.
usageCodeSigning | Certificate can be used for Code Signing.
usageCrlSign | Certificate can be used for Encipherment.
usageDataEncipherment | Certificate can be used for Data Encipherment.
usageDigitalSignature | Certificate can be used for Digital Signatures.
usageEmailProtection | Certificate can be used for Email Protection.
usageIPSecEndSystem | Certificate can be used for IPSec End System.
usageIPSecTunnel | Certificate can be used for IPSec Tunneling.
usageIPSecUser | Certificate can be used for IPSec Users.
usageKeyAgreement | Certificate can be used for Key Agreement.
usageKeyEncipherment | Certificate can be used for Key Encipherment.
usageNone | Certificate has no usage flag.
usageNonRepudiation | Certificate can be used prevent Repudiation.
usageOfflineCrlSign | Certificate can be used for CRL Signing.
usageServerAuthentication | Certificate can be used for Server Authentication.
usageTimeStampSigning | Certificate can be used for Time Stamp signing.
Specifies how the certificate is to be used. The values are additive.
CACertificate
The certifying Certificate Authority certificate for this certificate taken from the Certificate Store.
Lifetime
Default is 60. Specifies the number of months the certificate is to remain valid.
UseSignatureKey
Default is False. Specifies the type of key type to use. When False, the key type is Exchange, for data transfer. If True, the key type will be a digital signature, for data authentication.
Provider
Value | Description
providerBase | Microsoft Base Cryptographic Provider v1.0.
providerBaseDSS | Microsoft Base DSS Cryptographic Provider.
providerBaseDSSDH | Microsoft Base DSS and Diffie-Hellman Cryptographic Provider.
providerDHSchannel | Microsoft DH SChannel Cryptographic Provider.
providerEnhancedBase | Microsoft Enhanced Cryptographic Provider v1.0.
providerEnhancedDSSDH | Microsoft Enhanced DSS and Diffie-Hellman Cryptographic Provider.
providerEnhancedRSAAES | Microsoft Enhanced RSA and AES Cryptographic Provider (Prototype).
providerExchange | Microsoft Exchange Cryptographic Provider v1.0.
providerGemSafe | Gemplus GemSAFE Card CSP v1.0.
providerRSASchannel | Microsoft RSA SChannel Cryptographic Provider.
providerSchlumberger | Schlumberger Cryptographic Service Provider.
providerSicrypt | Infineon SICRYPT Base Smart Card CSP.
providerStrong | Microsoft Strong Cryptographic Provider.
Default is providerBase. The cryptographic provider used with the certificate.
Remarks

This method is used to create a new certificate. If an invalid CA certificate is provided, a certInvalidCA error will be thrown.

The Name parameter represents the Subject Name and is expected to be in x500 format. An example of an x500 formatted name value is CN=Test Cert, OU=Test Cert Division, O=Test Inc, C=US with CN standing for Common Name, OU for Organizational Unit, O for Organization, and C for Country. The only required value is CN. Other values include E for E-mail, S for State, and L for Locale. If the specified name is invalid, a certInvalidCertName error will be thrown

To set the Certificate Location and Store that will hold the certificate, use the Location and Name properties, respectively.

SHA will always be the signature algorithm in use when creating the certificate.

If CACertificate is not present, the certificate will be created as a self-signed CA certificate. To create a non-CA certificate, the CA certificate must already be present on the system.

At the present time this method is not fully support in Windows NT 4.0 and Windows 2000 SP2 and SP3. There are no known problems in Windows 9x or in Windows XP.

Error Codes

This method may generate the following error code (refer to CertificateErrorConstants for a complete list of error codes):

  • certInvalidCertName
  • certInvalidCA
  • certInvalidProvider
  • certError
See Also

CertificateStore Object | CertificateStore Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
DeleteCert Method
CertificateStore Object : DeleteCert Method
The Certificate to delete.
Description
Removes the Certificate from the Certificate Store.
Syntax
Visual Basic
Public Sub DeleteCert( _
   ByVal Cert As Certificate _
)
Parameters
Cert
The Certificate to delete.
Remarks

This method is used to remove an existing certificate from a certificate store. If the certificate does not exist a certNotFound error will be thrown. If the certificate cant be deleted a certNoDelete error will be thrown. For any other error a certError will be thrown.

Error Codes

This method may generate the following error code (refer to CertificateErrorConstants for a complete list of error codes):

  • certNotFound
  • certNoDelete
  • certError
See Also

CertificateStore Object | CertificateStore Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Find Method
CertificateStore Object : Find Method
Name of the certificate store.
Registry location of the certificate store.
Name of the Certificate Authority that issued/signed the certificate. Matches the IssuedBy property of the returned certificate.
Serial number of the certificate. Matches the SerialNumber property of the returned certificate.
Description
Searches the specified certificate store for the specified Certificate and returns the result.
Syntax
Visual Basic
Public Function Find( _
   ByVal Name As String, _
   ByVal Location As StoreLocationConstants, _
   ByVal IssuedBy As String, _
   ByVal SerialNumber As String _
) As Certificate
Parameters
Name
Name of the certificate store.
Location
Value | Description
locationCurrentUser | Store is located in the HKEY_CURRENT_USER registry key.
locationLocalMachine | Store is located in the HKEY_LOCAL_MACHINE registry key.
locationRemote | Used by a Certificate that is not part of a store.
Registry location of the certificate store.
IssuedBy
Name of the Certificate Authority that issued/signed the certificate. Matches the IssuedBy property of the returned certificate.
SerialNumber
Serial number of the certificate. Matches the SerialNumber property of the returned certificate.
Return Value
A Certificate Object that matches the parameters.
Remarks

This method is used to do a quick lookup of the specified certificate.

Error Codes

This method may generate the following error code (refer to CertificateErrorConstants for a complete list of error codes):

  • ptNoCertificate (no matching certificate found)
See Also

CertificateStore Object | CertificateStore Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Load Method
CertificateStore Object : Load Method
Filepath of the certificate to load.
Certificate password.
Description
Loads the certificates in a certificate file into the Certificate Store.
Syntax
Visual Basic
Public Sub Load( _
   ByVal CertFileName As String, _
   Optional ByVal Password As String _
)
Parameters
CertFileName
Filepath of the certificate to load.
Password
Certificate password.
See Also

CertificateStore Object | CertificateStore Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Refresh Method
CertificateStore Object : Refresh Method
Description
Populates the Certificates property with the certificates in the store.
Syntax
Visual Basic
Public Sub Refresh()
See Also

CertificateStore Object | CertificateStore Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Certificates Property
CertificateStore Object : Certificates Property
Description
Collection of Certificate Objects in the store.
Property type
Read-only property
Syntax
Visual Basic
Public Property Certificates As Certificates
Remarks
The Refresh method must be called to populate this collection.
See Also

CertificateStore Object | CertificateStore Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
KeyUsageSelect Property
CertificateStore Object : KeyUsageSelect Property
Description
Filters out all certificates that do not have the specified KeyUsage attribute.
Property type
Write-only property
Syntax
Visual Basic
Public Property KeyUsageSelect
Remarks

The default value is UsageAll.

When set to UsageAll, all certificates can be included in the Certificates property of the same object. When set to another value, the Certificates Object (collection) is filled with certificates that possess the specified KeyUsage value.

The Refresh method must be called after setting this property to refresh the Certificates Object.

See Also

CertificateStore Object | CertificateStore Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Location Property
CertificateStore Object : Location Property
Description
Location of the certificate store.
Property type
Read-write property
Syntax
Visual Basic
Public Property Location As StoreLocationConstants
See Also

CertificateStore Object | CertificateStore Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
Name Property
CertificateStore Object : Name Property
Description
Name of the certificate store.
Property type
Read-write property
Syntax
Visual Basic
Public Property Name As String
Remarks

Some common names are:

Name | Description
"MY" | Personal certificates.
"CA" | Certifying authority certificates.
"ROOT" | Root certificates.
"SPC" | Software publisher certificates.
See Also

CertificateStore Object | CertificateStore Members


%%PageItemTitle%%

Dart CertificateList Control and Objects
AppearanceConstants Enumeration
Description
Enumerates the Appearance property.
Members
Member | Value | Description
cc3D | 1 | (Default) 3D. Paints control or object with three-dimensional effects.
ccFlat | 0 | Flat. Paints controls and forms without visual effects.


%%PageItemTitle%%

Dart CertificateList Control and Objects
BorderStyleConstants Enumeration
Description
Enumerates the BorderStyle property.
Members
Member | Value | Description
ccFixedSingle | 1 | Fixed Single.
ccNone | 0 | None (no border or border-related elements).


%%PageItemTitle%%

Dart CertificateList Control and Objects
CertificateErrorConstants Enumeration
Description
Certificate Error Constants
Members
Member | Value | Description
certError | 11100 | Unknown or Miscellaneous error.
certFileInvalid | 14008 | The Certificate file is not a valid pfx certificate file.
certFileInvalidPassword | 14009 | The password is invalid for the specified certificate file.
certInvalidCA | 14007 | The CA Certificate is invalid.
certInvalidCertName | 14003 | Invalid Certificate Name.
certInvalidProvider | 14002 | Invalid Provider.
certInvalidStoreLocation | 14004 | Invalid Store Location.
certNoDelete | 14006 | Could Not Delete Certificate.
certNotFound | 14005 | The Certificate could not be found in the Certificate Store.
certOk | 0 | No Error.


%%PageItemTitle%%

Dart CertificateList Control and Objects
KeyUsageConstants Enumeration
Description
Enumerates the Usage parameter of the KeyUsage property.
Members
Member | Value | Description
usageAll | -1 | Used for the KeyUsageSelect property only, selects all Certificates in the Store.
usageCertSign | 4 | Certificate can be used for Certificate Signing.
usageClientAuthentication | 512 | Certificate can be used for Client Authentication.
usageCodeSigning | 1024 | Certificate can be used for Code Signing.
usageCrlSign | 1 | Certificate can be used for Encipherment.
usageDataEncipherment | 16 | Certificate can be used for Data Encipherment.
usageDigitalSignature | 128 | Certificate can be used for Digital Signatures.
usageEmailProtection | 2048 | Certificate can be used for Email Protection.
usageIPSecEndSystem | 4096 | Certificate can be used for IPSec End System.
usageIPSecTunnel | 8192 | Certificate can be used for IPSec Tunneling.
usageIPSecUser | 16384 | Certificate can be used for IPSec Users.
usageKeyAgreement | 8 | Certificate can be used for Key Agreement.
usageKeyEncipherment | 32 | Certificate can be used for Key Encipherment.
usageNone | 0 | Certificate has no usage flag.
usageNonRepudiation | 64 | Certificate can be used prevent Repudiation.
usageOfflineCrlSign | 2 | Certificate can be used for CRL Signing.
usageServerAuthentication | 256 | Certificate can be used for Server Authentication.
usageTimeStampSigning | 32768 | Certificate can be used for Time Stamp signing.


%%PageItemTitle%%

Dart CertificateList Control and Objects
ProviderConstants Enumeration
Description
Enumerates the cryptographic providers allowed by Microsoft. The most commonly used provider for Microsoft certificates is the Microsoft Base Cryptographic Provider.
Members
Member | Value | Description
providerBase | 0 | Microsoft Base Cryptographic Provider v1.0.
providerBaseDSS | 4 | Microsoft Base DSS Cryptographic Provider.
providerBaseDSSDH | 3 | Microsoft Base DSS and Diffie-Hellman Cryptographic Provider.
providerDHSchannel | 5 | Microsoft DH SChannel Cryptographic Provider.
providerEnhancedBase | 6 | Microsoft Enhanced Cryptographic Provider v1.0.
providerEnhancedDSSDH | 7 | Microsoft Enhanced DSS and Diffie-Hellman Cryptographic Provider.
providerEnhancedRSAAES | 8 | Microsoft Enhanced RSA and AES Cryptographic Provider (Prototype).
providerExchange | 9 | Microsoft Exchange Cryptographic Provider v1.0.
providerGemSafe | 2 | Gemplus GemSAFE Card CSP v1.0.
providerRSASchannel | 10 | Microsoft RSA SChannel Cryptographic Provider.
providerSchlumberger | 12 | Schlumberger Cryptographic Service Provider.
providerSicrypt | 1 | Infineon SICRYPT Base Smart Card CSP.
providerStrong | 11 | Microsoft Strong Cryptographic Provider.


%%PageItemTitle%%

Dart CertificateList Control and Objects
StoreLocationConstants Enumeration
Description
Enumerates the possible values of the Location property of the CertificateStore Object.
Members
Member | Value | Description
locationCurrentUser | 1 | Store is located in the HKEY_CURRENT_USER registry key.
locationLocalMachine | 0 | Store is located in the HKEY_LOCAL_MACHINE registry key.
locationRemote | 2 | Used by a Certificate that is not part of a store.


%%ItemTitle%%

PowerTCP Mail for ActiveX
Certificate Manager


%%Phrase%%

Dart CertificateList Control and Objects
References


%%Phrase%%

References


%%Phrase%%

Dart Tcp, Daemon, Udp Controls
References