epoc32/include/smtpset.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     1 // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
     2 // All rights reserved.
     3 // This component and the accompanying materials are made available
     4 // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
     5 // which accompanies this distribution, and is available
     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
     7 //
     8 // Initial Contributors:
     9 // Nokia Corporation - initial contribution.
    10 //
    11 // Contributors:
    12 //
    13 // Description:
    14 //
    15 
    16 #if !defined (__SMTPSET_H__)
    17 #define __SMTPSET_H__
    18 
    19  
    20 #include <msvuids.h>
    21 #include <miutset.h>
    22 
    23 /** Default SMTP server port number.*/
    24 const TUint32 KSMTPDefaultPortNumber = 25;
    25 
    26 /** Default/maximum addresses to include in body header of reply/forward messages */
    27 const TInt KSmtpToCcIncludeLimitDefault = 0;
    28 const TInt KSmtpToCcIncludeLimitMax = KMaxTInt;
    29 
    30 
    31 /**
    32 Defines options that allows the user to automatically email themselves a copy 
    33 of all emails that are sent from the phone.
    34 
    35 @see CImSmtpSettings::SendCopyToSelf() 
    36 
    37 @publishedAll
    38 @released
    39 */
    40 enum TImSMTPSendCopyToSelf
    41 	{
    42 	/** Do not send a copy. */
    43 	ESendNoCopy,
    44 	/** Send a copy, with the user's address added to the To address list. */
    45 	ESendCopyAsToRecipient,
    46 	/** Send a copy, with the user's address added to the Cc: address list. */
    47 	ESendCopyAsCcRecipient,
    48 	/** Send a copy, with the user's address added to the Bcc: address list. */
    49 	ESendCopyAsBccRecipient
    50 	};
    51 /**
    52 Defines sending options for new email messages.
    53 
    54 The option has no direct effect on the SMTP MTM, although messages in the 
    55 outbox which are marked as ESendMessageOnNextConnection or ESendMessageImmediately 
    56 will be appended automatically to the list of messages supplied by the client 
    57 when either CBaseServerMtm::CopyFromLocal() or CBaseServerMtm::MoveFromLocal() 
    58 are called. 
    59 
    60 @publishedAll
    61 @released
    62 */
    63 enum TImSMTPSendMessageOption
    64 	{
    65 	/** Send message immediately. */
    66 	ESendMessageImmediately,
    67 	/** Send message when the next connection occurs. */
    68 	ESendMessageOnNextConnection,
    69 	/** Send message only when the user requests this. */
    70 	ESendMessageOnRequest
    71 	};
    72 
    73 /**
    74 Defines status values for the SMTP MTM. 
    75 
    76 @publishedAll
    77 @released
    78 */
    79 enum TMsgImOutboxSendState
    80 	{
    81 	/** Idle. */
    82 	EMsgOutboxProgressWaiting,
    83 	/** Connecting to server. */
    84 	EMsgOutboxProgressConnecting,
    85 	/** Sending messages. */
    86 	EMsgOutboxProgressSending,
    87 	/** Sending complete. */
    88 	EMsgOutboxProgressDone
    89 	};
    90 
    91 /** Sending state for SMTP. 
    92 
    93 @publishedAll
    94 @released
    95 */
    96 enum TSmtpSessionState
    97 	{
    98 	/** Dialling, looking up DNS, or connecting to SMTP server. */
    99 	EConnectingToSmtp,
   100 	/** Waiting for the SMTP server to send welcome message. */
   101 	EWaitingForReply,
   102 	/** Sending HELO/EHLO command to the server. */
   103 	EAuthorisingSmtp,
   104 	/** Sending the STARTTLS command, if a secure connection was requested. */
   105 	ESendingStarttls,
   106 	/** Exchanging certificates with server, if a secure connection was requested. */
   107 	ESettingSecurity,
   108 	/** Sending a message to the server. */
   109 	ESendingImail,
   110 	/** Logging result. */
   111 	ELogDataEvent,
   112 	/** Disconnecting from the SMTP server. */
   113 	EClosingSmtp,
   114 	/** AUTH in progress. */
   115 	EAuthInProgress,
   116 	/** RSET in progress. */
   117 	EResetSmtp
   118 	};
   119 
   120 class TImImailFileProgress				
   121 /** 
   122 Status information about the SMTP message which is being sent. 
   123 
   124 @publishedAll
   125 @released
   126 */
   127 	{
   128 public:
   129 	/**
   130 	Amount of data from the message already sent to the server in bytes.
   131 	
   132 	Note that the SMTP MTM encodes the text and binary data inside an email message 
   133 	while it is sending the data. As a result, iBytesToSend is likely to increase 
   134 	(by as much as one third) while a message is being sent. The size increase 
   135 	represents all additional bytes which have been added to the RFC 822 message 
   136 	to encode the data.
   137 	*/
   138 	TInt				iBytesSent;
   139 	/** Amount of data from the message still to be sent to the server in bytes. */
   140 	TInt				iBytesToSend;
   141 	/** Sending state. */
   142 	TSmtpSessionState	iSessionState;
   143 	};
   144 
   145 class TImSmtpProgress
   146 /**
   147 Progress information for SMTP operations on the Internet Mail MTM.
   148 
   149 The information is obtained through calling CMsvOperation::Progress() 
   150 on the operation. It is packaged into an 8-bit descriptor. 
   151 
   152 Messaging clients use the getter functions to get various types
   153 of information about an operation's progress. The setter functions
   154 are for use by the MTM.
   155 
   156 @publishedAll
   157 @released
   158 */
   159 	{
   160 
   161 public:
   162 	IMPORT_C TMsgImOutboxSendState	Status() const; // Progress: current progress status of mail session
   163 	IMPORT_C TInt MsgNo() const;		            // Progress: No. of message currently being sent; zero=1st message
   164 	IMPORT_C TInt Error() const;			        // Summary: completion code from end of last session
   165 	IMPORT_C TInt Sent() const;			            // Summary: No. messages sent successfully
   166 	IMPORT_C TInt NotSent() const;		            // Summary: No. messages I didn't attempt to send
   167 	IMPORT_C TInt FailedToSend() const;	            // Summary: No. messages attempted to send but failed
   168 	IMPORT_C TInt SendTotal() const;		        // Sent() + NotSent() + FailedToSend() = SendTotal()
   169 	IMPORT_C void SetError(TInt anError);
   170 	IMPORT_C void SetStatus(TMsgImOutboxSendState aStatus);
   171 	IMPORT_C void SetMsgNo(TInt aMsgNo);
   172 	IMPORT_C void InitialiseTotal(const TInt& aTotal);
   173 	IMPORT_C void UpdateSent();
   174 	IMPORT_C void UpdateFailedToSend();
   175 	IMPORT_C void DecrementSendTotal();
   176 	IMPORT_C TMsvId	ServiceId() const;
   177 	IMPORT_C void SetServiceId(TMsvId aServiceId);
   178 	IMPORT_C TInt ConnectionState() const;
   179 	IMPORT_C TInt ConnectionIAP() const;
   180 	IMPORT_C void SetConnectionIAP(TInt aConnectionIAP);
   181 
   182 public:
   183 	/** Status information about the message that is currently being sent (if 
   184 	sending is in progress). */
   185 	TImImailFileProgress			iSendFileProgress;
   186 
   187 private:
   188 	TMsgImOutboxSendState	iStatus;
   189 	TInt					iError;
   190 	TInt					iMsgNo;
   191 	TInt					iSent;
   192 	TInt					iNotSent;
   193 	TInt					iFailedToSend;
   194 	TInt					iSendTotal;
   195 	TMsvId					iServiceId;
   196 	};
   197 
   198 class CImSmtpSettings : public CImBaseEmailSettings
   199 /**
   200 Run-time configuration settings for an SMTP account.
   201 
   202 Messaging clients should use an instance of this class to specify
   203 and retrieve configuration settings that are used by the SMTP service when
   204 executing email operations.  
   205 
   206 Service settings such as the email body encoding, reply address, character set,
   207 and whether to attach a signature or vCard can be specified using this class.
   208 Storing and restoring from the message store is also supported.
   209 
   210 To use this class to change a setting:
   211 
   212 1) Set the current context to the SMTP service entry using CMsvStore.
   213 
   214 2) Create an instance of CImSmtpSettings and put it on the cleanup stack.
   215 
   216 3) Retrieve the existing settings by calling CImSmtpSettings::RestoreL().
   217 
   218 4) Specify whether to add a vCard to outbound email by calling CImSmtpSettings::SetAddVCardToEmail().
   219 
   220 5) Save the new settings by calling CImSmtpSettings::StoreL().
   221 
   222 6) Pop and destroy the CImSmtpSettings instance.
   223 
   224 @see CMsvStore
   225 
   226 @publishedAll
   227 @released
   228 */
   229 	{
   230 public:
   231 	IMPORT_C CImSmtpSettings();
   232 	IMPORT_C virtual ~CImSmtpSettings();
   233 	IMPORT_C void Reset();
   234 	IMPORT_C const TPtrC EmailAlias() const;
   235 	IMPORT_C void SetEmailAliasL(const TDesC& aEmailAlias);
   236 	IMPORT_C const TPtrC EmailAddress() const;
   237 	IMPORT_C void SetEmailAddressL(const TDesC& aEmailAddress);
   238 	IMPORT_C const TPtrC ReplyToAddress() const;
   239 	IMPORT_C void SetReplyToAddressL(const TDesC& aReplyToAddress);
   240 	IMPORT_C const TPtrC ReceiptAddress() const;
   241 	IMPORT_C void SetReceiptAddressL(const TDesC& aReceiptAddress);
   242 	IMPORT_C TMsgOutboxBodyEncoding BodyEncoding() const;
   243 	IMPORT_C void SetBodyEncoding(TMsgOutboxBodyEncoding aBodyEncoding);
   244 	IMPORT_C const TUid DefaultMsgCharSet() const;
   245 	IMPORT_C void SetDefaultMsgCharSet(TUid aDefaultMsgCharSet);
   246 	IMPORT_C TBool AddVCardToEmail() const;
   247 	IMPORT_C void SetAddVCardToEmail(TBool aFlag);
   248 	IMPORT_C TBool AddSignatureToEmail() const;
   249 	IMPORT_C void SetAddSignatureToEmail(TBool aFlag);
   250 	IMPORT_C TBool RequestReceipts() const;
   251 	IMPORT_C void SetRequestReceipts(TBool aFlag);
   252 	IMPORT_C TImSMTPSendCopyToSelf SendCopyToSelf() const;
   253 	IMPORT_C void SetSendCopyToSelf(TImSMTPSendCopyToSelf aSendCopyToSelf);
   254 	IMPORT_C TImSMTPSendMessageOption SendMessageOption() const;
   255 	IMPORT_C void SetSendMessageOption(TImSMTPSendMessageOption aSendMessageOption);
   256 	IMPORT_C CImSmtpSettings& CopyL(const CImSmtpSettings& aCImSmtpSettings);
   257 	IMPORT_C TBool operator==(const CImSmtpSettings& aCImSmtpSettings) const;
   258 	IMPORT_C const TPtrC8 LoginName() const;
   259 	IMPORT_C void SetLoginNameL(const TDesC8&);
   260 	IMPORT_C const TPtrC8 Password() const;
   261 	IMPORT_C void SetPasswordL(const TDesC8&);
   262 	IMPORT_C TBool SMTPAuth() const;
   263 	IMPORT_C void SetSMTPAuth(TBool aFlag);
   264 	IMPORT_C TBool InboxLoginDetails() const;
   265 	IMPORT_C void SetInboxLoginDetails(TBool aFlag);
   266 	IMPORT_C TInt ToCcIncludeLimit() const;
   267 	IMPORT_C void SetToCcIncludeLimitL(TInt aLimit);
   268 	IMPORT_C void SetTlsSslDomainL(const TDesC8& aDomainName);
   269 	IMPORT_C TPtrC8 TlsSslDomain() const;
   270 
   271 private:
   272 	class TImSmtpSettingsExtension
   273 		{
   274 	public:
   275 		inline TImSmtpSettingsExtension();
   276 	public:
   277 		HBufC*	iReceiptAddress;
   278 		HBufC8* iLoginName;
   279 		HBufC8* iPassword;
   280 		HBufC8*	iTlsSslDomain;
   281 		TInt	iToCcIncludeLimit;
   282 		};
   283 
   284 	inline TImSmtpSettingsExtension* Extension() const;
   285 	inline void CheckExtensionExistsL();
   286 
   287 private:
   288 	enum TImSMTPEmailSettings
   289 		{
   290 		KSmtpSettingsClearFlag				= 0x00000000,
   291 		KSmtpBaseEmailSettingsLastUsedFlag	= CImBaseEmailSettings::EBaseEmailSettingsLastUsedFlag,	//0x00000002
   292 		KSmtpAddVCardToEmailFlag			= KSmtpBaseEmailSettingsLastUsedFlag << 1,	//0x00000004
   293 		KSmtpAddSignatureToEmailFlag		= KSmtpAddVCardToEmailFlag << 1,			//0x00000008
   294 		KSmtpRequestReceipts				= KSmtpAddSignatureToEmailFlag << 1,		//0x00000010
   295 		KSmtpSmtpAuthFlag					= KSmtpRequestReceipts << 1,				//0x00000020
   296 		KSmtpInboxLoginDetails				= KSmtpSmtpAuthFlag << 1,					//0x00000040
   297 		KSmtpEmailSettingsLastUsedFlag		= KSmtpInboxLoginDetails					//0x00000040
   298 		};
   299 
   300 	HBufC*						iEmailAlias;
   301 	HBufC*						iEmailAddress;
   302 	HBufC*						iReplyToAddress;
   303 	TImSmtpSettingsExtension*	iExtension; // renamed iReceiptAddress
   304 	TMsgOutboxBodyEncoding		iBodyEncoding;
   305 	TUid						iDefaultMsgCharSet;
   306 	TImSMTPSendCopyToSelf		iSendCopyToSelf;
   307 	TImSMTPSendMessageOption	iSendMessageOption;
   308 	};
   309 	
   310 inline CImSmtpSettings::TImSmtpSettingsExtension* CImSmtpSettings::Extension() const
   311 	{
   312 	return iExtension;
   313 	}
   314 
   315 inline void CImSmtpSettings::CheckExtensionExistsL()
   316 	{
   317 	if (!iExtension)
   318 		iExtension=new (ELeave) CImSmtpSettings::TImSmtpSettingsExtension;
   319 	}
   320 
   321 inline CImSmtpSettings::TImSmtpSettingsExtension::TImSmtpSettingsExtension() : iReceiptAddress(NULL),iLoginName(NULL),iPassword(NULL),iTlsSslDomain(NULL),iToCcIncludeLimit(KSmtpToCcIncludeLimitDefault)
   322 	{
   323 	}
   324 
   325 #endif    // #define __SMTPSET_H__