Mime C Library 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 C library/class/libs for creating and verifying DKIM / DomainKey signatures.
Create/Dispose
HCkMime CkMime_Create(void);
Creates an instance of the CkMime object and returns a handle (i.e. a "void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.
void CkMime_Dispose(HCkMime handle);
Objects created by calling CkMime_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.
C "Properties"
void CkMime_getBoundary(HCkMime cHandle, HCkString retval);
void CkMime_putBoundary(HCkMime cHandle, const char *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.
void CkMime_getCharset(HCkMime cHandle, HCkString retval);
void CkMime_putCharset(HCkMime cHandle, const char *newVal);
The charset, such as "ISO-8859-1" or "utf-8"
void CkMime_getContentType(HCkMime cHandle, HCkString retval);
void CkMime_putContentType(HCkMime cHandle, const char *newVal);
The MIME content type, such as "text/plain", "text/html", "multipart/alternative", "multipart/mixed", etc.
void CkMime_getCurrentDateTime(HCkMime cHandle, HCkString retval);
Returns the current date/time in RFC 822 format.
void CkMime_getDisposition(HCkMime cHandle, HCkString retval);
void CkMime_putDisposition(HCkMime cHandle, const char *newVal);
The content disposition, which can be "attachment", "inline", etc.
void CkMime_getEncoding(HCkMime cHandle, HCkString retval);
void CkMime_putEncoding(HCkMime cHandle, const char *newVal);
A content encoding such as "base64", "quoted-printable", "7bit", "8bit", etc.
void CkMime_getFilename(HCkMime cHandle, HCkString retval);
void CkMime_putFilename(HCkMime cHandle, const char *newVal);
The filename when the content disposition is "attachment".
void CkMime_getLastErrorHtml(HCkMime cHandle, HCkString retval);
Error information in HTML format for the last method called.
void CkMime_getLastErrorText(HCkMime cHandle, HCkString retval);
Error information in plain-text format for the last method called.
void CkMime_getLastErrorXml(HCkMime cHandle, HCkString retval);
Error information in XML format for the last method called.
void CkMime_getMicalg(HCkMime cHandle, HCkString retval);
void CkMime_putMicalg(HCkMime cHandle, const char *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.
void CkMime_getName(HCkMime cHandle, HCkString retval);
void CkMime_putName(HCkMime cHandle, const char *newVal);
The name attribute of the content-type header field.
long CkMime_getNumEncryptCerts(HCkMime cHandle);
The number of certificates found when decrypting S/MIME. This property is set after UnwrapSecurity is called.
long CkMime_getNumHeaderFields(HCkMime cHandle);
The number of header fields. Header field names and values can be retrieved by index (starting at 0) by calling GetHeaderFieldName and GetHeaderFieldValue.
long CkMime_getNumParts(HCkMime cHandle);
The number of sub-parts contained within this message. Each sub-part is a complete Chilkat MIME message itself.
long CkMime_getNumSignerCerts(HCkMime cHandle);
The number of certificates found when verifying signature(s). This property is set after UnwrapSecurity is called.
void CkMime_getProtocol(HCkMime cHandle, HCkString retval);
void CkMime_putProtocol(HCkMime cHandle, const char *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.
BOOL CkMime_getUnwrapExtras(HCkMime cHandle);
void CkMime_putUnwrapExtras(HCkMime cHandle, BOOL newVal);
Controls whether extra (informative) header fields are added to the MIME message when unwrapping security.
BOOL CkMime_getUseMmDescription(HCkMime cHandle);
void CkMime_putUseMmDescription(HCkMime cHandle, BOOL 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.
BOOL CkMime_getUtf8(HCkMime cHandle);
void CkMime_putUtf8(HCkMime cHandle, BOOL newVal);
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.
BOOL CkMime_getVerboseLogging(HCkMime cHandle);
void CkMime_putVerboseLogging(HCkMime cHandle, BOOL newVal);
To be documented soon...
void CkMime_getVersion(HCkMime cHandle, HCkString retval);
The version, such as "1.0.0".
C "Methods"
void CkMime_AddContentLength(HCkMime cHandle);
To be documented soon...
BOOL CkMime_AddDetachedSignature(HCkMime cHandle, HCkCert 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 TRUE for success, FALSE for failure.
BOOL CkMime_AddDetachedSignature2(HCkMime cHandle, HCkCert cert, BOOL 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 TRUE for success, FALSE for failure.
BOOL CkMime_AddDetachedSignaturePk(HCkMime cHandle, HCkCert cert, HCkPrivateKey privateKey);
To be documented soon.
BOOL CkMime_AddDetachedSignaturePk2(HCkMime cHandle, HCkCert cert, HCkPrivateKey privateKey, BOOL transferHeaderFields);
To be documented soon.
BOOL CkMime_AddEncryptCert(HCkMime cHandle, HCkCert cert);
To be documented soon.
BOOL CkMime_AddHeaderField(HCkMime cHandle, const char *name, const char *value);
Adds a header field to the MIME.
BOOL CkMime_AppendPart(HCkMime cHandle, HCkMime 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.
BOOL CkMime_AppendPartFromFile(HCkMime cHandle, const char *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 TRUE for success, FALSE for failure.
BOOL CkMime_AsnBodyToXml(HCkMime cHandle, HCkString outStr);
To be documented soon...
void CkMime_ClearEncryptCerts(HCkMime cHandle);
To be documented soon...
BOOL CkMime_ContainsEncryptedParts(HCkMime cHandle);
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.
BOOL CkMime_ContainsSignedParts(HCkMime cHandle);
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.
void CkMime_Convert8Bit(HCkMime cHandle);
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.
void CkMime_ConvertToMultipartAlt(HCkMime cHandle);
To be documented soon. Returns TRUE for success, FALSE for failure.
void CkMime_ConvertToMultipartMixed(HCkMime cHandle);
To be documented soon. Returns TRUE for success, FALSE for failure.
BOOL CkMime_ConvertToSigned(HCkMime cHandle, HCkCert 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 TRUE for success, FALSE for failure.
BOOL CkMime_ConvertToSignedPk(HCkMime cHandle, HCkCert cert, HCkPrivateKey privateKey);
To be documented soon...
BOOL CkMime_Decrypt(HCkMime cHandle);
To be documented soon. Returns TRUE for success, FALSE for failure.
BOOL CkMime_Decrypt2(HCkMime cHandle, HCkCert cert, HCkPrivateKey privateKey);
To be documented soon. Returns TRUE for success, FALSE for failure.
BOOL CkMime_Encrypt(HCkMime cHandle, HCkCert cert);
Encrypt a MIME message object using a digital certificate. Returns TRUE for success, FALSE for failure.
BOOL CkMime_EncryptN(HCkMime cHandle);
To be documented soon...
HCkStringArray CkMime_ExtractPartsToFiles(HCkMime cHandle, const char *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
BOOL CkMime_GetBodyBinary(HCkMime cHandle, HCkByteData 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.
BOOL CkMime_GetBodyDecoded(HCkMime cHandle, HCkString 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.
BOOL CkMime_GetBodyEncoded(HCkMime cHandle, HCkString 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.
HCkCert CkMime_GetEncryptCert(HCkMime cHandle, long index);
Returns the Nth certificate found when decrypting. The EncryptCerts property contains the number of certificates.
void CkMime_GetEntireBody(HCkMime cHandle, HCkString str);
Returns the entire MIME body, including all sub-parts.
void CkMime_GetEntireHead(HCkMime cHandle, HCkString str);
Returns the MIME header.
BOOL CkMime_GetHeaderField(HCkMime cHandle, const char *name, HCkString 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.
BOOL CkMime_GetHeaderFieldName(HCkMime cHandle, int index, HCkString fieldName);
Returns the Nth MIME header field name.
BOOL CkMime_GetHeaderFieldValue(HCkMime cHandle, int index, HCkString fieldValue);
Returns the Nth MIME header field value.
BOOL CkMime_GetMime(HCkMime cHandle, HCkString mime);
Returns a string containing the complete MIME message, including all sub-parts.
BOOL CkMime_GetMimeBytes(HCkMime cHandle, HCkByteData outBytes);
Returns a byte array containing the complete MIME message, including all sub-parts.
HCkMime CkMime_GetPart(HCkMime cHandle, long index);
Returns the Nth sub-part of the MIME message. Indexing begins at 0.
HCkCert CkMime_GetSignerCert(HCkMime cHandle, long index);
Returns the Nth digital certificate used to sign the MIME message. Indexing begins at 0.
BOOL CkMime_GetXml(HCkMime cHandle, HCkString xml);
Converts the MIME (or S/MIME) message to XML and returns the XML as a string.
BOOL CkMime_IsApplicationData(HCkMime cHandle);
Return true if the MIME message contains application data, otherwise returns false.
BOOL CkMime_IsAttachment(HCkMime cHandle);
Return true if this MIME message is an attachment, otherwise returns false
BOOL CkMime_IsAudio(HCkMime cHandle);
Return true if the MIME message contains audio data, otherwise returns false.
BOOL CkMime_IsEncrypted(HCkMime cHandle);
Returns true if the MIME message is encrypted.
BOOL CkMime_IsHtml(HCkMime cHandle);
Return true if the MIME body is HTML
BOOL CkMime_IsImage(HCkMime cHandle);
Return true if the MIME message contains image data, otherwise returns false.
BOOL CkMime_IsMultipart(HCkMime cHandle);
Return true if the MIME message is multipart (multipart/mixed, multipart/related, multipart/alternative, etc.), otherwise returns false.
BOOL CkMime_IsMultipartAlternative(HCkMime cHandle);
Return true if the MIME message is multipart/alternative, otherwise returns false.
BOOL CkMime_IsMultipartMixed(HCkMime cHandle);
Return true if the MIME message is multipart/mixed, otherwise returns false.
BOOL CkMime_IsMultipartRelated(HCkMime cHandle);
Return true if the MIME message is multipart/related, otherwise returns false.
BOOL CkMime_IsPlainText(HCkMime cHandle);
Return true if the MIME message body is plain text, otherwise returns false.
BOOL CkMime_IsSigned(HCkMime cHandle);
Return true if the MIME message is digitally signed, otherwise returns false.
BOOL CkMime_IsText(HCkMime cHandle);
Return true if the MIME message body is any text content type, such as text/plain, text/html, text/xml, etc., otherwise returns false.
BOOL CkMime_IsUnlocked(HCkMime cHandle);
Returns true if the component is already unlocked, false if not.
BOOL CkMime_IsVideo(HCkMime cHandle);
Return true if the MIME message contains video data, otherwise returns false.
BOOL CkMime_IsXml(HCkMime cHandle);
Return true if the MIME message body is XML, otherwise returns false.
BOOL CkMime_LoadMime(HCkMime cHandle, const char *mimeMsg);
Discards the current contents of the MIME object and loads a new MIME message from a string.
BOOL CkMime_LoadMimeBytes(HCkMime cHandle, HCkByteData bData);
Loads a MIME document from an in-memory byte array.
BOOL CkMime_LoadMimeFile(HCkMime cHandle, const char *fileName);
Discards the current contents of the MIME object and loads a new MIME message from a file. Returns TRUE for success, FALSE for failure.
BOOL CkMime_LoadXml(HCkMime cHandle, const char *xml);
Converts XML to MIME and replaces the MIME object's contents with the converted XML.
BOOL CkMime_LoadXmlFile(HCkMime cHandle, const char *fileName);
Converts XML to MIME and replaces the MIME object's contents with the converted XML. Returns TRUE for success, FALSE for failure.
BOOL CkMime_NewMessageRfc822(HCkMime cHandle, HCkMime 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.
BOOL CkMime_NewMultipartAlternative(HCkMime cHandle);
Discards the current MIME message header fields and contents, if any, an initializes the MIME object to be an empty mulipart/alternative message.
BOOL CkMime_NewMultipartMixed(HCkMime cHandle);
Discards the current MIME message header fields and contents, if any, an initializes the MIME object to be an empty mulipart/mixed message.
BOOL CkMime_NewMultipartRelated(HCkMime cHandle);
Discards the current MIME message header fields and contents, if any, an initializes the MIME object to be an empty mulipart/related message.
BOOL CkMime_RemovePart(HCkMime cHandle, int index);
Removes the Nth subpart from the MIME message.
BOOL CkMime_SaveBody(HCkMime cHandle, const char *filename);
Saves the MIME message body to a file. If the body is base64 or quoted-printable encoded, it is automatically decoded.
BOOL CkMime_SaveLastError(HCkMime cHandle, const char *filename);
Saves the last error information to an XML formatted file.
BOOL CkMime_SaveMime(HCkMime cHandle, const char *filename);
Saves the MIME message to a file, in MIME format. (This is the same as the .EML format used by Microsoft Outlook Express.)
BOOL CkMime_SaveXml(HCkMime cHandle, const char *filename);
Converts the MIME message to XML and saves to an XML file.
void CkMime_SetBody(HCkMime cHandle, const char *str);
To be documented soon...
BOOL CkMime_SetBodyFromBinary(HCkMime cHandle, HCkByteData dbuf);
Sets the MIME message body from a byte array.
BOOL CkMime_SetBodyFromEncoded(HCkMime cHandle, const char *encoding, const char *str);
Sets the MIME message body from a Base64 or Quoted-Printable encoded string.
BOOL CkMime_SetBodyFromFile(HCkMime cHandle, const char *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).
BOOL CkMime_SetBodyFromHtml(HCkMime cHandle, const char *str);
Sets the MIME message body from a string containing HTML, and also updates the content-type to be text/html
BOOL CkMime_SetBodyFromPlainText(HCkMime cHandle, const char *str);
Sets the MIME message body from a string containing plain text, and also updates the content-type to be text/plain
BOOL CkMime_SetBodyFromXml(HCkMime cHandle, const char *str);
Sets the MIME message body from a string containing XML, and also updates the content-type to be text/xml
BOOL CkMime_SetCSP(HCkMime cHandle, HCkCSP 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.
BOOL CkMime_SetHeaderField(HCkMime cHandle, const char *name, const char *value);
Adds or replaces a MIME message header field. If the field already exists, it is automatically replaced. Otherwise it is added.
void CkMime_SetVerifyCert(HCkMime cHandle, HCkCert cert);
Allows a certificate to be explicitly specified for verifying a signature.
HCkEmail CkMime_ToEmailObject(HCkMime cHandle);
Returns the MIME message converted to a CkEmail object. Returns a null reference on failure
BOOL CkMime_UnlockComponent(HCkMime cHandle, const char *unlockCode);
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.
BOOL CkMime_UnwrapSecurity(HCkMime cHandle);
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.
void CkMime_UrlEncodeBody(HCkMime cHandle, const char *charset);
To be documented soon...
BOOL CkMime_Verify(HCkMime cHandle);
To be documented soon...
const char *CkMime_asnBodyToXml(HCkMime cHandle);
To be documented soon...
const char *CkMime_bodyDecoded(HCkMime cHandle);
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.
const char *CkMime_bodyEncoded(HCkMime cHandle);
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.
const char *CkMime_boundary(HCkMime cHandle);
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.
const char *CkMime_charset(HCkMime cHandle);
The charset, such as "ISO-8859-1" or "utf-8"
const char *CkMime_contentType(HCkMime cHandle);
The MIME content type, such as "text/plain", "text/html", "multipart/alternative", "multipart/mixed", etc.
const char *CkMime_currentDateTime(HCkMime cHandle);
Returns the current date/time in RFC 822 format.
const char *CkMime_disposition(HCkMime cHandle);
The content disposition, which can be "attachment", "inline", etc.
const char *CkMime_encoding(HCkMime cHandle);
A content encoding such as "base64", "quoted-printable", "7bit", "8bit", etc.
const char *CkMime_entireBody(HCkMime cHandle);
Returns the entire MIME body, including all sub-parts.
const char *CkMime_entireHead(HCkMime cHandle);
Returns the MIME header.
const char *CkMime_filename(HCkMime cHandle);
The filename when the content disposition is "attachment".
const char *CkMime_getBodyDecoded(HCkMime cHandle);
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.
const char *CkMime_getBodyEncoded(HCkMime cHandle);
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.
const char *CkMime_getEntireBody(HCkMime cHandle);
Returns the entire MIME body, including all sub-parts.
const char *CkMime_getEntireHead(HCkMime cHandle);
Returns the MIME header.
const char *CkMime_getHeaderField(HCkMime cHandle, const char *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.
const char *CkMime_getHeaderFieldName(HCkMime cHandle, int index);
Returns the Nth MIME header field name.
const char *CkMime_getHeaderFieldValue(HCkMime cHandle, int index);
Returns the Nth MIME header field value.
const char *CkMime_getMime(HCkMime cHandle);
Returns a string containing the complete MIME message, including all sub-parts.
const char *CkMime_getXml(HCkMime cHandle);
Converts the MIME (or S/MIME) message to XML and returns the XML as a string.
const char *CkMime_header(HCkMime cHandle, const char *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.
const char *CkMime_headerName(HCkMime cHandle, int index);
Returns the Nth MIME header field name.
const char *CkMime_headerValue(HCkMime cHandle, int index);
Returns the Nth MIME header field value.
const char *CkMime_lastErrorHtml(HCkMime cHandle);
Error information in HTML format for the last method called.
const char *CkMime_lastErrorText(HCkMime cHandle);
Error information in plain-text format for the last method called.
const char *CkMime_lastErrorXml(HCkMime cHandle);
Error information in XML format for the last method called.
const char *CkMime_micalg(HCkMime cHandle);
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.
const char *CkMime_mime(HCkMime cHandle);
Returns a string containing the complete MIME message, including all sub-parts.
const char *CkMime_name(HCkMime cHandle);
The name attribute of the content-type header field.
const char *CkMime_protocol(HCkMime cHandle);
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.
const char *CkMime_xml(HCkMime cHandle);
Converts the MIME (or S/MIME) message to XML and returns the XML as a string.
|