The Management API

1. The Management API What it is (and isn’t) Defining variables Accessing “singleton” variables Accessing Table variables

2. What it is… An API that allows you to… • Create a list of all management variables such as those used in SNMP on the system • Protect management variables from concurrent access by multiple threads • Read and write management variables • Register functions that will be called when a variable is written to • Check values that are written to variables (to make sure the values are within the valid ranges)

3. What it’s not… • An prepackaged SNMP Management station parallel to the SNMP Agent

4. Advantages • Variables are centralized • A common interface • Easy access to variables • Location is transparent • Easy integration with extensions • Advanced Web Server • SNMP Agent

5. SNMPBrowser Web Browser NET+OS Application Overview • Access Data • State • Connections • System up time • Location • Physical Address • Jobs • Statistics Netsilicon Management Interface

6. Variable Properties typedef struct { MAN_ID_TYPEid void *varPointer; int isFunction; int size; int type int dimensions; int numberDimensions; MAN_SEMAPHORE*semaphores; int numberSemaphores; void *rangeFn; void *rangeInfo manTableInfoType*tableInfo; void *callbackFn; } manVarType; • Define a variable • ID • Type • Size • Dimension • Memory • Range • Semaphore • Callback Function • Table

7. Variable Properties: id • String value • Unlimited length (memory constraint) char *snmpInPktsVar = “1.3.6.1.2.1.6.1” char *serlNoVar = “SerialNumber”

8. var->size = sizeof (INT32) var->varPointer = malloc (size) var->size = sizeof (INT8) memSize = var->size * var->dimensions[0] var->varPointer = malloc (memSize) Variable Properties: varPointer/isFunction = 0 • Memory Address • Causes allocation of a new variable of the specified type • isFunction set to variable INT8 ipAddress[4] var->type = MAN_INT8 var->isFunction = MAN_VAR var->dimensions = {4} var->numberDimensions = 1 INT32 inMsgCount; var->type = MAN_INT32 var->isFunction = MAN_VAR

9. inMsgCountAccessFn (var, buffer, indices, isWrite, timeout) static INT32 inMsgCount = 0; memcpy (buffer, inMsgCount, sizeof (INT32)); Variable Properties: varPointer/isFunction = MAN_FN • Function Address • Specifies function to access existing variable • Defined asmanAccessFunctionTypeor manTableAccessFunctionType • isFunction set as MAN_FN manAccessFunctionTypeinMsgCountAccessFn ( ); varPointer = inMsgCountAccessFn ; isFunction = MAN_FN;

10. Variable Properties: size • Define the variable size • Dependent on variable type • Automatically calculated internally when submitted • Requires manual setting for MAN_UNKNOWN INT32 inMsgCount; size = NULL struct FOO entry ; type = MAN_UNKNOWN size = sizeof (struct FOO); size = sizeof (INT32) = 4

11. Character MAN_CHAR Integer MAN_INT8 MAN_INT16 MAN_INT32 MAN_INT64 Word MAN_WORD8 MAN_WORD16 MAN_WORD32 MAN_WORD64 Variable Properties: type • Float (4 bytes) (unsupported) • MAN_FLOAT • Double (8 bytes) (unsupported) • MAN_DOUBLE • Unknown (structure) • MAN_UNKNOWN • Octet String • MAN_OCTET_STRING • Table • MAN_SNMP_TABLE

12. Variable Properties: dimension • Number of dimensions • Maximum is 10 • Coordinates for each dimension INT8 ipAddress[4] numberDimensions = 1 dimensions[] = {4} INT8 port[4][2] numberDimensions = 2 dimensions[] = {4, 2}

13. Variable Properties: semaphores • Controls access to variable • Prevents collision when accessed by multiple applications • Lock before variable is accessed • Unlock after variable is accessed • Supports multiple semaphores • FIFO order when locking • LIFO order when unlocking Access Variable Sem 1 Sem 2 Sem 3 Sem 4 Sem 5

14. Variable Properties: rangeFn • User defined function • MAN_ERROR_TYPE(*manTestFn) (manVarType *var, void *buffer) • Validate values • Legal states • Control boundary of variable • Minimum and maximum range • Called when before variable is updated • Return MAN_SUCCESS to allow update

15. Variable Properties: callbackFn • User defined function • MAN_ERROR_TYPE (*manCallbackFunctionType) (MAN_ID_TYPE *var, void *buffer, int buflen, void* fnd) • Notification • variable is changed • Called after variable is updated • Singleton variable • Table • Each entry in dimensional variable • Supports multiple callbacks, executed in the order registered *var->varPointer = 5; (callbackFn) (var)

