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

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)

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

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

Access Data –State –Connections –System up time –Location –Physical Address –Jobs –Statistics Netsilicon Management Interface SNMP BrowserWeb Browser NET+OS Application Overview

typedef struct { MAN_ID_TYPE id void*varPointer; intisFunction; intsize; inttype intdimensions; intnumberDimensions; MAN_SEMAPHORE *semaphores; intnumberSemaphores; void*rangeFn; void*rangeInfo manTableInfoType *tableInfo; void*callbackFn; } manVarType ; Define a variable ID Type Size Dimension Memory Range Semaphore Callback Function Table Variable Properties

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

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 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

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

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 Variable Properties: size

Character MAN_CHAR Integer MAN_INT8 MAN_INT16 MAN_INT32 MAN_INT64 Word MAN_WORD8 MAN_WORD16 MAN_WORD32 MAN_WORD64 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 Variable Properties: type

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} Variable Properties: dimension

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 Sem 1 Sem 2Sem 3 Sem 4Sem 5 Access Variable Variable Properties: semaphores

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 Variable Properties: rangeFn

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) Variable Properties: callbackFn

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

tcpConnStatetcpConnLocalAddrtcpConnLocalPorttcpConnRemPort Listen (2) Established (5) Closed (1) Established (5) tcpConnRemAddr Example Variable Table

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

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 ) { tcpConnTableIndexTyp e *index = indexInfo; tcpConnTableType *currentRow = (tcpConnTableType*) row; value = memcmp (currentRow->tcpConnLocalPort, index->tcpConnLocalPort, 4) return (value); } Table Properties: indexFn

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 Management API Capabilities

MAN_ERROR_TYPE manAddVariableList (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 Register Variable List

MAN_ERROR_TYPE manDeleteVariableList (manVarType *varList ) –Unregisters variable list from Master list –Frees memory –Causes rehashing of table Unregister Variable List

MAN_ERROR_TYPE manGetVariableInfo ( MAN_ID_TYPE id, int *type, int *size, int *dimensions, int *numberDimensions) Access Variable Properties

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 INT32 getValue = 0; man G et INT32 (“ inMsgCount ”, &getValue, NULL, 10) totalSize = var -> size; memcpy (getValue, var -> varPointer, totalSize); Retrieve Singleton Variable

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 INT8 getValue[4] = 0; man G et Array (“ ipAddress ”, getValue, 4, 10) totalSize = var -> size * ( var -> dimensions) memcpy (getValue, var -> varPointer, totalSize); Retrieve Dimensional Variable

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 INT32 setValue = 50; man S et INT32 (“ inMsgCount ”, &setValue, NULL, 10) totalSize = var -> size; memcpy (var -> varPointer, setValue, totalSize); Update Singleton Variable

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 INT8 setValue[4] = {10,32,52,70}; man S et Array (“ ipAddress ”, setValue, 4, 10) totalSize = var -> size * ( var -> dimensions) memcpy (var -> varPointer, setValue, totalSize); Update a Dimensional Variable

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 Add 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 Remove a Callback Function

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

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

Update table entry Retrieve table entry Retrieve table entry position Delete table entry Add new table entry Access Tables

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; typedef struct { WORD8 tcpConnLocalAddr[4] INT32 tcpConnLocalPort WORD8 tcpConnRemAddr[4] INT32 tcpConnRemPort } tcpConnTableIndexType;

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 Update 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 Retrieve a Table Entry

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 Retrieve Table Entry Position

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 Remove 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 Add a Table Entry