//
// FILE     : fm_client.js
// TASK     : JavaScript-Funktionen fuer den Aufbau einer
//            Kommunikationsverbindung von einer FloraWeb-Seite zur
//            FloraMap-Anbindung.
// PROJECT  : FloraWeb/FloraMap
// AUTHORS  : ik
// VERSION  : V1.1.0.0
// DATE     : 2001/11/01
// LAST     : 2004/08/16
// COPYRIGHT: (c) 2001-2004 doctronic GmbH & Co. KG
//            Adenauerallee 45-49, D-53332 Bornheim, Germany
//
//-------------------------------------------------------------------------
//
// To do:
//
// History:
//   2004/08/16: V1.1.0.0: Die Kernroutinen unterscheiden nun zwischen
//                         Kommunikationsverbindungen von FloraWeb und
//                         von anderen, externen Quellen.
//                         Ferner koennen nun verschiedene Versionen der
//                         FloraMap-Komponente geoeffnet werden.
//   2001/11/30: V1.0.0.0
//
// Known Bugs:
//
//-------------------------------------------------------------------------
//

//
// Globaler (pfui!) Zwischenspeicher fuer die Funktion innerhalb der
// FloraWeb-Seite, welche die Daten fuer FloraMap bereitstellen wird.
// (s. dtfwOpenFloraMap())
//

// Die Client Funktion
var _dtfwClientFunction = null;

//-------------------------------------------------------------------------

//
// SUMMARY: FloraMap-Fenster oeffnen
// TASK   : Oeffnet das FloraMap-Fenster fuer das Hauptfenster des
//          angegebenen Frames, falls noetig. Wenn kein Frame angegeben
//          wurde, wird das Hauptfenster des aktuellen Frames verwendet.
//          Wurde fuer das jeweilige Hauptfenster bereits ein
//          FloraMap-Fenster geoeffnet und ist dieses noch offen, so
//          wird es nur in den Vordergrund geholt, sofern moeglich.
// PARAMS : sVersion        - FloraMap-Version. (Derzeit werden
//                            lediglich die zugegebenermassen wenig
//                            sprechenden Versionen "alt" und "neu"
//                            unterst{ue}tzt.)
//          bExternalClient - {tt:True}, wenn diese Funktion von einem
//                            *externen* FloraMap-Client aufgerufen
//                            wurde. Andernfalls - zum Beispiel aus
//                            FloraWeb heraus - [tt:False}.
//          oMainFrame      - Optional. Frame, fuer dessen Hauptfenster
//                            das FloraMap-Fenster geoeffnet werden
//                            soll.
// RETURNS: Das FloraMap-Fenster oder {tt:null}.
//
function dtfwOpenFloraMapWindow (sVersion, bExternalClient, oMainFrame)
{
  var oFloraMapStore = null;
  var oFloraMapWindow = null;


  // Es wird zumindest die Version und die Client-Angabe benoetigt.
  if (dtfwOpenFloraMapWindow.arguments.length >= 2)
  {
    // Das Hauptfenster ist optional...
    if (dtfwOpenFloraMapWindow.arguments.length > 2)
    {
      // ... aber diesmal angegeben.
      oFloraMapStore = dtfwGetTopFrame (oMainFrame);
    }

    else
    {
      //
      // Keine Hauptfenster? Dann greifen wir eben auf das
      // Hauptfenster des aktuellen Fensters zurueck.
      //
      oFloraMapStore = dtfwGetTopFrame ();
    };

    // Ist denn nun ein Hauptfenster bekannt?
    if (oFloraMapStore != null)
    {
      var sPath = "";


      //
      // Den fuer die angegebene Version und den angegebenen Client
      // gueltigen Zugriffspfad zusammenschrauben.
      //
      sPath = dtfwGetFloraMapPath (sVersion, bExternalClient);

      //
      // Existiert im fraglichen Hauptfenster bereits ein Verweis
      // auf ein FloraMap-Fenster?
      //
      if (isDefined (typeof(oFloraMapStore._dtfwFloraMap)))
      {
        // Und auch eine zugehoerige Pfadangabe?
        if (isDefined (typeof(oFloraMapStore._dtfwFloraMapPath)))
        {
          // Und stimmt diese mit dem aktuellen Pfad ueberein?
          if (sPath == oFloraMapStore._dtfwFloraMapPath)
          {
            // Dann sieht das doch nach einem guten Fenster aus.
            oFloraMapWindow = oFloraMapStore._dtfwFloraMap;

            // Oder ist es etwa bereits geschlossen?
            if (oFloraMapWindow != null)
            {
              if (oFloraMapWindow.closed)
              {
                // Dann wollen wir es auch nicht mehr!
                oFloraMapWindow = null;
              };
            };
          };
        };
      };

      //
      // Wenn kein bereits passendes FloraMap-Fenster offen war,
      // basteln wir uns eben ein eigenes.
      //
      if (oFloraMapWindow == null)
      {
        oFloraMapWindow = open (sPath,
          "FloraWeb_FloraMap",
          "toolbar=no,location=no,directories=no," +
          "status=no,menubar=no,scrollbars=yes," +
          "resizable=no,width=800,height=720", true);
      };

      // Nun sollte aber eins da sein.
      if (oFloraMapWindow != null)
      {
        //
        // Und dieses bekommt den Fokus. (Sollte es sich bei dem
        // Fenster um ein bereits offenes und im Hintergrund
        // befindliches handeln, wird es dadurch in den Vordergrund
        // geholt.)
        //
        oFloraMapWindow.focus();

        // Fenster und Pfad fuer spaetere Zugriffe speichern.
        oFloraMapStore._dtfwFloraMap = oFloraMapWindow;
        oFloraMapStore._dtfwFloraMapPath = sPath;
      };
    };
  };

  return oFloraMapWindow;
}

