Dokumentace systému Bakaláři - "XML část"

Obsah

  1. Přihlášení
  2. Získávání dat
  3. Dokumentace login.aspx

Přihlášení

Varování: Tato část je nekompletní a potřebuje výrazné úpravy

Přihlašování, stejně jako ostatní akce, probíhá přes URL http://server.tld/login.aspx. Pro každé načtení údajů je potřeba předat zašifrované (vypadá to jako jednosměrný hash) údaje v parametru hx. Jak přesně bude vypadat odpověď určuje parametr pm.

Pro výpočet hashe je nutné znát "sůl". Tu zjistíme tak, že parametrem gethx předáme přihlašovací jméno v plain-textu (tak, jak je).

Příklad - získání soli

Stáhneme XML soubor z http://server/login.aspx?gethx=<jmeno>, měl by vypadat asi takto:

<?xml version="1.0" encoding="windows-1250">
  <results>
    <res>1</res>
    <typ>Z</typ>
    <ikod>(kód použitý pro výpočet hashe)</ikod>
    <salt>(sůl)</salt>
    <pheslo></pheslo>
  </results>

Pokud server jméno nezná, odpoví takto (opravdu pošle nevalidní XML):

<res>2</res></results>

Jakmile máme sůl, můžeme se směle pustit do vypočítávání hashe, ovšem pouze za předpokladu, že víme jak. Hash je v tomto případě Base64 reprezentace SHA-512. Hashe musíme vypočítat hned dva: pro první jako zdroj použijeme řetězec <sůl><interní kód><typ><heslo>, pro druhý hash, který později budeme používat jako parametr hx, bude zdroj *login*<uživatelské jméno>*pwd*<první hash>*sgn*ANDR<aktuální datum ve formátu yyyyMMdd>.

Příklad - ověření hashe

URL tentokrát bude http://server/login.aspx?pm=login&hx=<hash>. Neúspěch:

<?xml version="1.0" encoding="windows-1250">
  <results>
    <result>-1</result>
    <message>Chyba přihlášení</message>
  </results>

... a úspěch:

<?xml version="1.0" encoding="windows-1250">
  <results>
    <result>-1</result>
    <message>LOGIN OK</message>
    <verze>14/15.20150623</verze>
    <jmeno>(Příjmení Jméno, třída)</jmeno>
    <typ>Z</typ>
    <strtyp>Žák</strtyp>
    <skola>(Škola)</skola>
    <moduly>(názvy dostupných modulů oddělené hvězdičkami)</moduly>
  </results>

Ukázka - implementace přihlašování v PHP
function login($server, $name, $password) {
  $tmp = file_get_contents($server . "/login.aspx?gethx=" . $name);
  $xml = simplexml_load_string($tmp);
  if(!isset($xml->res) || $xml->res != "1") {
    return false;
  }

  $type = $xml->typ;
  $salt = $xml->salt;
  $icode = $xml->ikod;

  $hash = base64_encode(hash("sha512", $salt . $icode . $type . $password, true));
  $hash = base64_encode(hash("sha512", "*login*" . $name . "*pwd*" . $hash .
    "*sgn*ANDR" . date("Ymd"), true));

  $tmp = file_get_contents($server . "/login.aspx?pm=login&hx=" . $hash);
  $xml = simplexml_load_string($tmp);
  if(!isset($xml->result) || $xml->result != "01") {
    return false;
  }

  return true;
  // Přihlášení proběhlo úspěšně
}

Získávání dat

Načtení všech dat probíhá podobně jako ověření hashe, pouze změníte hodnotu parametru pm na all nebo jméno sekce, která vás zajímá.

Dostupné sekce:

Pokud má pm hodnotu all, pak má odpověď následující tvar:

<?xml version="1.0" encoding="windows-1250">
  <results>
    <xmlsekce>
      (Obsah získaný pomocí pm=sekce)
    </xmlsekce>
    ...
  </results>
Dále se budu zabývat jen jednotlivými sekcemi

