PIMAP Class

Properties Methods Events Configuration Settings Errors

The PIMAP component is used to communicate with IMAP servers to retrieve and process OpenPGP encrypted and/or signed messages and any attachments.

Class Name

IPWorksOpenPGP_PIMAP

Procedural Interface

 ipworksopenpgp_pimap_open();
 ipworksopenpgp_pimap_close($res);
 ipworksopenpgp_pimap_register_callback($res, $id, $function);
 ipworksopenpgp_pimap_get_last_error($res);
 ipworksopenpgp_pimap_get_last_error_code($res);
 ipworksopenpgp_pimap_set($res, $id, $index, $value);
 ipworksopenpgp_pimap_get($res, $id, $index);
 ipworksopenpgp_pimap_do_addmessageflags($res, $flags);
 ipworksopenpgp_pimap_do_appendtomailbox($res);
 ipworksopenpgp_pimap_do_checkmailbox($res);
 ipworksopenpgp_pimap_do_closemailbox($res);
 ipworksopenpgp_pimap_do_config($res, $configurationstring);
 ipworksopenpgp_pimap_do_connect($res);
 ipworksopenpgp_pimap_do_copytomailbox($res);
 ipworksopenpgp_pimap_do_createmailbox($res);
 ipworksopenpgp_pimap_do_decrypt($res);
 ipworksopenpgp_pimap_do_decryptandverifysignature($res);
 ipworksopenpgp_pimap_do_deletefrommailbox($res);
 ipworksopenpgp_pimap_do_deletemailbox($res);
 ipworksopenpgp_pimap_do_deletemailboxacl($res, $user);
 ipworksopenpgp_pimap_do_disconnect($res);
 ipworksopenpgp_pimap_do_doevents($res);
 ipworksopenpgp_pimap_do_examinemailbox($res);
 ipworksopenpgp_pimap_do_expungemailbox($res);
 ipworksopenpgp_pimap_do_fetchmessageheaders($res);
 ipworksopenpgp_pimap_do_fetchmessageinfo($res);
 ipworksopenpgp_pimap_do_fetchmessagepart($res, $partid);
 ipworksopenpgp_pimap_do_fetchmessagepartheaders($res, $partid);
 ipworksopenpgp_pimap_do_fetchmessagetext($res);
 ipworksopenpgp_pimap_do_getmailboxacl($res);
 ipworksopenpgp_pimap_do_interrupt($res);
 ipworksopenpgp_pimap_do_listmailboxes($res);
 ipworksopenpgp_pimap_do_listsubscribedmailboxes($res);
 ipworksopenpgp_pimap_do_localizedate($res, $datetime);
 ipworksopenpgp_pimap_do_movetomailbox($res);
 ipworksopenpgp_pimap_do_noop($res);
 ipworksopenpgp_pimap_do_renamemailbox($res, $newname);
 ipworksopenpgp_pimap_do_resetmessageflags($res);
 ipworksopenpgp_pimap_do_searchmailbox($res, $searchcriteria);
 ipworksopenpgp_pimap_do_selectmailbox($res);
 ipworksopenpgp_pimap_do_setmailboxacl($res, $user, $rights);
 ipworksopenpgp_pimap_do_subscribemailbox($res);
 ipworksopenpgp_pimap_do_unsetmessageflags($res);
 ipworksopenpgp_pimap_do_unsubscribemailbox($res);
 ipworksopenpgp_pimap_do_verifysignature($res);

Remarks

The PIMAP class offers an easy-to-use interface: it implements a standard IMAP client, as specified in RFC 1730 and RFC 2060, and supports decrypting and verifying signatures of encrypted and signed emails using OpenPGP. Additionally, it enables you to create messages bound for multiple recipients with different keys, simultaneously encrypt and compress with the most popular compression algorithms, and control other aspects such as the encrypting algorithm to use.

Connect to a Mail Server

The first step in using the class is specifying a MailServer, a User to connect as, and a Password to authenticate with. After that, one or more requests may be sent to the server via the class's methods. Results are retrieved through events and a number of key properties.

Examine a Mailbox

Normally, after connecting to the server a Mailbox is selected (or examined) using the ExamineMailbox method. After the Mailbox is selected, MessageCount and RecentMessageCount show the number of messages in the mailbox, and MailboxFlags shows the flags pertaining to the mailbox.

A number of operations may be performed by the server in response to commands sent via the class's methods. The primary arguments for most commands are the Mailbox property and the MessageSet property. The MessageSet property denotes either a single message or a range of messages. Other arguments are specified through other properties such as SortCriteria, MessageFlags, etc.

Responses are received through events such as MessageInfo and MailboxList, and are also reflected in properties such as MessageText, MessageSubject, etc.

