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 java.io.IOException; 20 import java.io.InputStream; 21 import java.io.OutputStream; 22 import java.net.SocketException; 23 import java.net.URI; 24 25 /** 26 * This interface defines a "transport", which is defined here as being one layer below the 27 * specific wire protocols such as POP3, IMAP, or SMTP. 28 * 29 * Practically speaking, it provides a definition of the common functionality between them 30 * (dealing with sockets & streams, SSL, logging, and so forth), and provides a seam just below 31 * the individual protocols to enable better testing. 32 * 33 * The following features are supported and presumed to be common: 34 * 35 * Interpretation of URI 36 * Support for SSL and TLS wireline security 37 */ 38 public interface Transport { 39 40 /** 41 * Connection security options for transport that supports SSL and/or TLS 42 */ 43 public static final int CONNECTION_SECURITY_NONE = 0; 44 public static final int CONNECTION_SECURITY_SSL = 1; 45 public static final int CONNECTION_SECURITY_TLS = 2; 46 47 /** 48 * Get a new transport, using an existing one as a model. The new transport is configured as if 49 * setUri() and setSecurity() have been called, but not opened or connected in any way. 50 * @return a new Transport ready to open() 51 */ newInstanceWithConfiguration()52 public Transport newInstanceWithConfiguration(); 53 54 /** 55 * Set the Uri for the connection. 56 * 57 * @param uri The Uri for the connection 58 * @param defaultPort If the Uri does not include an explicit port, this value will be used. 59 */ setUri(URI uri, int defaultPort)60 public void setUri(URI uri, int defaultPort); 61 62 /** 63 * @return Returns the host part of the Uri 64 */ getHost()65 public String getHost(); 66 67 /** 68 * @return Returns the port (either from the Uri or from the default) 69 */ getPort()70 public int getPort(); 71 72 /** 73 * Returns the user info parts of the Uri, if any were supplied. Typically, [0] is the user 74 * and [1] is the password. 75 * @return Returns the user info parts of the Uri. Null if none were supplied. 76 */ getUserInfoParts()77 public String[] getUserInfoParts(); 78 79 /** 80 * Set the desired security mode for this connection. 81 * @param connectionSecurity A value indicating the desired security mode. 82 * @param trustAllCertificates true to allow unverifiable certificates to be used 83 */ setSecurity(int connectionSecurity, boolean trustAllCertificates)84 public void setSecurity(int connectionSecurity, boolean trustAllCertificates); 85 86 /** 87 * @return Returns the desired security mode for this connection. 88 */ getSecurity()89 public int getSecurity(); 90 91 /** 92 * @return true if the security mode indicates that SSL is possible 93 */ canTrySslSecurity()94 public boolean canTrySslSecurity(); 95 96 /** 97 * @return true if the security mode indicates that TLS is possible 98 */ canTryTlsSecurity()99 public boolean canTryTlsSecurity(); 100 101 /** 102 * @return true if the security mode indicates that all certificates can be trusted 103 */ canTrustAllCertificates()104 public boolean canTrustAllCertificates(); 105 106 /** 107 * Set the socket timeout. 108 * @param timeoutMilliseconds the read timeout value if greater than {@code 0}, or 109 * {@code 0} for an infinite timeout. 110 */ setSoTimeout(int timeoutMilliseconds)111 public void setSoTimeout(int timeoutMilliseconds) throws SocketException; 112 113 /** 114 * Attempts to open the connection using the supplied parameters, and using SSL if indicated. 115 */ open()116 public void open() throws MessagingException, CertificateValidationException; 117 118 /** 119 * Attempts to reopen the connection using TLS. 120 */ reopenTls()121 public void reopenTls() throws MessagingException; 122 123 /** 124 * @return true if the connection is open 125 */ isOpen()126 public boolean isOpen(); 127 128 /** 129 * Closes the connection. Does not send any closure messages, simply closes the socket and the 130 * associated streams. Best effort only. Catches all exceptions and always returns. 131 * 132 * MUST NOT throw any exceptions. 133 */ close()134 public void close(); 135 136 /** 137 * @return returns the active input stream 138 */ getInputStream()139 public InputStream getInputStream(); 140 141 /** 142 * @return returns the active output stream 143 */ getOutputStream()144 public OutputStream getOutputStream(); 145 146 /** 147 * Write a single line to the server, and may generate a log entry (if enabled). 148 * @param s The text to send to the server. 149 * @param sensitiveReplacement If the command includes sensitive data (e.g. authentication) 150 * please pass a replacement string here (for logging). Most callers simply pass null, 151 */ writeLine(String s, String sensitiveReplacement)152 void writeLine(String s, String sensitiveReplacement) throws IOException; 153 154 /** 155 * Reads a single line from the server. Any delimiter characters will not be included in the 156 * result. May generate a log entry, if enabled. 157 * @return Returns the string from the server. 158 * @throws IOException 159 */ readLine()160 String readLine() throws IOException; 161 162 } 163