Sekce absence
<?xml version="1.0" encoding="windows-1250">
  <results>
    <result>01</result>
    <message>ABSENCE OK</message>
    <absence>
      <hranice>0,2</hranice>
      <seznam>
        <abs>
          <datum>(Datum ve formátu YYYYMMDD)</datum>
          <den>(Český název dne v týdnu)</den>
          <A>(Nevím, co to je, u mě vždycky 0)</A>
          <AOk>(Počet omluvených hodin)</AOk>
          <AMiss>(Počet neomluvených hodin)</AMiss>
          <ALate>(Počet pozdních příchodů)</ALate>
          <ASoon>(Počet brzkých odchodů)</ASoon>
          <ASchool>(Počet hodin zameškaných kvůli soutěžím atd.)</ASchool>
        </abs>
        ...
      </seznam>
      <zameskanost>
        <nadpis>(Nadpis, dělejte si s ním, co chcete)</nadpis>
        <predmet>
          <nazev>(Plnohodnotný název předmětu)</nazev>
          <oduceno>(Počet hodin, které proběhly nebo počet hodin, které žák navštívil)</oduceno>
          <absbase>(Omluvené + neomluvené hodiny)</absbase>
          <absschool>(Absence kvůli soutěžím)</absschool>
          <abssoon>(Brzké odchody)</abssoon>
          <abslate>(Pozdní příchody)</abslate>
        </predmet>
        ...
      </zameskanost>
    </absence>
  </results>

Sekce akce
<?xml version="1.0" encoding="windows-1250">
  <results>
    <result>01</result>
    <message>AKCE OK</message>
    <akceall>
      <akce>
        <nazev>(Název akce)</nazev>
        <datum>(Datum ve formátu YYYYMMDD)</datum>
        <cas>(Lidsky čitelné časové rozpětí, může být prázdné)</cas>
        <popis>(Popis)</popis>
        <zobrazit>(Číslo <0;2>, nevím, jak přesně funguje)</zobrazit>
      </akce>
      ...
    </akceall>
  </results>

Sekce pololetni
<?xml version="1.0" encoding="windows-1250">
  <results>
    <result>01</result>
    <message>POLO OK</message>
    <tabulka>
      <pololeti>
        <polo>
          <sloupec>(Číslo sloupce)</sloupec>
          <rok>(První rok školního roku)</rok>
          <rocnik>(Číslo ročníku)</rocnik>
          <rocnikslovy>(Jméno ročníku, např. první, druhý...)</rocnikslovy>
          <pololeti>(Číslo pololetí s tečkou na konci)</pololeti>
          <opak>(A/N)</opak>
        </polo>
        ...
      </pololeti>
      <predmety>
        <predmet>
          <nazev>(Název předmětu)</nazev>
          <znamky>
            <znamka>
              <sloupec>(Číslo pololetí)</sloupec>
              <value>(Známka)</value>
              <opak>(A/N)</opak>
            </znamka>
            ...
          </znamky>
        </predmet>
        ...
      </predmety>
    </tabulka>
    <souhrny>
      <souhrn>
        <rocnik>(Číslo ročníku)</rocnik>
        <rocnikslovy>(Název ročníku)</rocnikslovy>
        <pololeti>(Číslo pololetí s tečkou na konci)</pololeti>
        <prumer>(Průměr známek)</prumer>
        <zameskane>(Počet omluvených hodin)</zameskane>
        <neomluvene>(Počet neomluvených hodin)</neomluvene>
        <hodnoceni>(Slovní hodnocení)</hodnoceni>
        <vysvedceni>(Datum ve formátu YYYYMMDD)</vysvedceni>
        <opak>(A/N)</opak>
      </souhrn>
      ...
    </souhrny>
    <vychovna>
      <vychovne>
        <rok>(Školní rok, např. 2014/15)</rok>
        <pololeti>(Číslo pololetí, bez tečky na konci)</pololeti>
        <nazev>(Název, titulek...)</nazev>
        <datum>(Datum ve formátu YYYYMMDD)</datum>
        <text>(Popis)</text>
      </vychovne>
      ...
    </vychovna>
  </results>

Sekce predmety
<?xml version="1.0" encoding="windows-1250">
  <results>
    <result>01</result>
    <message>PREDMETY OK</message>
    <predmety>
      <predmet>
        <nazev>(Název předmětu)</nazev>
        <zkratka>(Zkratka předmětu)</zkratka>
        <ucitel>(Jméno učitele)</ucitel>
        <zkratkauc>(Zkratka jména učitele)</zkratkauc>
        <mailuc>(Email učitele)</mailuc>
      </predmet>
      ...
    </predmety>
  </results>

Sekce predvidac
<?xml version="1.0" encoding="windows-1250">
  <results>
    <result>01</result>
    <message>PREDVIDAC OK</message>
    <typypru>
      <typ>
        <nazev>(Název hodnoty známky)</nazev>
        <zkratka>(Zkratka hodnoty známky)</zkratka>
        <vaha>(Hodnota/váha známky)</vaha>
      </typ>
      ...
    </typypru>
  </results>