16. Table Properties • Field information • Size • Type • Index information • Compare index fields • Data information typedef struct { int numberFields; int *fieldType; int *fieldSize; void *indexFn; void *indexInfo; } manTableInfoType;

17. Example Variable Table tcpConnState tcpConnLocalAddr tcpConnLocalPort tcpConnRemAddr tcpConnRemPort Listen (2) 10.52.32.20 10 10.52.32.80 10 Established (5) 10.52.32.35 15 10.52.32.65 15 Closed (1) 10.52.32.52 5 10.52.32.25 5 Established (5) 10.52.32.78 12 10.52.32.8 12

18. 1 * sizeof (INT32) 4 * sizeof (WORD8) 1 * sizeof (INT32) MAN_INT32 4 * sizeof (WORD8) MAN_WORD8 1 * sizeof (INT32) MAN_INT32 MAN_WORD8 MAN_INT32 Table Properties: fieldType/fieldSize • Structures are transparent to the APIs • Number of fields in each entry • List of types for each field • List of sizes for each field typedef struct { int numberFields; int *fieldType; int *fieldSize; void *indexFn; void *indexInfo; } manTableInfoType; Fields fieldType fieldSize fieldType tcpConnState tcpConnLocalAddr fieldSize tcpConnLocalPort tcpConnRemAddr tcpConnRemPort

19. Table Properties: indexFn • User defined function used to locate entry in table • Current row is compared with index passed by application • Return results • -1 if index of entry is less than index in current row • 0 if index of entry is equal to index in current row • 1 if index of entry is greater than index in current row int (*manIndexFunctionType) (void *index, void *row, void *indexInfo) { tcpConnTableIndexType *index = indexInfo; tcpConnTableType *currentRow = (tcpConnTableType*) row; value = memcmp (currentRow->tcpConnLocalPort, index->tcpConnLocalPort, 4) return (value); }

20. Management API Capabilities • Register a list of variables • Access variable property • Retrieve a variable value • Update a variable value • Add callback routine • Register change function • Un-register variable list • Access a table

21. Register Variable List • MAN_ERROR_TYPEmanAddVariableList(manVarType*varList, int numberVars) • Registers custom variable list to master list • Supports one or more different lists • Verifies the properties of each variable • Calculates size and allocates memory • Each variable is hashed for faster access • No duplicate variables allowed

22. Unregister Variable List • MAN_ERROR_TYPEmanDeleteVariableList(manVarType*varList) • Unregisters variable list from Master list • Frees memory • Causes rehashing of table

23. Access Variable Properties • MAN_ERROR_TYPEmanGetVariableInfo(MAN_ID_TYPEid, int *type, int *size, int *dimensions, int *numberDimensions)

24. MAN_ERROR_TYPE manGetWORD* (MAN_ID_TYPE id, void *buffer, int *indices MAN_TIMEOUT_TYPE timeout) MAN_ERROR_TYPE manGetChar (MAN_ID_TYPE id, void *buffer, int *indices MAN_TIMEOUT_TYPE timeout) MAN_ERROR_TYPE manGetOctetString (MAN_ID_TYPE id, void *buffer, int *indices MAN_TIMEOUT_TYPE timeout) MAN_ERROR_TYPE manGetUnknown (MAN_ID_TYPE id, void *buffer, int size, int *indices MAN_TIMEOUT_TYPE timeout) MAN_ERROR_TYPE manGetINT* (MAN_ID_TYPE id, void *buffer, int *indices MAN_TIMEOUT_TYPE timeout) Reads a value from variable memory into buffer Index allows an entry to be accessed from dimensional variable Double and float not supported totalSize = var->size; memcpy (getValue, var->varPointer, totalSize); Retrieve Singleton Variable INT32getValue = 0; manGetINT32 (“inMsgCount”, &getValue, NULL, 10)

25. MAN_ERROR_TYPE manGetArray (MAN_ID_TYPE id, void *buffer, int size, MAN_TIMEOUT_TYPE timeout) Not valid for MAN_OCTET_STRING and MAN_SNMP_TABLE type Reads all entries from dimensional variable into buffer Buffer size must be equal to or greater than dimensional totalSize = var->size * ( var->dimensions) memcpy (getValue, var->varPointer, totalSize); Retrieve Dimensional Variable INT8getValue[4] = 0; manGetArray (“ipAddress”, getValue, 4, 10)

