Požadavek save-file

Účel a dopady

Uloží jeden soubor (text, XML, binární obsah, nebo převod HTML→PDF) do úložiště serveru, případně jako přílohu čekající na připojení k dokumentu (attach), případně do ZIP archivu (zip). Obsah lze zadat přímo v těle požadavku, nebo (nezdokumentovaná možnost) natáhnout přes HTTP pomocí from-url.

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

Server využívá oprávnění save-file u virtuálních adresářů (resolveVirt); atribut path-log je účinný jen pro r_admin.

XML požadavek (syntax + popis)

  <request>
   <save-file
    path="{string}"
    name="{string}"
    codepage="acp|utf8|utf16|{#number}"
    file-type="txt|xml|pdf|base64|hex|json"
    content-prefix="{string}"
    not-replace="{bool}"
    attach="{bool}"
    zip="{bool}"
    zipped-file="{string}"
    path-log="{bool}"
    from-url="{bool}"
    pdf-source="text|xml"
    title="{string}"
    jsdelay="{number}"
    pdf-engine="{string}"
    pdf-pagesize="{string}"
    pdf-orientation="{string}"
    pdf-margins="{string}"
    userid="{string}"
    password="{string}"
    >
    {obsah souboru, nebo tělo požadavku na from-url}
   </save-file>
  </request>

Parametry a pravidla (atributy, potomci)

V této revizi byly doplněny vlastnosti sdílené s save-files:

• path - Podsložka cílového souboru (bez jména); neuvedena = výchozí úložiště. (typ: string; nepovinný)
• name - Jméno cílového souboru; u attach="true" se z něj použije jen přípona. (typ: string; nepovinný)
• codepage - acp|utf8|utf16|číslo kódové stránky. (typ: string; nepovinný; výchozí: acp)
• file-type - txt|xml|pdf|base64|hex|json; neznámá/chybějící hodnota ponechává výchozí txt. (typ: enum; nepovinný; výchozí: txt) – hodnota json v dosavadní dokumentaci chyběla.
• content-prefix - Text vložený před uložený obsah. (typ: string; nepovinný)
• not-replace - Neumožní přepsat existující soubor stejného jména. (typ: bool; nepovinný; výchozí: false)
• attach - Uloží jako přílohu čekající na připojení k dokumentu (save-document) namísto path. (typ: bool; nepovinný; výchozí: false)
• zip - Uloží do ZIP archivu místo samostatného souboru. (typ: bool; nepovinný; výchozí: false)
• zipped-file - Jméno souboru uvnitř ZIP archivu. (typ: string; nepovinný)
• path-log - Vrátit v odpovědi plnou vyřešenou cestu; účinné jen pro r_admin. (typ: bool; nepovinný; výchozí: false) – v dosavadní dokumentaci chyběl.
• from-url - Obsah souboru se místo těla požadavku natáhne přes HTTP GET podle zbytku uzlu (jako by šlo o send-request); userid/password pak slouží k HTTP autentizaci cíle. (typ: bool; nepovinný; výchozí: false) – v dosavadní dokumentaci zcela chyběl.
• pdf-source, title, jsdelay - Řízení převodu do PDF (file-type="pdf") – stejný význam jako v dosavadní dokumentaci.
• pdf-engine, pdf-pagesize, pdf-orientation, pdf-margins - Další řízení PDF konverze (velikost/orientace stránky, okraje, konverzní engine). (typ: string; nepovinné) – v dosavadní dokumentaci chyběly.
• pdf-base-url, pdf-ignore-cert, pdf-print-background, pdf-mime, pdf-load-timeout, pdf-print-timeout - Další PDF atributy dostupné jen v sestaveních s podporou Qt PDF tisku. (nepovinné) – v dosavadní dokumentaci chyběly.

Potomek: obsah uzlu (text nebo vnořené XML) je vlastní obsah ukládaného souboru, není-li aktivní from-url.

Příklady požadavku

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

Zpracování a vedlejší účinky

Pravidla zpracování odpovídají save-files; rozdíl je jen v tom, že save-file ukládá právě jeden soubor přímo z vlastních atributů, zatímco save-files iteruje přes vnořené uzly file.

XML odpověď (syntax + popis)

  <response>
   <save-file
    type="ok|error"
    path="{string}"
    name="{string}"
    orig-name="{string}"
    descr="{string}"
    >
    <error ... /> ?
   </save-file>
  </response>

Popis obsahu viz sdílený typ save-file-result.

Příklady odpovědi

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

Chyby a reakce

• type="error" descr="Pri provadeni doslo k chybe" – selhání zápisu souboru/přílohy.
• type="error" descr="Nerozpoznany nazev souboru" – nepodařilo se určit cílovou cestu/jméno.
• type="error" descr="Konverze do PDF se nezdarila" – selhání PDF konverze.

Výraz pro identifikaci chyb: save-file[@type='error'] (odkaz na popis detailu: @descr).

Související požadavky

• save-files – uložení více souborů najednou.
• load-files – párový požadavek pro čtení.
• save-document – připojení souboru uloženého s attach="true".