Požadavek get-messages

Účel a dopady

Vrátí zprávy zaslané přihlášenému uživateli. Ve výchozím režimu jde o dosud nepotvrzené/čekající zprávy z paměti serveru (s volitelným čekáním na nové doručení); s atributem confirmed="true" jde naopak o dotaz na již potvrzené (historické) zprávy uložené v databázi, filtrovatelné podle typu a data. Ve výchozím režimu může požadavek nastavit i stav avoid-wait, který ukončí všechna právě probíhající čekání daného uživatele napříč jeho session.

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

• Dostupné každému přihlášenému uživateli pro jeho vlastní zprávy; žádná zvláštní role není vyžadována.
• Vyžaduje, stejně jako většina požadavků, dokončenou (ne „justlogin“) session – při rozjednaném dvoufázovém přihlášení (SMS, viz login) je i tento požadavek zamítnut chybou „Vase prihlaseni nebylo dokonceno“. Na rozdíl od staré dokumentace tedy nejde o požadavek zcela nezávislý na stavu přihlášení – nevyžaduje jen to, aby v rámci nové session předcházel explicitní <login>.

XML požadavek (syntax + popis)

  <request>
   <get-messages
    confirmed="{bool}"
    already="{bool}"
    wait="{number}"
    avoid-wait="{bool}"
    type="{number}"
    from="{datetime}"
    to="{datetime}"
    />
  </request>

Parametry a pravidla (atributy, potomci)

Požadavek nemá potomky. Chování se zásadně liší podle atributu confirmed.

Režim čekajících zpráv (confirmed neuveden nebo různý od "true")

• already - Opětovné získání - Zahrne do odpovědi i zprávy, které již byly jednou doručeny, ale dosud nejsou potvrzené. Jediná hodnota, která toto chování vypne, je přesně "false" – cokoli jiného (včetně neuvedení atributu) se chová jako true. (typ: bool; nepovinný; výchozí: true)
• wait - Čekání na zprávu (sekundy) - Je-li atribut uveden, požadavek čeká na doručení nové zprávy. Hodnota 0 znamená čekat neomezeně dlouho; jinak jde o horní limit čekání v sekundách. Není-li atribut uveden vůbec, server nečeká a odpověď vrátí okamžitě. (typ: number; nepovinný)
• avoid-wait - Zákaz čekání - "true" okamžitě ukončí všechna aktuálně probíhající čekání (i z jiných session) téhož uživatele; jiná hodnota (i neuvedení atributu) tuto akci neprovede. Následné volání get-messages se řídí vlastním atributem avoid-wait (chová se opět normálně). (typ: bool; nepovinný; výchozí: false)

Režim potvrzených zpráv (confirmed="true")

• type - Filtr typu - Omezí výsledek na zprávy s tímto číselným typem. Neplatná/chybějící hodnota filtr vynechá. (typ: number; nepovinný)
• from - Filtr od data - Omezí výsledek na zprávy odeslané od tohoto data/času. Neplatná/chybějící hodnota filtr vynechá. (typ: datetime; nepovinný)
• to - Filtr do data - Je-li atribut uveden, server jako hodnotu filtru ve skutečnosti znovu použije atribut type, nikoli hodnotu to. Filtr „do data“ je tak za současného stavu kódu prakticky nefunkční – buď se vůbec nenastaví, nebo se pokusí interpretovat obsah type jako datum/čas. (typ: datetime; nepovinný; chování viz poznámka)
• already, wait, avoid-wait se v tomto režimu nečtou a nemají žádný efekt.

Příklady požadavku

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

Zpracování a vedlejší účinky

• Režim čekajících zpráv: je-li wait uveden, server periodicky kontroluje frontu zpráv uživatele (a připojení klienta) až do vypršení limitu, doručení nové zprávy, nebo zásahu avoid-wait; není-li wait uveden, vrátí okamžitě aktuální stav fronty. Vrácené zprávy se interně označí časem příštího možného opětovného doručení, takže se – nejsou-li potvrzeny (typicky požadavkem confirm-message) – po určité době znovu nabídnou volání s already=true.
• Režim potvrzených zpráv: server zavolá uloženou proceduru pro potvrzené zprávy (parametry type/from/to, viz omezení výše) a vrátí odpovídající uzly message přímo z databáze; nic se přitom neoznačuje k opětovnému doručení.
• Zobrazované jméno odesílatele (from-name) se dohledává z aktuálního registru uživatelů, ale jen v režimu potvrzených zpráv – v režimu čekajících zpráv se tento vyhledávací krok neprovede, takže from-name je tam vždy prázdné.
• Časové údaje submited_*/delivered_* se vrací zdvojeně – jednou v UTC (..._utc_dt/..._utc_tm), jednou přepočtené do lokálního času serveru (..._dt/..._tm), obojí s milisekundovou přesností (HH:MM:SS:mmm).