//-------------------------------------------------------------------------

//
// SUMMARY: FloraMap-Zugriffspfad ermitteln
// TASK   : Ermittelt zu der angegebenen Version und dem angegebenen Modus
//          den passenden FloraMap-Zugriffspfad
// PARAMS : sVersion        - FloraMap-Version. (Derzeit werden
//                            lediglich die zugegebenermassen wenig
//                            sprechenden Versionen "alt" und "neu"
//                            unterst{ue}tzt.)
//          bExternalClient - {tt:True}, wenn diese Funktion von einem
//                            *externen* FloraMap-Client aufgerufen
//                            wurde. Andernfalls - zum Beispiel aus
//                            FloraWeb heraus - [tt:False}.
// RETURNS: Den passenden FloraMap-Zugriffspfad.
//
function dtfwGetFloraMapPath(sVersion, bExternalClient)
{
  var sPath = "";
  var sVers = "alt";
  var bECln = false;


  // Wurde eine Version angegeben?
  if (dtfwGetFloraMapPath.length >= 1)
  {
    // Dann diese an Stelle des Standardwertes verwenden.
    sVers = sVersion;
  };

  // Liegen Angaben vor, ob es sich um einen externen Client handelt?
  if (dtfwGetFloraMapPath.length >= 2)
  {
    // Herrlich. Dann diese ebenfalls uebernehmen.
    bECln = bExternalClient;
  };

  // Was darf's denn sein? Die neue Version?
  if (sVers == "neu")
  {
    // Von wo aus betrachtet? Von extern?
    if (bECln)
    {
      // Dann bitte wie folgt auf FloraMap zugreifen.
      sPath = "../../cg_floramap/cg_floramap.html"
    }
    else
    {
      // Von intern sieht's etwas anders aus.
      sPath = "cg_floramap/cg_floramap.html";
    };
  }
  else
  {
    // Die alte Version. Okay. Von extern betrachtet?
    if (bECln)
    {
      // Von aussen bitte wie angegeben darauf zugreifen.
      sPath = "../floramap.html";
    }
    else
    {
      // Aus FloraWeb heraus bitte so.
      sPath = "floramap/floramap.html";
    };
  };

  return sPath;
}

