CkMime Perl Programming
Reference Documentation
CkMime
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
$obj = new chilkat::CkMime();
Properties
# str is a CkString object (output)
get_Boundary( str )
# newVal is a string (input)
put_Boundary( newVal )
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.
# sb is a CkString object (output)
get_Charset( sb )
# newVal is a string (input)
put_Charset( newVal )
The charset, such as "ISO-8859-1" or "utf-8"
# str is a CkString object (output)
get_ContentType( str )
# newVal is a string (input)
put_ContentType( newVal )
The MIME content type, such as "text/plain", "text/html", "multipart/alternative", "multipart/mixed", etc.
# str is a CkString object (output)
get_CurrentDateTime( str )
Returns the current date/time in RFC 822 format.
# str is a CkString object (output)
get_Disposition( str )
# newVal is a string (input)
put_Disposition( newVal )
The content disposition, which can be "attachment", "inline", etc.
# str is a CkString object (output)
get_Encoding( str )
# newVal is a string (input)
put_Encoding( newVal )
A content encoding such as "base64", "quoted-printable", "7bit", "8bit", etc.
# str is a CkString object (output)
get_Filename( str )
# newVal is a string (input)
put_Filename( newVal )
The filename when the content disposition is "attachment".
# str is a CkString object (output)
LastErrorHtml( str )
Error information in HTML format for the last method called.
# str is a CkString object (output)
LastErrorText( str )
Error information in plain-text format for the last method called.
# str is a CkString object (output)
LastErrorXml( str )
Error information in XML format for the last method called.
# str is a CkString object (output)
get_Micalg( str )
# newVal is a string (input)
put_Micalg( newVal )
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.
# str is a CkString object (output)
get_Name( str )
# newVal is a string (input)
put_Name( newVal )
The name attribute of the content-type header field.
# Returns an integer value
get_NumEncryptCerts( )
The number of certificates found when decrypting S/MIME. This property is set after UnwrapSecurity is called.
# Returns an integer value
get_NumHeaderFields( )
The number of header fields. Header field names and values can be retrieved by index (starting at 0) by calling GetHeaderFieldName and GetHeaderFieldValue.
# Returns an integer value
get_NumParts( )
The number of sub-parts contained within this message. Each sub-part is a complete Chilkat MIME message itself.
# Returns an integer value
get_NumSignerCerts( )
The number of certificates found when verifying signature(s). This property is set after UnwrapSecurity is called.
# str is a CkString object (output)
get_Protocol( str )
# newVal is a string (input)
put_Protocol( newVal )
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.
# Returns a boolean value
get_UnwrapExtras( )
# newVal is a boolean (input)
put_UnwrapExtras( newVal )
Controls whether extra (informative) header fields are added to the MIME message when unwrapping security.
# Returns a boolean value
get_UseMmDescription( )
# newVal is a boolean (input)
put_UseMmDescription( newVal )
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.
# Returns a boolean value
get_Utf8( )
# b is a boolean (input)
put_Utf8( b )
When set to true, all "const char *" arguments are expected to be utf-8 strings. If set to false, the "const char *" arguments are expected to be ANSI strings.
# Returns a boolean value
get_VerboseLogging( )
# newVal is a boolean (input)
put_VerboseLogging( newVal )
To be documented soon...
# str is a CkString object (output)
get_Version( str )
The version, such as "1.0.0".
Methods
AddContentLength( )
To be documented soon...
# cert is a CkCert object (input)
# Returns a boolean value
AddDetachedSignature( cert )
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.
# transferHeaderFields is a boolean (input)
# Returns a boolean value
AddDetachedSignature2( cert, transferHeaderFields )
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.
# Returns a boolean value
AddDetachedSignaturePk( cert, privateKey )
To be documented soon.
# transferHeaderFields is a boolean (input)
# Returns a boolean value
AddDetachedSignaturePk2( cert, privateKey, transferHeaderFields )
To be documented soon.
# Returns a boolean value
AddEncryptCert( cert )
To be documented soon.
# name is a string (input)
# value is a string (input)
# Returns a boolean value
AddHeaderField( name, value )
Adds a header field to the MIME.
# mime is a CkMime object (input)
# Returns a boolean value
AppendPart( mime )
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.
# filename is a string (input)
# Returns a boolean value
AppendPartFromFile( filename )
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.
# outStr is a CkString object (output)
# Returns a boolean value
AsnBodyToXml( outStr )
To be documented soon...
ClearEncryptCerts( )
To be documented soon...
# Returns a boolean value
ContainsEncryptedParts( )
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.
# Returns a boolean value
ContainsSignedParts( )
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.
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.
ConvertToMultipartAlt( )
To be documented soon. Returns 1 for success, 0 for failure.
ConvertToMultipartMixed( )
To be documented soon. Returns 1 for success, 0 for failure.
# cert is a CkCert object (input)
# Returns a boolean value
ConvertToSigned( cert )
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.
# Returns a boolean value
ConvertToSignedPk( cert, privateKey )
To be documented soon...
# Returns a boolean value
Decrypt( )
To be documented soon. Returns 1 for success, 0 for failure.
# Returns a boolean value
Decrypt2( cert, privateKey )
To be documented soon. Returns 1 for success, 0 for failure.
# cert is a CkCert object (input)
# Returns a boolean value
Encrypt( cert )
Encrypt a MIME message object using a digital certificate. Returns 1 for success, 0 for failure.
# Returns a boolean value
EncryptN( )
To be documented soon...
# dirPath is a string (input)
ExtractPartsToFiles( dirPath )
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 Extract Files from MIME
# db is a CkByteData object (output)
# Returns a boolean value
GetBodyBinary( db )
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.
# decodedBody is a CkString object (output)
# Returns a boolean value
GetBodyDecoded( decodedBody )
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 1 for success, 0 for failure. MIME Body vs. Sub-Parts
# encodedBody is a CkString object (output)
# Returns a boolean value
GetBodyEncoded( encodedBody )
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 1 for success, 0 for failure. MIME Body vs. Sub-Parts
# index is an integer (input)
# Returns a CkCert object
GetEncryptCert( index )
Returns the Nth certificate found when decrypting. The EncryptCerts property contains the number of certificates.
# str is a CkString object (output)
GetEntireBody( str )
Returns the entire MIME body, including all sub-parts. Returns 1 for success, 0 for failure.
# str is a CkString object (output)
GetEntireHead( str )
Returns the MIME header. Returns 1 for success, 0 for failure.
# name is a string (input)
# value is a CkString object (output)
# Returns a boolean value
GetHeaderField( name, value )
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 1 for success, 0 for failure.
# index is an integer (input)
# fieldName is a CkString object (output)
# Returns a boolean value
GetHeaderFieldName( index, fieldName )
Returns the Nth MIME header field name. Returns 1 for success, 0 for failure.
# index is an integer (input)
# fieldValue is a CkString object (output)
# Returns a boolean value
GetHeaderFieldValue( index, fieldValue )
Returns the Nth MIME header field value. Returns 1 for success, 0 for failure.
# mime is a CkString object (output)
# Returns a boolean value
GetMime( mime )
Returns a string containing the complete MIME message, including all sub-parts. Returns 1 for success, 0 for failure.
# outBytes is a CkByteData object (output)
# Returns a boolean value
GetMimeBytes( outBytes )
Returns a byte array containing the complete MIME message, including all sub-parts.
# index is an integer (input)
# Returns a CkMime object
GetPart( index )
Returns the Nth sub-part of the MIME message. Indexing begins at 0.
# index is an integer (input)
# Returns a CkCert object
GetSignerCert( index )
Returns the Nth digital certificate used to sign the MIME message. Indexing begins at 0.
# xml is a CkString object (output)
# Returns a boolean value
GetXml( xml )
Converts the MIME (or S/MIME) message to XML and returns the XML as a string. Returns 1 for success, 0 for failure.
# Returns a boolean value
IsApplicationData( )
Return true if the MIME message contains application data, otherwise returns false.
# Returns a boolean value
IsAttachment( )
Return true if this MIME message is an attachment, otherwise returns false
# Returns a boolean value
IsAudio( )
Return true if the MIME message contains audio data, otherwise returns false.
# Returns a boolean value
IsEncrypted( )
Returns true if the MIME message is encrypted.
# Returns a boolean value
IsHtml( )
Return true if the MIME body is HTML
# Returns a boolean value
IsImage( )
Return true if the MIME message contains image data, otherwise returns false.
# Returns a boolean value
IsMultipart( )
Return true if the MIME message is multipart (multipart/mixed, multipart/related, multipart/alternative, etc.), otherwise returns false.
# Returns a boolean value
IsMultipartAlternative( )
Return true if the MIME message is multipart/alternative, otherwise returns false.
# Returns a boolean value
IsMultipartMixed( )
Return true if the MIME message is multipart/mixed, otherwise returns false.
# Returns a boolean value
IsMultipartRelated( )
Return true if the MIME message is multipart/related, otherwise returns false.
# Returns a boolean value
IsPlainText( )
Return true if the MIME message body is plain text, otherwise returns false.
# Returns a boolean value
IsSigned( )
Return true if the MIME message is digitally signed, otherwise returns false.
# Returns a boolean value
IsText( )
Return true if the MIME message body is any text content type, such as text/plain, text/html, text/xml, etc., otherwise returns false.
# Returns a boolean value
IsUnlocked( )
Returns true if the component is already unlocked, false if not.
# Returns a boolean value
IsVideo( )
Return true if the MIME message contains video data, otherwise returns false.
# Returns a boolean value
IsXml( )
Return true if the MIME message body is XML, otherwise returns false.
# mimeMsg is a string (input)
# Returns a boolean value
LoadMime( mimeMsg )
Discards the current contents of the MIME object and loads a new MIME message from a string.
# fileName is a string (input)
# Returns a boolean value
LoadMimeFile( fileName )
Discards the current contents of the MIME object and loads a new MIME message from a file. Returns 1 for success, 0 for failure.
# xml is a string (input)
# Returns a boolean value
LoadXml( xml )
Converts XML to MIME and replaces the MIME object's contents with the converted XML.
# fileName is a string (input)
# Returns a boolean value
LoadXmlFile( fileName )
Converts XML to MIME and replaces the MIME object's contents with the converted XML. Returns 1 for success, 0 for failure.
# mimeObject is a CkMime object (input)
# Returns a boolean value
NewMessageRfc822( mimeObject )
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.
# Returns a boolean value
NewMultipartAlternative( )
Discards the current MIME message header fields and contents, if any, an initializes the MIME object to be an empty mulipart/alternative message.
# Returns a boolean value
NewMultipartMixed( )
Discards the current MIME message header fields and contents, if any, an initializes the MIME object to be an empty mulipart/mixed message.
# Returns a boolean value
NewMultipartRelated( )
Discards the current MIME message header fields and contents, if any, an initializes the MIME object to be an empty mulipart/related message.
# index is an integer (input)
# Returns a boolean value
RemovePart( index )
Removes the Nth subpart from the MIME message.
# filename is a string (input)
# Returns a boolean value
SaveBody( filename )
Saves the MIME message body to a file. If the body is base64 or quoted-printable encoded, it is automatically decoded.
# filename is a string (input)
# Returns a boolean value
SaveLastError( filename )
Saves the last error information to an XML formatted file.
# filename is a string (input)
# Returns a boolean value
SaveMime( filename )
Saves the MIME message to a file, in MIME format. (This is the same as the .EML format used by Microsoft Outlook Express.)
# filename is a string (input)
# Returns a boolean value
SaveXml( filename )
Converts the MIME message to XML and saves to an XML file.
# str is a string (input)
SetBody( str )
To be documented soon...
# dbuf is a CkByteData object (input)
# Returns a boolean value
SetBodyFromBinary( dbuf )
Sets the MIME message body from a byte array.
# encoding is a string (input)
# str is a string (input)
# Returns a boolean value
SetBodyFromEncoded( encoding, str )
Sets the MIME message body from a Base64 or Quoted-Printable encoded string.
# fileName is a string (input)
# Returns a boolean value
SetBodyFromFile( fileName )
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).
# str is a string (input)
# Returns a boolean value
SetBodyFromHtml( str )
Sets the MIME message body from a string containing HTML, and also updates the content-type to be text/html
# str is a string (input)
# Returns a boolean value
SetBodyFromPlainText( str )
Sets the MIME message body from a string containing plain text, and also updates the content-type to be text/plain
# str is a string (input)
# Returns a boolean value
SetBodyFromXml( str )
Sets the MIME message body from a string containing XML, and also updates the content-type to be text/xml
# csp is a CkCSP object (input)
# Returns a boolean value
SetCSP( csp )
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.
# name is a string (input)
# value is a string (input)
# Returns a boolean value
SetHeaderField( name, value )
Adds or replaces a MIME message header field. If the field already exists, it is automatically replaced. Otherwise it is added.
# cert is a CkCert object (input)
SetVerifyCert( cert )
Allows a certificate to be explicitly specified for verifying a signature.
# Returns a CkEmail object
ToEmailObject( )
Returns the MIME message converted to a CkEmail object. Returns a null reference on failure
# unlockCode is a string (input)
# Returns a boolean value
UnlockComponent( unlockCode )
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.
# Returns a boolean value
UnwrapSecurity( )
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.
# charset is a string (input)
UrlEncodeBody( charset )
To be documented soon...
# Returns a boolean value
Verify( )
To be documented soon...
# Returns a string
asnBodyToXml( )
To be documented soon...
# Returns a string
bodyDecoded( )
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 string
bodyEncoded( )
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 string
boundary( )
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.
# Returns a string
charset( )
The charset, such as "ISO-8859-1" or "utf-8"
# Returns a string
contentType( )
The MIME content type, such as "text/plain", "text/html", "multipart/alternative", "multipart/mixed", etc.
# Returns a string
currentDateTime( )
Returns the current date/time in RFC 822 format.
# Returns a string
disposition( )
The content disposition, which can be "attachment", "inline", etc.
# Returns a string
encoding( )
A content encoding such as "base64", "quoted-printable", "7bit", "8bit", etc.
# Returns a string
entireBody( )
Returns the entire MIME body, including all sub-parts.
# Returns a string
entireHead( )
Returns the MIME header.
# Returns a string
filename( )
The filename when the content disposition is "attachment".
# Returns a string
getBodyDecoded( )
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. MIME Body vs. Sub-Parts
# Returns a string
getBodyEncoded( )
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. MIME Body vs. Sub-Parts
# Returns a string
getEntireBody( )
Returns the entire MIME body, including all sub-parts.
# Returns a string
getEntireHead( )
Returns the MIME header.
# name is a string (input)
# Returns a string
getHeaderField( name )
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.
# index is an integer (input)
# Returns a string
getHeaderFieldName( index )
Returns the Nth MIME header field name.
# index is an integer (input)
# Returns a string
getHeaderFieldValue( index )
Returns the Nth MIME header field value.
# Returns a string
getMime( )
Returns a string containing the complete MIME message, including all sub-parts.
# Returns a string
getXml( )
Converts the MIME (or S/MIME) message to XML and returns the XML as a string.
# name is a string (input)
# Returns a string
header( name )
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.
# index is an integer (input)
# Returns a string
headerName( index )
Returns the Nth MIME header field name.
# index is an integer (input)
# Returns a string
headerValue( index )
Returns the Nth MIME header field value.
# Returns a string
lastErrorHtml( )
Error information in HTML format for the last method called.
# Returns a string
lastErrorText( )
Error information in plain-text format for the last method called.
# Returns a string
lastErrorXml( )
Error information in XML format for the last method called.
# Returns a string
micalg( )
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.
# Returns a string
mime( )
Returns a string containing the complete MIME message, including all sub-parts.
# Returns a string
name( )
The name attribute of the content-type header field.
# Returns a string
protocol( )
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.
# Returns a string
xml( )
Converts the MIME (or S/MIME) message to XML and returns the XML as a string.
|