snmpAPI \- Simple Network Management Protocol application programming interface. version 2 #include STATUS snmpOpen(application) NAME application STATUS snmpClose( how ) HOW how STATUS snmpLook( eventType ) SPTYPE *eventType STATUS snmpErrorDescription( requestId, error ) INTEGER *requestId, DESCRIPTION error STATUS snmpGetRequest( host, application, requestId, qos, variableNames ) NAME host, NAME application, INTEGER requestId, QOS qos, VARLIST variableNames STATUS snmpGetIndication( replyId, variableNames ) INTEGER *replyId, VARLIST *variableNames STATUS snmpGetResponse( replyId, errorStatus, errorIndex, variableValues ) INTEGER replyId, INTEGER errorStatus, INTEGER errorIndex, VARLIST variableValues STATUS snmpGetConfirm( requestId, errorStatus, errorIndex, variableValues ) INTEGER *requestId, INTEGER *errorStatus, INTEGER *errorIndex, VARLIST *variableValues ) STATUS snmpGetNextRequest( host, application, requestId, qos, variableNames ) NAME host, NAME application, INTEGER requestId, QOS qos, VARLIST variableNames STATUS snmpGetNextIndication( replyId, variableNames ) INTEGER *replyId, VARLIST *variableNames STATUS snmpGetNextResponse( replyId, errorStatus, errorIndex, variableValues ) INTEGER replyId, INTEGER errorStatus, INTEGER errorIndex, VARLIST variableValues STATUS snmpGetNextConfirm( requestId, errorStatus, errorIndex, variableValues ) INTEGER *requestId, INTEGER *errorStatus, INTEGER *errorIndex, VARLIST *variableValues STATUS snmpGetBulkRequest( host, application, requestId, qos, maxRepetitions, nonRepeaters, variableNames ) NAME host, NAME application, INTEGER requestId, QOS qos, INTEGER maxRepetitions, INTEGER nonRepeaters, VARLIST variableNames STATUS snmpGetBulkIndication( replyId, maxRepetitions, nonRepeaters, variableNames ) INTEGER *replyId, INTEGER *maxRepetitions, INTEGER *nonRepeaters, VARLIST *variableNames STATUS snmpGetBulkResponse( replyId, errorStatus, errorIndex, variableValues ) INTEGER replyId, INTEGER errorStatus, INTEGER errorIndex, VARLIST variableValue STATUS snmpGetBulkConfirm( requestId, errorStatus, errorIndex, variableValues ) INTEGER *requestId, INTEGER *errorStatus, INTEGER *errorIndex, VARLIST *variableValues STATUS snmpSetRequest( host, application, requestId, qos, variableValues ) NAME host, NAME application, INTEGER requestId, QOS qos, VARLIST variableValues STATUS snmpSetIndication( replyId, variableValues ) INTEGER *replyId, VARLIST *variableValues STATUS snmpSetResponse( replyId, errorStatus, errorIndex ) INTEGER replyId, INTEGER errorStatus, INTEGER errorIndex STATUS snmpSetConfirm( requestId, errorStatus, errorIndex ) INTEGER *requestId, INTEGER *errorStatus, INTEGER *errorIndex STATUS snmpInformRequest( host, application, requestId, qos, variableValues ) NAME host, NAME application, INTEGER requestId, QOS qos, VARLIST variableValues STATUS snmpInformIndication( host, application, variableValues ) NAME host, NAME application, VARLIST *variableValues STATUS snmpInformResponse( replyId, errorStatus, errorIndex ) INTEGER replyId, INTEGER errorStatus, INTEGER errorIndex STATUS snmpInformConfirm( requestId, errorStatus, errorIndex ) INTEGER *requestId, INTEGER *errorStatus, INTEGER *errorIndex STATUS snmpTrapRequest( VARLIST *variableValues ) VARLIST *variableValues STATUS snmpTrapIndication( host, application, variableValues ) NAME host, NAME application, VARLIST *variableValues DESCRIPTION The above, mentioned functions which can be used as building blocks for the construction of snmp-based agent and - manager applications can be divided in several categories; General functions. The snmpopen function should be issued before any other snmp function will be processed. It is used to get connected to the Snmp Protocol Machine(SPM) (assignment of service access point identifiers). Further it eventually takes care of the initialization of the SPM, if no SPM was running. The vari- able 'application' specifies the name of this application. The function returns a status value (STATUS) to denote wether it was succesfull (SUCCESS) or wether it failed( FAILURE). This applies to all functions defined by this API. The snmpClose should be called before terminating a connec- tion with the SPM. It is the counterpart of the snmpOpen call. It disconnects the SPM and the application. The 'how' parameter is used to denote if pending requests need to be handled or may be discarded. The values GRACEFULL denotes that the requests must be handled. The value DISCARD allows an inmediate disconnection. The snmpLook function is used to determine if data is avail- able that needs to be processed. The snmplook provides the possibility to check on service access point for the occurrence of events. If an event happens the 'type' parame- ter denotes the kind of event (kind of service primitive) that occurred. Added to the types of serviceprimitives are: TIMEOUT denotes that no event happened in this period, NONSNMP denotes that an event occurred at a user specified socket( One of the userset), ERR_IND refers to a provider generated error indication. The snmpErrorDescription function provides additional infor- mation why a request could not be processed by the SPM. The 'request-id' provides the identification, the DESCRIPTION returns a string with additional information. 2. Manager send functions. The snmpGetRequest constructs an appropriate request, which is sent to an agent. The hostname indicates the remote machine where the agent is running. The 'application' param- eter indicates the name of the agent on that particular host. The 'request_id' is used to identify a request among several outstanding requests. The 'quality of service' parameter specifies if encryption and/or authentication are needed. Finally, the variableNames are used to select the individual objects. The snmpGetNextRequest is used to retrieve the successors of the objects as specified by the variableNames. snmpGetBulkRequest retrieves as much data as possible. The hostname indicates the remote machine where the agent is running. The 'application' parameter indicates the name of the agent on that particular host. The 'request_id' is used to identify a request among several outstanding requests. The 'quality of service' parameter specifies if encryption and/or authentication are needed. Max-repetitions indicates the number of variables which should be retrieved at most once. Non-repeaters indicates the maximum number of times that other variables should be retrieved. snmpSetRequest This function is used to change the value of the objects as specified in the variableValues field. A snmpInformRequest is used for communication among managers. 3. Manager receive functions. The snmpTrapIndication function denotes that the agent, identified by 'host' and 'application' generated a trap. The trap is concerned the objects instances 'variableValues'. The snmpInformIndication indicates that the manager identi- fied by 'host' and 'application' passes the object instances 'variableValues'. The snmpGetConfirm function is be used to obtain the results of a completed get request. 'Request-id' denotes to which request this confirm belongs. 'Errorindex' and 'errorstatus' provide information about the success of the information and the 'variableValues ' contains the object instances. The functions described below, have the same parameters as the snmpGetConfirm. snmpGetNextConfirm snmpGetBulkConfirm The functions snmpSetConfirm and snmpInformConfirm are also identical to snmpGetConfirm except for the 'variableValues'. So the application has to keep a copy of the 'varia- bleValues' sent by the related request primitive. 4. Agent send functions. To build an agent application the following send functions are available. One function to send a trap and several func- tions to generate a response. The snmpGetResponse is the answer to a snmpGetIndication received by the agent. 'Errorindex' and 'errorstatus' pro- vide information about the success of the information and the 'variableValues ' contains the object instances. The 'reply_id' must be the same as the 'reply_id' that was returned with the snmpGetIndication. The functions described below, have the same parameters as the snmpGetResponse. snmpGetNextResponse snmpGetBulkResponse The snmpSetResponse are also identical to snmpGetConfirm except for the 'variableValues'. So the application has to keep a copy of the 'variableValues' sent by the related request primitive. Besides thes reponse functions a snmpTrapRequest function exists. An agent can generate a trap by generating a TrapRequest. The TrapRequest contains the variableValues. The SPM can deduce all managers related, to the combination of 'variableValues and the application, from the administrative model. 5. Agent receive functions. The agent specific receive function deal with the processing of indications. snmpGetIndication This function contains the replyid and variableNames to be retrieved by the manager. The agent has to use the replyid in the corresponding response. The function snmpGetNextIndication, is used to denote that the successors of the objects as supplied by the list varia- bleNames must be retreived. The agent has to use the replyid in the corresponding response. The function snmpSetIndication is used to denote that the values of the objects of the variable binding list must be modified. This function contains the replyid and varia- bleValues to be set by the manager. The agent has to use the replyid in the corresponding response. The function snmpGetBulkIndication is used to denote that the manager wants to retrieve bulkdata. Max-repetitions indicates the number of variables which should be retrieved at most once. Non-repeaters indicates the maximum number of times that other variables should be retrieved. BUGS none ... :) AUTHORS The SNMP group at the University of Twente, the Netherlands. Mailaddress: