Přejít na obsah
Flexideo
Skip to main content

Požadavek send-message

Účel a dopady​

Odešle zprávu jinému uživateli serveru. Zpráva se uloží do databáze a je-li příjemce právě přihlášen v live režimu, server se ho pokusí okamžitě upozornit; jinak mu zpráva zůstává k vyzvednutí, až se přihlásí.

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

  • Dostupné každému přihlášenému uživateli bez zvláštního oprávnění; odesílatelem je vždy volající uživatel.
  • Podléhá standardnímu transakčnímu zpracování obálky <request> (transactional/přeskočení při odvolané transakci) – viz obálka požadavku.

XML požadavek (syntax + popis)​

  <request>
   <send-message
    to="{number}"
    type="{number}"
    msg="{string}"
    data="{string}"
    avoid-join="{bool}"
    size="{number}"
    >
    {string}
   </send-message>
  </request>

Parametry a pravidla (atributy, potomci)​

  • to - Číslo příjemce - Identifikátor uživatele, kterému se zpráva odešle. (typ: number; povinný – chybí-li nebo jej nelze převést na celé číslo, požadavek skončí chybou)
  • type - Typ zprávy - Libovolné celé číslo typu zprávy; server hodnotu jen ukládá a nijak dál nevaliduje. (typ: number; nepovinný; výchozí: 0; hodnota 1 je konvenčně používána pro zprávy generované serverem při uložení dokumentu s prvkem messenger)
  • msg - Text zprávy - Textový obsah zprávy uložený jako msg v databázi. (typ: string; nepovinný)
  • data - Binární data zprávy (atributem) - Alternativa k tělu elementu; hodnota se do binárních dat zprávy převede přímo (ne hex dekódováním). Je-li uveden, má přednost před size+tělem elementu. (typ: string; nepovinný)
  • avoid-join - Neslučovat zprávy - Předává se do databázové procedury; přesnou logiku slučování zpráv stejného typu určuje uložená procedura. (typ: bool; nepovinný; výchozí: false; server porovnává hodnotu s doslovným řetězcem "true")
  • size - Velikost binárních dat v těle - Použije se jen tehdy, není-li uveden atribut data; udává počet bajtů, na které se hexadecimálně zapsaný text v těle elementu dekóduje. Není-li size ani data uvedeno, tělo elementu se ignoruje. (typ: number; nepovinný)

Tělo elementu obsahuje volitelný text; má význam jen v kombinaci s size (viz výše), jinak se nepoužije.

Závislosti​

  • data (je-li uveden) má přednost před size + tělem elementu.
  • Selže-li rozpoznání číselné hodnoty to, ani číselné hodnoty type (je-li type uveden), požadavek skončí obecnou chybou „ID zpravy se nepodarilo rozpoznat“ – tato chyba tedy nemusí nutně znamenat problém s to, může jít i o neplatné type.
  • Text zprávy (msg) je omezen na přibližně 900 znaků a binární data (data/tělo) na 6144 bajtů; překročení limitu vede k neúspěchu uložení zprávy (viz „Chyby a reakce“).

Příklady požadavku​

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

Zpracování a vedlejší účinky​

  • Server nejprve vyhledá cílového uživatele (to) mezi přihlášenými/známými uživateli; neexistuje-li, nebo nemá povoleno přijímat zprávy (žádný objekt messages), požadavek skončí chybou dřív, než dojde k jakémukoli zápisu.
  • Úspěšné uložení zprávy vygeneruje jedinečné id zprávy a server se pokusí příjemce upozornit, je-li právě přihlášen v live režimu (notifyLiver); výsledek tohoto pokusu se promítne do atributu recipient v odpovědi (online/offline), ale sám o sobě neovlivňuje, zda uložení zprávy uspělo.
  • Selže-li uložení zprávy v databázi (např. kvůli překročení délkových limitů msg/data), server vrátí chybu s vnořenými diagnostickými uzly (viz „Chyby a reakce“) a v odpovědi to neovlivní to, které je i zde vraceno jako platně rozpoznané číslo.

XML odpověď (syntax + popis)​

Úspěšná odpověď:

  <response>
   <send-message
    type="ok"
    id="{number}"
    to="{number}"
    recipient="online|offline"
    />
  </response>

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

  • type - Výsledek - "ok" při úspěchu, "error" při chybě. (typ: enum; povolené hodnoty: ok, error)
  • id - Identifikátor zprávy - Jedinečné číslo nově uložené zprávy. Přítomen jen při úspěchu. (typ: number)
  • to - Příjemce - Při úspěchu a při obou chybách popsaných níže echoem vrací hodnotu to z požadavku (jako číslo); při chybě rozpoznání ID vrací surový nezpracovaný text atributu to z požadavku. (typ: number/string podle větve)
  • recipient - Stav příjemce - Přítomen jen při úspěchu; určuje, zda byl příjemce v okamžiku odeslání přihlášen v live režimu. (typ: enum; povolené hodnoty: online, offline)
  • detail - Popis chyby - Přítomen jen v chybové odpovědi, viz „Chyby a reakce“. (typ: string)

Příklady odpovědi​

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

Chyby a reakce​

  • <send-message type="error" to="{surový text}" detail="ID zpravy se nepodarilo rozpoznat"/> – to (nebo type, je-li uveden) se nepodařilo převést na číslo; sebeuzavírající, bez vnořeného uzlu error.
  • <send-message type="error" to="{to}" detail="Prijemce zpravy nema povolene zasilani zprav"/> – cílový uživatel neexistuje nebo nemá aktivované úložiště zpráv; sebeuzavírající.
  • <send-message type="error" to="{to}" detail="Pri provadeni doslo k chybam"> + vnořené diagnostické uzly error + </send-message> – uložení zprávy do databáze selhalo (např. překročení délkových limitů msg/data); otevírací/uzavírací značka, ne sebeuzavírající. Pozor na text „doslo k chybam“ (množné číslo) – liší se od obvyklejšího jednotného „doslo k chybe“ používaného jinde v protokolu.
  • Výraz pro identifikaci chyb v odpovědi serveru: send-message[@type='error'].

Související požadavky​