add new findServer() method and javadoc comments

r=sspitzer
#15140

mailnews/compose/public/nsISmtpService.idl

@@ -49,8 +49,37 @@ interface nsISmtpService : nsISupports {
 					   in nsIUrlListener aUrlListener, in nsISmtpServer aServer,
                        out nsIURI aURL);
 
+  /**
+   * A copy of the array of SMTP servers, as stored in the preferences
+   */
   readonly attribute nsISupportsArray smtpServers;
+
+  /**
+   * The default server, across sessions of the app
+   * (eventually there will be a session default which does not
+   * persist past shutdown)
+   */
   attribute nsISmtpServer defaultServer;
+
+  /**
+   * create a new SMTP server.
+   * Use this instead of createInstance(), so that the SMTP Service can
+   * be aware of this server
+   */
   nsISmtpServer createSmtpServer();
+
+  /**
+   * find the server with the given hostname.
+   * @param hostname the hostname of the server
+   * @returns null if no server is found
+   */
+  nsISmtpServer findServer(in string hostname);
+
+  /**
+   * delete the given server from the server list.
+   * does nothing if the server does not exist
+   * @param server the server to delete. Use findServer() if you only know
+   *   the hostname
+   */
   void deleteSmtpServer(in nsISmtpServer server);
 };

mailnews/compose/src/nsSmtpService.cpp

@@ -35,6 +35,10 @@ typedef struct _findServerByKeyEntry {
     nsISmtpServer *server;
 } findServerByKeyEntry;
 
+typedef struct _findServerByHostnameEntry {
+    const char *hostname;
+    nsISmtpServer *server;
+} findServerByHostnameEntry;
 
 static NS_DEFINE_CID(kCSmtpUrlCID, NS_SMTPURL_CID);
 
@@ -427,3 +431,44 @@ nsSmtpService::DeleteSmtpServer(nsISmtpServer *aServer)
     return rv;
 
 }
+
+PRBool
+nsSmtpService::findServerByHostname(nsISupports *element, void *aData)
+{
+    nsresult rv;
+    
+    nsCOMPtr<nsISmtpServer> server = do_QueryInterface(element, &rv);
+    if (NS_FAILED(rv)) return PR_TRUE;
+
+    findServerByHostnameEntry *entry = (findServerByHostnameEntry*)aData;
+
+    nsXPIDLCString hostname;
+    rv = server->GetHostname(getter_Copies(hostname));
+    if (NS_FAILED(rv)) return PR_TRUE;
+
+    if (((const char*)hostname) &&
+        nsCRT::strcmp(hostname, entry->hostname) == 0) {
+        entry->server = server;
+        return PR_FALSE;        // stop when found
+    }
+    return PR_TRUE;
+}
+
+NS_IMETHODIMP
+nsSmtpService::FindServer(const char *hostname, nsISmtpServer ** aResult)
+{
+    if (!aResult) return NS_ERROR_NULL_POINTER;
+
+    findServerByHostnameEntry entry;
+    entry.server=nsnull;
+    entry.hostname = hostname;
+
+    mSmtpServers->EnumerateForwards(findServerByHostname, (void *)&entry);
+
+    // entry.server may be null, but that's ok.
+    // just return null if no server is found
+    *aResult = entry.server;
+    NS_IF_ADDREF(*aResult);
+    
+    return NS_OK;
+}

mailnews/compose/src/nsSmtpService.h

@@ -58,6 +58,8 @@ protected:
     
 private:
     static PRBool findServerByKey (nsISupports *element, void *aData);
+    static PRBool findServerByHostname (nsISupports* element, void *aData);
+    
     nsresult createKeyedServer(const char* key,
                                nsISmtpServer **aResult = nsnull);
     nsCOMPtr<nsISupportsArray> mSmtpServers;