//-------------------------------------------------------------------------

//
// SUMMARY: FloraMap-Kommunikation beginnen
// TASK   : Stellt die Kommunikationsverbindung zwischen dem externen
//          oder internen Client und dem FloraMap-Fenster her.
//          Schl{ae}gt der Verbindungsaufbau fehl, *weil* *kein*
//          *FloraMap-Fenster* *ge{oe}ffnet* *werden* *konnte*, zeigt
//          die Funktion bei internen Clients eine Fehlermeldung an.
// PARAMS : sVersion        - FloraMap-Version. (Derzeit werden
//                            lediglich die zugegebenermassen wenig
//                            sprechenden Versionen "alt" und "neu"
//                            unterst{ue}tzt.)
//          bExternalClient - {tt:True}, wenn diese Funktion von einem
//                            *externen* FloraMap-Client aufgerufen
//                            wurde. Andernfalls [tt:False}.
//          oFMClientFunc   - Daten{ue}bermittlungsfunktion des Client.
//          nTry            - Optional. Dieser Parameter wird nur
//                            intern verwendet und gibt die Anzahl der
//                            gescheiterten Verbindungsversuche an.
// RETURNS: {tt:True}, wenn das FloraMap-Fenster ge{oe}ffnet bzw.
//          genutzt werden konnte, andernfalls {tt:False}.
//
//          NOTE: Der R{ue}ckgabewert enth{ae}lt *keinerlei*
//                Informationen {ue}ber die angestrebte
//                Kommunikationsverbindung, da diese evtl. noch
//                aufgebaut wird, w{ae}hrend diese Funktion selbst
//                schon beendet wurde!
//
function dtfwOpenFloraMap (sVersion, bExternalClient,
                           oFMClientFunc, nTry)
{
  var bRetVal;


  bRetVal = false;

  // Wurden ausreichend Parameter angegeben?
  if (dtfwOpenFloraMap.arguments.length >= 3)
  {
    var nMaxTries = 6;
    var nTries = 0;


    //
    // Wir muessen die angegebene Client-Funktion leider global
    // zwischenspeichern, da wir im Fehlerfall mit setTimeout()
    // versuchen, die Kommunikation spaeter aufzubauen.
    //
    _dtfwClientFunction = oFMClientFunc;

    // Laeuft der Zaehler "Anzahl Versuche" schon mit?
    if (dtfwOpenFloraMap.arguments.length >= 4)
    {
      // Dann die Anzahl bisher gescheiterter Versuche uebernehmen.
      nTries = nTry;
    };

    //
    // Wir versuchen es ein paar mal. Wenn's bis dahin nicht geklappt
    // hat, gehen wir von einem echten Fehler aus.
    //
    if (nTries < nMaxTries)
    {
      //
      // FloraMap-Fenster oeffnen bzw. auf ein evtl. bereits
      // geoeffnetes zugreifen.
      //
      var oFloraMapWindow =
        dtfwOpenFloraMapWindow (sVersion,
                                bExternalClient,
                                oFMClientFunc (null));

       // FloraMap-Fenster wie auch immer bekommen?
      if (oFloraMapWindow != null)
      {
        // So, ein FloraMap-Fenster haetten wir schonmal.
        bRetVal = true;

        //
        // Wenn das Fenster gerade erst geoeffnet wurde, ist die
        // graphische Benutzerschnittstelle u.U. noch nicht geladen.
        // Das wird geprueft, indem auf eine in der
        // Benutzerschnittstelle enthaltenen Funktion zugegriffen wird.
        // Die Funktion selbst wird nicht ausgefuehrt, es reicht der
        // Zugriff auf diese Funktion.
        // Dieser Zugriff wird aber erst ab dem ersten Durchgang
        // geprueft (nTries > 0), da das Fenster - sollte es wirklich
        // eben erst erstellt worden sein - noch komplett initialisiert
        // werden muss.
        //
        if ((dtfwClientRPC (oFloraMapWindow,
                            "FM_GUI", "dtfwBeginSPTransfer") != null) &&
            (nTries > 0 ))
        {
          // Alles bestens, der Datentransfer kann beginnen.
          oFMClientFunc (oFloraMapWindow);
        }

        else
        {
          //
          // Der Inhalt des FloraMap-Fensters ist noch nicht
          // vollstaendig geladen. Wir versuchen es in wenigen
          // Augenblicken nochmal.
          //
          nTries++;
          setTimeout ("dtfwOpenFloraMap('" + sVersion + "', " +
                                        bExternalClient +
                                        ", _dtfwClientFunction, " +
                                        nTries + ");",
                      2000);
        };
      }

      else
      {
        //
        // Es konnte auf kein FloraMap-Fenster zugegriffen werden.
        // Wenn es sich um einen internen Client handelt -
        // bspw. FloraWeb - ...
        //
        if (!bExternalClient)
        {
          // ... wird im Fehlerfall noch eine Meldung praesentiert.
          // Andernfalls muss sich der externe Client selbst um einen
          // sprechenden Benutzerhinweis bemuehen.
          //
          dtfwComFailed ();
        };
      };
    }

    else
    {
      //
      // Das war nichts, es konnte nach nMaxTries Versuchen keine
      // Verbindung hergestellt werden.
      //
      dtfwComFailed ();
    };
  };

  return bRetVal;
}