Decrypt

To process an encrypted or signed message, first retrieve the message text and headers by calling FetchMessageHeaders and FetchMessageText. To decrypt a message specify the private key to be used for decryption by setting the Key* properties. For instance:

PIMAP1.KeyCount = 1
PIMAP1.KeyKeyring(0) = "c:\my_keyring_dir"
PIMAP1.KeyUserId(0) = "recipient@nsoftware.com"
PIMAP1.KeyPassphrase(0) = "password"

The specified private key will be used to decrypt the message when calling Decrypt.

Verify

To verify the signature of a message specify the public key to be used for signature verification by setting the SignerKey* properties. For instance:

PIMAP1.SignerKeyCount = 1
PIMAP1.SignerKeyKeyring(0) = "c:\my_keyring_dir"
PIMAP1.SignerKeyUserId(0) = "sender@nsoftware.com"

The specified public key will be used to verify the signature when calling VerifySignature. To decrypt and verify in one step call DecryptAndVerifySignature.

Retrieve MIME Message Parts

The MessagePart event describes the MIME structure of retrieved messages. One MessagePart event is fired for every message part, giving information about the particular part. Later on, message parts may be retrieved separately through the FetchMessagePart method. This speeds up processing by avoiding the need to retrieve full messages from the server.

Trace Client and Server Communication

The PITrail event traces the interaction between the client and the server. It includes all exchanges except for transfers of messages, message parts, and message headers.

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.


AuthMechanism	The authentication mechanism to be used when connecting to the mail server.
AutoDecodeParts	Determines whether to automatically decode message parts.
Command	Can be used to send additional commands directly to the server.
Connected	Shows whether the component is connected.
EndByte	The byte index of the position where the transfer should end.
FirewallAutoDetect	This property tells the component whether or not to automatically detect and use firewall system settings, if available.
FirewallType	This property determines the type of firewall to connect through.
FirewallHost	This property contains the name or IP address of firewall (optional).
FirewallPassword	This property contains a password if authentication is to be used when connecting through the firewall.
FirewallPort	This property contains the TCP port for the firewall Host .
FirewallUser	This property contains a user name if authentication is to be used connecting through a firewall.
Idle	The current status of the component.
KeyCount	The number of records in the Key arrays.
KeyEncoded	The key.
KeyKeyring	The location of the keyring.
KeyPassphrase	The passphrase for the key's secret key (if any).
KeyUserId	The user Id of the key.
LastReply	The last reply from the server.
LocalHost	The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
Mailbox	Name of the mailbox selected on the server.
MailboxFlags	Defines flags in the selected mailbox.
MailboxListCount	The number of records in the MailboxList arrays.
MailboxListFlags	The mailbox flags in a mailbox listing.
MailboxListName	The mailbox name in a mailbox listing.
MailboxListSeparator	The Separator property contains the character that separates the different parts in the mailbox path hierarchy.
MailPort	The port of the IMAP server (default is 143).
MailServer	The name or address of the mail server (IMAP server).
Message	Provides the raw message content.
MessageContentEncoding	The ContentEncoding of the selected message.
MessageContentType	The ContentType of the message.
MessageCount	The total number of messages on the Mailbox .
MessageDate	The time the message was created.
MessageDeliveryTime	The time the message was delivered to the mail server.
MessageFlags	Contains the flags of the current message.
MessageFrom	The address of the author of the message.
MessageHeaderCount	The number of records in the MessageHeader arrays.
MessageHeaderField	This property contains the name of the HTTP header (same case as it is delivered).
MessageHeaderValue	This property contains the header contents.
MessageHeadersString	String version of RFC822-encoded headers of the message.
MessageId	The message identifier of the current message.
MessageInfoCount	The number of records in the MessageInfo arrays.
MessageInfoDate	The date of a message in a message info listing.
MessageInfoFlags	Message flag in a message info listing.
MessageInfoFrom	The sender of a message in a message info listing.
MessageInfoMessageId	The unique identifier of a message in a message info listing.
MessageInfoSize	The size of a message in a message info listing.
MessageInfoSubject	The subject of a message in a message info listing.
MessageInReplyTo	The unique message identifier of the message this one is in reply to.
MessageNetId	The globally unique identifier of the message.
MessagePartCount	The number of records in the MessagePart arrays.
MessagePartContentDisposition	This property shows the value of the Content-Disposition header of the message part.
MessagePartContentEncoding	This property shows how the data is encoded.
MessagePartContentId	This property shows the value of the Content-Id header of the message part.
MessagePartContentType	This property shows the type of data contained in the message part.
MessagePartFilename	This property shows the filename corresponding to the part (if the part was included in the message as an attached file).
MessagePartId	This property contains the identifier of a part listing which may be identified in other parts or messages.
MessagePartMultipartMode	This property shows how this part relates to the message's whole multipart structure ('mixed', 'alternative', etc.
MessagePartParameters	This property contains the additional parameters passed to the ContentType header such as the part charset etc.
MessagePartSize	This property contains the size of a part in a message part listing.
MessageRecipientCount	The number of records in the MessageRecipient arrays.
MessageRecipientAddress	This property contains the email address of the recipient.
MessageRecipientName	This property contains name of the recipient.
MessageRecipientOptions	This property contains the recipient sending options (used only by SMTP).
MessageRecipientType	This property contains the recipient type: To, Cc, or BCc.
MessageReplyTo	Email address(s) where replies to the message should be sent.
MessageSender	The address of the sender of the message.
MessageSet	The set of messages to operate on.
MessageSize	The size of the selected message.
MessageSubject	The subject of the message.
MessageText	The body of the retrieved message.
Overwrite	Indicates whether or not the component should overwrite files during transfer.
Password	The password used to authenticate to the MailServer .
PeekMode	When set to True, the message Seen flag is not changed during reading.
RecentMessageCount	Number of new messages in the Mailbox .
SignerKeyCount	The number of records in the SignerKey arrays.
SignerKeyEncoded	The key.
SignerKeyKeyring	The location of the keyring.
SignerKeyUserId	The user Id of the key.
SortCriteria	Sorts criteria to use for message retrieval operations.
SSLAcceptServerCertEncoded	The certificate (PEM/base64 encoded).
SSLCertEncoded	The certificate (PEM/base64 encoded).
SSLCertStore	The name of the certificate store for the client certificate.
SSLCertStorePassword	If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
SSLCertStoreType	The type of certificate store for this certificate.
SSLCertSubject	The subject of the certificate used for client authentication.
SSLServerCertEncoded	The certificate (PEM/base64 encoded).
SSLStartMode	Determines how the component starts the SSL negotiation.
StartByte	The byte index of the position where the transfer should start.
Timeout	A timeout for the component.
UIDMode	If true, permanent message identifiers are used instead of the default temporary identifiers.
UIDValidity	The UIDValidity parameter sent from the server in response to SelectMailbox command.
User	The user name used to authenticate to the MailServer .

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.


