.TH SNMP_AGENT_API 3 "02 Apr 2001"
.UC 5
.SH NAME
snmp_agent_api \- embedding an agent into a external application
.SH SYNOPSIS
.nf
#include <ucd-snmp/ucd-snmp-config.h>
#include <ucd-snmp/ucd-snmp-includes.h>
#include <ucd-snmp/ucd-snmp-agent-includes.h>

main () {
  int agentx_subagent=1; /* change this if you're a master agent */

  snmp_enable_stderrlog();

  /* if we're an agentx subagent */
  if (agentx_subagent) {
      /* make us a agentx client. */
      ds_set_boolean(DS_APPLICATION_ID, DS_AGENT_ROLE, 1);
  }

  init_agent("yourappname");

  /* initialize your mib code here */
  init_my_mib_code();

  /* yourappname will be used to read yourappname.conf files. */
  init_snmp("yourappname");

  /* If we're going to be a snmp master agent */
  if (!agentx_subagent)
      init_master_agent(161, NULL, NULL);  /* open port 161 (UDP:snmp) */

  /* you're main loop here... */
  while(whatever) {
      /* if you use select(), see snmp_api(3) */
      /*     --- OR ---  */
      agent_check_and_process(0); /* 0 == don't block */
  }

  /* at shutdown time */
  snmp_shutdown("yourappname");
}

Then:
cc ... -lucdagent -lucdmibs -lsnmp # other libraries may be needed here

.fi
.SH DESCRIPTION
.PP
Our goal is to create a easy to use interface to the ucd-snmp package
such that you can take code that you have written that has been
designed to be a ucd-snmp mib module and embed it into an external
application where you can either chose to be a SNMP master agent or an
AgentX sub-agent using the same mib module code.  Our suggestion is
that you use our (or another) SNMP agent as the AgentX master agent
and chose to become an AgentX subagent which then attaches to the
master.
.PP
Starting with version 4.1, the ucd-snmp package provides a pair of
libraries that enables easy embedding of an SNMP or AgentX agent into
an external software package. AgentX is an extensible protocol
designed to allow multiple SNMP sub-agents all run on one machine
under a single SNMP master agent.  It is defined in RFC 2741.
.PP
You will need to perform a few tasks in order to accomplish
this. First off, you will need to initialize both the SNMP library and
the SNMP agent library. As indicated above, this is done slightly
differently depending on whether or not you are going to perform as a
master agent or an AgentX sub-agent.
.SH CONFIGURATION
.PP
If you intend to operate as an AgentX sub-agent, you will have to
configured the ucd-snmp package as follows:
.RS
  ./configure --with-mib-modules="agentx/subagent"
.RE
Additionally, you will need to link against the libucdmibs library and 
call subagent_pre_init() as indicated above.
.SH COMPILING
.PP
In order to make use of any of the above API, you will need to clinch
against at least two libraries: the libucdagent library and the
libsnmp library. Additionally, if you plan to make use of any of the
code in the agent's mib modules (like the AgentX subagent support),
you will need to link against the libucdmibs library as well.
.SH FUNCTIONS
.IP "snmp_enable_stderrlog()"
Logs error output from the SNMP agent to the standard error stream.
.IP "ds_set_boolean()"
Please see the
.BR "default_store"(3)
manual page for more information
about this API.
.IP "init_agent(char *name)"
Initializes the embedded agent.  This should be called before the
.BR "init_snmp()"
call.  
.I name
is used to dictate what .conf file to read when
.BR "init_snmp()"
is called later.
.IP "init_snmp(char *name)"
Initializes the SNMP library.  Note that one of the things this will
do will be to read configuration files in an effort to configure your
application. It will attempt to read the configuration files named by
the
.I name
string that you passed in.  It can be used to configure access
control, for instance.   Please see the
.BR "read_config" "(3), " "snmp_config" "(5), and " "snmpd.conf"(5)
manual pages for further details on
this subject.
.IP "init_master_agent(port, NULL, NULL)"
Initializes the master agent and opens all its necessary ports.
.I port
is the port you want to listen for SNMP requests on.
.IP "agent_check_and_process(int block)"
This checks for packets arriving on the SNMP port and processes them
if some are found.  If 
.I block
is non-zero, the function call will block until a packet arrives or an 
alarm must be run (see
.BR "snmp_alarm" "(3)). The return value from this"
function is a positive integer if packets were processed, zero if an
alarm occurred and -1 if an error occured.
.IP "snmp_shutdown(char *name);"
This shuts down the agent, saving any needed persistent storage, etc.
.SH "SEE ALSO"
.BR "select"(2), 
.BR "snmp_api"(3),
.BR "default_store"(3),
.BR "snmp_alarm"(3),
.BR "read_config(3)",
.BR "snmp_config"(5),
.BR "snmpd.conf"(5)