XML odpověď (syntax + popis)

  <response>
   <messages>
    <message
     id="{number}"
     from="{number}"
     from-name="{string}"
     submited_utc_dt="{date}"
     submited_utc_tm="{time}"
     submited_dt="{date}"
     submited_tm="{time}"
     type="{number}"
     avoid-join="{bool}"
     already="{bool}"
     delivered_utc_dt="{date}"
     delivered_utc_tm="{time}"
     delivered_dt="{date}"
     delivered_tm="{time}"
     msg="{string}"
     size="{number}"
     >
     {string}
    </message> *
    <error ... /> *
   </messages>
  </response>

Parametry a pravidla (atributy, potomci) – odpověď

Odpověď messages sama nemá žádné atributy (potvrzuje se stará dokumentace). Obsahuje nula a více uzlů message a – jen v režimu confirmed="true" při selhání databáze – i vnořené diagnostické uzly error, viz „Chyby a reakce“.

• id - Identifikátor zprávy - Jedinečné číslo zprávy. (typ: number)
• from - Odesílatel - Číslo (id) uživatele, který zprávu odeslal. (typ: number)
• from-name - Jméno odesílatele - Zobrazované jméno odesílatele. V režimu čekajících zpráv vždy prázdné (viz „Zpracování“); v režimu potvrzených zpráv vyplněné, je-li odesílatel dohledatelný. (typ: string)
• submited_utc_dt / submited_utc_tm - Datum/čas odeslání (UTC) - čas má tvar HH:MM:SS:mmm (s milisekundami). (typ: date/time)
• submited_dt / submited_tm - Datum/čas odeslání (lokální čas serveru) - stejný formát jako výše. (typ: date/time)
• type - Typ zprávy - Číselné rozlišení zvolené odesilatelem; zprávy se stejným typem mohou být slučovány. (typ: number)
• avoid-join - Zákaz slučování - Zda odesílatel zprávu označil jako neslučitelnou s ostatními. (typ: bool)
• already - Opětovné doručení - "true" u zprávy, která již byla dříve doručena a čeká na potvrzení (opětovné doručení); "false" při prvním doručení. Nejde o totéž co požadavkový atribut already – jde o vlastnost samotné zprávy, ne o parametr dotazu (na rozdíl od dojmu, který budí stará dokumentace). (typ: bool)
• delivered_utc_dt / delivered_utc_tm / delivered_dt / delivered_tm - Datum/čas doručení - Přítomné jen v režimu potvrzených zpráv, a jen eviduje-li databáze čas doručení. (typ: date/time)
• msg - Text zprávy - Přítomen jen obsahuje-li zpráva textovou část. (typ: string)
• size - Velikost binární části - Skutečná velikost binárních dat; obsah uzlu message pak nese tato data hexadecimálně kódovaná (dvojnásobná délka oproti size). Přítomen jen obsahuje-li zpráva binární část. (typ: number)

Příklady odpovědi

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

Chyby a reakce

• Režim čekajících zpráv se nikdy nevrací jako chyba – potvrzuje se stará dokumentace: odpověď je vždy <messages> s nula a více <message>, bez chybového stavu.
• Režim potvrzených zpráv (confirmed="true") chybu vrátit může – na rozdíl od staré dokumentace. Selže-li načtení potvrzených zpráv, server do těla <messages> vloží diagnostické uzly error bez jakéhokoli doprovodného stavového atributu na <messages>.
• Výraz pro identifikaci chyb v odpovědi serveru: messages[error].

Související požadavky

• confirm-message – potvrzení přijetí zprávy vrácené tímto požadavkem.
• send-message – odeslání zprávy, kterou tento požadavek vrací.