AddMessageFlags	Adds the specified flags to the messages specified by MessageSet .
AppendToMailbox	Appends the message in MessageText to the mailbox specified by Mailbox .
CheckMailbox	Sends a 'CHECK' command to the server.
CloseMailbox	Removes all messages marked with 'Deleted' flag from the currently selected mailbox and unselect mailbox.
Config	Sets or retrieves a configuration setting .
Connect	Connects to an IMAP server.
CopyToMailbox	Copies the messages specified by MessageSet to the mailbox specified by Mailbox .
CreateMailbox	Creates a new mailbox specified by Mailbox .
Decrypt	Decrypts the message.
DecryptAndVerifySignature	Decrypts and verifies the signature of the message.
DeleteFromMailbox	Marks the messages specified by MessageSet as deleted.
DeleteMailbox	Deletes a mailbox specified by Mailbox .
DeleteMailboxACL	Deletes mailbox access control rights for a specific user.
Disconnect	Disconnects from an IMAP server.
DoEvents	Processes events from the internal message queue.
ExamineMailbox	Selects a Mailbox (Read-only mode).
ExpungeMailbox	Removes all messages marked with 'Deleted' flag from the currently selected mailbox.
FetchMessageHeaders	Retrieves the message headers of messages specified by the MessageSet property.
FetchMessageInfo	Retrieves information about messages specified by the MessageSet property.
FetchMessagePart	Retrieves the message part specified by PartID.
FetchMessagePartHeaders	Retrieves the headers of message part specified by PartID.
FetchMessageText	Retrieves the message text of messages specified by the MessageSet property.
GetMailboxACL	Retrieves mailbox access control rights.
Interrupt	Interrupt the current method.
ListMailboxes	Lists all mailboxes matching all criteria in the Mailbox property.
ListSubscribedMailboxes	Lists all subscribed mailboxes matching all criteria in the Mailbox property.
LocalizeDate	Converts a valid RFC 822 message date to local date and time.
MoveToMailbox	Moves the messages specified by MessageSet to the mailbox specified by Mailbox .
Noop	Sends a 'NOOP' command to the server.
RenameMailbox	Change the name of Mailbox to NewName .
ResetMessageFlags	Replaces the flags of the messages specified by MessageSet with the flags specified by MessageFlags .
SearchMailbox	Search selected mailbox for specified text.
SelectMailbox	Select a Mailbox.
SetMailboxACL	Sets mailbox access control rights for a specific user.
SubscribeMailbox	Subscribes to the mailbox specified by Mailbox .
UnsetMessageFlags	Removes the flags specified by MessageFlags from the messages specified by MessageSet .
UnsubscribeMailbox	Unsubscribes from the mailbox specified by Mailbox .
VerifySignature	Verifies the signature of the current message.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.