Sekce rozvrhakt
Upozornění: k této sekci se dostanete pomocí hodnoty rozvrh
Varování: tato část je nekompletní a potřebuje výrazné úpravy
<?xml version="1.0" encoding="windows-1250">
  <results>
    <result>01</result>
    <message>ROZVRH OK</message>
    <rozvrh>
      <typ>akt</typ>
      <kodcyklu>(Kód cyklu)</kodcyklu>
      <zkratkacyklu>(Zkratka cyklu)</zkratkacyklu>
      <nazevcyklu>(Název cyklu)</nazevcyklu>
      <hodiny>
        <pocet>(Počet hodin)</pocet>
        <hod>
          <caption>(Označení hodiny)</caption>
          <begintime>(Čas ve formátu H:MM)</begintime>
          <endtime>(Čas ve formátu H:MM)</endtime>
        </hod>
        ...
      </hodiny>
      <dny>
        <pocet>(Počet dní)</pocet>
        <den>
          <zkratka>(Zkratka dne)</zkratka>
          <datum>(Datum ve formátu YYYYMMDD)</datum>
          <hodiny>
            <hod>
              <typ>(X, H nebo A)</typ>
              (A minimálně 17 (!) dalších nepovinných tagů...)
            </hod>
            ...
          </hodiny>
          ...
        </den>
        ...
      </dny>
    </rozvrh>
  </results>

Sekce rozvrhnext
Varování: tato část je nekompletní a potřebuje výrazné úpravy

Nevím, jak se k této sekci dostat


Sekce rozvrhperm
Varování: tato část je nekompletní a potřebuje výrazné úpravy

Nevím, jak se k této sekci dostat


Sekce suplovani
<?xml version="1.0" encoding="windows-1250">
  <results>
    <result>01</result>
    <message>SUPLOVANI OK</message>
    <suplovani>
      <den>
        <oznaceni>(Označení dne)</oznaceni>
        <seznam>
          <supl>
            <text>(Popis změny)</text>
          </supl>
          ...
        </seznam>
      </den>
      ...
    </suplovani>
  </results>

Sekce ukoly
<?xml version="1.0" encoding="windows-1250">
  <results>
    <result>01</result>
    <message>UKOLY OK</message>
    <ukoly>
      <ukol>
        <predmet>(Název předmětu, do kterého úkol patří)</predmet>
        <zkratka>(Zkratka předmětu)</zkratka>
        <zadano>(Datum ve formátu YYYYMMDDHHMM)</zadano>
        <nakdy>(Datum ve formátu YYYYMMDDHHMM)</nakdy>
        <popis>(Popis)</popis>
        <status>(Stav úkolu, např. proběhlo)</status>
        <typ>(Číslo. Nevím, jak přesně funguje)</typ>
        <id>(Zřejmě ID úkolu)</id>
      </ukol>
      ...
    </ukoly>
  </results>

Sekce znamky
<?xml version="1.0" encoding="windows-1250">
  <results>
    <result>01</result>
    <message>ZNAMKY OK</message>
    <predmety>
      <predmet>
        <nazev>(Název předmětu)</nazev>
        <zkratka>(Zkratka předmětu)</zkratka>
        <prumer>(Průměr, který se má zobrazit uživateli)</prumer>
        <numprumer>(Přesný průměr)</numprumer>
        <prepocet>(?)</prepocet>
        <bodytoznm>(?)</bodytoznm>
        <ctvrt>(Čtvrtletní známka)</ctvrt>
        <znamky>
          <znamka>
            <pred>(Zkratka předmětu)</pred>
            <maxb>(Maximum bodů)</maxb>
            <znamka>(Známka, znak - lze nahradit .5)</znamka>
            <zn>(?)</zn>
            <bd>(?, pravděpodobně počet získaných bodů)</bd>
            <datum>(Datum ve formátu YYMMDD)</datum>
            <udeleno>(Datum a čas ve formátu YYMMDDHHMM)</udeleno>
            <vaha>(Váha známky)</vaha>
            <caption>(Popis)</caption>
            <poznamka>(Poznámka)</poznamka>
            <typ>(?)</typ>
            <ozn>(?)</ozn>
          </znamka>
          ...
        </znamky>
      </predmet>
      ...
    </predmety>
  </results>