public/awesome-cordova-plugins
public/awesome-cordova-plugins
9
0
Fork 0
forked from github/awesome-cordova-plugins
Code Pull Requests Activity

feat(cordova-plugin-imap) add support for iOS; (#3790)

Browse Source 
extend the method ‘listMailFolders’;
add new method ‘getFullMessageDataOnNewSession’
This commit is contained in:
Aleksandar Noveski 2021-10-02 11:44:53 +02:00 committed by GitHub
parent 529ec51bda
commit 34b16a98a8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 184 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

238
src/@awesome-cordova-plugins/plugins/imap/index.ts
View File

@ -7,7 +7,18 @@ export interface Config {
*/
host: string;
/**
* Username or email address for authentication.
* Optional parameter. Port of the IMAP server to connect.
* Default set to: 993
*/
port?: number;
/**
* iOS ONLY
* Optional parameter. Encryption type to use.
* Default set to: TLS/SSL
*/
connectionType?: ConnectionType;
/**
* Username or email address for authentication.
*/
user: string;
/**
@ -31,6 +42,45 @@ export interface Connection {
exception?: string;
}
export interface MessageHeaders {
/**
* Message consecutive number.
*/
messageNumber: number;
/**
* The name of the folder where the message is contained.
*/
folder: string;
/**
* Sender's data.
*/
from: Address[];
/**
* TO recipients data.
*/
toRecipients: Address[];
/**
* CC recipients data.
*/
ccRecipients: Address[];
/**
* BCC recipients data.
*/
bccRecipients: Address[];
/**
* The date when the message was received.
*/
receivedDate: string;
/**
* Message's subject header.
*/
subject: string;
/**
* Message's active flags.
*/
flags: string[];
}
export interface Message {
/**
* Message consecutive number.
@ -45,9 +95,9 @@ export interface Message {
*/
from: Address[];
/**
* Optional. All recipients data.
* All recipients data.
*/
allRecipients?: Address[];
allRecipients: Address[];
/**
* TO recipients data.
*/
@ -61,13 +111,13 @@ export interface Message {
*/
bccRecipients: Address[];
/**
* Optional. Reply data.
* Reply data.
*/
replyTo?: Address[];
replyTo: Address[];
/**
* Optional. Date when the message was sent.
* Date when the message was sent.
*/
sentDate?: string;
sentDate: string;
/**
* The date when the message was received.
*/
@ -77,41 +127,46 @@ export interface Message {
*/
subject: string;
/**
* Android ONLY
* Optional. Short description for the message.
*/
description?: string;
/**
* Optional.
*
*/
fileName?: string;
fileName: string;
/**
* Android ONLY
* Optional.
*/
disposition?: string;
/**
* Message's active flags.
*/
flags: string;
flags: string[];
/**
* Android ONLY
* Optional.
*/
lineCount?: number;
/**
* Android ONLY
* Optional. All Headers available on a message.
*/
allMessageHeaders?: object;
/**
* Android ONLY
* Optional. Type of message's content.
*/
contentType?: string;
/**
* Optional. Message's body with its content and attachments.
* Message's body with its content and attachments.
*/
bodyContent?: Content[];
bodyContent: Content[];
/**
* Optional. Message's memory size.
* Message's memory size.
*/
size?: number;
size: number;
}
export interface Address {
@ -124,9 +179,10 @@ export interface Address {
*/
personal?: string;
/**
* Data type.
* Android ONLY
* Optional. Data type.
*/
type: string;
type?: string;
}
export interface Content {
@ -155,8 +211,24 @@ export interface ModificationResult {
modifiedMessages: number[];
}
export enum ConnectionType {
/**
* Clear-text connection for the protocol.
*/
Clear = 'Clear',
/**
* Starts with clear-text connection at the beginning, then switch to encrypted connection using TLS/SSL.
*/
StartTLS = 'StartTLS',
/**
* Encrypted connection using TLS/SSL.
*/
TLSSSL = 'TLS/SSL',
}
export enum Comparison {
/**
* Android ONLY
* The less than or equal to operator.
*/
LE = 'LE',
@ -173,6 +245,7 @@ export enum Comparison {
*/
NE = 'NE',
/**
* Android ONLY
* The greater than operator.
*/
GT = 'GT',
@ -199,6 +272,7 @@ export enum FlagEnum {
*/
FLAGGED = 'FLAGGED',
/**
* Android ONLY
* "RECENT" message flag
*/
RECENT = 'RECENT',
@ -207,6 +281,7 @@ export enum FlagEnum {
*/
SEEN = 'SEEN',
/**
* Android ONLY
* "USER" message flag
*/
USER = 'USER',
@ -214,15 +289,36 @@ export enum FlagEnum {
* "DELETED" message flag. Note: Add this flag to delete the message from the mailbox
*/
DELETED = 'DELETED',
/**
* iOS ONLY
* "SENT" message flag.
*/
SENT = 'Sent',
/**
* iOS ONLY
* "FORWARDED" message flag.
*/
FORWARDED = 'Forwarded',
/**
* iOS ONLY
* "SubmitPending" message flag.
*/
SubmitPending = 'SubmitPending',
/**
* iOS ONLY
* "SUBMITTED" message flag.
*/
SUBMITTED = 'Submitted',
}
/**
* @name Imap
* @description
* This plugin will enable an Ionic application to use the IMAP (Internet Message Access Protocol) features.
* This plugin is in Beta version and it offers support only for Android.
* The plugin uses Java Mail API.
* Planned improvements and support for iOS.
* This plugin will enable a Cordova application to use the IMAP (Internet Message Access Protocol) features
* The plugin offers support for Android and iOS.
* To enable the IMAP features on Android, this plugin uses the framework [Java Mail API](https://javaee.github.io/javamail/) and for iOS, it uses the [MailCore 2](http://libmailcore.com/) library.
*
*
* @usage
* ```typescript
* import { Imap } from '@awesome-cordova-plugins/imap/ngx';
@ -235,6 +331,8 @@ export enum FlagEnum {
*
* this.imap.connect({
* host: 'imap.gmail.com',
* port: 993,
* connectionType: ConnectionType.TLSSSL // (iOS ONLY) Encryption type to use. Default set to: TLS/SSL
* user: 'my_email@gmail.com',
* password: 'my-pass'
* })
@ -253,10 +351,13 @@ export enum FlagEnum {
* .then((res: boolean) => console.log(res))
* .catch((error: any) => console.error(error));
*
* Note: Connected to an IMAP service is REQUIRED to be able to get data from the below functions.
* // Note: Connected to an IMAP service is REQUIRED to be able to get data from the below functions.
*
*
* this.imap.listMailFolders()
* // listMailFolders('*') using a '*' pattern will return all folder names
* // listMailFolders('INBOX*') using a pattern with a folder name will list all the subfolder names of that folder that match the pattern
*
* this.imap.listMailFolders('*')
* .then((res: boolean) => console.log(res))
* .catch((error: any) => console.error(error));
*
@ -284,7 +385,7 @@ export enum FlagEnum {
*
*
* this.imap.listMessagesHeadersByConsecutiveNumber('INBOX', 1200, 1280)
* .then((res: Message[]) => {
* .then((res: MessageHeaders[]) => {
* // Returns array with messages' headers data
* console.log(res)
* })
@ -294,7 +395,7 @@ export enum FlagEnum {
*
*
* this.imap.listMessagesHeadersByDate('INBOX', 1601503200000, Comparison.GE)
* .then((res: Message[]) => {
* .then((res: MessageHeaders[]) => {
* // Returns array with messages' headers data
* console.log(res)
* })
@ -313,6 +414,22 @@ export enum FlagEnum {
* });
*
*
* this.imap.getFullMessageDataOnNewSession({
* host: 'imap.gmail.com',
* port: 993,
* connectionType: ConnectionType.TLSSSL // (iOS ONLY) Encryption type to use. Default set to: TLS/SSL
* user: 'my_email@gmail.com',
* password: 'my-pass'
* }, 'INBOX', 1205)
* .then((res: Message) => {
* // Returns "Message" object with the full message data including attachments.
* console.log(res)
* })
* .catch((error: any) => {
* console.error(error)
* });
*
*
* this.imap.copyToFolder('INBOX', 'Spam', [1204, 1205, 1206, 1207])
* .then((res: boolean) => {
* // Returns "true" if the process is successful, else returns "false".
@ -323,8 +440,8 @@ export enum FlagEnum {
* });
*
*
* Sets a flag on a message
* "setFlag()" can be used for deleting messages setting the Delete flag to "FlagEnum.DELETED"
* * Sets a flag on a message
* * "setFlag()" can be used for deleting messages setting the Delete flag to "FlagEnum.DELETED"
* this.imap.setFlag('INBOX', [1206, 1205, 1204], FlagEnum.SEEN, true)
* .then((res: ModificationResult) => {
*
@ -344,15 +461,14 @@ export enum FlagEnum {
plugin: 'cordova-plugin-imap',
pluginRef: 'imap',
repo: 'https://github.com/aleksandar888/cordova-plugin-imap.git',
platforms: ['Android'],
platforms: ['Android', 'iOS'],
})
@Injectable()
export class Imap extends AwesomeCordovaNativePlugin {
/**
* This function "connect(clientData: Config)" tries to connect and authenticate with the IMAP server.
*
* @param clientData {Config} Connection configuration
* @returns {Promise<Connection>} Returns a promise with the connection data
* @return {Promise<Connection>} Returns a promise with the connection data
*/
@Cordova()
connect(clientData: Config): Promise<Connection> {
@ -361,8 +477,7 @@ export class Imap extends AwesomeCordovaNativePlugin {
/**
* "disconnect()" Closes the connection with the server.
*
* @returns {Promise<boolean>} Returns a promise status.
* @return {Promise<boolean>} Returns a promise status.
*/
@Cordova()
disconnect(): Promise<boolean> {
@ -371,8 +486,7 @@ export class Imap extends AwesomeCordovaNativePlugin {
/**
* "isConnected()" Checks the current state of the connection.
*
* @returns {Promise<boolean>} Returns a promise with connection status
* @return {Promise<boolean>} Returns a promise with connection status
*/
@Cordova()
isConnected(): Promise<boolean> {
@ -382,20 +496,27 @@ export class Imap extends AwesomeCordovaNativePlugin {
/** Note: Connected to an IMAP service is REQUIRED to be able to get data from the below functions. */
/**
* "listMailFolders()" Lists the name of all the mail folders in the mailbox.
* Returns an array of Folder names based on a regular expression pattern.
*
* @returns {Promise<string[]>} Returns array with all folder names.
* Example:
*
* listMailFolders('*') using a '*' pattern will return all folder names
* listMailFolders('INBOX*') using a pattern with a folder name will list all the subfolder names that match the pattern
*
*
* "listMailFolders(pattern: string)" Lists the name of mail folders in the mailbox.
* @param pattern {string} Regular expression pattern.
* @return {Promise<string[]>} Returns array of folder names matching the pattern.
*/
@Cordova()
listMailFolders(): Promise<string[]> {
listMailFolders(pattern: string): Promise<string[]> {
return;
}
/**
* "getMessageCountByFolderName(folderName: string)" Gets the count of the messages in the folder.
*
* @param folderName {string} The name of the desired folder.
* @returns {Promise<number>} Returns the consecutive number of the last message.
* @return {Promise<number>} Returns the consecutive number of the last message.
*/
@Cordova()
getMessageCountByFolderName(folderName: string): Promise<number> {
@ -404,11 +525,10 @@ export class Imap extends AwesomeCordovaNativePlugin {
/**
* "searchMessagesByDatePeriod(folderName: string, dateInMilliseconds: number, comparison: Comparison)" Returns the messages' consecutive number.
*
* @param folderName {string} The name of the desired folder
* @param dateInMilliseconds {number} Date in milliseconds
* @param comparison {Comparison} A comparison operator
* @returns {Promise<number[]>} Returns array with the messages' consecutive numbers.
* @return {Promise<number[]>} Returns array with the messages' consecutive numbers.
*/
@Cordova()
searchMessagesByDatePeriod(
@ -421,40 +541,37 @@ export class Imap extends AwesomeCordovaNativePlugin {
/**
* "listMessagesHeadersByConsecutiveNumber(folderName: string, start: number, end: number)" Returns messages' headers data based on a "start" and "end" message consecutive number.
*
* @param folderName {string} The name of the desired folder
* @param start {number} Consecutive number of the first message.
* @param end {number} Consecutive number of the last message
* @returns {Promise<Message[]>} Returns array with the messages' headers data.
* @return {Promise<MessageHeaders[]>} Returns array with the messages' headers data.
*/
@Cordova()
listMessagesHeadersByConsecutiveNumber(folderName: string, start: number, end: number): Promise<Message[]> {
listMessagesHeadersByConsecutiveNumber(folderName: string, start: number, end: number): Promise<MessageHeaders[]> {
return;
}
/**
* "listMessagesHeadersByDate(folderName: string, dateInMilliseconds: number, comparison: Comparison)" Returns messages' headers data based on a date.
*
* @param folderName {string} The name of the desired folder
* @param dateInMilliseconds {number} Date in milliseconds.
* @param comparison {Comparison} A comparison operator
* @returns {Promise<Message[]>} Returns array messages' headers data.
* @return {Promise<MessageHeaders[]>} Returns array messages' headers data.
*/
@Cordova()
listMessagesHeadersByDate(
folderName: string,
dateInMilliseconds: number,
comparison: Comparison
): Promise<Message[]> {
): Promise<MessageHeaders[]> {
return;
}
/**
* "getFullMessageData(folderName: string, messageNumber: number)" Returns the full message's data including its attachments.
*
* @param folderName {string} The name the message's folder
* "getFullMessageData(folderName: string, messageNumber: number)" Returns the full message data including its attachments.
* @param folderName {string} The name the message's folder.
* @param messageNumber {number} Message's consecutive number.
* @returns {Promise<Message>} Returns "Message" object with full message data.
* @return {Promise<Message>} Returns "Message" object with full message data.
*/
@Cordova()
getFullMessageData(folderName: string, messageNumber: number): Promise<Message> {
@ -462,12 +579,26 @@ export class Imap extends AwesomeCordovaNativePlugin {
}
/**
* "copyToFolder(sourceFolder: string, destinationFolder: string, messageNums: number[])" Copy messages to a desired folder.
*
* This function "getFullMessageDataOnNewSession(clientData: Config, folderName: string, messageNumber: number)" downloads the full message data using a
* separate session with the server. It is suitable for downloading message data while the app is already connected to a third server.
* "getFullMessageDataOnNewSession(clientData: Config, folderName: string, messageNumber: number)" Returns the full message data including its attachments.
* @param clientData {Config} Connection configuration.
* @param folderName {string} The name the message's folder.
* @param messageNumber {number} Message's consecutive number.
* @return {Promise<Message>} Returns "Message" object with full message data.
*/
@Cordova()
getFullMessageDataOnNewSession(clientData: Config, folderName: string, messageNumber: number): Promise<Message> {
return;
}
/**
* "copyToFolder(sourceFolder: string, destinationFolder: string, messageNums: number[])" Copy messages to a desired folder.
* @param sourceFolder {string} The name of the source folder.
* @param destinationFolder {string} The name of the destination folder.
* @param messageNums {number[]} Array with messages' consecutive numbers or array with single message consecutive number.
* @returns {Promise<Message>} Returns boolean status of the process.
* @return {Promise<Message>} Returns boolean status of the process.
*/
@Cordova()
copyToFolder(sourceFolder: string, destinationFolder: string, messageNums: number[]): Promise<boolean> {
@ -476,12 +607,11 @@ export class Imap extends AwesomeCordovaNativePlugin {
/**
* "setFlag(folderName: string, messageNums: number[], flag: FlagEnum, status: boolean)" Set or remove flag from a message
*
* @param folderName {string} The name of the source folder where the messages are contained.
* @param messageNums {number[]} Array with messages' consecutive numbers or array with single message consecutive number
* @param flag {FlagEnum} Desired message flag.
* @param status {boolean} Set status to "true" to set the flag on a message; or to "false" to remove the flag from the message
* @returns {Promise<ModificationResult>} Returns object with status and array with messages' consecutive numbers of the modified messages
* @return {Promise<ModificationResult>} Returns object with status and array with messages' consecutive numbers of the modified messages
*/
@Cordova()
setFlag(folderName: string, messageNums: number[], flag: FlagEnum, status: boolean): Promise<ModificationResult> {