ConnectionStatus	Fired to indicate changes in connection state.
EndTransfer	Fired when the message or the part data finishes transferring.
Error	Information about errors during data delivery.
Header	Fired every time a header line comes in.
KeyPassphrase	Fired if the passphrase of current key is incorrect or empty.
MailboxACL	Fires for each set of access control rights returned by the server.
MailboxList	Fired for each mailbox received through the ListMailboxes and ListSubscribedMailboxes methods.
MessageInfo	Fired with information for the message(s) retrieved by the server.
MessagePart	Fired for each message part when FetchMessageInfo is called.
PITrail	Traces the commands sent to the mail server, and the respective replies.
Progress	Fired as progress is made.
RecipientInfo	Fired for each recipient key of the encrypted message.
SignatureInfo	Fired during verification of the signed message.
SSLServerAuthentication	Fired after the server presents its certificate to the client.
SSLStatus	Shows the progress of the secure connection.
StartTransfer	Fired when the message or the part data starts transferring.
Status	Shows the progress of the operation.
Transfer	Fired while the message gets transferred from the MailServer .
VerificationStatus	Fired after verification of the signed message.

Configuration Settings

The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.


Comment	The OpenPGP message comment.
ProcessAttachments	Whether or not to process attachments.
LogLevel	Specifies the level of detail that is logged.
RequireValidSignature	Specifies if an invalid signature is considered an error condition.
SymmetricPassphrase	The password used for symmetric encryption or decryption.
VersionHeader	The Version header value in the ASCII armored OpenPGP message.
AlwaysReturnUIDs	Instructs the server to return UIDs even if not in UIDMode.
AppendToMailboxDateTime	Specifies the date-time parameter used in the initial APPEND request.
AuthorizationIdentity	The value to use as the authorization identity when SASL authentication is used.
AutoDecodeSubject	Instructs the component to automatically decode message subjects.
EnableIMAPIDLE	Enables or disables IDLE command support in the component.
FetchAfterSearch	Determines if messages matching the SearchCriteria are fetched after calling SearchMailbox.
IncludeHeaders	Instructs the component to include the headers in the LocalFile.
UTF7MailboxNames	Specifies whether or not to automatically encode and decode UTF-7 mailbox names.
ConnectionTimeout	Sets a separate timeout value for establishing a connection.
FirewallAutoDetect	Tells the component whether or not to automatically detect and use firewall system settings, if available.
FirewallHost	Name or IP address of firewall (optional).
FirewallPassword	Password to be used if authentication is to be used when connecting through the firewall.
FirewallPort	The TCP port for the FirewallHost;.
FirewallType	Determines the type of firewall to connect through.
FirewallUser	A user name if authentication is to be used connecting through a firewall.
KeepAliveTime	The inactivity time in milliseconds before a TCP keep-alive packet is sent.
KeepAliveInterval	The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received.
Linger	When set to True, connections are terminated gracefully.
LingerTime	Time in seconds to have the connection linger.
LocalHost	The name of the local host through which connections are initiated or accepted.
LocalPort	The TCP port in the local host where the component binds.
MaxLineLength	The maximum amount of data to accumulate when no EOL is found.
MaxTransferRate	The transfer rate limit in bytes per second.
RecordLength	The length of received data records.
TCPKeepAlive	Determines whether or not the keep alive socket option is enabled.
UseIPv6	Whether to use IPv6.
TcpNoDelay	Whether or not to delay when sending packets.
ReuseSSLSession	Determines if the SSL session is reused.
SSLCipherStrength	The minimum cipher strength used for bulk encryption.
SSLEnabledProtocols	Used to enable/disable the supported security protocols.
SSLProvider	The name of the security provider to use.
SSLSecurityFlags	Flags that control certificate verification.
OpenSSLCADir	The path to a directory containing CA certificates.
OpenSSLCAFile	Name of the file containing the list of CA's trusted by your application.
OpenSSLCipherList	A string that controls the ciphers to be used by SSL.
OpenSSLPrngSeedData	The data to seed the pseudo random number generator (PRNG).
AbsoluteTimeout	Determines whether timeouts are inactivity timeouts or absolute timeouts.
FirewallData	Used to send extra data to the firewall.
InBufferSize	The size in bytes of the incoming queue of the socket.
OutBufferSize	The size in bytes of the outgoing queue of the socket.
CodePage	The system code page used for Unicode to Multibyte translations.