DownloadManager::Observer::OnDownloadCreated

content/public/browser/download_manager.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 //
 // The DownloadManager object manages the process of downloading, including
 // updates to the history system and providing the information for displaying
 // the downloads view in the Destinations tab. There is one DownloadManager per
 // active browser context in Chrome.
 //
 // Download observers:
@@ skipping 61 matching lines @@
   // Shutdown the download manager. Content calls this when BrowserContext is
   // being destructed. If the embedder needs this to be called earlier, it can
   // call it. In that case, the delegate's Shutdown() method will only be called
   // once.
   virtual void Shutdown() = 0;
 
   // Interface to implement for observers that wish to be informed of changes
   // to the DownloadManager's collection of downloads.
   class CONTENT_EXPORT Observer {
    public:
+    // A DownloadItem was created.  Useful methods on the item that are
+    // guaranteed to work as advertised include GetId(), AddObserver(),
+    // SetExternalData(), GetURL(). The item is guaranteed to be accessible via
+    // DownloadManager::GetDownload(). No other guarantees are made about its
+    // state: it may have just been loaded from history, it may be an active
+    // download, or it may be a SavePage download, it may or may not already be
+    // persisted. If a consumer needs a DownloadItem's filename, it should wait
+    // for an OnDownloadUpdated() when the filename is not empty(). When the
+    // history is loaded on startup, this method may be called many (thousands)
+    // of times at once.

[Randy Smith (Not in Mondays), 2012/07/23 18:40:50]

Can you shorten this a bit?  I think we're ok just warning that this may make
visible an item before it's file name has been determined, and telling the
consumer how to figure out if it's in that state.  (+ the final warning about
history loading.)

[benjhayden, 2012/07/23 18:54:22]

Please just give me a string to copy-paste into here.

[Randy Smith (Not in Mondays), 2012/07/23 19:00:06]

Sure, though please confirm with Asanka that what I'm writing is accurate:

--
A DownloadItem was created.  Unlike ModelChanged, this item may be visible
before the filename is determined; in this case the return value of
GetTargetFileName() will be null.  This method may be called an arbitrary number
of times, e.g. when loading history on startup.  As a result, consumers should
avoid doing large amounts of work in OnDownloadCreated().
TODO(<whoever>): When we've fully specified the possible states of the
DownloadItem in download_item.h and removed ModelChanged, we should remove the
caveat above.

[benjhayden, 2012/07/25 16:24:38]

Done.

+    virtual void OnDownloadCreated(
+        DownloadManager* manager, DownloadItem* item) {}
+
     // New or deleted download, observers should query us for the current set
     // of downloads.
-    virtual void ModelChanged(DownloadManager* manager) = 0;
+    virtual void ModelChanged(DownloadManager* manager) {}
 
     // Called when the DownloadManager is being destroyed to prevent Observers
     // from calling back to a stale pointer.
     virtual void ManagerGoingDown(DownloadManager* manager) {}
 
     // Called immediately after the DownloadManager puts up a select file
     // dialog.
     // |id| indicates which download opened the dialog.
     virtual void SelectFileDialogDisplayed(
         DownloadManager* manager, int32 id) {}
@@ skipping 136 matching lines @@
  protected:
   virtual ~DownloadManager() {}
 
  private:
   friend class base::RefCountedThreadSafe<DownloadManager>;
 };
 
 }  // namespace content
 
 #endif  // CONTENT_PUBLIC_BROWSER_DOWNLOAD_MANAGER_H_