FULL-C: snmp 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: odesílání SNMP TRAP zpráv

Zařízení SDS umožňuje odeslat SNMP TRAP zprávu, na základě logiky uvnitř vašeho FULL-C programu.

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

         void snmp_send_trap(unsigned int IP0, unsigned int IP1, unsigned int IP2, unsigned int IP3, unsigned int PDUspecificType, unsigned int tableIndex);
 unsigned int snmp_send_trap_status(void);

Proměnné IP0 až IP3 skládají (po částech) dohromady konkrétní IP adresu (IP0.IP1.IP2.IP3), na kterou je SNMP TRAP odeslán.

Princip

SNMP protokol, který je podporován všemi zařízeními SDS, poskytuje i možnost odeslání tzv. TRAP zprávy ze zařízení SDS. Tato zpráva se typicky odesílá, pokud je splněna nějaká uživatelem určená podmínka (příklad: teplota čidla překročí X stupňů).

Funkce snmp_send_trap má jako parametry cílovou IP adresu, "PDU Specific" hodnotu (toto je namapováno na konkrétní OID) a index do tabulky, pokud je potřebný (pokud OID představuje řádek MIB tabulky).

Každé zařízení SDS podporuje různý seznam TRAP zpráv (závisí to na hardwarové konfiguraci zařízení).

Každá TRAP zpráva obsahuje v sobě tyto položky:

• "Enterprises" - výchozí OID určující zařízení SDS (konstanta) (určuje výrobce)
• "PDU Specific" číslo (někde taky jako "TRAP INDEX") - toto je mapováno na konkrétní OID položky (úplný seznam viz tabulka OID).
• "Table Index" číslo - pro položky v SNMP tabulce, kde je stejný výchozí OID, ale tabulkový index (řádek) se liší
• Identifikace odesílatele (konkrétní zařízení SDS - tj. IP adresa)
• Aktuální hodnotu (např. teplota čidla) - tato hodnota je vyplněna přímo zařízením SDS, v okamžiku odeslání TRAPu

Aktuální hodnota je zvolena podle vybraného OID (tj. OID které je v TRAP zprávě), a formát aktuální hodnoty odpovídá přesně tomu, co by vrátilo SNMP GET.

Tyto položky jsou vyhodnoceny na straně příjemce, a následně je vyvolána specifická akce (to už je na vás).

Postup

Postup odeslání TRAP zprávy:

1. FULL-C program vyhodnotí podmínky a rozhodne se odeslat TRAP zprávu
2. FULL-C program zjistí, zda-li není právě odesílána jiná TRAP zpráva (pomocí snmp_send_trap_status), pokud ano tak se musí čekat...
3. FULL-C program zavolá funkci snmp_send_trap() přičemž správně vyplní parametry funkce (cílovou IP adresu a TRAP INDEX)
4. SDS sestaví TRAP zprávu, přičemž podle vybraného "PDU Specific" a "Table Index", do zprávy vyplní hodnotu platnou v tomto okamžiku
5. SDS se pokusí odeslat TRAP zprávu (pokud není ARP záznam, odeslání je odloženo, a místo toho se pošle ARP dotaz)
6. Příjemce přijme TRAP zprávu a zpracuje ji.
7. FULL-C program kontroluje stav (povedlo / nepovedlo) a případně opakuje odesílání

Hodnoty

Všechny TRAP položky jsou přímo svázány s aktuální hodnotou, kterou lzezískat SNMP dotazem na konkrétní OID. Např. TRAP pro stav optického vstupu, v sobě nese hodnotu proměnné, kterou by stejný OID přesně v okamžiku odeslání TRAPu poskytl při svém přečtení (SNMP GET).

Speciální TRAP je položka "sdsCustomVarTrap1", který předává proměnnou, kterou lze předtím nastavit pomocí FULL-C funkce SDS_set_u(140, val); (tzn. zápis na index 140 nastavuje tuto hodnotu). Viz příklad dále.

Příklad

Nejprve je potřeba vědět, jaký vůbec TRAP chceme odeslat.

Pro tento příklad použijeme SDS-BIG a vybereme si teplotu z druhého teplotního čidla připojeného na 1-WIRE sběrnici.

V OID tabulce si najdeme správný řádek:

Full OID	TRAP INDEX	OID Type	MIB Name	Description
....	....	....	....	....
.1.3.6.1.4.1.33283.1.30.6.1.4.2	304 [2]	Integer	sdsOneWireFullValIDX0.2	(RO) First value received from 1-WIRE device.
....	....	....	....	....

A pro sdsOneWireFullValIDX0.2 je odpovídající TRAP INDEX (PDU SPECIFIC) = 304 (hodnota před hranatými závorkami) a TRAP TABLE INDEX = 2 (hodnota v hranatých závorkách). Tyto údaje lze také zjistit z MIB souboru pro dané zařízení.

