TChilkatMime Delphi Reference
TChilkatMime
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
var
obj: IChilkatMime;
...
begin
obj := CoChilkatMime.Create();
Properties
property Boundary: WideString
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.
property Charset: WideString
The charset, such as "ISO-8859-1" or "utf-8"
property ContentType: WideString
The MIME content type, such as "text/plain", "text/html", "multipart/alternative", "multipart/mixed", etc.
property CurrentDateTime: WideString readonly
Returns the current date/time in RFC 822 format.
property Disposition: WideString
The content disposition, which can be "attachment", "inline", etc.
property Encoding: WideString
A content encoding such as "base64", "quoted-printable", "7bit", "8bit", etc.
property Filename: WideString
The filename when the content disposition is "attachment".
property LastErrorHtml: WideString readonly
Error information in HTML format for the last method called.
property LastErrorText: WideString readonly
Error information in plain-text format for the last method called.
property LastErrorXml: WideString readonly
Error information in XML format for the last method called.
property Micalg: WideString
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.
property Name: WideString
The name attribute of the content-type header field.
property NumEncryptCerts: Integer readonly
The number of certificates found when decrypting S/MIME. This property is set after UnwrapSecurity is called.
property NumHeaderFields: 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.
property NumParts: Integer readonly
The number of sub-parts contained within this message. Each sub-part is a complete Chilkat MIME message itself.
property NumSignerCerts: Integer readonly
The number of certificates found when verifying signature(s). This property is set after UnwrapSecurity is called.
property Protocol: WideString
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.
property UnwrapExtras: Integer
Controls whether extra (informative) header fields are added to the MIME message when unwrapping security.
property UseMmDescription: Integer
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.
property VerboseLogging: Integer
To be documented soon...
property Version: WideString readonly
The version, such as "1.0.0".
Methods
procedure AddContentLength();
To be documented soon...
function AddDetachedSignature(cert: TChilkatCert): Integer;
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 1 for success, 0 for failure.
function AddDetachedSignature2(cert: TChilkatCert, transferHeaderFields: Integer): Integer;
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 1 for success, 0 for failure.
function AddDetachedSignaturePk(cert: TChilkatCert, key: TPrivateKey): Integer;
To be documented soon.
function AddDetachedSignaturePk2(cert: TChilkatCert, key: TPrivateKey, transferHeaderFields: Integer): Integer;
To be documented soon.
function AddEncryptCert(cert: TChilkatCert): Integer;
To be documented soon.
procedure AddHeaderField(fieldName: WideString, fieldValue: WideString);
Adds a header field to the MIME.
procedure AppendPart(iMime: TChilkatMime);
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(fileName: WideString): Integer;
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 1 for success, 0 for failure.
function AsnBodyToXml(): WideString;
To be documented soon...
procedure ClearEncryptCerts();
To be documented soon...
function ContainsEncryptedParts(): Integer;
Returns 1 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 0.
function ContainsSignedParts(): Integer;
Returns 1 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 0.
Note: The same concept also applies to opaque signatures, such as with the MIME produced by calling ConvertToSigned.
procedure 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(): Integer;
To be documented soon. Returns 1 for success, 0 for failure.
function ConvertToMultipartMixed(): Integer;
To be documented soon. Returns 1 for success, 0 for failure.
function ConvertToSigned(cert: TChilkatCert): Integer;
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 1 for success, 0 for failure.
function ConvertToSignedPk(cert: TChilkatCert, key: TPrivateKey): Integer;
To be documented soon...
function Decrypt(): Integer;
To be documented soon. Returns 1 for success, 0 for failure.
function Decrypt2(cert: TChilkatCert, key: TPrivateKey): Integer;
To be documented soon. Returns 1 for success, 0 for failure.
function Encrypt(cert: TChilkatCert): Integer;
Encrypt a MIME message object using a digital certificate. Returns 1 for success, 0 for failure.
function EncryptN(): Integer;
To be documented soon...
function ExtractPartsToFiles(dirPath: WideString): TCkStringArray;
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 a null reference on failure
function GetBodyBinary(): OleVariant;
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 1 for success, 0 for failure.
function GetBodyDecoded(): WideString;
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 a zero-length WideString on failure
function GetBodyEncoded(): WideString;
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 a zero-length WideString on failure
function GetEncryptCert(index: Integer): TChilkatCert;
Returns the Nth certificate found when decrypting. The EncryptCerts property contains the number of certificates.
function GetEntireBody(): WideString;
Returns the entire MIME body, including all sub-parts. Returns a zero-length WideString on failure
function GetEntireHead(): WideString;
Returns the MIME header. Returns a zero-length WideString on failure
function GetHeaderField(name: WideString): WideString;
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 a zero-length WideString on failure
function GetHeaderFieldName(index: Integer): WideString;
Returns the Nth MIME header field name. Returns a zero-length WideString on failure
function GetHeaderFieldValue(index: Integer): WideString;
Returns the Nth MIME header field value. Returns a zero-length WideString on failure
function GetMime(): WideString;
Returns a string containing the complete MIME message, including all sub-parts. Returns a zero-length WideString on failure
function GetMimeBytes(): OleVariant;
Returns a byte array containing the complete MIME message, including all sub-parts. Returns 1 for success, 0 for failure.
function GetPart(index: Integer): TChilkatMime;
Returns the Nth sub-part of the MIME message. Indexing begins at 0.
function GetSignerCert(index: Integer): TChilkatCert;
Returns the Nth digital certificate used to sign the MIME message. Indexing begins at 0.
function GetXml(): WideString;
Converts the MIME (or S/MIME) message to XML and returns the XML as a string. Returns a zero-length WideString on failure
function IsApplicationData(): Integer;
Return true if the MIME message contains application data, otherwise returns false.
function IsAttachment(): Integer;
Return true if this MIME message is an attachment, otherwise returns false
function IsAudio(): Integer;
Return true if the MIME message contains audio data, otherwise returns false.
function IsEncrypted(): Integer;
Returns true if the MIME message is encrypted.
function IsHtml(): Integer;
Return true if the MIME body is HTML
function IsImage(): Integer;
Return true if the MIME message contains image data, otherwise returns false.
function IsMultipart(): Integer;
Return true if the MIME message is multipart (multipart/mixed, multipart/related, multipart/alternative, etc.), otherwise returns false.
function IsMultipartAlternative(): Integer;
Return true if the MIME message is multipart/alternative, otherwise returns false.
function IsMultipartMixed(): Integer;
Return true if the MIME message is multipart/mixed, otherwise returns false.
function IsMultipartRelated(): Integer;
Return true if the MIME message is multipart/related, otherwise returns false.
function IsPlainText(): Integer;
Return true if the MIME message body is plain text, otherwise returns false.
function IsSigned(): Integer;
Return true if the MIME message is digitally signed, otherwise returns false.
function IsText(): Integer;
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 IsVideo(): Integer;
Return true if the MIME message contains video data, otherwise returns false.
function IsXml(): Integer;
Return true if the MIME message body is XML, otherwise returns false.
function LoadMime(mimeMsg: WideString): Integer;
Discards the current contents of the MIME object and loads a new MIME message from a string.
procedure LoadMimeBytes(binaryMime: OleVariant);
Loads a MIME document from an in-memory byte array.
function LoadMimeFile(fileName: WideString): Integer;
Discards the current contents of the MIME object and loads a new MIME message from a file. Returns 1 for success, 0 for failure.
function LoadXml(xml: WideString): Integer;
Converts XML to MIME and replaces the MIME object's contents with the converted XML.
function LoadXmlFile(fileName: WideString): Integer;
Converts XML to MIME and replaces the MIME object's contents with the converted XML. Returns 1 for success, 0 for failure.
procedure NewMessageRfc822(iMime: TChilkatMime);
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.
procedure NewMultipartAlternative();
Discards the current MIME message header fields and contents, if any, an initializes the MIME object to be an empty mulipart/alternative message.
procedure NewMultipartMixed();
Discards the current MIME message header fields and contents, if any, an initializes the MIME object to be an empty mulipart/mixed message.
procedure NewMultipartRelated();
Discards the current MIME message header fields and contents, if any, an initializes the MIME object to be an empty mulipart/related message.
procedure RemovePart(index: Integer);
Removes the Nth subpart from the MIME message.
function SaveBody(filename: WideString): Integer;
Saves the MIME message body to a file. If the body is base64 or quoted-printable encoded, it is automatically decoded.
function SaveLastError(filename: WideString): Integer;
Saves the last error information to an XML formatted file.
function SaveMime(filename: WideString): Integer;
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(filename: WideString): Integer;
Converts the MIME message to XML and saves to an XML file.
procedure SetBody(str: WideString);
To be documented soon...
procedure SetBodyFromBinary(binaryData: OleVariant);
Sets the MIME message body from a byte array.
procedure SetBodyFromEncoded(encoding: WideString, bodyText: WideString);
Sets the MIME message body from a Base64 or Quoted-Printable encoded string.
function SetBodyFromFile(filename: WideString): Integer;
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).
procedure SetBodyFromHtml(bodyText: WideString);
Sets the MIME message body from a string containing HTML, and also updates the content-type to be text/html
procedure SetBodyFromPlainText(bodyText: WideString);
Sets the MIME message body from a string containing plain text, and also updates the content-type to be text/plain
procedure SetBodyFromXml(bodyText: WideString);
Sets the MIME message body from a string containing XML, and also updates the content-type to be text/xml
procedure SetCSP(iCsp: TChilkatCSP);
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.
procedure SetHeaderField(fieldName: WideString, fieldValue: WideString);
Adds or replaces a MIME message header field. If the field already exists, it is automatically replaced. Otherwise it is added.
procedure SetVerifyCert(iCert: TChilkatCert);
Allows a certificate to be explicitly specified for verifying a signature.
function UnlockComponent(unlockCode: WideString): Integer;
Unlocks the component allowing for the full functionality to be used. If this method unexpectedly returns 0, examine the contents of the LastErrorText property to determine the reason for failure. Returns 1 for success, 0 for failure.
function UnwrapSecurity(): Integer;
Decrypts and verifies all digital signatures contained within the MIME message, and returns 1 if all decryptions and verifications succeeded. Otherwise returns 0. After unwrapping, the information regarding security and certificates can be obtained by the methods GetSignerCert and GetEncryptCert, and the properties NumEncryptCerts and NumSignerCerts. Returns 1 for success, 0 for failure.
procedure UrlEncodeBody(charset: WideString);
To be documented soon...
function Verify(): Integer;
To be documented soon...
|