From 0fb4954f1939012430938e9727cd3f3637b82aec Mon Sep 17 00:00:00 2001
From: Dick Hollenbeck <dick@softplc.com>
Date: Fri, 2 Dec 2011 10:57:44 -0600
Subject: [PATCH] fix comments, add IO_MGR::Save()

---
 pcbnew/io_mgr.cpp | 25 ++++++++++++++++++++++---
 pcbnew/io_mgr.h   | 17 +++++++++++++----
 2 files changed, 35 insertions(+), 7 deletions(-)

diff --git a/pcbnew/io_mgr.cpp b/pcbnew/io_mgr.cpp
index 3471d04c1b..063d3cfcc1 100644
--- a/pcbnew/io_mgr.cpp
+++ b/pcbnew/io_mgr.cpp
@@ -100,6 +100,25 @@ BOARD* IO_MGR::Load( PCB_FILE_T aFileType, const wxString& aFileName,
 }
 
 
+void IO_MGR::Save( PCB_FILE_T aFileType, const wxString& aFileName, BOARD* aBoard, PROPERTIES* aProperties )
+{
+    // release the PLUGIN even if an exception is thrown.
+    PLUGIN::RELEASER pi = PluginFind( aFileType );
+
+    if( (PLUGIN*) pi )  // test pi->plugin
+    {
+        pi->Save( aFileName, aBoard, aProperties );  // virtual
+        return;
+    }
+
+    wxString msg;
+
+    msg.Printf( _( "Plugin type '%s' is not found." ), ShowType( aFileType ).GetData() );
+
+    THROW_IO_ERROR( msg );
+}
+
+
 BOARD* PLUGIN::Load( const wxString& aFileName, BOARD* aAppendToMe, PROPERTIES* aProperties )
 {
     // not pure virtual so that plugins only have to implement subset of the PLUGIN interface,
@@ -107,21 +126,21 @@ BOARD* PLUGIN::Load( const wxString& aFileName, BOARD* aAppendToMe, PROPERTIES*
 
     wxString msg;
 
-    msg.Printf( _( "Plugin %s does not implement the BOARD Load() function.\n" ),
+    msg.Printf( _( "Plugin %s does not implement the BOARD Load() function." ),
             PluginName().GetData() );
 
     THROW_IO_ERROR( msg );
 }
 
 
-void PLUGIN::Save( const wxString* aFileName, BOARD* aBoard, PROPERTIES* aProperties )
+void PLUGIN::Save( const wxString& aFileName, BOARD* aBoard, PROPERTIES* aProperties )
 {
     // not pure virtual so that plugins only have to implement subset of the PLUGIN interface,
     // e.g. Load() or Save() but not both.
 
     wxString msg;
 
-    msg.Printf( _( "Plugin %s does not implement the BOARD Save() function.\n" ),
+    msg.Printf( _( "Plugin %s does not implement the BOARD Save() function." ),
             PluginName().GetData() );
 
     THROW_IO_ERROR( msg );
diff --git a/pcbnew/io_mgr.h b/pcbnew/io_mgr.h
index 93f845f7ad..3c20ed4b49 100644
--- a/pcbnew/io_mgr.h
+++ b/pcbnew/io_mgr.h
@@ -116,21 +116,27 @@ public:
 
     /**
      * Function Save
-     * will write a full aBoard to a storage file in a format that this
+     * will write either a full aBoard to a storage file in a format that this
      * implementation knows about, or it can be used to write a portion of
      * aBoard to a special kind of export file.
      *
      * @param aFileName is the name of a file to save to on disk.
      * @param aBoard is the BOARD document (data tree) to save or export to disk.
      *
+     * @param aBoard is the in memory document tree from which to extract information
+     *  when writing to \a aFileName.  The caller continues to own the BOARD, and
+     *  the plugin should refrain from modifying the BOARD if possible.
+     *
      * @param aProperties is an associative array that can be used to tell the
      *  saver how to save the file, because it can take any number of
      *  additional named tuning arguments that the plugin is known to support.
+     *  The caller continues to own this object (plugin may not delete it), and
+     *  plugins should expect it to be optionally NULL.
      *
      * @throw IO_ERROR if there is a problem saving or exporting.
      */
     static void Save( PCB_FILE_T aFileType, const wxString& aFileName,
-            PROPERTIES* aProperties = NULL );
+            BOARD* aBoard, PROPERTIES* aProperties = NULL );
 };
 
 
@@ -237,7 +243,10 @@ public:
      * aBoard to a special kind of export file.
      *
      * @param aFileName is the name of a file to save to on disk.
-     * @param aBoard is the BOARD document (data tree) to save or export to disk.
+     *
+     * @param aBoard is the class BOARD in memory document tree from which to
+     *  extract information when writing to \a aFileName.  The caller continues to
+     *  own the BOARD, and the plugin should refrain from modifying the BOARD if possible.
      *
      * @param aProperties is an associative array that can be used to tell the
      *  saver how to save the file, because it can take any number of
@@ -247,7 +256,7 @@ public:
      *
      * @throw IO_ERROR if there is a problem saving or exporting.
      */
-    virtual void Save( const wxString* aFileName, BOARD* aBoard,
+    virtual void Save( const wxString& aFileName, BOARD* aBoard,
                     PROPERTIES* aProperties = NULL );
 
     //-----</PUBLIC PLUGIN API>------------------------------------------------