//-------------------------------------------------------------------------

//
// SUMMARY: Kommunikationsfehlermeldung
// TASK   : Stellt im Falle eines Kommunikationsfehlers einen
//          entsprechenden Benutzerhinweis in einem Dialog dar.
//
function dtfwComFailed ()
{
  alert (unescape ("Die%20Verbindung%20zu%20FloraMap%20konnte%20" +
                   "nicht%20innerhalb%20des%20vorgegebenen%20" +
                   "Zeitlimits%20hergestellt%20werden.%20Bitte%20" +
                   "versuchen%20Sie%20es%20erneut%20und%20stellen%20" +
                   "Sie%20sicher%2C%20dass%20Ihr%20Browser%20" +
                   "zus%E4tzliche%20Programmfenster%20nicht%20" +
                   "unterbindet."));
}

//-------------------------------------------------------------------------

//
// SUMMARY: Ferner Funktionsaufruf
// TASK   : Liefert eine Funktion aus einem anderen Bereich.
// PARAMS : oFloraMap - Hauptfenster des Bereiches.
//          oFrame    - Name des Bereiches.
//          oFunction - Name der gewuenschten Funktion innerhalb des
//                      Bereiches.
// RETURNS: Die gewuenschte Funktion oder {tt:null}.
//
function dtfwClientRPC (oFloraMap, oFrame, oFunction)
{
  if (dtfwClientRPC.arguments.length == 3)
  {
    if ((oFloraMap != null) && (oFrame != null) && (oFunction != null))
    {
      var oDestFrame;


      oDestFrame = dtfwFindFrame (oFloraMap, oFrame);

      if (oDestFrame != null)
      {
        if (isDefined (typeof (oDestFrame[oFunction])))
        {
          return oDestFrame[oFunction];
        };
      };
    };
  };

  return null;
};

//-------------------------------------------------------------------------

// Abhaengigkeiten pruefen und Bibliothek registrieren.

if ((typeof (daisyCheckLibrary) != "undefined") &&
    (typeof (daisyCheckLibrary) != "null"))
{
  if (daisyCheckLibrary ("FloraMap_Tools", null))
  {
    daisyRegisterLibrary ("FloraMap_Client", "1.00");
  }

  else
  {
    alert ("ERROR: Unable to resolve dependencies:\n" +
           "fm_client.js requires fm_tools.js!");
  };
}

else
{
  alert ("ERROR: Unable to resolve dependencies:\n" +
         "fm_client.js requires daisytools.js!");
};

//-------------------------------------------------------------------------
//-------------------------------------------------------------------------