Program v SDS-C tak zavolá funkci s těmito parametry:

 unsigned int status;

 unsigned int PDUspecificType, tableIndex;
 unsigned char ip0, ip1, ip2, ip3;

 // PRO NÁŠ PŘÍKLAD:
  // ip1, ip2, ip3, ip4 => jednotlivé části IP adresy cílového stroje (TRAP RECEIVER)  tzn.:  ip1.ip2.ip3.ip4 (a.b.c.d)
  // PDU SPECIFIC (TRAP INDEX) = 304
  // TABLE INDEX = 2 
  ip0 = a;
  ip1 = b;
  ip2 = c;
  ip3 = d;
  PDUspecificType = 304;
  tableIndex = 2;
 // ---
 
 // musíme začít s hodnotou 4 (požadavek na opakované odeslání)
 status = 4;

 // smyčka (dokud se to nepovede odeslat)
 while (status == 4)
 {

  // požádáme SDS o odeslání TRAP
  snmp_send_trap(ip0, ip1, ip2, ip3, PDUspecificType , tableIndex );

  // takže . . .
  status = snmp_send_trap_status();
 
  // okamžitý test, zda-li se nesnažíme odeslat TRAP dříve, než se dokončilo předchozí odesílání
  if (status == 5)
  {
    // v tomto případě, stále nebyla odeslána předchozí TRAP zpráva,
    // musíme proto chvíli počkat, a pak to zkusit znovu
 
    wait(250); // tady je škoda čekat, když by program mohl dělat něco jiného - to už je na vás

    // a zkusíme to znovu (lehkým trikem)
    status = 4; continue;
  };
 
  // takže odesílání TRAPu probíhá, takže:
 
  // počkáme, dokud není zpráva odeslána
  while (status == 1)
  { 
   status = snmp_send_trap_status();
   //

   wait(100}; // dělej něco jiného, zatímco se čeká . . .

  }
 
  // v tuto chvíli je 'status' vyplněn finální hodnotou
 
  // pokud místo TRAP odešel ARP, musíme odeslat TRAP znovu
  if (status == 4) continue;
 
  // jiná chyba
  if ((status == 3)||(status == 6))
  {
   // byly použity špatné parametry (3) - zkuste použít správné hodnoty
   // nebo není dostatek paměti (6) - zkuste nějakou uvolnit
 
   printf("Chyba. TRAP neodeslan.\n");
 
   // nepokračuj
   break;
  }

  // jinak zřejmě hotovo:
  printf("Hotovo, výsledek = %d\n", status);
  break;
 
 }
 

Samozřejmě tato funkce se musí zavolat jen jednou pro odeslání TRAPu. Logika chování je už na programátorovi konkrétního FULL-C programu.

Některé položky mají TABLE INDEX = 0. To znamená, že se jedná o SNMP OID položku která není v tabulce, tj. která existuje jen jako jediná pro daný OID. V tomto případě použijte číslo nula na pozici TABLE INDEX.

Příklad pro speciální TRAP (kde lze nastavit proměnnou v SNMP TRAP paketu pomocí FULL-C):

 ...
 // nastav promennou kterou specialni TRAP prenese na server
 SDS_set_u(140, trapValue); 
 // odesli trap [specialni TRAP => 401, 0]
 snmp_send_trap(ip0, ip1, ip2, ip3, 401, 0);

Stavové hodnoty

Program musí použít volání funkce snmp_send_trap_status pro zjištění okamžitého stavu - a to vždy před pokusem odeslat SNMP TRAP (aby se ověřilo, že se odesílání dá provést), a potom lze funkci snmp_send_trap_status využít pro ověření, že se odeslání skutečně povedlo (ne vždy se to povede, z různých důvodů). Pokud program zjistí, že se odeslání nepovedlo, měl by se to pokusit zopakovat znovu za nějakou chvíli.

snmp_send_trap_status()    význam
-------------------------+-----------------------------------------------------------------------
 0                       |  klid, můžete odeslat TRAP
 1                       |  pracuje (pokouší se odeslat TRAP), čekejte
 2                       |  provedeno
 3                       |  byly zadány neplatné parametry - zpráva neodeslána
 4                       |  místo TRAP zprávy byl odeslán ARP, takže musíte zopakovat odesílání
 5                       |  nebylo dokončeno odesílání předchozího TRAP, čekejte a zkuste znovu
 6                       |  nedostatek HEAP paměťi pro odeslání TRAP - zpráva neodeslána

Pokud funkce snmp_send_trap_status vrátí hodnotu 2, je vše jak má být (OK). Jiné hodnoty (mimo 0 a 1) znamenají určitou situaci, kterou je potřeba řešit - ne vždy je to jednoznačně chyba, může stačit chvíli počkat a zkusit TRAP odeslat znovu.