1 /* 2 * Copyright (C) 2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.email.mail; 18 19 import com.android.emailcommon.mail.CertificateValidationException; 20 import com.android.emailcommon.mail.MessagingException; 21 22 import java.io.IOException; 23 import java.io.InputStream; 24 import java.io.OutputStream; 25 import java.net.InetAddress; 26 import java.net.SocketException; 27 28 /** 29 * This interface defines a "transport", which is defined here as being one layer below the 30 * specific wire protocols such as POP3, IMAP, or SMTP. 31 * 32 * Practically speaking, it provides a definition of the common functionality between them 33 * (dealing with sockets & streams, SSL, logging, and so forth), and provides a seam just below 34 * the individual protocols to enable better testing. 35 * 36 * The following features are supported and presumed to be common: 37 * 38 * Interpretation of URI 39 * Support for SSL and TLS wireline security 40 */ 41 public interface Transport extends Cloneable { 42 43 /** 44 * Connection security options for transport that supports SSL and/or TLS 45 */ 46 public static final int CONNECTION_SECURITY_NONE = 0; 47 public static final int CONNECTION_SECURITY_SSL = 1; 48 public static final int CONNECTION_SECURITY_TLS = 2; 49 50 /** 51 * Get a new transport, using an existing one as a model. The new transport is configured as if 52 * setUri() and setSecurity() have been called, but not opened or connected in any way. 53 * @return a new Transport ready to open() 54 */ clone()55 public Transport clone(); 56 57 /** 58 * Sets the host 59 */ setHost(String host)60 public void setHost(String host); 61 62 /** 63 * Sets the port 64 */ setPort(int port)65 public void setPort(int port); 66 67 /** 68 * Returns the host or {@code null} if none was specified. 69 */ getHost()70 public String getHost(); 71 72 /** 73 * Returns the port or {@code 0} if none was specified. 74 */ getPort()75 public int getPort(); 76 77 /** 78 * Set the desired security mode for this connection. 79 * @param connectionSecurity A value indicating the desired security mode. 80 * @param trustAllCertificates true to allow unverifiable certificates to be used 81 */ setSecurity(int connectionSecurity, boolean trustAllCertificates)82 public void setSecurity(int connectionSecurity, boolean trustAllCertificates); 83 84 /** 85 * @return Returns the desired security mode for this connection. 86 */ getSecurity()87 public int getSecurity(); 88 89 /** 90 * @return true if the security mode indicates that SSL is possible 91 */ canTrySslSecurity()92 public boolean canTrySslSecurity(); 93 94 /** 95 * @return true if the security mode indicates that TLS is possible 96 */ canTryTlsSecurity()97 public boolean canTryTlsSecurity(); 98 99 /** 100 * @return true if the security mode indicates that all certificates can be trusted 101 */ canTrustAllCertificates()102 public boolean canTrustAllCertificates(); 103 104 /** 105 * Set the socket timeout. 106 * @param timeoutMilliseconds the read timeout value if greater than {@code 0}, or 107 * {@code 0} for an infinite timeout. 108 */ setSoTimeout(int timeoutMilliseconds)109 public void setSoTimeout(int timeoutMilliseconds) throws SocketException; 110 111 /** 112 * Attempts to open the connection using the supplied parameters, and using SSL if indicated. 113 */ open()114 public void open() throws MessagingException, CertificateValidationException; 115 116 /** 117 * Attempts to reopen the connection using TLS. 118 */ reopenTls()119 public void reopenTls() throws MessagingException; 120 121 /** 122 * @return true if the connection is open 123 */ isOpen()124 public boolean isOpen(); 125 126 /** 127 * Closes the connection. Does not send any closure messages, simply closes the socket and the 128 * associated streams. Best effort only. Catches all exceptions and always returns. 129 * 130 * MUST NOT throw any exceptions. 131 */ close()132 public void close(); 133 134 /** 135 * @return returns the active input stream 136 */ getInputStream()137 public InputStream getInputStream(); 138 139 /** 140 * @return returns the active output stream 141 */ getOutputStream()142 public OutputStream getOutputStream(); 143 144 /** 145 * Write a single line to the server, and may generate a log entry (if enabled). 146 * @param s The text to send to the server. 147 * @param sensitiveReplacement If the command includes sensitive data (e.g. authentication) 148 * please pass a replacement string here (for logging). Most callers simply pass null, 149 */ writeLine(String s, String sensitiveReplacement)150 void writeLine(String s, String sensitiveReplacement) throws IOException; 151 152 /** 153 * Reads a single line from the server. Any delimiter characters will not be included in the 154 * result. May generate a log entry, if enabled. 155 * @return Returns the string from the server. 156 * @throws IOException 157 */ readLine()158 String readLine() throws IOException; 159 160 /** 161 * @return The local address. If we have an open socket, get the local address from this. 162 * Otherwise simply use {@link InetAddress#getLocalHost}. 163 */ getLocalAddress()164 InetAddress getLocalAddress() throws IOException; 165 } 166