Chilkat VB.NET Mime Class Reference

Mime

Chilkat MIME allows you to easily create and manipulate MIME and S/MIME messages from within your applications. ("Chilkat MIME" may be referred to as "Chilkat S/MIME" on some chilkatsoft.com web pages. They are the same product.) The Chilkat MIME license also includes the Chilkat DKIM component/class/libs for creating and verifying DKIM / DomainKey signatures.

Object Creation

(C#)
Chilkat.Mime obj = new Chilkat.Mime();
(VB.NET)
Dim obj As New Chilkat.Mime()

Properties

Boundary As String

The boundary string to be used if this is a multipart message. By default, the boundary is automatically generated to be a unique and random string, so explicitly setting the boundary is not necessary.

Charset As String

The charset, such as "ISO-8859-1" or "utf-8"

ContentType As String

The MIME content type, such as "text/plain", "text/html", "multipart/alternative", "multipart/mixed", etc.

CurrentDateTime As String (ReadOnly)

Returns the current date/time in RFC 822 format.

Disposition As String

The content disposition, which can be "attachment", "inline", etc.

Encoding As String

A content encoding such as "base64", "quoted-printable", "7bit", "8bit", etc.

Filename As String

The filename when the content disposition is "attachment".

LastErrorHtml As String (ReadOnly)

Error information in HTML format for the last method called.

LastErrorText As String (ReadOnly)

Error information in plain-text format for the last method called.

LastErrorXml As String (ReadOnly)

Error information in XML format for the last method called.

Micalg As String

The MIC algorithm, such as "SHA1" when the content type is multipart/signed. Properties such as this are rarely set manually, as Chilkat MIME automatically sets it to the correct value when creating a signed message.

Name As String

The name attribute of the content-type header field.

NumEncryptCerts As Integer (ReadOnly)

The number of certificates found when decrypting S/MIME. This property is set after UnwrapSecurity is called.

NumHeaderFields As Integer (ReadOnly)

The number of header fields. Header field names and values can be retrieved by index (starting at 0) by calling GetHeaderFieldName and GetHeaderFieldValue.

NumParts As Integer (ReadOnly)

The number of sub-parts contained within this message. Each sub-part is a complete Chilkat MIME message itself.

NumSignerCerts As Integer (ReadOnly)

The number of certificates found when verifying signature(s). This property is set after UnwrapSecurity is called.

Protocol As String

A protocol such as "application/x-pkcs7-signature". Properties such as this are rarely set manually, as Chilkat MIME automatically sets it to the correct value when creating a signed message.

UnwrapExtras As Boolean

Controls whether extra (informative) header fields are added to the MIME message when unwrapping security.

UseMmDescription As Boolean

Controls whether the boilerplate text "This is a multi-part message in MIME format." is used as the body content of a multipart MIME part.

VerboseLogging As Boolean

To be documented soon...

Version As String (ReadOnly)

The version, such as "1.0.0".

Methods

Sub AddContentLength()

To be documented soon...

Function AddDetachedSignature(ByVal cert As Cert) As Boolean

Signs the message using the certificate provided. If successful, the message is converted to "multipart/signed" and the original message will be contained in the first sub-part.

Returns true for success, false for failure.

Function AddDetachedSignature2(ByVal cert As Cert, ByVal transferHeaderFields As Boolean) As Boolean

Same as AddDetachedSignature, except an extra argument is provided to control whether header fields from the calling MIME object are transferred to the content part of the multipart/signed object. This method transforms the calling object into a multipart/signed MIME with two sub-parts. The first contains the original content of the calling object, and the second contains the digital signature.

Returns true for success, false for failure.

Function AddDetachedSignaturePk(ByVal cert As Cert, ByVal privateKey As PrivateKey) As Boolean

To be documented soon.

Function AddDetachedSignaturePk2(ByVal cert As Cert, ByVal privateKey As PrivateKey, ByVal transferHeaderFields As Boolean) As Boolean

To be documented soon.

Function AddEncryptCert(ByVal cert As Cert) As Boolean

To be documented soon.

Function AddHeaderField(ByVal name As String, ByVal value As String) As Boolean

Adds a header field to the MIME.

Function AppendPart(ByVal mime As Mime) As Boolean

Appends a MIME message to the sub-parts of this message. Arbitrarily complex messages with unlimited nesting levels can be created. If the calling Mime object is not already multipart, it is automatically converted to multipart/mixed first.

Function AppendPartFromFile(ByVal filename As String) As Boolean

Loads a file and creates a Mime message object using the file extension to determine the content type, and adds it as a sub-part to the calling object.

Returns true for success, false for failure.

Function AsnBodyToXml() As String

To be documented soon...

Sub ClearEncryptCerts()

To be documented soon...

Function ContainsEncryptedParts() As Boolean

Returns true if the MIME message contains encrypted parts.

Note: This method examines the MIME as-is. If UnwrapSecurity is called and it is successful, then the MIME should no longer contain encrypted parts, and this method would return 0.

Note: If a signed MIME message is then encrypted, then it is not possible to know that the MIME is both encrypted and signed until UnwrapSecurity is called. (In other words, it is not possible to know the contents of the encrypted MIME until it is decrypted.) Therefore, the ContainsSignedParts method would return false.

Function ContainsSignedParts() As Boolean

Returns true if the MIME message contains signed parts.

Note: This method examines the MIME as-is. If UnwrapSecurity is called and it is successful, then the MIME should no longer contain signed parts, and this method would return 0.

Note: If a signed MIME message is then encrypted, then it is not possible to know that the MIME is both encrypted and signed until UnwrapSecurity is called. (In other words, it is not possible to know the contents of the encrypted MIME until it is decrypted.) Therefore, the ContainsSignedParts method would return false.

Note: The same concept also applies to opaque signatures, such as with the MIME produced by calling ConvertToSigned.

Sub Convert8Bit()

Changes the content-transfer-encoding to "base64" for all 8bit or binary MIME subparts. This allows for the MIME to be exported as a string via the GetMime method.

Function ConvertToMultipartAlt() As Boolean

To be documented soon.

Returns true for success, false for failure.

Function ConvertToMultipartMixed() As Boolean

To be documented soon.

Returns true for success, false for failure.

Function ConvertToSigned(ByVal cert As Cert) As Boolean

Digitally signs the calling Mime object, but rather than the signature becoming a sub-part of the message (as in AddDetachedSignature) it becomes part of the message. In S/MIME terms, the message becomes application/x-pkcs7-mime rather than multipart/signed.

Note: This is commonly referred to as an opaque signature.

Returns true for success, false for failure.

Function ConvertToSignedPk(ByVal cert As Cert, ByVal privateKey As PrivateKey) As Boolean

To be documented soon...

Function Decrypt() As Boolean

To be documented soon.

Returns true for success, false for failure.

Function Decrypt2(ByVal cert As Cert, ByVal privateKey As PrivateKey) As Boolean

To be documented soon.

Returns true for success, false for failure.

Function Encrypt(ByVal cert As Cert) As Boolean

Encrypt a MIME message object using a digital certificate.

Returns true for success, false for failure.

Function EncryptN() As Boolean

To be documented soon...

Function ExtractPartsToFiles(ByVal dirPath As String) As StringArray

Recursively descends through the parts of a MIME message and extracts all parts having a filename to a file. The files are created in dirPath. Returns a (Ck)StringArray object containing the names of the files created. The filenames are obtained from the "filename" attribute of the content-disposition header. If a filename does not exist, then the MIME part is not saved to a file.

Returns Nothing on failure

Extract Files from MIME

Function GetBodyBinary() As Byte()

Returns the body of the MIME message as a block of binary data. The body is automatically converted from its encoding type, such as base64 or quoted-printable, before being returned.

Returns Nothing on failure

Function GetBodyDecoded() As String

Returns the body of the MIME message as a string. The body is automatically converted from its encoding type, such as base64 or quoted-printable, before being returned.

Returns Nothing on failure

MIME Body vs. Sub-Parts

Function GetBodyEncoded() As String

Returns the body of the MIME message as a String. The body is explicitly not decoded from it's encoding type, so if it was represented in Base64, you will get the Base64 encoded body, as an example.

Returns Nothing on failure

MIME Body vs. Sub-Parts

Function GetEncryptCert(ByVal index As Integer) As Cert

Returns the Nth certificate found when decrypting. The EncryptCerts property contains the number of certificates.

Function GetEntireBody() As String

Returns the entire MIME body, including all sub-parts.

Returns Nothing on failure

Function GetEntireHead() As String

Returns the MIME header.

Returns Nothing on failure

Function GetHeaderField(ByVal name As String) As String

Returns the content of a MIME header field. The "fieldName" is case-insensitive, and if the MIME header field does not exist, an empty string is returned.

Returns Nothing on failure

Function GetHeaderFieldName(ByVal index As Integer) As String

Returns the Nth MIME header field name.

Returns Nothing on failure

Function GetHeaderFieldValue(ByVal index As Integer) As String

Returns the Nth MIME header field value.

Returns Nothing on failure

Function GetMime() As String

Returns a string containing the complete MIME message, including all sub-parts.

Returns Nothing on failure

Function GetMimeBytes() As Byte()

Returns a byte array containing the complete MIME message, including all sub-parts.

Returns Nothing on failure

Function GetPart(ByVal index As Integer) As Mime

Returns the Nth sub-part of the MIME message. Indexing begins at 0.

Function GetSignerCert(ByVal index As Integer) As Cert

Returns the Nth digital certificate used to sign the MIME message. Indexing begins at 0.

Function GetXml() As String

Converts the MIME (or S/MIME) message to XML and returns the XML as a string.

Returns Nothing on failure

Function IsApplicationData() As Boolean

Return true if the MIME message contains application data, otherwise returns false.

Function IsAttachment() As Boolean

Return true if this MIME message is an attachment, otherwise returns false

Function IsAudio() As Boolean

Return true if the MIME message contains audio data, otherwise returns false.

Function IsEncrypted() As Boolean

Returns true if the MIME message is encrypted.

Function IsHtml() As Boolean

Return true if the MIME body is HTML

Function IsImage() As Boolean

Return true if the MIME message contains image data, otherwise returns false.

Function IsMultipart() As Boolean

Return true if the MIME message is multipart (multipart/mixed, multipart/related, multipart/alternative, etc.), otherwise returns false.

Function IsMultipartAlternative() As Boolean

Return true if the MIME message is multipart/alternative, otherwise returns false.

Function IsMultipartMixed() As Boolean

Return true if the MIME message is multipart/mixed, otherwise returns false.

Function IsMultipartRelated() As Boolean

Return true if the MIME message is multipart/related, otherwise returns false.

Function IsPlainText() As Boolean

Return true if the MIME message body is plain text, otherwise returns false.

Function IsSigned() As Boolean

Return true if the MIME message is digitally signed, otherwise returns false.

Function IsText() As Boolean

Return true if the MIME message body is any text content type, such as text/plain, text/html, text/xml, etc., otherwise returns false.

Function IsUnlocked() As Boolean

Returns true if the component is already unlocked, false if not.

Function IsVideo() As Boolean

Return true if the MIME message contains video data, otherwise returns false.

Function IsXml() As Boolean

Return true if the MIME message body is XML, otherwise returns false.

Function LoadMime(ByVal mimeMsg As String) As Boolean

Discards the current contents of the MIME object and loads a new MIME message from a string.

Function LoadMimeBinary(ByVal binData As Byte()) As Boolean

Loads a MIME document from an in-memory byte array.

Returns true for success, false for failure.

Function LoadMimeFile(ByVal fileName As String) As Boolean

Discards the current contents of the MIME object and loads a new MIME message from a file.

Returns true for success, false for failure.

Function LoadXml(ByVal xml As String) As Boolean

Converts XML to MIME and replaces the MIME object's contents with the converted XML.

Function LoadXmlFile(ByVal fileName As String) As Boolean

Converts XML to MIME and replaces the MIME object's contents with the converted XML.

Returns true for success, false for failure.

Function NewMessageRfc822(ByVal mimeObject As Mime) As Boolean

Clears the Mime object and initializes it such that the header contains a "content-type: message/rfc822" line and the body is the MIME text of the Mime object passed to the method.

Function NewMultipartAlternative() As Boolean

Discards the current MIME message header fields and contents, if any, an initializes the MIME object to be an empty mulipart/alternative message.

Function NewMultipartMixed() As Boolean

Discards the current MIME message header fields and contents, if any, an initializes the MIME object to be an empty mulipart/mixed message.

Function NewMultipartRelated() As Boolean

Discards the current MIME message header fields and contents, if any, an initializes the MIME object to be an empty mulipart/related message.

Function RemovePart(ByVal index As Integer) As Boolean

Removes the Nth subpart from the MIME message.

Function SaveBody(ByVal filename As String) As Boolean

Saves the MIME message body to a file. If the body is base64 or quoted-printable encoded, it is automatically decoded.

Function SaveLastError(ByVal filename As String) As Boolean

Saves the last error information to an XML formatted file.

Function SaveMime(ByVal filename As String) As Boolean

Saves the MIME message to a file, in MIME format. (This is the same as the .EML format used by Microsoft Outlook Express.)

Function SaveXml(ByVal filename As String) As Boolean

Converts the MIME message to XML and saves to an XML file.

Sub SetBody(ByVal str As String)

To be documented soon...

Function SetBodyFromBinary(ByVal binData As Byte()) As Boolean

Sets the MIME message body from a byte array.

Function SetBodyFromEncoded(ByVal encoding As String, ByVal str As String) As Boolean

Sets the MIME message body from a Base64 or Quoted-Printable encoded string.

Function SetBodyFromFile(ByVal fileName As String) As Boolean

Sets the MIME message body from the contents of a file. Note: A MIME message consists of a header and a body. The body may itself be a MIME message that consists of a header and body, etc. This method loads the contents of a file into the body of a MIME message, without replacing the header.

The Content-Type and Content-Transfer-Encoding header fields are automatically updated to match the type of content loaded (based on file extension). If your application requires the MIME to have a specific Content-Type and/or Content-Transfer-Encoding, set the ContentType and Encoding properties after calling this method (not before).

Function SetBodyFromHtml(ByVal str As String) As Boolean

Sets the MIME message body from a string containing HTML, and also updates the content-type to be text/html

Function SetBodyFromPlainText(ByVal str As String) As Boolean

Sets the MIME message body from a string containing plain text, and also updates the content-type to be text/plain

Function SetBodyFromXml(ByVal str As String) As Boolean

Sets the MIME message body from a string containing XML, and also updates the content-type to be text/xml

Function SetCSP(ByVal csp As Csp) As Boolean

Sets the encryption and digital signature preferences for this message. The CSP object will control the Cryptographic Service Provider used, the key container within the CSP to be used, and the encryption/hash algorithms.

Function SetHeaderField(ByVal name As String, ByVal value As String) As Boolean

Adds or replaces a MIME message header field. If the field already exists, it is automatically replaced. Otherwise it is added.

Sub SetVerifyCert(ByVal cert As Cert)

Allows a certificate to be explicitly specified for verifying a signature.

Function UnlockComponent(ByVal unlockCode As String) As Boolean

Unlocks the component allowing for the full functionality to be used. If this method unexpectedly returns false, examine the contents of the LastErrorText property to determine the reason for failure.

Returns true for success, false for failure.

Function UnwrapSecurity() As Boolean

Decrypts and verifies all digital signatures contained within the MIME message, and returns true if all decryptions and verifications succeeded. Otherwise returns false. After unwrapping, the information regarding security and certificates can be obtained by the methods GetSignerCert and GetEncryptCert, and the properties NumEncryptCerts and NumSignerCerts.

Returns true for success, false for failure.

Sub UrlEncodeBody(ByVal charset As String)

To be documented soon...

Function Verify() As Boolean

To be documented soon...