26. MAN_ERROR_TYPE manSetWORD* (MAN_ID_TYPE id, void buffer, int *indices MAN_TIMEOUT_TYPE timeout) MAN_ERROR_TYPE manSetChar (MAN_ID_TYPE id, void buffer, int *indices MAN_TIMEOUT_TYPE timeout) MAN_ERROR_TYPE manSetOctetString (MAN_ID_TYPE id, void *buffer, int *indices MAN_TIMEOUT_TYPE timeout) MAN_ERROR_TYPE manSetUnknown (MAN_ID_TYPE id, void *buffer, int size, int *indices MAN_TIMEOUT_TYPE timeout) MAN_ERROR_TYPE manSetINT* (MAN_ID_TYPE id, void buffer, int *indices MAN_TIMEOUT_TYPE timeout) Writes value from buffer into variable memory Index allows an entry to be accessed from dimensional variable Double and float not supported totalSize = var->size; memcpy (var->varPointer, setValue, totalSize); Update Singleton Variable INT32setValue = 50; manSetINT32 (“inMsgCount”, &setValue, NULL, 10)

27. MAN_ERROR_TYPE manSetArray (MAN_ID_TYPE id, void *buffer, int size, MAN_TIMEOUT_TYPE timeout) Not valid for MAN_OCTET_STRING_TYPE and MAN_SNMP_TABLE Writes buffer into dimensional variable Buffer size must equal dimensional size totalSize = var->size * ( var->dimensions) memcpy (var->varPointer, setValue, totalSize); Update a Dimensional Variable INT8setValue[4] = {10,32,52,70}; manSetArray (“ipAddress”, setValue, 4, 10)

28. Add a Callback Function • MAN_ERROR_TYPE manAddVariableCallback (MAN_ID_TYPE id, int*indices, manCallbackFunctionType *fn, void *fnd) • User defined function executed when variable is updated • Routine must be defined as manCallbackFunctionType • Sets one or more callback routines per variable • Sets a callback for an entry in dimensional variable • Multiple functions are executed in the order added

29. Remove a Callback Function • MAN_ERROR_TYPE manDeleteVariableCallback (MAN_ID_TYPE id, int*indices, manCallbackFunctionType *fn, void *fnd) • Removes user defined function when variable is updated • One callback is removed if multiple set

30. Set Variable Change Function • MAN_ERROR_TYPE manRegisterChangeFn (manVariableChangeFnType *fn) • User defined function executed when variable is accessed • Sets one routine for all variables

31. Remove Variable Change Function • MAN_ERROR_TYPE manUnregisterChangeFn (void) • Removes the user defined function executed when a variable is accessed

32. Access Tables • Update table entry • Retrieve table entry • Retrieve table entry position • Delete table entry • Add new table entry

33. typedef struct { WORD8 tcpConnLocalAddr[4] INT32 tcpConnLocalPort WORD8 tcpConnRemAddr[4] INT32 tcpConnRemPort } tcpConnTableIndexType; Table Index • An entry requires a unique identifier • Distinguish between entries • Sorting and searching entries in table • Defined as manTableIndexType typedef struct { int numericIndex; int wantExact; void *snmpIndex; } manTableIndexType;

34. Update Table Entry • MAN_ERROR_TYPE manSetSnmpRow (MAN_ID_TYPE id, manTableIndexType *index, manTableIndexType *newIndex, void *buffer, MAN_TIMEOUT_TYPE timeout) • Updates entry that matches index when exact • Updates first entry greater or equal to index when not exact • Relocates entry in table if index is changed

35. Retrieve a Table Entry • MAN_ERROR_TYPE manGetSnmpRow (MAN_ID_TYPE id, manTableIndexType *index, void *buffer, MAN_TIMEOUT_TYPE timeout) • Retrieves entry that matches index when exact • Retrieves first entry greater or equal to index when not exact

36. Retrieve Table Entry Position • MAN_ERROR_TYPE manGetSnmpRowPos (MAN_ID_TYPE id, manTableIndexType *index, int *pos, MAN_TIMEOUT_TYPE timeout) • Get position of entry that matches index when exact • Get position of first entry greater or equal to index when not exact

37. Remove a Table Entry • MAN_ERROR_TYPE manDeleteSnmpRow (MAN_ID_TYPE id, manTableIndexType *index, MAN_TIMEOUT_TYPE timeout) • Deletes entry that matches index when exact • Deletes first entry greater or equal to index when not exact • Releases memory allocated for entry

38. Add a Table Entry • MAN_ERROR_TYPE manInsertSnmpRow (MAN_ID_TYPE id, manTableIndexType *index, void *buffer, MAN_TIMEOUT_TYPE timeout) • Inserts before entry which matches index when exact • Inserts before first entry greater or equal to index when not exact • Allocates memory for new entry