Požadavek get-settings

Účel a dopady

Načte blok XML dat uložený pod daným typem nastavení (a případně konkrétním tb-id/user) z databáze. Požadavek nic nemění, jen čte.

Dostupnost, kontext, oprávnění apod.

• Dostupné každému přihlášenému uživateli pro vlastní nastavení.
• Je-li uveden atribut user odkazující na jiného uživatele než volajícího, smí požadavek provést jen uživatel s r_admin nebo r_power; jinak je zamítnut bez ohledu na to, zda cílová položka vůbec existuje.

XML požadavek (syntax + popis)

  <request>
   <get-settings
    type="{string}"
    tb-id="{number}"
    user="{number}"
    envelope="{bool}"
    />
  </request>

Parametry a pravidla (atributy, potomci)

• type - Typ nastavení - Název oblasti nastavení předávaný beze změny uložené proceduře; aplikační vrstva serveru hodnotu nijak neomezuje ani nevaliduje. (typ: string; nepovinný – chybí-li, předává se prázdný řetězec)
• tb-id - Identifikátor položky - Rozlišuje více položek téhož typu nastavení. (typ: number; nepovinný)
• user - Číslo uživatele - Omezuje nastavení na konkrétního uživatele. (typ: number; nepovinný)
• envelope - Vracet v obálce - Řídí tvar úspěšné odpovědi, viz sekce Zpracování a XML odpověď níže. (typ: bool; nepovinný; výchozí: false)

Požadavek nemá žádné potomky.

Závislosti

• Je-li user uveden a je různý od ID volajícího, je požadavek zamítnut, pokud volající nemá r_admin ani r_power.
• Atribut tb-id, který se nepodaří převést na číslo, se chová jako neuvedený.

Příklady požadavku

(Zatím bez ověřeného příkladu.)

Zpracování a vedlejší účinky

• Server zavolá uloženou proceduru pro čtení nastavení s parametry type, tb-id, user. Přesný tvar uloženého obsahu (např. konkrétní kořenový element vráceného XML) určuje databázová procedura.
• envelope="true": úspěšná odpověď se zabalí do <get-settings type="…" …envelope="true"> + syrový uložený obsah + </get-settings>. Hodnota atributu type v obálce je řetězec vrácený uloženou procedurou (obvykle shodný s požadovaným typem), ne literál "ok".
• envelope chybí nebo je "false": úspěšná odpověď neobsahuje žádnou obalovou značku <get-settings> – do odpovědi jde přímo syrový uložený obsah bez obálky.
• Chyba se hlásí vždy stejně, bez ohledu na envelope – viz sekce Chyby a reakce. Klient tak pozná chybu podle toho, že kořenový element odpovědi je get-settings s type="error"; u úspěchu bez envelope kořenový element get-settings vůbec není.

XML odpověď (syntax + popis)

  <response>
   <get-settings
    type="{string}"
    tb-id="{number}"
    user="{number}"
    envelope="true"
    >
    {syrový uložený obsah}
   </get-settings>
  </response>

Bez envelope (úspěch): <response>{syrový uložený obsah}</response> – bez značky get-settings.

Příklady odpovědi

(Zatím bez ověřeného příkladu.)

Chyby a reakce

Chybová odpověď je vždy zabalena do <get-settings type="error" …/>, nezávisle na envelope:

• descr="Nemate opravneni pro pristup k nastavenim jineho uzivatele" – uveden cizí user bez r_admin/r_power.
• state="1" descr="Neexistuje" – uložená procedura nevrátila žádný záznam.
• state="2" descr="Prazdny zaznam" – záznam byl nalezen, ale jeho obsah se nepodařilo přečíst/dekódovat.
• descr="Pri provadeni doslo k chybe" – selhání při volání databáze nebo procedury.

Atribut chybové odpovědi je descr (ne detail).

Související požadavky

• save-settings – uložení stejného typu dat.
• sql-query – další způsob práce s daty ve stejné skupině požadavků.