NAME

       snmpm_user - Behaviour module for the SNMP manager user.

DESCRIPTION

       This  module defines the behaviour of the manager user. A snmpm_user compliant module must
       export the following functions:

         * handle_error/3

         * handle_agent/4

         * handle_pdu/4

         * handle_trap/3

         * handle_inform/3

         * handle_report/3

         * handle_invalid_result/2

       The semantics of them and their exact signatures are explained below.

       Some of the function has no defined  return  value  (void()),  they  can  ofcourse  return
       anythyng.  But  the  functions that do have specified return value(s) must adhere to this.
       None of the functions can use exit of throw to return.

DATA TYPES

       snmp_gen_info() = {ErrorStatus :: atom(),
                          ErrorIndex  :: pos_integer(),
                          Varbinds    :: [snmp:varbind()]}
       snmp_v1_trap_info() :: {Enteprise :: snmp:oid(),
                               Generic   :: integer(),
                               Spec      :: integer(),
                               Timestamp :: integer(),
                               Varbinds  :: [snmp:varbind()]}

EXPORTS

       handle_error(ReqId, Reason, UserData) -> void()

              Types:

                 ReqId = integer()
                 Reason = {unexpected_pdu, SnmpInfo} | {invalid_sec_info,  SecInfo,  SnmpInfo}  |
                 {empty_message, Addr, Port} | term()
                 SnmpInfo = snmp_gen_info()
                 SecInfo = term()
                 Addr = ip_address()
                 Port = integer()
                 UserData = term()

              This  function  is  called  when the manager needs to communicate an "asynchronous"
              error to the user: e.g. failure to send  an  asynchronous  message  (i.e.  encoding
              error),  a received message was discarded due to security error, the manager failed
              to generate a response message to a received inform-request, or when  receiving  an
              unexpected PDU from an agent (could be an expired async request).

              If  ReqId  is  less then 0, it means that this information was not available to the
              manager (that info was never retrieved before the message was discarded).

              For SnmpInfo see handle_agent below.

       handle_agent(Addr, Port, Type, SnmpInfo, UserData) -> Reply

              Types:

                 Addr = ip_address()
                 Port = integer()
                 Type = pdu | trap | report | inform
                 SnmpInfo = SnmpPduInfo | SnmpTrapInfo | SnmpReportInfo | SnmpInformInfo
                 SnmpPduInfo = snmp_gen_info()
                 SnmpTrapInfo = snmp_v1_trap_info()
                 SnmpReportInfo = snmp_gen_info()
                 SnmpInformInfo = snmp_gen_info()
                 UserData = term()
                 Reply = ignore | {register, UserId, TargetName, AgentConfig}
                 UserId = term()
                 TargetName = target_name()
                 AgentConfig = [agent_config()]

              This function is called when a message is received from an unknown agent.

              Note that this will always be the default user that is called.

              For more info about the agent_config(), see register_agent.

              The arguments Type and SnmpInfo relates in the following way:

                * pdu - SnmpPduInfo (see handle_pdu for more info).

                * trap - SnmpTrapInfo (see handle_trap for more info).

                * report - SnmpReportInfo (see handle_report for more info).

                * inform - SnmpInformInfo (see handle_inform for more info).

              The only user which would return {register, UserId, TargetName, AgentConfig} is the
              default user.

       handle_pdu(TargetName, ReqId, SnmpPduInfo, UserData) -> void()

              Types:

                 TargetName = target_name()
                 ReqId = term()
                 SnmpPduInfo = snmp_gen_info()
                 UserData = term()

              Handle  the  reply to an asynchronous request, such as async_get, async_get_next or
              async_set.

              It could also be a late reply to a synchronous request.

              ReqId is returned by the asynchronous request function.

       handle_trap(TargetName, SnmpTrapInfo, UserData) -> Reply

              Types:

                 TargetName = TargetName2 = target_name()
                 SnmpTrapInfo = snmp_v1_trap_info() | snmp_gen_info()
                 UserData = term()
                 Reply = ignore | unregister | {register, UserId, TargetName2, AgentConfig}
                 UserId = term()
                 AgentConfig = [agent_config()]

              Handle a trap/notification message from an agent.

              For more info about the agent_config(), see register_agent

              The only user which would return {register, UserId, TargetName2,  agent_info()}  is
              the default user.

       handle_inform(TargetName, SnmpInformInfo, UserData) -> Reply

              Types:

                 TargetName = TargetName2 = target_name()
                 SnmpInformInfo = snmp_gen_info()
                 UserData = term()
                 Reply  =  ignore  |  no_reply  |  unregister  |  {register, UserId, TargetName2,
                 AgentConfig}
                 UserId = term()
                 AgentConfig = [agent_config()]

              Handle a inform message.

              For more info about the agent_config(), see register_agent

              The only user which would return {register, UserId,  TargetName2,  AgentConfig}  is
              the default user.

              If  the  inform  request  behaviour  configuration  option is set to user or {user,
              integer()}, the response (acknowledgment) to this inform-request will be sent  when
              this function returns.

       handle_report(TargetName, SnmpReportInfo, UserData) -> Reply

              Types:

                 TargetName = TargetName2 = target_name()
                 Addr = ip_address()
                 Port = integer()
                 SnmpReportInfo = snmp_gen_info()
                 UserData = term()
                 Reply = ignore | unregister | {register, UserId, TargetName2, AgentConfig}
                 UserId = term()
                 AgentConfig = [agent_config()]

              Handle a report message.

              For more info about the agent_config(), see register_agent

              The  only  user  which would return {register, UserId, TargetName2, AgentConfig} is
              the default user.

       handle_invalid_result(IN, OUT) -> void()

              Types:

                 IN = {Func, Args}
                 Func = atom()
                 Args = list()
                 OUT = {crash, CrashInfo} | {result, InvalidResult}
                 CrashInfo = {ErrorType, Error, Stacktrace}
                 ErrorType = atom()
                 Error = term()
                 Stacktrace = list()
                 InvalidResult = term()

              If any of the other callback functions crashes (exit, throw or a  plain  crash)  or
              return  an  invalid result (if a valid return has been specified), this function is
              called. The purpose is to allow the user handle this error (for instance  to  issue
              an error report).

              IN  reprecents  the  function  called  (and  its  arguments).  OUT  represents  the
              unexpected/invalid result.