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