FULL-C: smtp client functions

Tato stránka popisuje programovací jazyk FULL-C, který je dostupný na vybraných zařízeních SDS. 
Některá zařízení používají SDS-C, pro který máme návody jinde na této WiKi.

Síťové funkce: email

Zařízení SDS umožňuje odeslat email, na určenou adresu, prostřednictvím SMTP serveru. Obsah emailu, nadpis (subject) a cílovou emailovou adresu určuje FULL-C program.

Za tímto účelem jsou k dispozici tyto dvě funkce:

         void smtp_send(char * TargetEmailAddress, char * EmailSubject, char * TextContent);
 unsigned int smtp_send_status(void);

Princip

SDS se připojí k SMTP serveru a pošlu mu email, vytvořený z parametrů funkce smtp_send().

Odesílání emailu chvíli trvá a přitom může dojít i k chybě nebo odmítnutí SMTP serverem. FULL-C program pravidelně kontroluje stav voláním smtp_send_status() funkce.

Příklad

V tomto příkladu odesílá SDS email.

void main(void)
{
 unsigned int status;

 printf("sending email...\n");
 
 smtp_send("test@email.cz", "Test Subject", "This is the first line.\nAnd this is the second line.");
 
 // pockame na dokonceni
 status = smtp_send_status(); 
 while (status == 277)
 {
   status = smtp_send_status();
 }
 
 // zpracujeme vysledek
 if (status == 256)
 {
   // uspech
   printf("DONE OK \n");
 } else
 {
   // email nebyl odeslan, chyba
   printf("ERROR: %u \n", status);
 }

}

Stavové hodnoty

Program musí použít volání funkce smtp_send_status() pro zjištění okamžitého stavu.

 smtp_send_status()         význam
-------------------------+-----------------------------------------------------------------------
 0                       |  klid, žádná akce nebyla zahájena
 256                     |  hotovo OK (email doručen na SMTP server)
 257                     |  timeout (email neodeslán, server nereaguje)
 258                     |  SMTP server není připraven komunikovat (email neodeslán)
 259                     |  chyba v "HELO" odpovědi (pokud se používá právě "HELO") (email neodeslán)
 260                     |  SMTP sender odmítl adresu odesílatele jako neplatnou (email neodeslán)
 261                     |  SMTP sender odmítl adresu příjemce jako neplatnou (email neodeslán)
 262                     |  SMTP chyba "554 Relay Access Denied" (server odmítá přeposlat email - antispam ochrana) (email neodeslán)
 263                     |  SMTP server odmítá přijmout text těla emailu (email neodeslán)
 264                     |  SMTP server nepřijal email (not queued) (email neodeslán)
 265                     |  SMTP server nepodporuje "AUTH LOGIN" příkaz (email neodeslán)
 266                     |  SMTP server odmítl uživatelské jméno pro přihlášení (email neodeslán)
 267                     |  SMTP server odmítl heslo pro přihlášení (email neodeslán)
 268                     |  SMTP server hlásí chybu "550 Invalid Recipient" (email neodeslán)
 269                     |  nelze otevřít spojení na TCP server (email neodeslán)
 270                     |  pokoušíte se o odeslání dalšího emailu, zatímco předchozí činnost ještě není dokončena (nový email neodeslán)
 271                     |  SMTP chyba "501 Wrong Syntax" (email neodeslán)
 272                     |  není k dispozici FULL-C heap paměť pro sestavení a odeslání emailu (email neodeslán)
 273                     |  v tuto chvíli nemá zařízení SDS platnou vlastní IP adresu (email neodeslán)
 274                     |  SMTP chyba "421 You Have Been Temporarily Banned" (antispam ochrana na serveru) (email neodeslán)
 275                     |  zařízení SDS nemá Ethernetové připojení (odpojený kabel, vypnutý switch, ...) (email neodeslán)
 276                     |  funkce byla zavolána s neplatnými parametry (email neodeslán)
 277                     |  čekejte, pracuji (právě se SDS pokouší odeslat email)

POZOR

Dokud není email úplně odeslán, musí být všechny tři texty stále platné a k dispozici. Toto je příčinou častého problému, kdy se jednotlivé vstupy do funkce alokují na lokálním stacku, a volající funkce se opustí dříve než je email skutečně odeslán (nepočká se na výsledek smtp_send_status() viz příklad). Potom se např. odešle email s prázdným obsahem (body) atd. - příčinu je potřeba nejdříve hledat ve vlastním full-c programu.